# Can Hallmark Integrate with Existing Design Systems?

> Learn how Hallmark integrates with existing design systems by using a design.md file as your single source of truth for efficient page builds.

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

---

**Hallmark integrates with existing design systems by reading a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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](https://github.com/Nutlope/hallmark) repository.

## How Hallmark Detects and Locks a Design System

The integration flow centers on a single file: [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (case-insensitive, also accepts [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)). According to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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.

```python

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), Tailwind v4 `@theme`, DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) that references your current token files:

```markdown

# 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`](https://github.com/Nutlope/hallmark/blob/main/verbs/redesign.md), this flow guarantees that subsequent runs simply read the existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/export-formats.md), Hallmark emits tokens in four portable formats:

| Format | Use Case |
|--------|----------|
| [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | Universal CSS custom properties |
| Tailwind v4 `@theme` | Next-generation Tailwind projects |
| DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/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:

```html
<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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file as the source of truth.
- The lock is **opt-in**: create [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or let Hallmark generate the DTCG [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json) export for bidirectional sync. The DTCG format in [`references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/references/export-formats.md) is specifically designed for this interoperability.

### What happens if I modify [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) temporarily, then restore it after testing.