Skip to content

Anti-AI-slop design skill for Claude Code, Cursor, and Codex.

CSS

Skill · opt-in design.md lock-the-system flow

Youssef6020d445edbf
diff --git a/README.md b/README.md
index 09a7a52..3500c41 100644
--- a/README.md
+++ b/README.md
@@ -114,6 +114,7 @@ Each page is its own self-contained HTML + CSS — no shared theme, no shared la
- **SaaS page sequence.** Hero → social proof → features → testimonials → pricing → FAQ → CTA → footer. Real prices, not "contact sales for pricing." Specific testimonials with role + company.
- **Wordmark may use a different display face.** A Geist-bodied SaaS page can set its wordmark in Fraunces. Same-family collapse on Bento / Stat-Led / Workbench / Marquee Hero is the new "un-branded" tell.
- **`study` extracts DNA, not pixels.** Refusal heuristics, type-role vocabulary (no font ID guessing), confirmation step before any code. Three worked examples in [`docs/study-examples.md`](docs/study-examples.md).
+- **Opt-in `design.md` lock-the-system flow.** Iterate freely on the first builds; when the system is settled, say *"lock the system"* (or *"give me a design.md"*) and Hallmark extracts the build's tokens + voice into a portable design system at the project root. From that point on every Hallmark run defers to it, the diversification rule inverts to consistency, and the file becomes the single source of truth for scaling the design across a real app. Phrase-triggered, never auto-emitted — no churn across iterations. See [`skill/references/design-md.md`](skill/references/design-md.md).
---
diff --git a/skill/SKILL.md b/skill/SKILL.md
index f59ebae..77862eb 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -359,6 +359,7 @@ The non-negotiables live in [`references/`](references/). **Be precise about wha
- [`custom-craft.md`](references/custom-craft.md) — load only when an enrichment archetype requires construction (CSS art, SVG, declarative animation, etc.).
- [`assets.md`](references/assets.md) — load only when an enrichment archetype needs an external asset (icons, illustration, photography, Lottie).
- [`custom-theme.md`](references/custom-theme.md) — load only when Step 2.6 routes to custom.
+- [`design-md.md`](references/design-md.md) — load only when the user explicitly asks Hallmark to lock the system into a portable file (phrases: *"lock the system"*, *"give me a design.md"*, *"make this portable"*, etc.). Opt-in; never fires on a vanilla build.
**Load-at-the-end:**
- [`slop-test.md`](references/slop-test.md) — load at Step 7 (the gate-check after build), not earlier.
@@ -403,7 +404,7 @@ Before emitting any code, output a tight summary of what you're about to ship. T
- **Diversification** · differs from Pastel on display style + accent hue
```
-**Six required bullets, one optional:**
+**Six required bullets, one optional, plus a CTA line:**
1. **Macrostructure** — the named pick from [`macrostructures.md`](references/macrostructures.md).
2. **Theme** — for catalog: name + one-line palette summary (paper colour band · accent hue · display style). For custom: `custom (vibe: "<4–8 words>" · paper oklch(<L%> <C> <H>) · accent oklch(<L%> <C> <H>) <one-word hue label> · <display face> + <body face>)`.
@@ -413,6 +414,12 @@ Before emitting any code, output a tight summary of what you're about to ship. T
6. **Slop test** — `65 / 65 ✓` if all gates pass, or `N / 65 — fails: <gate numbers>` if any are open. Run the slop test BEFORE writing this row; the slop test is Step 7.
7. **Diversification** *(optional, only when `.hallmark/log.json` has prior entries)* — what axes differ vs the previous run.
+**Then one quiet CTA line, italicised, after the bullets:**
+
+> *System portable? Say `lock the system` to extract this build's tokens + voice into a `design.md`.*
+
+Skip the CTA line when (a) the build is component-scope, or (b) `design.md` already exists at the project root (the system is already locked). See [`design-md.md`](references/design-md.md) for the full opt-in flow.
+
**Three more sample preview blocks** for the model to imitate, varied across macrostructure types:
*Long Document (editorial, motion-cut):*
@@ -481,6 +488,7 @@ Always:
- **Append to project memory.** After you write the stamp, update (or create) `.hallmark/log.json` at the project root. Append a new entry at the **front** of the array: `{ "date": "<YYYY-MM-DD>", "macrostructure": "<name>", "theme": "<name>", "enrichment": "<E# name or 'none'>", "brief": "<one-line summary>" }`. **Custom entries** also carry `"theme": "custom"` plus `"theme_axes": "<paper-band> / <display-style> / <accent-hue>"` and an optional `"vibe": "<4–8 words>"` — see [`custom-theme.md`](references/custom-theme.md) § F. Trim the file to the last 20 entries (rotate the oldest off). Create `.hallmark/` and the file if they don't exist; respect any existing `.gitignore` (the user may or may not want this committed). This file is what Step 2.5 reads on the next run.
- **Always emit `tokens.css`.** After writing the page CSS, also write `tokens.css` at the project root containing every `--color-*`, `--font-*`, `--space-*`, `--text-*`, `--ease-*`, `--dur-*`, `--rule-*`, and `--radius-*` token used in the build. The page CSS imports `tokens.css` (or, on framework projects, the project's existing entry-point includes it) — the page CSS must reference tokens by name, never inline raw values. Even single-page builds get a `tokens.css`. This is what makes the design system portable to the next project. Load [`export-formats.md`](references/export-formats.md) at this point only when the project warrants additional formats — see below.
- **Multi-format exports on `design.md` projects.** If a `design.md` exists at the project root (a system-managed project), append all four export formats — `tokens.css`, Tailwind v4 `@theme`, DTCG `tokens.json`, shadcn/ui CSS variables — into `design.md`'s `## Exports` section. Load [`export-formats.md`](references/export-formats.md) for the canonical mapping from Hallmark tokens to each format. Single-page projects skip this step (they get only `tokens.css`).
+- **Opt-in `design.md` (lock-the-system flow).** If the user explicitly asks Hallmark to lock the build's design system into a portable file (phrases: *"lock the system"*, *"give me a design.md"*, *"make this portable"*, etc.), load [`design-md.md`](references/design-md.md) and follow it. Page-scope only; component-scope skips. **The default verb does NOT auto-emit `design.md`** — users iterate freely first, then ask for it once the system is settled. If `design.md` already exists, refresh its `## Exports` section instead of overwriting. The Step 5 preview block carries a one-line CTA surfacing this option after every page-build.
### 7. The slop test
diff --git a/skill/references/design-md.md b/skill/references/design-md.md
new file mode 100644
index 0000000..a965d17
--- /dev/null
+++ b/skill/references/design-md.md
@@ -0,0 +1,100 @@
+# design.md — opt-in portable design system
+
+Loaded by [`SKILL.md`](../SKILL.md) Step 6 ONLY when the user explicitly asks Hallmark to lock the current build's design system into a portable file. The default verb does NOT auto-emit `design.md`. The user iterates freely until they say the system is settled, then asks for it.
+
+## Triggers (phrase-only — no new verb)
+
+Fire ONLY when the user says one of:
+
+- *"lock the system"* / *"lock the design system"*
+- *"give me a design.md"* / *"write a design.md"*
+- *"extract this to a design system"* / *"extract the tokens"*
+- *"make this portable"*
+- *"I want to use this in another project"*
+
+For everything else — including the default build, the redesign verb on a single page, and free iteration on the same brief — skip. The single-page redesign and default verb stay token-portable via `tokens.css`; `design.md` is the explicit lock-in step.
+
+## Scope
+
+- **Page-builds only.** Skip on component-scope — a single component is too small to be a system.
+- **Multi-page redesign keeps existing behaviour.** `hallmark redesign --multi-page` produces the heavyweight `design.md` per [`verbs/redesign.md`](verbs/redesign.md) § Multi-page flow. That flow already implies a locked system, so the rule there is unchanged.
+- **No-overwrite policy.** If `design.md` already exists at the project root, do NOT overwrite. Refresh its `## Exports` section instead and emit one line: *"design.md detected — refreshed Exports, system unchanged."*
+
+## CTA — surface the offer in the Step 5 preview
+
+After every default + redesign page-build, append one quiet line at the bottom of the preview block:
+
+> *System portable? Say `lock the system` to extract this build's tokens + voice into a `design.md`.*
+
+Skip the CTA when (a) the build is component-scope, or (b) `design.md` already exists in the project (system is already locked).
+
+## Format (the tight version)
+
+Write the file at the project root. Match the project's case convention (`design.md` or `DESIGN.md`). Target ~45 lines — enough to seed a real app, not so much that it becomes a wiki to maintain. The format:
+
+````markdown
+# Design — <Project name>
+
+Locked design system. Future Hallmark runs read this file first; pages defer
+to it. Amend intentionally — the file is the rule.
+
+## System
+- Genre · <editorial / modern-minimal / atmospheric / playful>
+- Macrostructure · <name>
+- Theme · <catalog: NAME · or · custom (vibe: "<4–8 words>")>
+- Axes · <paper-band> / <display-style> / <accent-hue>
+
+## Tokens (canonical · `tokens.css` is the source of truth)
+```css
+:root {
+ --color-paper: oklch(<L> <C> <H>);
+ --color-paper-2: oklch(<L> <C> <H>);
+ --color-ink: oklch(<L> <C> <H>);
+ --color-ink-2: oklch(<L> <C> <H>);
+ --color-rule: oklch(<L> <C> <H>);
+ --color-accent: oklch(<L> <C> <H>);
+ --color-accent-ink: oklch(<L> <C> <H>);
+ --color-focus: oklch(<L> <C> <H>);
+
+ --font-display: "<face>", ...;
+ --font-body: "<face>", ...;
+ --font-mono: "<face>", ...;
+
+ /* 4-pt spacing scale, named: --space-3xs … --space-4xl. See tokens.css. */
+ /* Type scale, 1.25 (major-third) ratio: --text-xs … --text-display. */
+
+ --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+ --dur-fast: 180ms; --dur-base: 240ms; --dur-slow: 320ms;
+
+ --radius-card: <px>; --radius-pill: <px>; --radius-input: <px>;
+}
+```
+
+## CTA voice
+- Primary · <fill colour> · <radius> · <padding rhythm>
+- Secondary · <outline / ghost> · <same radius>
+
+## Motion stance
+- <silent · 1–2 reveal primitives · motion-cut>
+- Reduced-motion fallback · ≤150 ms opacity crossfade.
+
+## Exports
+`tokens.css` (in this project) is the source of truth. For Tailwind v4
+`@theme`, DTCG `tokens.json`, or shadcn/ui CSS variables, ask *"extend
+design.md with Tailwind exports"* (or the format you want) — Hallmark will
+append them per [`export-formats.md`](skill/references/export-formats.md).
+````
+
+State the picks aloud BEFORE writing the file. *"Genre: editorial. Macrostructure: Long Document. Theme: catalog Editorial. Locking this as the project's system."* Then write.
+
+## After the file is written
+
+Once `design.md` exists, [`SKILL.md`](../SKILL.md) Step 0's pre-flight scan detects it on every subsequent run. From that point on:
+
+- All future Hallmark runs READ `design.md` first; subsequent picks (genre / theme / typography / motion / CTA voice) defer to it.
+- The diversification rule INVERTS — pages must SHARE the system, not differ from each other.
+- If a future page genuinely needs a different system, AMEND `design.md` with a `## Variants` section rather than overriding locally — the file evolves; per-page overrides do not.
+
+## Why opt-in (not auto-emit)
+
+Briefs iterate. The first build is rarely the settled design. Auto-emitting `design.md` on every default build would either churn the file across iterations or lock a weak system before the user has reviewed it. Opt-in mirrors how design teams actually work — formalise the system after the patterns hold, not on day one. The CTA in the preview block keeps the feature discoverable without forcing it.