# How Hallmark Scans an Existing Design System Before Generating New UI: The design.md Detection Flow > Learn how Hallmark scans your design.md file to detect your existing design system before generating new UI, ensuring consistency and adherence to your defined constraints. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-18 --- **Hallmark detects a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), Hallmark specifically looks for [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)) in the project root. If the file is detected, Hallmark logs a confirmation message: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) is present, these tokens are sourced directly from the locked system as defined in [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/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. ```bash # 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md). This flow creates a new [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file containing the current token set and exports [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) for portable reuse, effectively establishing a new canonical source for future runs. ```bash # 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) containing CSS custom properties derived from the scanned system. - Users can generate a new [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) file at the project root containing CSS custom properties for colors, fonts, spacing, and other values. When a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file containing the current build's token set and exports [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) for portable reuse, as documented in [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).