How Hallmark's Pre-Flight Scan Works: Automatic Design System Detection

Hallmark's pre-flight scan automatically analyzes your codebase for six critical design signals—ranging from locked design specifications to motion preferences—to establish a grounded design baseline before generating UI components.

The Nutlope/hallmark repository implements an intelligent pre-flight scan as Step 0 of its design workflow. This mandatory inspection phase discovers existing styling decisions in your project, ensuring that subsequent AI-generated components respect your established design system rather than overriding it with conflicting defaults.

How the Pre-Flight Scan Detects Design Signals

According to the source definition in skills/hallmark/SKILL.md, Hallmark executes a six-phase inspection in strict priority order. The scan emits a concise pre-flight findings block and caches the results in .hallmark/preflight.json for subsequent runs.

Priority 1: Locked Design Systems via design.md

If design.md (or DESIGN.md) exists at your project root, Hallmark treats this file as a locked design system that overrides all other signals. The scanner immediately defers to this specification and skips heuristic detection for remaining categories, ensuring explicit design contracts take precedence over inferred patterns.

Signals 2–6: Automatic Discovery

When no root-level design document is present, Hallmark proceeds to analyze dependency manifests and source files for five additional signal categories:

Font Stack Detection examines package.json for font-related dependencies such as next/font, @fontsource/*, expo-google-fonts, or geist. It also inspects HTML files for <link rel="stylesheet"> tags referencing external fonts, tailwind.config.{js,ts} for theme.extend.fontFamily declarations, and CSS @import statements pulling Google Fonts.

Palette Extraction identifies color definitions through OKLCH, HSL, or hexadecimal values inside :root CSS blocks. The scanner also reads Tailwind's theme.extend.colors, token files like tokens.json or design-tokens.{json,yaml}, and any Design Tokens Community Group (DTCG) compatible token files.

Micro-Interaction Stance determines motion philosophy by scanning package.json for animation libraries. Presence of framer-motion, gsap, motion, lenis, lottie-react, @react-spring/*, or auto-animate marks the project as motion-on; absence defaults the stance to motion-cut, ensuring animations respect performance preferences.

Spacing Scale Analysis reads Tailwind configuration for theme.extend.spacing values, CSS custom properties matching the --space-* pattern, or explicit 4-pt/8-pt grid scales defined in stylesheets.

Framework Identification parses package.json dependencies to determine the primary framework: next resolves to Next.js, astro to Astro, vue to Vue, svelte or @sveltejs/kit to Svelte/SvelteKit, and @remix-run/* to Remix. If no framework dependencies are detected, Hallmark defaults to vanilla HTML.

Caching and CLI Usage

After completing the six-phase inspection, Hallmark serializes the findings to .hallmark/preflight.json and reuses this cache on subsequent invocations to minimize filesystem I/O. You can force a fresh scan using the --refresh-preflight flag.

# Initial scan (creates .hallmark/preflight.json)

hallmark

# Force re-scan ignoring cache

hallmark --refresh-preflight

The CLI outputs a structured findings block that maps each detected signal to its source location:

Pre-flight findings:
· design.md: not found
· Font stack: Geist + Geist Mono (next/font, package.json L23)
· Palette: OKLCH custom properties (app/globals.css :root)
· Motion: framer-motion 11 installed (package.json L41)
· Spacing: Tailwind extend.spacing (4-pt scale, tailwind.config.ts L18)
· Framework: Next.js 15 (app router)

Why the Pre-Flight Scan Is Important

The pre-flight scan prevents design system fragmentation by grounding Hallmark's generative decisions in existing constraints rather than assumptions. By detecting your current typography, color space, motion preferences, and spacing grid from actual source files—specifically as implemented in Nutlope/hallmark—the tool ensures that generated components integrate seamlessly without requiring manual style reconciliation. This detection phase also establishes whether your project follows a strict design contract via design.md, enabling deterministic, repeatable UI generation across multiple runs.

Summary

• Hallmark's pre-flight scan inspects six signal categories in priority order, starting with a locked design.md check.
• The scan detects fonts via package dependencies and Tailwind config, colors via CSS variables and token files, motion via library presence, spacing via 4-pt/8-pt scales, and frameworks via dependency names.
• Findings are cached in .hallmark/preflight.json for performance, with --refresh-preflight available to invalidate the cache.
• This Step 0 inspection ensures generated components respect your existing design system, preventing style conflicts and maintaining visual consistency.

Frequently Asked Questions

What happens if my project has a design.md file?

If Hallmark detects design.md or DESIGN.md at the project root, it treats this file as a locked design system and immediately halts heuristic detection for other signals. All subsequent generation respects the specifications within this document, overriding any inferred constraints from package.json or CSS files.

How do I force Hallmark to re-scan my project?

Run hallmark --refresh-preflight to invalidate the cached .hallmark/preflight.json and trigger a fresh inspection of all six signal categories. This is useful after adding new font dependencies, motion libraries, or design token files.

Which motion libraries trigger the "motion-on" stance?

Hallmark marks projects as motion-on if package.json contains any of the following: framer-motion, gsap, motion, lenis, lottie-react, @react-spring/*, or auto-animate. If none are present, the scan defaults to motion-cut, signaling Hallmark to avoid animation-heavy generation patterns.

Does Hallmark recognize CSS custom properties for spacing?

Yes. The scan identifies spacing scales through CSS custom properties matching the --space-* pattern, Tailwind's theme.extend.spacing configuration, or standard 4-pt/8-pt grid definitions found in your stylesheet, as referenced in skills/hallmark/SKILL.md lines 57–58.

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