How Hallmark Scans an Existing Design System Before Generating New UI: The design.md Detection Flow

Hallmark detects a design.md file at the project root to lock in the design system, forcing all subsequent UI generation to defer to the existing constraints rather than random selection.

Hallmark is an AI-powered interface generation tool that preserves visual consistency by treating a single markdown file as the source of truth. When operating on a codebase, the Nutlope/hallmark repository checks for a locked design specification before making any generative decisions, ensuring new components adhere to established patterns.

Detection Phase: Locating the design.md Source File

Root-Level File Presence Check

When a Hallmark run starts, it performs a file-presence check at the repository root to determine if the project follows a system-managed workflow. According to skills/hallmark/SKILL.md, Hallmark specifically looks for design.md (or DESIGN.md) in the project root.

If the file is detected, Hallmark logs a confirmation message:

design.md detected at project root — this is a system-managed project.
Reading the locked design system; subsequent picks defer to it.

This detection immediately switches Hallmark from stochastic generation mode to deterministic, constraint-based generation.

Loading the Locked Design System into State

Parsing and Deferring to Canonical Values

Once detected, the contents of design.md are parsed and loaded into Hallmark’s internal state. All subsequent generative decisions—including genre, theme, typography, spacing, motion, and CTA voice—are then deferred to the values defined in this file instead of being randomly generated.

This routing ensures that any new UI elements, components, or page structures inherit the exact specifications of the existing design system.

Redesign Workflows and Multi-Page Consistency

Reading the System Before Page-Level Generation

When a user invokes the redesign verb, Hallmark enforces a strict read-before-write policy. As documented in skills/hallmark/references/verbs/redesign.md, the system first reads the locked design system before applying any macro-structure or page-level picks.

This read-lock-then-generate sequence guarantees consistency across multiple pages of the same product, preventing style drift between different sections or iterations of the application.

Token Export and CSS Generation

Emitting tokens.css from Scanned Values

Regardless of whether a design system already exists, Hallmark always emits a tokens.css file at the project root. This file contains CSS custom properties for colors, fonts, spacing, and other design primitives.

When a design.md is present, these tokens are sourced directly from the locked system as defined in skills/hallmark/references/export-formats.md. This ensures that the exported CSS variables align perfectly with the scanned design system, allowing any new UI to reference the same token values.

# Run Hallmark on a project that already has a design system

hallmark run

# Hallmark will automatically detect and load the design system

# Output (example):

#   design.md detected at project root — this is a system-managed project.

#   Reading the locked design system; subsequent picks defer to it.

Opt-In Flow for Design System Locking

Creating design.md from Current Build State

If no design.md exists, Hallmark provides an opt-in mechanism to lock the current build’s design system into a new file. By prompting Hallmark with phrases such as “lock the system” or “give me a design.md”, users trigger the lock-the-system flow described in skills/hallmark/references/design-md.md.

This flow creates a new design.md file containing the current token set and exports tokens.css for portable reuse, effectively establishing a new canonical source for future runs.

# Explicitly ask Hallmark to lock the current system into a design file

hallmark lock design

# Hallmark creates/updates `design.md` with the current token set

# and writes `tokens.css` for portable reuse

Summary

• Hallmark scans for design.md at the project root to detect a locked design system.
• Upon detection, the system parses the file and routes all generative decisions through its constraints.
• The redesign workflow always reads the locked system before applying page-level changes.
• Hallmark exports tokens.css containing CSS custom properties derived from the scanned system.
• Users can generate a new design.md via the lock-the-system flow when none exists.

Frequently Asked Questions

What filename does Hallmark scan for to detect an existing design system?

Hallmark scans for design.md (or DESIGN.md) located at the project root. When found, it logs a confirmation message and treats the project as system-managed, deferring all subsequent generation to the values defined within that file according to skills/hallmark/SKILL.md.

How does Hallmark use the scanned design system during a redesign?

When executing the redesign verb, Hallmark first reads the locked design system from design.md before applying any macro-structure or page-level picks. This ensures consistency across multiple pages of the same product, as specified in skills/hallmark/references/verbs/redesign.md.

Where does Hallmark export design tokens after scanning the system?

Regardless of whether a design system exists, Hallmark emits a tokens.css file at the project root containing CSS custom properties for colors, fonts, spacing, and other values. When a design.md is present, these tokens are sourced directly from the locked system.

Can Hallmark create a design system file if my project doesn't have one?

Yes. If no design.md exists, you can invoke the lock-the-system flow by prompting Hallmark with phrases like "lock the system" or "give me a design.md". This creates a new design.md file containing the current build's token set and exports tokens.css for portable reuse, as documented in skills/hallmark/references/design-md.md.

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