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

> Discover what Hallmark's pre-flight scan collects: design system presence, fonts, colors, motion, spacing, and framework detection. Get your design fingerprint.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: tutorial
- Published: 2026-08-08

---

**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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and supporting documentation in [`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) according to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Hallmark reuses this cached data on subsequent runs unless:

- The user explicitly requests a refresh
- [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash

# Trigger pre-flight scan from project root

hallmark scan

```

The resulting [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) follows this structure:

```json
{
  "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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) and reused until dependencies change or a refresh is requested.
- The presence of [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](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 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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.