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

> Discover how Hallmark's pre-flight scan automatically detects design signals in your codebase, establishing a baseline for UI component generation. Learn its importance today.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-21

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) for subsequent runs.

### Priority 1: Locked Design Systems via design.md

If [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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.

```bash

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

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](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, 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) lines 57–58.