Can Hallmark Integrate with Existing Design Systems?

Hallmark integrates with existing design systems by reading a design.md file at your project root and treating it as the single source of truth for all subsequent page builds.

Unlike tools that impose their own visual language, Hallmark is architected to adopt whatever system you already have in place. Whether you're working with a Tailwind config, CSS custom properties, or a formal design token library, Hallmark can lock onto those definitions and propagate them across every generated page. This article explains the exact mechanism, based on the source code in the Nutlope/hallmark repository.

How Hallmark Detects and Locks a Design System

The integration flow centers on a single file: design.md (case-insensitive, also accepts DESIGN.md). According to SKILL.md, Hallmark explicitly checks for this file before any genre or theme selection occurs. If found, the diversification rule is inverted so that consistency is enforced instead of variety.

# Conceptual flow from SKILL.md

if design_md_exists():
    genre_diversification = False      # consistency required

    theme_source = "design.md"         # locked system

else:
    genre_diversification = True       # variety allowed

When locked, three things happen:

1. All picks defer to design.md — genre, macro-structure, color palette, typography, spacing, motion, and component choices are pulled from the specifications.
2. The CSS stamp records provenance — design-system: design.md and designed-as-app are embedded so future runs know to read the file first.
3. Four export formats are emitted — tokens.css, Tailwind v4 @theme, DTCG tokens.json, and shadcn/ui CSS variables are auto-generated in the ## Exports section.

Importing Your Existing Tokens

Hallmark does not require you to start from scratch. To integrate Hallmark with an existing design system, create a minimal design.md that references your current token files:

# design.md

## Tokens

```css
@import "src/tailwind.css";   /* your existing Tailwind theme */

Exports

• Tailwind v4 @theme — auto-generated by Hallmark
• DTCG tokens.json — auto-generated by Hallmark
• shadcn/ui CSS variables — auto-generated by Hallmark

Now any Hallmark command will read [`src/tailwind.css`](https://github.com/Nutlope/hallmark/blob/main/src/tailwind.css) and apply those tokens to every generated page. The [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) file at your project root remains the canonical artifact, importable by any framework that supports CSS variables.

## Locking a System Multi-Page Redesign

When you run `hallmark redesign --multi-page`, Hallmark produces a full [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) that other pages will lock onto:

```bash

# Generate pages and lock the system

hallmark redesign --multi-page

# Or, after analyzing an existing site

hallmark study <url-or-screenshot>

# User: "lock the DNA"   ← Hallmark writes design.md

As implemented in verbs/redesign.md, this flow guarantees that subsequent runs simply read the existing design.md, keeping your entire site synchronized with the same design language.

Design System Drift Detection

Integration isn't a one-time event. The audit verb, defined in verbs/audit.md, continuously flags any page that diverges from the locked system:

• Theme drift (colors, fonts outside the defined set)
• Macrostructure violations (layout patterns not in the system)
• Missing stamps (pages built before the lock was established)

This enforcement ensures that your Hallmark and design system integration remains clean and consistent over time.

Export Format Compatibility

As documented in references/export-formats.md, Hallmark emits tokens in four portable formats:

Format	Use Case
tokens.css	Universal CSS custom properties
Tailwind v4 @theme	Next-generation Tailwind projects
DTCG tokens.json	Design-tool interoperability (Figma, Tokens Studio)
shadcn/ui CSS variables	Component library integration

These formats let downstream projects import the same token set without transformation. For example, in a React project using shadcn/ui:

<link rel="stylesheet" href="/tokens.css">
<link rel="stylesheet" href="/shadcn-vars.css">

All components now reference identical design tokens, guaranteeing visual consistency with Hallmark-generated pages.

Integration Limits and Expectations

Understanding what Hallmark does not do is equally important:

• No automatic inference — Hallmark will not scan your codebase and guess your design system. The lock-in step must be explicitly requested (e.g., "lock the system" or "give me a design.md").
• No runtime execution — Hallmark reads static token definitions only. It does not execute JavaScript, import npm packages, or process Tailwind plugins at build time.
• Manual mapping required — If your UI library expects an unsupported token format, expose it through one of the four export formats or map it manually.

These constraints mirror real-world design-team workflows where the system is formalized only after patterns have been vetted.

Summary

• Hallmark adopts existing design systems rather than replacing them, using a design.md file as the source of truth.
• The lock is opt-in: create design.md manually or via hallmark redesign --multi-page.
• Four export formats (CSS, Tailwind, DTCG, shadcn/ui) ensure compatibility with downstream tools.
• The audit verb detects drift and enforces consistency across all pages.
• Integration is declarative and version-controlled — no hidden side effects or runtime code execution.

Frequently Asked Questions

Does Hallmark automatically detect my Tailwind config?

No. Hallmark does not automatically scan for or import Tailwind configuration files. You must explicitly create a design.md that references your existing tokens, typically via @import "path/to/your/tailwind.css". This opt-in approach ensures no accidental overwrites of your carefully tuned system.

Can I use Hallmark with a design system created in Figma or Tokens Studio?

Yes. Export your tokens as DTCG-format JSON, then reference that file in your design.md or let Hallmark generate the DTCG tokens.json export for bidirectional sync. The DTCG format in references/export-formats.md is specifically designed for this interoperability.

What happens if I modify design.md after pages are already built?

Hallmark will apply the updated tokens to subsequent builds, and the audit verb will flag any existing pages that no longer match the locked system. You can then run hallmark redesign to propagate the changes across all pages, ensuring the entire site stays synchronized.

Is there a way to temporarily override the locked design system for a single page?

No. Once a design.md is present, the system is locked for consistency. This is intentional — the diversification rule is inverted precisely to prevent one-off deviations that erode design system integrity. To experiment with alternatives, rename or remove design.md temporarily, then restore it after testing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}