how-to-guide

How to Integrate Hallmark with Existing Design Tokens and Frameworks

July 31, 2026 Nutlope/hallmark ↗

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 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 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, the scan checks for package.json, tailwind.config.*, tokens.*, and design.md files. If Hallmark discovers a 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, 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 first, then declare overrides in a local file (e.g., 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. 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. Hallmark reads any --* variable, eliminating the need to duplicate palettes.
  • Design-system 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.
/* 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)

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

// 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

---
// 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:

<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 toggles this attribute with the T key, which you can replicate for runtime theme changes.

<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. 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:

/* 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:

// 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 to prevent purging:

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

Alternatively, use @apply directives within CSS files that already import tokens.css.

Vue and Svelte

Scoped styles automatically inherit global custom properties. Import 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. 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:

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

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

/* 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, tailwind.config.*, tokens.*, and design.md during the pre‑flight phase, preserving locked values found in design.md.
  • Core tokens live in 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 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, 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 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) that imports Hallmark's 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →