How Hallmark's Pre-Flight Scan Works Across Six Signal Sources

Hallmark's pre-flight scan inspects six fixed signal sources—ranging from design.md to framework dependencies—to detect existing design constraints before generating any code, caching results in .hallmark/preflight.json for subsequent runs.

Before generating any design code, Hallmark performs a pre-flight scan to understand what already exists in your project. According to the Nutlope/hallmark source code documented in skills/hallmark/SKILL.md, this scan examines six distinct signal sources in a strict sequence, ensuring that existing typography, color palettes, and framework conventions are preserved rather than overwritten.

The Six Signal Sources (in Order)

The scan follows a fixed priority order defined in the core skill documentation. Each source informs a specific design discipline, with findings emitted as a concise block before any generation begins.

0. The design.md Override

The scan first checks for a file named design.md or DESIGN.md at the project root. If present, it is treated as a locked design system that overrides all other signals. This file steers genre, theme, typography, spacing, and motion decisions, causing Hallmark to ignore conflicting signals from other sources.

1. Font Stack Detection

Hallmark detects the base type-family by inspecting several locations:

• package.json dependencies: next/font, @fontsource/*, expo-google-fonts, or geist
• HTML/layout files: <link rel="stylesheet" href="…fonts.googleapis.com/…"> tags
• Tailwind config: tailwind.config.{js,ts} for theme.extend.fontFamily
• CSS imports: Any @import of Google fonts

This detection ensures Hallmark reuses existing families like Geist, Inter, or JetBrains Mono rather than inventing conflicting alternatives.

2. Color Palette Extraction

The scan searches for color definitions in:

• :root CSS blocks: OKLCH, HSL, or hex values
• Tailwind config: theme.extend.colors
• Token files: tokens.json or design-tokens.{json,yaml}

These values provide the color foundation (paper, accent, ink) that Hallmark references via CSS tokens such as var(--color-…).

3. Micro-Interaction Stance

Hallmark checks package.json for motion libraries to determine animation philosophy:

• Motion libraries: framer-motion, gsap, motion, lenis, lottie-react, @react-spring/*, auto-animate

If any are found, the project is marked "motion-on"; otherwise it is "motion-cut" and Hallmark avoids adding motion primitives.

4. Spacing Scale Analysis

The scan identifies spacing conventions through:

• Tailwind: theme.extend.spacing
• CSS custom properties: Variables matching --space-*
• Explicit scales: Declarations using 4-pt or 8-pt grids

This drives the spacing token block (typically tokens.css) to ensure consistent component spacing.

5. Framework Identification

Finally, Hallmark detects the development environment by checking:

• Dependencies: next, astro, vue, svelte, @remix-run/*
• Config files: next.config.js, astro.config.mjs, etc.

This determines which framework conventions Hallmark must follow, such as Next.js App Router patterns versus vanilla HTML structures.

Scan Execution and Caching

After inspecting all six sources, Hallmark emits a pre-flight findings block to the console and writes the results to .hallmark/preflight.json. On subsequent runs, Hallmark consults this cached JSON for speed, bypassing the full scan unless the source files (package.json or tailwind.config.*) have newer modification timestamps than the cache.

The persistence rules are documented in skills/hallmark/SKILL.md (lines 77-81).

# Run Hallmark with automatic pre-flight scan

hallmark

Sample output:

Pre‑flight findings:
· 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)

Hallmark will preserve: font stack, palette, spacing scale.
Hallmark will introduce: macrostructure, microinteraction discipline,
slop‑test gates, hero enrichment recipe.

The generated cache file contains structured data:

// .hallmark/preflight.json
{
  "fontStack": "Geist + Geist Mono",
  "palette": "OKLCH custom properties",
  "motion": "on",
  "spacing": "4‑pt scale",
  "framework": "Next.js 15",
  "timestamp": "2026‑04‑30T12:45:02Z"
}

Forcing a Fresh Scan

To invalidate the cache and re-run the six-source inspection—such as after adding new dependencies—use the refresh command:

hallmark refresh pre‑flight

This ignores .hallmark/preflight.json, re-executes the full scan, and updates the cache with current signal states.

Summary

• Hallmark's pre-flight scan runs six signal detection routines in a fixed order (0-5) before any design generation.
• Signal 0 (design.md) acts as a master override, while signals 1-5 detect fonts, colors, motion libraries, spacing scales, and frameworks.
• Findings are persisted to .hallmark/preflight.json and reused on subsequent runs unless source files change.
• Use hallmark refresh pre-flight to manually trigger a re-scan and update the cache.

Frequently Asked Questions

What takes precedence if design.md contradicts my Tailwind config?

design.md always wins. According to the scan logic in skills/hallmark/SKILL.md, signal source 0 is treated as a locked design system that overrides all other detected signals, including font stacks and color palettes defined in tailwind.config.*.

How does Hallmark know if my project uses motion libraries?

Hallmark specifically checks package.json for known animation packages like framer-motion, gsap, lenis, or @react-spring/*. If any are listed in dependencies or devDependencies, the scan marks the project as "motion-on" and Hallmark will generate animation-compatible code.

Can I disable the pre-flight cache?

While there is no configuration flag to disable caching entirely, you can force a fresh scan at any time by running hallmark refresh pre-flight. This deletes the existing .hallmark/preflight.json and rebuilds it from current source files.

Which token file formats does the palette scan recognize?

The scan looks for color tokens in tokens.json, design-tokens.json, or design-tokens.yaml at the project root. It also extracts OKLCH, HSL, and hex values from any CSS file containing :root blocks or from Tailwind's theme.extend.colors configuration.

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