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

> Discover how Hallmark's pre-flight scan analyzes six signal sources from design files to dependencies, ensuring code adheres to constraints before generation. Learn more!

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-07-19

---

**Hallmark's pre-flight scan inspects six fixed signal sources—ranging from [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) to framework dependencies—to detect existing design constraints before generating any code, caching results in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.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](https://github.com/Nutlope/hallmark) source code documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) Override

The scan first checks for a file named [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json). On subsequent runs, Hallmark consults this cached JSON for speed, bypassing the full scan unless the source files ([`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) or `tailwind.config.*`) have newer modification timestamps than the cache.

The persistence rules are documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 77-81).

```bash

# 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:

```json
// .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:

```bash
hallmark refresh pre‑flight

```

This ignores [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/design.md) contradicts my Tailwind config?

**[`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) always wins.** According to the scan logic in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/tokens.json), [`design-tokens.json`](https://github.com/Nutlope/hallmark/blob/main/design-tokens.json), or [`design-tokens.yaml`](https://github.com/Nutlope/hallmark/blob/main/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.