From 58517f0f18eada2aef29dd338d81d26464ff1032 Mon Sep 17 00:00:00 2001
From: Youssef <speedyoussef@gmail.com>
Date: Thu, 4 Jun 2026 15:35:14 +0100
Subject: [PATCH] Append to an existing global stylesheet instead of
 overwriting it

When Hallmark builds into a project that already has an entry stylesheet
(e.g. app/globals.css, src/index.css), treat it as append-only: keep the
existing @tailwind / @import "tailwindcss" directives and the project's own
tokens, add the Hallmark layer below them, and keep any new @import at the
top. Overwriting it was silently dropping the framework's CSS entry
directives and the user's tokens, which left the whole app unstyled.
---
 skills/hallmark/SKILL.md                     | 1 +
 skills/hallmark/references/contract.md       | 1 +
 skills/hallmark/references/export-formats.md | 3 ++-
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/skills/hallmark/SKILL.md b/skills/hallmark/SKILL.md
index 859b6a4..f71f377 100644
--- a/skills/hallmark/SKILL.md
+++ b/skills/hallmark/SKILL.md
@@ -460,6 +460,7 @@ Always:
 - Cut motion before adding it. Most pages have too much, not too little. If removing an animation wouldn't lose the user information, remove it.
 - **Stamp the output.** The first non-empty line of the produced CSS file (or the top of `<style>` if inline) MUST be a comment of the form: `/* Hallmark · macrostructure: <name> · tone: <tone> · anchor hue: <hue> */`. This stamp is the durable record of what you chose. The next time Hallmark runs in this project, it reads the stamp and picks a *different* macrostructure. **For custom themes**, the stamp also carries the vibe, paper + accent OKLCH values, the chosen display + body fonts, and the three diversification axes — the full multi-line format is in [`custom-theme.md`](references/custom-theme.md) § E. **For studied-DNA builds** (Step 2.6 Condition 0 routed here from a `study` diagnosis), the stamp's `theme:` field is `studied-DNA (source: <URL or "image">)` followed by the paper OKLCH, accent OKLCH, and display + body fonts pulled directly from the diagnosis — not a catalog theme name. Diversification stays suspended for the run; the log entry below records `theme: studied-DNA` so Step 2.5 on the next run knows not to rotate against it.
 - **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.
+- **Never clobber an existing global stylesheet.** When the project already ships an entry stylesheet (`app/globals.css`, `src/index.css`, `src/styles/global.css`), it is **append-only**: keep its `@tailwind` / `@import "tailwindcss"` directives in place, add Hallmark's `:root` block and base rules below them, keep any new `@import` at the very top above all rules, and reuse the project's own token names (`--background`, `--foreground`, a Tailwind `@theme`) where they exist. Overwrite the file only if the user explicitly asks: silently removing a framework's CSS entry directives un-styles the entire app. See [`contract.md`](references/contract.md).
 - **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.
diff --git a/skills/hallmark/references/contract.md b/skills/hallmark/references/contract.md
index 233273f..410d19f 100644
--- a/skills/hallmark/references/contract.md
+++ b/skills/hallmark/references/contract.md
@@ -10,6 +10,7 @@ When producing new work:
 - Name tokens by semantic role, not value. `--color-ink`, not `--color-black`.
 - If the project uses Tailwind, extend the theme; do not inline arbitrary values across components.
 - If the project uses a framework, match the framework's file conventions — don't reinvent them.
+- **An existing global stylesheet is append-only.** If the project already ships one (`app/globals.css`, `src/index.css`, `src/styles/global.css`), add to it instead of replacing it: keep every `@tailwind` / `@import "tailwindcss"` directive exactly where it is, put Hallmark's `:root` tokens and base rules *below* them, and keep any new `@import` (e.g. `tokens.css`) at the very top of the file, above all other rules. Reuse the project's own token names (`--background`, `--foreground`, a Tailwind `@theme`) where they exist rather than shadowing them with a parallel set. Do a full rewrite only when the user explicitly asks for one: silently dropping a framework's CSS entry directives un-styles the entire app.
 - Include a short comment block at the top of the stylesheet naming the genre, the tone the user picked, the palette's anchor hue, and the structural fingerprint. This is the only comment you need.
 
 ## Scope and limits
diff --git a/skills/hallmark/references/export-formats.md b/skills/hallmark/references/export-formats.md
index 1248597..6d9ffad 100644
--- a/skills/hallmark/references/export-formats.md
+++ b/skills/hallmark/references/export-formats.md
@@ -53,7 +53,7 @@ The source. Plain CSS custom properties at `:root`. Every Hallmark page CSS impo
 /* page CSS continues — uses var(--color-paper), never raw values */
 ```
 
-Or, if the project uses a CSS bundler / framework that doesn't honour bare `@import`, the project's existing entry-point includes `tokens.css` first. The page CSS still references tokens by name, never by raw value.
+Or, if the project uses a CSS bundler / framework that doesn't honour bare `@import`, the project's existing entry-point imports `tokens.css` before the page CSS that consumes it (keep it among the other top-of-file `@import`s, never above or in place of `@import "tailwindcss"`). The page CSS still references tokens by name, never by raw value.
 
 **Worked example — editorial theme (Specimen-like):**
 
@@ -324,5 +324,6 @@ When SKILL.md Step 6 emits exports:
 1. **Always** write `tokens.css` next to the page CSS (or in the project root for multi-file projects). Format 1.
 2. **On `design.md`-managed projects** (multi-page), embed all four formats inline in `design.md`'s Exports section. The user copies whichever they need.
 3. **On Tailwind projects** (detected at pre-flight), additionally surface the Tailwind `@theme` block in the build output so the user knows where to paste it (typically into `app/globals.css` or the equivalent).
+4. **Merge into an existing entry stylesheet; never overwrite it.** When the target project already has `app/globals.css` (or `src/index.css`, `src/styles/global.css`): keep its existing `@import "tailwindcss"` / `@tailwind base|components|utilities` directives exactly as they are, append Hallmark's `:root` tokens and base rules *after* them, and keep any `@import "tokens.css"` at the very top of the file (CSS parses `@import` only before other rules, so a misplaced one is silently dropped and your tokens vanish). If the project already defines brand tokens (`--background`, `--foreground`, a Tailwind `@theme`), map Hallmark's roles onto those names rather than adding a parallel set, or scope Hallmark's tokens under a wrapper class. Replace the file outright only when the user has asked for a full takeover.
 
 Don't blanket-emit tokens.json or shadcn variables on single-page projects — the user can copy them out of `design.md` if they upgrade to a multi-page system.