# How to Integrate Hallmark with Existing Design Tokens and Frameworks

> Seamlessly integrate Hallmark with your design tokens and frameworks. Hallmark scans CSS custom properties, Tailwind configs, and DTCG JSON to map values and preserve your system.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-31

---

**Hallmark integrates with existing design tokens by scanning your repository for CSS custom properties, Tailwind configs, or DTCG JSON files, then mapping them to its token-first system in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) while preserving your locked values.**

Hallmark is a design skill that generates self-contained HTML and CSS pages through a strict token-first workflow. When adopting it into a codebase that already uses CSS custom properties, Tailwind themes, or Design Tokens Community Group (DTCG) formats, you must align your existing tokens with Hallmark's architecture. This guide demonstrates how to bridge Hallmark's token system—defined in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and enforced by the slop-test quality gates—with your current design infrastructure and frontend framework.

## Run a Pre‑flight Scan to Detect Existing Tokens

Hallmark begins integration by scanning your repository for existing design artifacts. According to the **Pre‑flight** section in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the scan checks for [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, `tokens.*`, and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files. If Hallmark discovers a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or token file, it preserves those values as **locked tokens** and only generates missing macrostructure or micro-interactions.

This scan ensures that Hallmark does not overwrite your existing design system. Instead, it treats discovered tokens as the source of truth, adding only the structural pieces needed to complete the page generation.

## Map Existing Tokens to Hallmark's CSS Architecture

Hallmark's core token definitions reside in **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)**, which declares 20+ theme-specific custom properties under `:root` and `[data-theme="…"]` selectors. The file defines variables such as `--color-accent`, `--font-display`, and `--space-md`, enabling theme switching via the `data-theme` attribute.

To integrate with your existing tokens, create a mapping strategy based on your current format:

- **CSS Custom Properties**: Import [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) first, then declare overrides in a local file (e.g., [`src/tokens/hallmark-overrides.css`](https://github.com/Nutlope/hallmark/blob/main/src/tokens/hallmark-overrides.css)). CSS cascade rules ensure your project-specific values take precedence.
- **Tailwind `theme.extend`**: Export Tailwind values to CSS custom properties using the `addBase` function in [`tailwind.config.js`](https://github.com/Nutlope/hallmark/blob/main/tailwind.config.js). This exposes Tailwind colors as `--color-brand` variables that Hallmark can reference.
- **DTCG JSON/YAML**: Convert JSON token keys to CSS custom properties using a one-time script, placing the output in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css). Hallmark reads any `--*` variable, eliminating the need to duplicate palettes.
- **Design-system [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)**: Hallmark treats this file as a locked system. It will not generate new tokens but will use those defined there for all subsequent operations.

```css
/* site/css/tokens.css – Core token definitions */
:root,
[data-theme="specimen"] {
  --color-paper:    oklch(96%  0.018 80);
  --color-accent:   #FC4C02;
  --font-display: "Fraunches", "Tiempos", ui-serif, Georgia, serif;
  --space-md: 1rem;
}

```

## Wire Token Files into Your Framework

Import Hallmark's token stylesheet into your framework's global CSS entry point to establish the variable scope.

**Next.js (App Router)**

```tsx
// app/globals.css
@import url('/site/css/tokens.css');

```

```tsx
// app/layout.tsx
import './globals.css';
import '/site/css/tokens.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" data-theme="midnight">
      <body>{children}</body>
    </html>
  );
}

```

**Astro**

```astro
---
// src/layouts/BaseLayout.astro
---
<link rel="stylesheet" href="/site/css/tokens.css" />

```

**Vue or Svelte**

Import the tokens into your root `<style>` block or global SCSS file. Scoped styles in these frameworks still resolve global custom properties without additional configuration.

**Vanilla HTML**

Include the stylesheet in your document head:

```html
<link rel="stylesheet" href="/site/css/tokens.css" />

```

Enable theme switching by adding the `data-theme` attribute to your `<html>` element. Hallmark's demo implementation in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) toggles this attribute with the **T** key, which you can replicate for runtime theme changes.

```html
<html data-theme="midnight">

```

## Enforce Locked Token Discipline

Hallmark requires **locked tokens** across all generated output, as specified in the "Locked tokens — no mid‑render improvisation" clause of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md). Once a theme is selected, every color or font reference must use a `var(--…)` token.

Replace any inline hex values or font declarations with token references:

```css
/* Non-compliant inline values */
.button { background:#FC4C02; font-family:"Fraunces", serif; }

/* Hallmark-compliant token references */
.button { background:var(--color-accent); font-family:var(--font-display); }

```

This discipline ensures that the slop-test gates pass and that your design remains consistent across framework boundaries.

## Align Framework-Specific Conventions

Different frameworks require specific patterns to consume CSS custom properties effectively.

**Next.js and React**

Use `className` with arbitrary value syntax or CSS Modules that reference the variables:

```tsx
// Using Tailwind arbitrary values
className="bg-[var(--color-accent)] text-[var(--color-accent-ink)]"

```

**Tailwind CSS**

When using Just-In-Time (JIT) mode, whitelist Hallmark tokens in [`tailwind.config.js`](https://github.com/Nutlope/hallmark/blob/main/tailwind.config.js) to prevent purging:

```js
// tailwind.config.js
module.exports = {
  safelist: [
    { pattern: /--color-(accent|paper|rule|muted)/ },
  ],
};

```

Alternatively, use `@apply` directives within CSS files that already import [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css).

**Vue and Svelte**

Scoped styles automatically inherit global custom properties. Import [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) in your global styles once, and all components can reference `--color-accent` and other tokens without additional setup.

## Generate Custom Themes When Needed

If your existing tokens do not match Hallmark's 20 catalog themes, trigger the **custom-theme** flow documented in [`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md). This process generates an OKLCH palette and font pairing based on a brand color or vibe you provide.

The generated theme lives in the page's `:root` scope using standard token naming conventions (e.g., `--color-accent`), ensuring the rest of your codebase remains compatible without refactoring.

## Validate Integration with the Slop-Test

After integration, run Hallmark's **slop-test**—a 57-gate quality check—to verify compliance. The test ensures no inline color or font values remain, that all interactive states (hover, focus, active, disabled, loading, error, success) are present, and that mobile breakpoints (320px, 375px, 414px, 768px) pass without horizontal scroll.

Invoke the CLI audit on specific components or folders:

```bash
npx skills run nutlope/hallmark audit ./src/components/Button.tsx

```

Results appear as a comment stamp at the top of generated files:

```css
/* Hallmark · pre‑emit critique: P5 H5 E5 S5 R5 V5 */

```

If gates fail, the CLI outputs human-readable fixes, such as replacing inline hex codes with `var(--color-accent)`.

## Summary

- Hallmark scans for existing tokens in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, `tokens.*`, and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) during the pre‑flight phase, preserving locked values found in [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md).
- Core tokens live in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under `:root` and `[data-theme="…"]` selectors, supporting runtime theme switching via the `data-theme` attribute.
- Map existing tokens by importing [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) first, then overriding with project-specific values, or by exporting Tailwind/DTCG values to CSS custom properties.
- Enforce **locked token discipline** by replacing all inline hex and font values with `var(--token-name)` references to pass the 57-gate slop-test.
- Import token stylesheets into framework entry points (Next.js [`layout.tsx`](https://github.com/Nutlope/hallmark/blob/main/layout.tsx), Astro layouts, Vue/Svelte global styles) to establish global scope.

## Frequently Asked Questions

### Does Hallmark overwrite my existing Tailwind configuration?

No. Hallmark preserves existing `tailwind.config.*` files during the pre‑flight scan. It exports Tailwind theme values to CSS custom properties using `addBase`, allowing Hallmark to reference your brand colors while keeping your Tailwind setup intact.

### Can I use Hallmark with a vanilla HTML project without a build step?

Yes. Hallmark generates self-contained HTML and CSS. Simply include `<link rel="stylesheet" href="/site/css/tokens.css">` in your document head. The system requires no JavaScript bundler or framework to function.

### How do I switch themes at runtime in a React application?

Toggle the `data-theme` attribute on the `<html>` element using React state or a vanilla JavaScript event listener. For example: `document.documentElement.dataset.theme = 'midnight'`. This mirrors the implementation in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) where the **T** key cycles through themes.

### What happens if my design tokens use different naming conventions than Hallmark?

Create a mapping file (e.g., [`src/tokens/hallmark-overrides.css`](https://github.com/Nutlope/hallmark/blob/main/src/tokens/hallmark-overrides.css)) that imports Hallmark's [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) first, then redeclares the variables using your preferred names while mapping to Hallmark's expected values. Alternatively, convert DTCG JSON tokens to CSS custom properties that align with Hallmark's naming (e.g., `--color-accent`, `--font-display`) before the integration scan runs.