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

> Learn how Hallmark preserves your design system during pre-flight scans. It uses design.md as an authority and caches results to prevent overwrites.

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

---

**Hallmark preserves existing design systems by detecting a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/design.md) or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md) file before executing any automatic detection routines. According to the implementation in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 177-179).

The cache invalidation triggers include:

- **File modification times**: If [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/hero-enrichment.md) at line 30, if the user provides an image asset or a previously cached [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) and reused unless [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) or any `tailwind.config.*` file is newer than the [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](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. 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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json). According to the implementation in [`skills/hallmark/references/hero-enrichment.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), Hallmark proceeds directly to the design generation phase without reading [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or loading cached pre-flight data.