How Hallmark Preserves Existing Design Systems During the Pre‑flight Scan

Hallmark preserves existing design systems by detecting a design.md file at the project root, treating it as a locked authority that overrides automatic catalog selections, and caching scan results in .hallmark/preflight.json to avoid redundant overwrites.

When working with the Nutlope/hallmark repository, the pre-flight scan serves as the critical first step that determines whether to generate new design tokens or defer to an existing system. This non-intrusive process ensures that Hallmark never unintentionally overwrites deliberate design decisions, maintaining consistency across page generations by respecting manually created or previously generated design specifications.

Detection of the Locked Design System

Hallmark initiates the preservation logic by checking the project root for a design.md or DESIGN.md file before executing any automatic detection routines. According to the implementation in skills/hallmark/SKILL.md at line 153, if this file exists, Hallmark immediately loads it as the locked design system, treating its definitions—covering palette, typography, spacing, and component choices—as the authoritative source for all subsequent picks.

When Hallmark detects this file, it emits a notice to the user: "design.md detected at project root — this is a system-managed project. Reading the locked design system; subsequent picks defer to it." This behavior, documented at line 185 of skills/hallmark/SKILL.md, ensures complete override of any automatic catalog-based selection, preserving the integrity of the existing design system.

Cache Management and Invalidation Logic

To optimize performance while respecting project stability, Hallmark serializes pre-flight findings to .hallmark/preflight.json. The system reuses this cached data across subsequent runs unless specific invalidation conditions are met, as detailed in skills/hallmark/SKILL.md (lines 177-179).

The cache invalidation triggers include:

• File modification times: If package.json or any tailwind.config.* file has a newer modification time (mtime) than the cache file, Hallmark invalidates the cache and performs a fresh scan.
• Explicit user commands: When the user requests a refresh using commands like "refresh pre-flight" or "scan again", Hallmark bypasses the cache regardless of file timestamps.

This mechanism ensures that the pre-flight scan remains responsive to actual project changes without unnecessarily reprocessing unchanged codebases.

Respecting Existing Assets

Beyond design tokens, Hallmark extends its preservation logic to physical assets. As documented in skills/hallmark/references/hero-enrichment.md at line 30, if the user provides an image asset or a previously cached .hallmark/preflight.json exists, Hallmark uses the existing asset and never overwrites it with a placeholder. This prevents accidental destruction of curated visual content during the scan phase.

User-Controlled Bypass Options

Hallmark provides an escape hatch for scenarios requiring a completely fresh start. As implemented in skills/hallmark/SKILL.md at line 190, users can explicitly command Hallmark to ignore the existing project structure. When this option is invoked, the pre-flight step is completely bypassed, allowing Hallmark to proceed directly to the design generation phase without loading cached data or existing design.md configurations.

Implementation Details

The pre-flight logic follows a clear decision tree that prioritizes existing systems over automatic detection. The pseudocode below illustrates the workflow implemented in the Hallmark skill system:

// Pre-flight scan logic extracted from SKILL.md workflow
if (fs.existsSync('design.md') || fs.existsSync('DESIGN.md')) {
  // Load the locked design system as authoritative source
  const designSystem = yaml.load(fs.readFileSync('design.md', 'utf8'));
  console.log('design.md detected — reading locked design system.');
  // All subsequent design picks defer to `designSystem`
} else {
  // Execute normal pre-flight detection (tokens, tailwind, etc.)
  const findings = scanProject();
  // Persist to cache for future runs
  fs.writeFileSync('.hallmark/preflight.json', JSON.stringify(findings));
}

// Cache validation logic
const cacheStat = fs.statSync('.hallmark/preflight.json');
const pkgStat = fs.statSync('package.json');
const tailwindStat = fs.statSync('tailwind.config.js');

if (pkgStat.mtime > cacheStat.mtime || tailwindStat.mtime > cacheStat.mtime) {
  // Invalidate cache and trigger re-scan
  runPreflightScan();
}

This implementation ensures that Hallmark's pre-flight scan remains aware of, preserves, and defers to any existing design system, maintaining consistency and respecting the developer's previous work.

Summary

• Locked system detection: Hallmark checks for design.md at the project root and treats it as the authoritative design authority, overriding automatic selections.
• Intelligent caching: Scan results are stored in .hallmark/preflight.json and reused unless package.json or tailwind.config.* files change, or the user explicitly requests a refresh.
• Asset protection: Existing image assets and cached data are never overwritten with placeholders during the pre-flight phase.
• User override: The pre-flight scan can be completely bypassed via user command to start fresh without loading existing configurations.

Frequently Asked Questions

What triggers Hallmark to re-scan the project instead of using cached data?

Hallmark re-scans the project when the modification time of package.json or any tailwind.config.* file is newer than the .hallmark/preflight.json cache file, or when the user explicitly issues a "refresh pre-flight" command. This ensures the design system reflects the current project state without unnecessary processing.

Can I manually create a design.md file to lock my design system?

Yes, you can manually create a design.md or DESIGN.md file at the project root. Hallmark will detect this file during the pre-flight scan and treat it as a locked design system, using its contents as the authoritative source for all subsequent design decisions and overriding any automatic catalog selections.

How does Hallmark handle existing image assets during the pre-flight scan?

Hallmark respects existing image assets by checking for supplied files or cached data in .hallmark/preflight.json. According to the implementation in skills/hallmark/references/hero-enrichment.md, the system uses existing assets and never overwrites them with placeholders, ensuring your curated visual content remains intact.

What happens if I want Hallmark to ignore my existing design system?

You can command Hallmark to ignore the existing project structure, which causes the pre-flight step to be completely bypassed. In this mode, documented at line 190 of skills/hallmark/SKILL.md, Hallmark proceeds directly to the design generation phase without reading design.md or loading cached pre-flight data.

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