@r1z4x/tezgah 1.9.0 → 1.11.0

package/skills/hallmark/references/comp.md

@@ -0,0 +1,104 @@
+# Comp before build: composing in pixels before composing in CSS
+
+Loaded **only** when the pre-flight found `TOGETHER_API_KEY` (signal 9): at the comp step after the Picks block, and for a generated still (§ Generated stills, at the end). With no key this file never loads and the build goes from the Picks block straight to Step 6. The comp step is never a blocker and never something to apologise for skipping.
+
+A rendered comp carries mass, interval and alignment at a glance, which prose cannot; reproducing an approved image is easier than inventing a composition from a paragraph.
+
+---
+
+## § What the comp is, and is not
+
+| It is | It is not |
+| --- | --- |
+| a composition proposal: mass, interval, alignment, where the eye lands first | a design system; the palette and pairing were settled in the Picks block and do not move |
+| the first viewport only, at the surface's own dimensions | a full page; comping below the fold buys nothing and costs a call per region |
+| a target to reproduce in code, measured against | a texture source; nothing from the comp is ever embedded in the page |
+| disposable once the build matches it | an asset; comps are not shipped and not committed |
+
+**The comp does not get a vote on the Floor.** An image generator will hand you eyebrows, a violet-to-cyan gradient, glassmorphism, and a fake browser window, because nothing in it has read the gates. Same rule as an archive exemplar: **take its composition, not its compliance.** A comp is never evidence that a gate is wrong, and "the comp had it" is not a waiver reason.
+
+---
+
+## § The call
+
+Two comps, three when the direction genuinely forks. One is not a choice and four is a shopping trip.
+
+```
+node <skill-dir>/scripts/imagegen.mjs "<prompt>" --size 1280x800 --n 1 --out .hallmark/comps/c1.png
+```
+
+The prompt is built from the Picks block and the stamp's idea or theme line, not from the prompt. A prompt that reads like the prompt produces the category default in pixels, the page `direction.md` sets aside. Carry, in this order: the **first viewport** as you planned it (what sits where, how large), the **idea** in a few plain words, the **ground and accent** as plain colour words, the **display class** (not the face name; no generator knows Erode), and the **macrostructure** as a compositional instruction. Then one negative clause naming what the category does, so the generator is pushed off it too.
+
+> *"Web page hero, top 1280x800 only. A rowing club's season set as one large race timetable, the next race the biggest line on the screen. White ground, deep green ink, one signal-yellow mark. Heavy grotesk headline flush left on five columns, two lines; the timetable on the other seven. A thin rule under the headline, nothing else above the fold. Flat, printed, no depth. Not a centred hero, no cards, no gradient, no device mockup."*
+
+**Vary the comps on one axis only.** Two comps that differ in everything are two prompts, and comparing them tells you nothing about the decision you are actually making. Vary the composition (where the weight sits, symmetry against asymmetry, type-led against image-led) and hold the system fixed.
+
+---
+
+## § The approval point
+
+Show both, side by side, at their own size. One line each on what differs. Then stop and ask which one, or whether neither.
+
+This is the second and last redirect window (the Picks block was the first) and it is much cheaper than the one after the build. **Do not build past a comp the user has not chosen.** "I'll build A and we can adjust" is how the approval point turns into decoration.
+
+If the user picks neither, ask which was closer on composition, change that axis, and re-call once. Two rounds is the ceiling; after that, build without a comp and say so in one line.
+
+---
+
+## § Reproduction discipline
+
+**A model reliably believes its recreation succeeded when it did not.** This is the failure mode that makes the whole step worthless if unguarded, because the belief is what stops you looking.
+
+So, before building anything below the fold:
+
+1. Screenshot the built page at **exactly the comp's dimensions** (1280x800).
+2. Put the two side by side and answer three questions in writing, one line each:
+   - **Mass.** Does the weight sit in the same place, at the same size, relative to the viewport?
+   - **Interval.** Are the gaps between the major elements the same proportion of the height?
+   - **Entry.** Does the eye land on the same element first?
+3. Name the largest divergence and fix it, or state in one line why the built version is right and the comp was wrong. Both are legitimate. Silence is not.
+
+The comp is the target, not the authority: reproducing a comp that misjudged the copy length is worse than diverging from it deliberately. What is banned is diverging without noticing.
+
+Record it in the stamp: `comp: 2 rendered · c1 approved · reproduced (checked at 1280x800)`, or `comp: skipped (no key)`, or `comp: 2 rendered · none approved · built unconstrained`.
+
+---
+
+## § The medium inventory
+
+Before writing a line of the build, every region of the approved comp gets a written implementation medium. Six or eight regions, one line each, and it takes about a minute.
+
+**The gate: a CSS gradient or a layered background is not a texture.** Writing "CSS" against a woven cloth, a sculpted panel, a printed halftone, a photographed material, or anything with grain is how a committed comp silently becomes a flat page with the same section order and none of its ambition. The inventory exists to make that substitution visible while it is still cheap.
+
+| Medium | What it is right for |
+| --- | --- |
+| **Code** (CSS/SVG) | what the page *draws*: rules, type, geometry, diagrams, anything that animates or reacts, anything that must reflow |
+| **Raster** (generated or supplied) | what the world *paints*: material, grain, cloth, paper fibre, photography, painted or sculpted surfaces, real depth |
+| **Neither** | the region the comp invented and the copy does not support. Cut it here, not after building it |
+
+Two rules on top:
+
+- **A raster region needs a real source:** a user-supplied asset, a library photograph (`imagery.md` § 2) or a generated still (§ Generated stills). A photograph from memory is not a source, and a region the comp painted as a picture never becomes a drawing (80).
+- **A region cannot change medium silently during the build.** Downgrading raster to CSS mid-build is the whole failure this section catches. Change it if the code argues for it, and say so in one line.
+
+Ship the inventory as part of the comp message, under the comps:
+
+```
+Timetable          code      a real table, must reflow
+Headline           code      type, must reflow
+Rule under head    code      1px, tokenised
+Next-race mark     code      the accent on one row, it moves once on load
+Rower photograph   raster    library photo; the comp's crew is not a real crew
+```
+
+---
+
+## § Generated stills
+
+A picture for the page itself, outside the comp step: only when `TOGETHER_API_KEY` is set and the user asked for generated images, or for a subject the library cannot reach (`imagery.md` § 1).
+
+```
+node <skill-dir>/scripts/imagegen.mjs "<prompt>" --size 1536x1024 --out <project>/images/<name>.png
+```
+
+Prompt like a photographer's prompt: one concrete subject, the place, the light and the lens (*a stack of rye loaves on a flour-dusted steel counter, early window light from the left, 50mm, shallow depth*), with *no text, no people facing the camera*. Look at every result; six fingers, doubled furniture and melted labels go back. Treatment and frame as for a library photo. Stamp `generated: <model> via imagegen.mjs`. Never auto-fire it.

package/skills/hallmark/references/craft.md

@@ -0,0 +1,116 @@
+# Craft
+
+Type, colour, surfaces, motion, copy, section openings, missing facts and finish, read on every page build, as numbers wherever a number exists. `layout.md` owns the canvas, the sizes, the sections and the hero; `imagery.md` owns the pictures; the theme supplies the material.
+
+## 1. Type
+
+At most two families, a display face and a body face (one family may do both). A third is one **outlier** with exactly one role (a wordmark, a headline figure, code; mono for code and measured figures counts as one); a second role makes it a third family in running use (37, F13). One family at different weights is one family.
+
+- **Weights:** three at most across the page, display and body together (F19), picked as extremes: 300 beside 800, or 400 beside 700.
+- **Sizes:** on a theme build, the roles in `layout.md` § 2, built on a 1.25 ratio from a 16px body, plus a wordmark size if the theme names one; a custom build sets its own scale from the scaffold's (`direction.md` § Mechanics). Hierarchy past those comes from weight and colour.
+- **Display:** tracking -0.02 to -0.04em on a regular-width face, 0 to -0.015em on a condensed or very heavy one (two letters touching is a fault); line-height 1.0 to 1.15, tighter as it grows (1.2 reads as inherited; a mixed-case poster head may close to 0.92). An uppercase head that can wrap never goes under 1.0 (55a). A head is one weight, one style and one colour: one word set apart by italic, colour, weight or a highlight is the accented word (38i, 38iii); stress comes from a line break or a second line at a second size.
+- **Display size:** `--text-display` (84px at 1440); a theme may set 5.5rem, 6rem when display-heavy, 7rem for a single word. A poster-scale theme or shape (Manifesto, Marquee Hero, a Poster hero) sizes with the screen, `clamp(4rem, 10vw, 9rem)`, full size at 1440 and held at 1920 (Floor 14), while the fold still holds the headline, one sentence and the action. A wide face takes the poster scale a step down.
+- **Headline by length:** count the rendered `h1`: 20 characters or fewer, full display (a single word may reach 7rem); 21 to 50, display; 51 to 90, `--text-display-s` or split at the sense break with `<br>`; over 90, rewrite. A `<br>` goes only between phrases and is checked at 375, where it often lands badly; heads take `text-wrap: balance`, body copy `pretty`, so no head ends on a stub and no paragraph on one word (F26).
+- **Heading measure** rides on the element in `ch` (the scaffold sets `h1` 20ch, `h2` 30ch, `h3` 40ch; a head at display-s about 24ch), never on the heading group's wrapper.
+- **Body:** 16px minimum, line-height 1.5 to 1.65, measure 45 to 75ch (25); never all caps, never justified without hyphenation (F22), never tracked past 0.05em.
+- **Labels, captions, table heads, meta, tags, chips, nav links:** the body face a step smaller, sentence case (lowercase on a theme whose voice is lowercase), untracked (67). Mono only for code, a figure or a measurement, or when mono is the theme's material (64). Capitals belong to a wordmark and to a theme whose display voice is uppercase, where a control may follow at 0.04em or less.
+- **Required:** `font-display: swap`; a fallback of the same build (a grotesk to `system-ui`, a serif to Georgia), metric overrides only where published; `font-synthesis: none`, only the weights you use; `tabular-nums` on figures that compare (F6); `text-wrap: balance` on heads (F3) and `pretty` on body; curly quotes, a true ellipsis, a non-breaking space inside unit pairs (`10 MB`, `⌘ K`) in a proportional face.
+- **Wordmark:** may take another face than the body, and on tone-rich themes should (`fonts.md` § The wordmark); one family throughout only when the body voice is the brand (a letter, a manifesto, a long document).
+
+## 2. Colour
+
+- **OKLCH everywhere.**
+- **Four layers.** Paper (light: L 92 to 98, chroma 0.005 to 0.015 toward the anchor hue; dark: L 12 to 18, 0.008 to 0.015). Ink (on light paper L 16 to 24, on dark L 88 to 96, tinted 0.005 to 0.014). Five to nine neutrals between them, each tinted 0.005 to 0.018 (22). One accent at chroma 0.12 to 0.22 with a paired `--color-accent-ink` (41). A focus colour on the accent's hue, chroma 0.18 to 0.22, L within 5% of the accent.
+- **Never a pure absolute** as a surface or an improvised value (7a, 7b); tint the greys toward the anchor.
+- **The accent is a signal, not a fill:** under 5% of any viewport under the default Restrained posture (23): an active nav item, a focus ring, a link underline on hover, the primary control, the one series a chart argues from.
+- **Postures,** declared in the stamp before code. **Restrained** (above). **Committed:** one colour carries 30 to 60% of the surface through `--color-field` or the paper family; the accent stays a signal. **Full palette:** three or four named roles (field, signal, seal, ink), each with a job and a footprint. **Drenched:** the surface is the colour; ink and rules derive from it. A declared surface colour is not accent footprint.
+- **Contrast:** body 4.5:1 (target 7:1) or APCA Lc 60; large text, icons, focus rings and field edges 3:1 or Lc 45 (40). Every rule that paints a dark surface swaps its text colour in the same rule (41); grey text never sits on a coloured surface.
+- **Bans:** gradients past three stops; purple-blue, purple-pink or cyan-on-dark anywhere (2a); glow shadows on dark, chromatic halos, spotlights (29); alpha as a colour's definition (alpha is for overlays and shadows); red and green as the only signal.
+- **Dark mode** is opt-in and derived, never inverted (`dark-mode.md`).
+
+## 3. Surfaces
+
+- **A primary axis:** left-biased, right-biased, top-heavy or bottom-weighted. Centre-biased is a default, not a choice (6b).
+- **Spacing is a scale:** `--space-3xs` 2px · `2xs` 4 · `xs` 8 · `sm` 12 · `md` 16 · `lg` 24 · `xl` 40 · `2xl` 64 · `3xl` 96 · `4xl` 144. A raw length where a token exists fails (24a); at most three optical nudges off the scale (24b). `gap` for siblings, `margin` only to break the flow.
+- **Grids:** CSS Grid for the page, Flexbox inside components; flex children that must shrink take `min-width: 0`, icons and images `flex-shrink: 0`. No empty cell and no orphan on a last row: change the count (F20). Grids hold their column count above 1440, and `vw` visuals carry a `max-width` (44d).
+- **The surface ladder:** whitespace, then a hairline (1px `--color-rule`), then a tinted well (`--color-paper-2` or `-3`, no border), then a card (a border or a shadow, never both, F24), kept for content that is independently interactive or of a different kind. Never white cards on a tinted page, a card in a card (4), or a bordered box inside a well; climb different rungs at different seams (9, F7). Sibling stats part with a top or vertical hairline: no leading padding on the first, no trailing on the last, the pattern reset wherever the column count changes.
+- **Depth is weight and scale.** One shadow at most: `0 1px 2px oklch(20% 0.01 <hue> / 0.05)` or `0 0 0 1px oklch(30% 0.01 <hue> / 0.06)`. Elevated surfaces are never darker than their canvas. Eight z levels: base 1, raised 10, dropdown 100, sticky 200, sticky-nav 300, modal 400, toast 500, tooltip 600 (56).
+- **Clipping:** `overflow-x: clip` keeps `sticky` and `fixed` working where `hidden` breaks them (34); the section holding a deliberate overflow keeps `overflow: visible`.
+- **Radii:** one per level, concentric (`inner = outer - padding`, at least 2px); image radii `min(1vw, var(--radius-card))`.
+
+## 4. The hero's motion
+
+Size, posture and composition are `layout.md` § 6; what it shows is `imagery.md` § 1.
+
+- **Entrance:** one settle of 0.4 to 0.8s including its stagger, from an already-visible default; a fade with an 8px rise is one motion. Never a fade, a sweep and a scale on one element; never bounce; never a starfield, a mouse parallax or an auto-rotating carousel.
+- **Before it ships,** the hero's visual shows the real thing, is big, keeps the accent under its footprint and weighs under 2 MB with a reduced-motion fallback; any no changes the visual, never the copy.
+
+## 5. Motion
+
+- **Who decides:** the theme's Motion section; a shape's reveal runs only where the theme allows one, the genre's default only where the theme is silent.
+- **Only `transform` and `opacity`** (10a); blur, `clip-path`, mask and shadow may join when they stay smooth on the element alone.
+- **Easings:** `--ease-out` for arrivals, `--ease-in` for exits, `--ease-in-out` for toggles; never the browser's `ease`, `linear` only for progress and scrubbing, no overshoot on UI state (12).
+- **Durations:** `--dur-micro` 120ms (press, tick, colour), `--dur-short` 220ms (hover, tooltip, menu), `--dur-long` 420ms (modal, drawer, accordion, reveal). Exits at 60 to 75% of the enter. Stagger 30 to 50ms between rows, 60 to 100ms between blocks, 500ms in all at most, once.
+- **One reveal per page,** staggered by `--i`, 0.4 to 0.8s in all, content visible without it (62; `patterns.md` § One reveal). Under reduced motion every reveal shows its end state at once and the render tier shoots that way; what must still run (a loader, a 150ms fade) takes `.keep-motion`.
+- **Scroll:** IntersectionObserver for reveals and threshold states; a passive, frame-throttled scroll listener only where direction matters; scroll-scrubbed motion only as one pattern from `scroll-choreography.md` (F8).
+- **State:** hover is one signal (11) that raises contrast: a colour step, or a 1px lift at micro on a control that keeps its colour. Tooltips wait 800 to 1000ms on hover, 0 on focus (17); focus rings never animate (15); menus, modals and accordions follow `microinteractions.md`.
+- **Never:** parallax, custom cursors, cursor followers, a marquee that will not pause on hover and focus (18), `will-change` on a whole class, a pulsing dot, a caret blinking past five beats, an infinite loop other than a loader, one small loop of 4s or less, or one ambient loop the theme declares (8s or slower). Every loop stops under reduced motion and off-screen, and one past 5 seconds carries a visible pause control (`patterns.md` § A loop that can pause).
+
+## 6. Copy
+
+Write as the owner would say it across a counter: the prompt's own nouns, a real place, a number the user gave, the verb a customer would use.
+
+- **The swap test:** a head that would work on a competitor's page is rewritten with a noun only this prompt has. *Software that works for you* fits anyone; *Invoices that chase themselves* fits one product.
+- **Three tests a line:** can the reader picture it, could it be proven false, could only this business say it. Specific beats clever: the place, the hour, the material, the result (*Sourdough at four, gone by ten*); a pun is a second-draft move, once a page at most.
+- **The subhead** says what it is, for whom and the one difference, in twelve words or fewer. **Section heads** say what the visitor will see or get (*Three loaves a morning*), never a category label (*Features*, *Our story*, *Why us*); a staged shape's one-word stage names are the exception.
+- **Rhythm:** a short line beside a longer one; verbs over adjectives; one idea a sentence; no triads of adjectives (*fast, simple, powerful*).
+- **Budget** (58): headlines seven words or fewer, section heads six or fewer; section intros one line; paragraphs two short sentences; lists four items of a three-word label and a ten-word line (five for steps that cannot merge; past that, a table); tables five rows; a set the user gave keeps its true count; 450 visible words a page at most. Read only the headings and the hero: if they tell the story, the rest is the right length.
+- **Refuse the generated voice:** everything gate 19 names, plus *Reimagine*, *Whether you're X or Y*, *It's not just X, it's Y*, *Say goodbye to*, *game-changer*, *journey*, a colon title (*Focus: the app for*), *Click here*, *Enter your email below*, a version string in marketing copy.
+- **Buttons:** the verb of the action (*Book a fitting*); *Continue* only as a flow's second step. **Errors:** what happened, why if known, what to do; no *Oops*, no exclamation marks. **Empty states:** what is empty, why it matters, one action. **Loading:** a spinner after 150 to 300ms, shown at least 300ms, beside the label; *Loading…* past 2s.
+- **Sample data** inside a built product uses `example.com`, the prompt's field names and values that read as samples (*Example Kitchen*, round amounts), never a figure a visitor could take as a claim (46a).
+- **Punctuation:** curly quotes, `…`, a true apostrophe, no `--` and no em or en dash (a comma, a colon, a full stop or parentheses instead), a non-breaking space before units. A full stop on every standalone sentence, none on list items.
+
+## 7. Opening a section
+
+The reflex is a small tracked-caps label above the heading, and the reflex is the tell (54). Ask *what does the reader not yet know?* If nothing, open with nothing. If something, it rides on a fact, a destination or an identifier, never on a name for what comes next. Twelve ways in:
+
+1. **Nothing:** air above, the heading flush.
+2. **The heading announces itself:** the subject in its first two words. Usually the best move.
+3. **A lead-in inside the paragraph** in a heavier weight, never on its own line.
+4. **A drop cap,** one a page, first paragraph only.
+5. **A rule that does more than rule:** hairline, fleuron, double rule, colour edge or pure gap; one divider language, varied in weight and placement from seam to seam (9).
+6. **A numeral at graphic scale,** one a page at most and never in the hero by habit: `clamp(6rem, 16vw, 14rem)`, only when the number is real and is the point (an issue, a year, a price that is the offer).
+7. **A real `<ol>`** with `counter()` when the sequence is genuine.
+8. **A caption below** the content instead of a label above it.
+9. **Marginalia** in the outer margin beside the body.
+10. **A change of paper:** the band's edge is the break.
+11. **A running head or folio:** continuous chrome at the page edge, legal because it persists rather than announces.
+12. **Persistence:** the heading stays in view while its content scrolls beneath.
+
+Two moves may share a section; three is noise. Use one opening, or two alternating, rotated against the log. Legal because each names something present: a `<figcaption>`, a `<th>`, a `<label>`, a `<legend>`, a nav or tab label, a byline or `<time>`, a unit after its figure, a code block's real filename, a live `role="status"` chip, one linked announcement that goes somewhere real, a plan name (which usually wants to be the heading).
+
+## 8. Missing facts
+
+Pictures, slots and the built product are `imagery.md` § 1 to § 4.
+
+- **A missing fact** (a venue, a date, a price) is a text slot, never an invented value: `<span class="fill" data-fill="venue">Venue to be announced</span>` in `--color-muted` inside a dashed outline (`patterns.md` § A fact the prompt did not give), so it reads as a blank to fill, never as a link or selected text; two a page at most, each in the handoff. When the job's anatomy asks for more facts than the prompt gave (hours, an address, dates, prices), slot the two a visitor needs to act and let the rest wait in the handoff. Only a fact the page cannot do without takes a slot: a row, a column or a line that would hold nothing but a missing fact is cut, never announced.
+- **A face the page is about** that the user has not supplied is a font slot: the display token names it first, a free face of the same build stands in and says so in one caption (stamp `waive 37`), and the handoff asks for the files.
+- **A section the user named but gave nothing for** is its heading, one line on what will go there and one text slot, or it merges into a neighbour; never a block of pending rows.
+- **A link whose URL the prompt does not give** points at the section of this page that does the most of it (`#lookbook`); the handoff names the URL it needs. Never an invented route.
+- **A form whose endpoint the prompt does not give** carries an empty `data-endpoint`, says plainly that nothing was sent, and never prints a success state (70; `patterns.md` § A form that posts nowhere yet).
+
+## 9. Finish
+
+The last 2%; sloplint's F-checks (`gates.md` § 5) report most of it.
+
+- **Controls:** one filled primary a page, dialogs counted as their own page (F4); secondaries outlined or typographic, never louder than the primary; nav actions quieter than the hero's. Marketing controls 44 to 52px, app UI 32 to 40px with a 44px hit target (48px on coarse pointers) (39b); two button sizes at most, 6px or more apart; an input matches the button beside it (39a). Delete takes a secondary style unless deleting is the page's one action.
+- **Inputs:** constant border width; the focus ring an `outline` (inset on inputs), never a border change; disabled by `opacity: 0.55`, `cursor: not-allowed` and the native attribute together (39a); `min-height: 1lh` reserved for helper text (F14); 16px on mobile; a `name`, `autocomplete`, the right `type` and `inputmode`, a `<label>` or `aria-label` on every field; paste never blocked; submit enabled until the request starts, and a failed submit focuses the first invalid field; an explicit `type` on every `<button>`. Full recipe: `interaction-and-states.md`.
+- **Testimonials** only when the user supplied them (46a): the attribution bottom-aligned, the avatar the real person or nothing; hanging punctuation on pull quotes.
+- **Pricing:** emphasise a tier with its button and a word, never a different card colour; buttons aligned across tiers at the bottom; a taller featured tier is a grid sibling on explicit rows, never negative margins.
+- **Tables:** sentence-case heads that never wrap, horizontal rules only, no outer border or card, full width. On a phone the column that names the row and the one that acts on it stay in view (F25): restack each row as a labelled block, or pin the first column.
+- **Responsive:** body-adjacent UI (meta, nav links, controls) larger on a phone, stepping down at 60rem; body never under 16px; every desktop sidebar or filter column collapses into a menu or disclosure; container queries for widgets whose layout depends on their box.
+- **Browser surfaces** (F16): keep what `base.css` themes (selection, caret, scrollbar, focus ring, underline).
+- **Nav:** one line, 56 to 80px; a sticky one taller than the scaffold's `scroll-padding-top` raises it. Text links in one weight across states (state is a colour or a soft background, never a primary fill); a tab row scrolls sideways rather than wrapping; under 60rem, links that no longer fit go behind a menu; the logo links home with an `aria-label`.
+- **The document:** `lang`, a `<title>` in the page's own words, a one-sentence meta description (F23); heading levels step one at a time (F21); every `<img>` has `width`, `height` and a file that exists (76).
+- **Prose pages:** line-height 1.65 to 1.75, a measure of 60 to 75ch (25). **Stats:** a title that never wraps, no icon. **Features and metadata** are a `<dl>`, the `<dt>` one weight heavier. **A one-field form:** 20rem wide, never an input and a button sharing one border.
+- **Assets:** `alt=""` when the subject is named beside the image; footer links at body weight; logo rows split evenly (3 + 3, never 5 + 1).

package/skills/hallmark/references/dark-mode.md

@@ -0,0 +1,49 @@
+# Dark mode: parity, never inversion
+
+Loaded only when the user asks for both modes ("dark mode too", "light and dark") or the pre-flight finds an existing mode system to respect. A dark theme (Midnight, Dusk, Kiln) is not a dual-mode page; this file is for pages that ship both modes from one token system. Never emit dual-mode unprompted.
+
+## The stance
+
+Dark mode is a second, equally designed rendering of the same system: not `filter: invert()`, not "flip the greys". Every token is re-derived by recipe; every contrast target holds identically in both modes; the anchor hue never moves. If a token would fail its contrast pairing after re-derivation, fix the derivation, never the requirement.
+
+## Token re-derivation (per token, from the light value)
+
+| Token | Dark derivation |
+| --- | --- |
+| `--color-paper` | L 12-18%, anchor-tinted (chroma 0.008-0.015). Never `#000`. |
+| `--color-paper-2/3` | Elevation is lighter: +3% L per level above paper (light mode steps darker; dark mode steps lighter). |
+| `--color-ink` | L 92-96%, anchor-tinted. Never `#fff`. |
+| `--color-ink-2` / muted / neutral | re-space the L steps between the new paper and ink so the typographic depth reads even; keep every chroma tint. |
+| `--color-rule` | L ~26-34%; hairlines must survive on the dark ground (check against paper-2, not just paper). |
+| `--color-accent` | chroma -0.02 to -0.04, L +5-10% (saturated light-mode accents glare on dark). |
+| `--color-accent-ink` | re-verify: >= 4.5:1 body / 3:1 large on the new accent fill. |
+| `--color-focus` | follows the accent derivation; ring contrast 3:1 or more against both papers. |
+| hue | Never moves between modes, on any token. |
+
+Plus one non-token move: reduce body `font-weight` by 50 units (400 to 350) in dark; light-on-dark text reads optically heavier.
+
+## Emission
+
+`tokens.css` carries the light block as-is, then exactly two additions:
+
+```css
+[data-mode="dark"] { /* only the tokens that move, re-derived per the table */ }
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-mode]) { /* the same overrides, for OS-preference auto mode */ }
+}
+```
+
+The `[data-mode]` attribute wins over the media query by construction (the media block only applies when no explicit mode is set). Toggle: one button setting `document.documentElement.dataset.mode`, persisted to `localStorage`, read before first paint in a 4-line inline script so the page never flashes the wrong mode. `color-scheme: light dark` on `:root` so form controls and scrollbars follow.
+
+## Dark discipline (the rules that change)
+
+- **Shadows off.** Elevation is lightness (the +3% ladder) or an inset hairline ring (`box-shadow: inset 0 0 0 1px var(--color-rule)`). A drop shadow on dark reads as glow; glow is legal only under the atmospheric genre carve-out (`genres/atmospheric.md` § Allowed here: two fixed blooms), which is a theme behaviour, not a mode behaviour.
+- **Cards lighter than canvas.** `paper-2` on `paper`, always; a card darker than its ground reads as a hole.
+- **One heading colour.** Headings all run `--color-ink`; per-heading colour variety that worked on light fragments on dark.
+- **Images.** Never CSS `invert`/`brightness` on raster images. Pick photographs that hold up on a dark ground (the library's `dark` and `mid` tones), or set a light one in a `paper-2` well so it reads as a plate. A theme's multiply plates (a duotone treatment, texture) need their dark-mode pair; texture.md notes the overlay swap for grain.
+- **Charts.** Marks re-derive like accents (chroma down, L up); gridlines from the dark `--color-rule`; see data-viz.md § Dark.
+
+## Verification
+
+Both modes run the full gate sweep: contrast gates 40-41 on every pairing in both modes (the render tier only sees the default mode; check the dark pairings numerically), gate 7a and 7b (no pure black or white) bind on the dark block too, and the stamp records `modes: light+dark` so the log knows.

package/skills/hallmark/references/data-viz.md

@@ -0,0 +1,48 @@
+# Data viz: charts that read as set, not generated
+
+Loaded when the prompt involves charts, data or dashboards, or the shape is Stat-Led or Workbench: a tabular spine, hairline grids, one series that argues, and no decorative dashboards (no donut walls, gauge rows or confetti of KPIs).
+
+## Form first (before any drawing)
+
+| The data is | The form is |
+| --- | --- |
+| one value | a stat tile (a large figure and a worded qualifier), never a one-bar chart |
+| two to five values compared | a stat row, or horizontal bars |
+| a series over time | a line, or a sparkline when it rides inside another component |
+| more than about seven categories | a table; more colours is not an answer |
+| parts of a whole | a stacked horizontal bar; never a pie, a donut or a gauge |
+
+The most underused form is emphasis: one accent series, everything else neutral. If every series is loud, none is.
+
+## Construction (inline SVG written for the data, no chart library)
+
+- **Bars**: <= 24px thick, 2-4px gaps, baseline at zero always; rounded only at the data end, <= 2px.
+- **Lines**: 2px stroke; markers only at annotated points (>= 6px); a sparkline may fade-fill to transparent, the one sanctioned gradient near a chart.
+- **Gridlines**: 1px solid `--color-rule`, never dashed, fewer than you think (3-5 horizontal lines); axis lines can be the grid's first line, not a heavier stroke.
+- **One y-axis.** Never dual axes, the classic way to fake a correlation. Two series with different units get two small charts (small multiples) instead.
+- **No mark shadows, no 3D, no gradients in marks** (the sparkline fade-fill excepted).
+- Sparklines inside components: no axes, no grid, no second colour.
+
+## Colour
+
+Adapted to Hallmark's one-accent discipline (an 8-hue categorical palette would fight everything else on the page):
+
+- **Single series**: the accent.
+- **Multi-series**: a lightness ramp on the accent hue (L steps of ~12-15%, chroma constant), assigned in a fixed order, never cycled; context/reference series in `--color-muted`.
+- **A second hue** only under Full-palette posture, from the declared roles, never invented mid-chart.
+- **Text never wears the data colour.** Labels, values, and axis text are `--color-ink` / `--color-muted`; a series is identified by a swatch beside its label, not by dyeing the words.
+- **Tabular numerals on every numeric surface** (values, axes, tables; F6).
+
+## Honesty (gate 46a binds here hardest)
+
+- Real numbers, or a text slot (`craft.md` § 8) where a figure is missing; a fabricated series is worse than an empty slot.
+- Bars start at zero; a truncated axis that exaggerates a delta is the numeric version of an invented metric. Annotate a zoomed view explicitly ("axis starts at 94%") when the data genuinely lives in a narrow band.
+- Sample data lives only inside a built product sample or a code surface, reads as a sample (totals sum, dates sequence) and is never a figure a visitor could take as a claim (`craft.md` § 6); the stamp notes `data: sample`.
+
+## Dark
+
+Marks re-derive like accents in [`dark-mode.md`](dark-mode.md) (chroma down, L up); gridlines from the dark `--color-rule`; the fade-fill drops to half opacity on dark grounds.
+
+## The dashboard bar
+
+A Workbench or dashboard build shows fewer, truer figures: one hero figure (stat tile), one supporting chart, one table. The KPI wall with six gauges is the tell this file exists to kill.

package/skills/hallmark/references/design-md.md

@@ -0,0 +1,53 @@
+# design.md: the locked system
+
+Loaded when the user asks to lock the current build's system into a portable file, or when a redesign reaches more than one page (`redesign.md`), after the scaffold has run: the file is written from `tokens.css`, never from the theme file. A single build never writes `design.md` on its own; `tokens.css` already makes every build portable, and the Picks block offers the lock in one line.
+
+## Triggers
+
+*lock the system*, *lock the design system*, *give me a design.md*, *export this as a design.md*, *extract the tokens*, *make this portable*, *I want to use this in another project*. Anything else, including more iteration on the same prompt, skips this file.
+
+- **Page builds and redesigns of more than one page.** A single component is too small to be a system.
+- **Never overwrite.** If `design.md` or `DESIGN.md` exists at the root, refresh its `## Exports` and say so in one line: *design.md found; Exports refreshed, system unchanged.*
+
+## Format
+
+At the project root, in the project's case convention, about 45 lines: enough to seed another page, short enough to maintain. State the picks aloud first (*Genre: editorial. Shape: Long Document. Theme: Newsprint. Locking this as the project's system.*), then write:
+
+````markdown
+# Design: <project name>
+
+The locked system. Every Hallmark run reads this first and pages share it. Change it on purpose; the file is the rule.
+
+## System
+- Genre: <editorial | modern-minimal | atmospheric | playful>
+- Shape of the first page: <macrostructure, or app screen>
+- Theme: <catalog name, or custom (vibe: "<4 to 8 words>")>
+- Axes: <paper band>/<display class>/<accent band> · posture: <posture>
+
+## Tokens
+`tokens.css` is the source of truth. The roles:
+```css
+:root {
+  --color-paper: oklch(<L> <C> <H>);  --color-paper-2: oklch(…);  --color-paper-3: oklch(…);
+  --color-ink: oklch(…);  --color-ink-2: oklch(…);  --color-muted: oklch(…);  --color-rule: oklch(…);
+  --color-accent: oklch(…);  --color-accent-ink: oklch(…);  --color-focus: oklch(…);
+  --font-display: "<face>", <fallbacks>;  --font-body: "<face>", <fallbacks>;  --font-outlier: <…>;
+  --radius-card: <px>;  --radius-pill: <px>;  --rule-hair: <px>;  --shadow-card: <value or none>;
+}
+```
+The spacing scale, the type scale, the easings and the durations are the scaffold's and live in `tokens.css`.
+
+## Controls
+- Primary: <fill> · <radius> · <height>
+- Secondary: <outline or text> · same radius and height
+
+## Motion
+- Character: <still | severe | brisk | calm>; one reveal at most; under reduced motion everything ends at once.
+
+## Exports
+`tokens.css` in this project. Tailwind, DTCG or shadcn blocks are added here on request, per `export-formats.md`.
+````
+
+## After the file exists
+
+The pre-flight finds it on every later run (SKILL.md Step 0). From then on every pick defers to it, the variety rule inverts (pages share the system rather than differ), and a page that genuinely needs something else amends `design.md` with a `## Variants` section instead of overriding it locally.

package/skills/hallmark/references/direction.md

@@ -0,0 +1,52 @@
+# Custom: a page of its own
+
+The opt-in path, taken only when the user asks for it (**custom**, "bespoke", "no theme", "a world of its own", "derive it"); silence deals a theme. The catalog takes it back when the user names a theme ("custom, something like Newsprint" is that theme with a mood note), when a `design.md` or a real brand already exists (inherit it), in component scope, and under `--fast` (say so).
+
+## Yours, all of it
+
+On a custom run nothing is dealt and nothing is prescribed: no theme, no shape, no section list, no component, no palette recipe, no draw. What the page is, how it is built and how it looks are your decisions, made for this one client. Hallmark keeps three things: the floor, the gates against machine-made pages, and the sweep. SKILL.md calls you a capable designer; here it means it in full.
+
+So aim higher than a good page. Make the one a design lead would bring to a client who has already turned down every template: something you have never made before, that no other prompt could have produced, that a designer would stop to look at twice. Be ambitious in the idea and exact in the execution.
+
+- **Unique is specific.** Every large decision belongs to this client: its subject, its place, its materials, its numbers, the way its people talk. Put the nearest competitor's name on the page; if it still works, keep going.
+- **Clean is exact, not empty.** A system you can see (a few type sizes far apart, one spacing rhythm, edges that line up), nothing on the page that is not doing a job, and on every screen one thing strong enough to be its reason.
+- **Full is the floor.** A custom page is a whole site, not a hero and a sampler: everything the client has to say and show, from the first screen to the footer, usually six to nine sections, each built around something worth looking at (the product working, a photograph, real facts set large, something to try). Less to look at is not cleaner, only thinner; a section that is a head and a paragraph is unfinished.
+- **Free is free.** Dark or light, one colour or four, type as the picture or photographs edge to edge, a structure no template has, something the visitor can try: every road is open when the idea asks for it.
+
+## Before the first line of code
+
+1. **Learn the subject.** What only this client has: the name and what it means, the place and how it looks, what it does in one verb, its real numbers, its hours and rituals, what its world makes, prints or wears, the words its customers use, and whatever the prompt supplies.
+2. **Set aside the page you would make anyway.** Picture the page this prompt gets without trying, and its obvious twist; neither ships. Yours is usually a split hero with the head on the left and a picture on the right, three numbered steps, rows of label and value between hairlines, a closing band with a form, a dark footer under a huge wordmark, small grey labels, and a pale ground with one careful accent. Two of those in one plan means the plan is the template: start again from the idea.
+3. **Go wide, then choose.** Sketch three directions as far apart as you can make them, two lines each: the idea, how the page is built, how it looks. Build the one a design lead would fight for, never the safest; borrow from the other two only what makes it stronger.
+4. **Let the idea run the page.** One thought the whole page grows from, true of this client and no other. It can live in the type, the colour, the structure, the motion, the way the product is shown, or something the visitor does. Let it decide the rest, top to bottom: an idea that stops at the hero is a template with a good hero.
+5. **Let the content build the structure.** Decide what a visitor must see, understand and do, and in what order, then give each part the form that shows it best. What the sections are, their order, the nav and the footer are yours; the stamp names what you made.
+
+## Spent
+
+What every model ships, refused on sight:
+
+- cream, off-white or beige paper with a high-contrast serif and a clay accent (65); near-black with one neon accent; a pale ground with one timid accent; purple into blue (2a); a hue picked for the category, such as blue for software or green for health;
+- the faces you reach for first (`fonts.md`, its banned and saturated lists) and any face a catalog theme sets;
+- a centred head over three cards, or the run of hero, features, call to action and footer (3, 8); a stock second action;
+- a subject painted on instead of known: paper or grain as a surface, a stamp, a dial or a knob as ornament, bevels, an engraving, a drawing of the thing (47c, 80);
+- an eyebrow, tracked capitals, mono labels, one coloured word in a head, middle-dot strings (54, 67, 64, 38iii, 63).
+
+## Pictures
+
+Only when the subject has something to show. A place, food, people at work, an object, a craft: photographs, few and large, the user's or the library's (`imagery.md` § 2), credited, never a wall of them (83). Software: the product itself, built and working (`imagery.md` § 4). A service, an idea or a body of words: type and colour can carry the whole page, and often should. Every picture passes the deletion test: take it away and the page loses a fact. A picture for mood alone goes.
+
+## Words
+
+The copy is half the design, and the first place a generated page gives itself away. `craft.md` § 6 binds in full: the owner's own nouns, a fact in every head, no line a competitor could use unchanged, about 80 words a screen. Give the headline a shape of its own: two clipped fragments in a row is the one every model reaches for. Then read the headings alone: they should tell this client's story and no one else's.
+
+## What still binds
+
+The Floor, every gate in `gates.md` (44a and 44c leave a custom hero free), `craft.md` wherever it states a rule (its sizes and its Restrained default are a theme's starting point, not yours), the facts rule (46a), licensed pictures, the stamp, the log, the sweep and both reviews. Not `layout.md`, the genre file, the shape catalog or the draw. `patterns.md` shows how states, slots and forms work, never how they look.
+
+## Mechanics
+
+- **Scaffold:** `theme.mjs scaffold --custom`. Fill every `--color-*` and `--font-*`; the scale it writes is a start, not a style, so set the sizes, spacing, widths and gaps the design needs and keep the names.
+- **Faces:** one family or two, three with an outlier that carries one role; free faces unless the user confirms a licence; the display face is one no catalog theme sets (`node <skill-dir>/scripts/theme.mjs check --face "<face>"`). `fonts.md` lists faces no theme uses: a start, not a menu.
+- **Colour:** OKLCH, any posture (`craft.md` § 2), declared in the stamp with its reason (23); contrast and focus unchanged (40, 41, 26a). Check the accent against the catalog with `theme.mjs check --hue <h>`, or with `--axes` once you know them.
+- **Picks block:** Shape and Theme become **Idea** (one sentence) and **Look** (ground, ink, accent and faces, each with where it came from); every other row says what you decided.
+- **Stamp and log:** `theme: custom · idea: "<one sentence>" · vibe: "<4 to 8 words>"`, the paper, accent and faces, `hero:` in your own words, and `posture` and `axes` as on any build: `<paper>/<display>/<accent>`, the values `theme.mjs check` prints (paper light, mid or dark; display a class such as roman-serif or grotesk-heavy; accent warm, cool, neutral or chromatic-<hue name>). The finish reviewer reads the idea where a theme build has its theme (`review-finish.md`).

package/skills/hallmark/references/export-formats.md

@@ -0,0 +1,80 @@
+# Export formats
+
+Loaded when a `design.md` exists and its `## Exports` need refreshing, or when the user asks for the tokens in another format. `tokens.css` is the source of truth, written by `theme.mjs scaffold`; every other format is a translation of it, written only when asked for.
+
+## The token set
+
+| Family | Tokens |
+| --- | --- |
+| Colour | `--color-paper`, `-paper-2`, `-paper-3`, `-ink`, `-ink-2`, `-muted`, `-rule` (and `-rule-2` where a theme sets one), `-accent`, `-accent-ink`, `-focus`, `-error`, `-success`; `-field` under a Committed posture, `-accent-2` where a theme names a second ink |
+| Type | `--font-display`, `--font-body`, `--font-outlier`; `--text-xs` to `--text-3xl` on a 1.25 ratio from 16px, `--text-display-s`, `--text-display`, and the roles `--text-section` (`h2`), `--text-title` (`h3`), `--text-lead` (an app screen: a fixed 1.2 ratio, the roles at small fixed steps); `--tracking-display` |
+| Space | `--space-3xs` (2px) to `--space-4xl` (144px), ten steps; `--container`, `--gutter`, `--gap-columns`, `--section-gap-s`, `--section-gap`, `--section-gap-l` |
+| Shape | `--radius-card`, `--radius-pill`, `--rule-hair`, `--shadow-card` |
+| Motion | `--ease-out`, `--ease-in`, `--ease-in-out`; `--dur-micro` 120ms, `--dur-short` 220ms, `--dur-long` 420ms |
+| Layers | `--z-base` 1, `-raised` 10, `-dropdown` 100, `-sticky` 200, `-sticky-nav` 300, `-modal` 400, `-toast` 500, `-tooltip` 600 |
+
+A page that needs another token names it by role and declares it in `tokens.css`; nothing downstream uses a name `tokens.css` does not declare.
+
+## `tokens.css` in a project
+
+The scaffold writes `tokens.css` and `base.css` beside the project's entry stylesheet (`src/index.css`, `app/globals.css`; `--dir` names another folder) and prints the two imports that fit it. They go right after the file's last `@import`, never below a rule: CSS drops an `@import` that follows one, and the tokens vanish without an error. Where the project already names its tokens (`--background`, a Tailwind `@theme`), map Hallmark's roles onto those names rather than adding a parallel set. Replace the file only when the user asks for a full takeover.
+
+## Tailwind v4
+
+Where the entry stylesheet imports Tailwind 4, the scaffold writes `tokens.css` in two blocks, and the imports follow `@import "tailwindcss"`:
+
+```css
+@import "tailwindcss";
+@import "./tokens.css";
+@import "./base.css" layer(base);
+```
+
+```css
+@theme static { --color-paper: oklch(96.5% 0.008 50); --font-display: "Fraunces", serif; --text-lg: 1.25rem; --radius-card: 4px; }
+:root { --space-lg: 24px; --dur-short: 220ms; --z-modal: 400; --section-gap: 144px; }
+```
+
+- **`@theme static`** holds every `--color-*`, `--font-*`, `--text-*`, `--tracking-*`, `--radius-*`, `--shadow-*` and `--ease-*` token, so each is a utility (`bg-paper`, `text-ink`, `font-display`, `rounded-card`) and, being static, still a variable for hand-written CSS. Everything else stays in `:root`.
+- **Never `--spacing-<name>`.** Tailwind sizes `w-`, `max-w-`, `p-` and `gap-` from that namespace, so `--spacing-xl: 40px` turns `max-w-xl` into 40px. The space scale needs no mapping: every step but 2px is a multiple of Tailwind's 4px unit (`--space-lg` is `p-6`, `--space-xl` is `p-10`, `--space-2xl` is `p-16`).
+- **Nine names are Tailwind's own:** `--text-xs`, `-sm`, `-lg`, `-xl`, `-2xl`, `-3xl` and the three `--ease-*`. The scaffold's values replace Tailwind's, so `text-lg` and `ease-out` change wherever the project uses them. On a new project, a restyle or a full redesign that is the system arriving. On one new page in a project whose other pages must not move, take those nine out of `@theme` and declare them on the page's root element.
+- **`base.css` goes in the base layer.** Unlayered, its element rules (`a { color: inherit }`, `h1 { max-width: 20ch }`) outrank every utility, because Tailwind's utilities sit in a layer.
+- **The stamp is read from the source.** Tailwind drops comments from what it emits; sloplint reads the stylesheet you wrote.
+
+Tailwind v3 (`@tailwind` directives): `tokens.css` stays one `:root` block, the stamp and both imports go above the directives (below them they are dropped), `base.css` with `layer(base)` so it lands after Preflight and under the utilities. Utilities on request: the same names under `theme.extend` in `tailwind.config`, each value a `var()` of the token.
+
+## DTCG `tokens.json`
+
+For Style Dictionary or Tokens Studio pipelines. Path-based, a `$type` on every token, OKLCH as a string (convert to hex only if the pipeline cannot read it, and say the conversion is lossy). A fluid size exports its maximum; the `clamp()` stays in CSS.
+
+```json
+{
+  "color": {
+    "paper": { "$value": "oklch(96.5% 0.008 50)", "$type": "color" },
+    "accent": { "$value": "oklch(62% 0.17 28)", "$type": "color" }
+  },
+  "font": { "display": { "$value": "General Sans, ui-sans-serif, sans-serif", "$type": "fontFamily" } },
+  "space": { "lg": { "$value": "24px", "$type": "dimension" } },
+  "duration": { "short": { "$value": "220ms", "$type": "duration" } }
+}
+```
+
+## shadcn/ui
+
+shadcn keeps full colour values in its own variables and maps them in `@theme inline`. Point its variables at Hallmark's tokens:
+
+```css
+:root {
+  --background: var(--color-paper); --foreground: var(--color-ink);
+  --card: var(--color-paper-2); --card-foreground: var(--color-ink);
+  --popover: var(--color-paper-2); --popover-foreground: var(--color-ink);
+  --primary: var(--color-accent); --primary-foreground: var(--color-accent-ink);
+  --secondary: var(--color-paper-3); --secondary-foreground: var(--color-ink-2);
+  --muted: var(--color-paper-2); --muted-foreground: var(--color-muted);
+  --accent: var(--color-paper-3); --accent-foreground: var(--color-ink);
+  --destructive: var(--color-error);
+  --border: var(--color-rule); --input: var(--color-rule); --ring: var(--color-focus);
+  --radius: var(--radius-card);
+}
+```
+
+shadcn's `accent` is a hover surface and its `muted` a quiet background, so its `@theme inline` block defines `--color-accent` and `--color-muted` with meanings that collide with Hallmark's. In a shadcn project, keep Hallmark's two tokens out of `@theme` and let the page CSS reach them through `var()`, or rename them there (`--color-signal`, `--color-ink-3`) and say so in the handoff.