What Information Does Hallmark’s Pre-Flight Scan Collect? Complete Guide to Design Signals

Hallmark’s pre-flight scan gathers six categories of design signals—design system presence, font stacks, color palettes, motion libraries, spacing scales, and framework detection—to build a cached "design fingerprint" stored in .hallmark/preflight.json.

The pre-flight scan is the first operation Hallmark runs when initializing a design workflow against the Nutlope/hallmark repository. According to skills/hallmark/SKILL.md and supporting documentation in skills/hallmark/references/hero-enrichment.md, this inspection creates a lightweight inventory of existing project assets, enabling Hallmark to preserve established conventions while identifying gaps that need to be filled.

The Six Core Design Signals

Hallmark inspects specific files and dependencies to extract six distinct signal sources. These findings determine which design assets exist and which defaults to apply.

Design System Detection

The scan checks for a locked design.md (or DESIGN.md) file at the project root. If this file exists, Hallmark treats it as the authoritative design system and skips most other detections, deferring to the documented specifications rather than inferred signals.

Font Stack Analysis

Hallmark parses package.json and configuration files to identify installed fonts. The scan detects:

• Next.js fonts: next/font imports and @fontsource/* packages
• Expo fonts: expo-google-fonts usage
• Geist: Explicit Geist font installations
• Google Fonts: <link rel="stylesheet"> references in HTML
• Tailwind configuration: theme.extend.fontFamily definitions in tailwind.config.{js,ts}
• CSS imports: @import statements referencing font families

This detection identifies available typefaces like Geist, Inter, or Space Grotesk.

Palette Extraction

The color signal inspection captures existing color tokens through multiple sources:

• CSS custom properties: OKLCH, HSL, and hex values defined in :root
• Tailwind extensions: theme.extend.colors in the Tailwind config
• Token files: DTCG-formatted files such as tokens.json or design-tokens.{json,yaml}

The scan determines whether the project uses standard CSS variables or maintains a formal Design Tokens Community Group (DTCG) token structure.

Micro-Interaction Stance

Hallmark flags the project's motion preferences by scanning package.json dependencies for animation libraries. The scan identifies:

• framer-motion
• gsap
• motion
• lenis
• lottie-react
• @react-spring/*
• auto-animate

When any of these libraries are present, Hallmark marks the project as "motion-on" and adjusts generated code to respect the existing animation stack.

Spacing Scale Detection

The scan identifies the project's baseline spacing system by inspecting:

• Tailwind configuration: theme.extend.spacing overrides
• CSS custom properties: Variables following the --space-* naming pattern
• Grid scales: Detection of 4-point or 8-point spacing systems

This ensures generated components align with the established spatial rhythm.

Framework Identification

Hallmark determines the primary framework to honor framework-specific conventions. The scan checks package.json dependencies for:

• Next.js: next
• Astro: astro
• Vue: vue
• Svelte/SvelteKit: svelte or @sveltejs/kit
• Remix: @remix-run/*

If no framework is detected, Hallmark falls back to vanilla HTML generation.

Persistence and Caching Mechanisms

The pre-flight scan writes findings once to .hallmark/preflight.json according to skills/hallmark/SKILL.md. Hallmark reuses this cached data on subsequent runs unless:

• The user explicitly requests a refresh
• package.json modification times are newer than the cache
• tailwind.config.* files have been updated since the last scan

This caching strategy prevents redundant file system inspections while ensuring the scan responds to dependency changes.

Edge Cases and Conflict Reporting

When Hallmark encounters a bare repository with no detectable signals, it emits a single line to standard output: "No pre-flight signals — proceeding with full Hallmark stack."

The scan also implements conflict detection. When contradictory signals appear—such as a motion library installed but no motion.div usage detected in source files—Hallmark flags these conflicts in the pre-flight output, alerting developers to potential configuration mismatches.

Accessing Pre-Flight Data

Developers can trigger the scan manually and inspect the generated cache:

# Trigger pre-flight scan from project root

hallmark scan

The resulting .hallmark/preflight.json follows this structure:

{
  "designMd": false,
  "fontStack": ["Geist", "Space Grotesk"],
  "palette": {
    "customProperties": true,
    "tailwindTokens": true,
    "tokensFile": "tokens.json"
  },
  "motionStance": "motion-on",
  "spacingScale": "4-pt",
  "framework": "Next.js"
}

Subsequent Hallmark commands automatically reference this cache:

hallmark build

# Output: "Pre-flight cached (last scan: 2026-04-30). Say 'refresh pre-flight' to re-scan."

Summary

• Hallmark's pre-flight scan inspects six signal categories: design system files, fonts, colors, motion libraries, spacing scales, and frameworks.
• Findings are cached in .hallmark/preflight.json and reused until dependencies change or a refresh is requested.
• The presence of design.md at the project root overrides other signals, establishing an authoritative design system.
• Motion detection scans for libraries like framer-motion and gsap to determine animation stance.
• Edge cases result in fallback to the full Hallmark stack, while conflicting signals trigger explicit warnings.

Frequently Asked Questions

How do I force Hallmark to re-run the pre-flight scan?

Request a refresh explicitly or modify package.json or tailwind.config.* files. The scan compares modification timestamps against the cache and automatically invalidates stale data when these core configuration files change.

What happens if my project uses a custom design system file?

If Hallmark detects design.md or DESIGN.md at the project root, it treats this file as the authoritative design specification. The scan skips most other detections and defers to the documented system, ensuring Hallmark respects your established design language.

Does Hallmark detect CSS-in-JS libraries for styling signals?

The current pre-flight scan focuses on Tailwind configurations, CSS custom properties, and standard token files. While it inspects package.json for motion and font dependencies, CSS-in-JS specific styling systems outside of Tailwind configurations are not explicitly cataloged in the current implementation.

Where does Hallmark store pre-flight scan results?

The scan writes a JSON representation of all detected signals to .hallmark/preflight.json in the project root. This file persists between runs and serves as the cached "design fingerprint" that subsequent Hallmark commands reference to avoid redundant file system inspections.

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