@r1z4x/tezgah 1.9.0 → 1.11.0

package/skills/hallmark/references/patterns.md

@@ -0,0 +1,202 @@
+# Patterns
+
+The parts every page repeats, written to pass the gates. Take the code's shape; the names, copy, values and composition are yours. `tokens.css`, `base.css` and the slot script come from the scaffold.
+
+## Controls, all eight states
+
+```css
+.btn { display: inline-flex; align-items: center; gap: var(--space-xs); min-height: 48px; padding: 0 var(--space-lg); border: 1px solid var(--color-ink); border-radius: var(--radius-input, var(--radius-pill)); background: var(--color-ink); color: var(--color-paper); font: 500 var(--text-md)/1 var(--font-body); white-space: nowrap; text-decoration: none; cursor: pointer; transition: background-color var(--dur-short) var(--ease-out), transform var(--dur-micro) var(--ease-out); }
+.btn:hover { background: var(--color-ink-2); }
+.btn:active { transform: translateY(1px); }
+.btn:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+.btn:disabled, .btn[aria-disabled="true"] { opacity: 0.55; cursor: not-allowed; transform: none; }
+.btn[aria-busy="true"] { cursor: progress; }
+.btn--quiet { background: transparent; color: var(--color-ink); border-color: var(--color-rule); }
+.btn--quiet:hover { background: var(--color-paper-2); }
+@media (prefers-reduced-motion: reduce) { .btn { transition: background-color var(--dur-short) linear; } }
+```
+
+One filled primary a page (F4); the quiet one goes somewhere else. Error and success belong to the form, below.
+
+## A photograph in a slot
+
+```html
+<figure class="photo" data-slot="hero" data-alt="The orchard in October, rows of trees heavy with fruit">
+  <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/.../1280px-....jpg"
+       srcset=".../960px-....jpg 960w, .../1280px-....jpg 1280w, .../1920px-....jpg 1920w" sizes="(min-width: 60rem) 45vw, 100vw"
+       width="4000" height="5000" alt="Rows of apple trees in October light" style="object-position: 50% 40%" fetchpriority="high">
+</figure>
+<p class="caption">Picking runs from September to the first frost.</p>
+```
+
+```css
+.photo { aspect-ratio: 4 / 5; min-height: 440px; margin: 0; border-radius: var(--radius-card); }
+.photo > img { outline: 1px solid color-mix(in oklab, var(--color-ink) 8%, transparent); outline-offset: -1px; }
+.caption { margin-top: var(--space-sm); font-size: var(--text-sm); color: var(--color-ink-2); }
+```
+
+The `<img>` comes from `theme.mjs photos`; `base.css` supplies the cover fit, the loading wash and the theme's treatment. The credit goes in the footer's *Photographs* line; the caption is a fact from the prompt, outside the frame. A product sample takes the same kind of slot with no `<img>`: the interface built at full size (`imagery.md` § 4).
+
+## A choice between a few
+
+```html
+<fieldset class="seg"><legend>Size</legend>
+  <input type="radio" name="size" id="s1" value="1" checked><label for="s1">One box</label>
+  <input type="radio" name="size" id="s2" value="2"><label for="s2">Two boxes</label>
+</fieldset>
+```
+
+```css
+.seg input { position: absolute; opacity: 0; width: 1px; height: 1px; }
+.seg label { display: inline-flex; align-items: center; min-height: 44px; padding: 0 var(--space-md); border: 1px solid var(--color-rule); cursor: pointer; }
+.seg input:checked + label { background: var(--color-ink); color: var(--color-paper); }
+.seg input:focus-visible + label { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+```
+
+The radios stay in the flow at one pixel (53); the label carries the state and the ring, in the body face, sentence case.
+
+## A rail and a switcher
+
+```html
+<ul class="rail" tabindex="0" aria-label="Upcoming dates">
+  <li><time datetime="2027-06-12">12 June</time> Whitby</li>
+  <!-- five or more items; the next one cut by the edge -->
+</ul>
+<div class="switch" data-switch>
+  <div class="seg" role="tablist" aria-label="Menu"><button role="tab" aria-selected="true" aria-controls="m1" id="t1">Lunch</button><button role="tab" aria-selected="false" aria-controls="m2" id="t2" tabindex="-1">Dinner</button></div>
+  <section role="tabpanel" id="m1" aria-labelledby="t1">...</section>
+  <section role="tabpanel" id="m2" aria-labelledby="t2" hidden>...</section>
+</div>
+```
+
+```css
+.rail { display: grid; grid-auto-flow: column; grid-auto-columns: minmax(16rem, 22%); gap: var(--gap-columns); overflow-x: auto; scroll-snap-type: x mandatory; scroll-padding-inline: var(--gutter); padding-inline: var(--gutter); overscroll-behavior-x: contain; }
+.rail > * { scroll-snap-align: start; }
+.rail:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 4px; }
+```
+
+The rail scrolls by touch, wheel and arrow keys once focused, and sits outside the container's padding so its edge cuts the next item. The switcher's tabs move with the arrow keys (a few lines of script set `aria-selected`, `tabindex` and `hidden`); without script every panel shows in order. A pinned pair is `position: sticky; top: var(--space-2xl)` on the visual's column, released under 60rem.
+
+## A fact the prompt did not give
+
+```html
+<p>Doors at <span class="fill" data-fill="time">time to be announced</span>, at <a href="#venue">the venue</a>.</p>
+```
+
+```css
+.fill { padding: 0 0.25em; border: 1px dashed color-mix(in oklch, var(--color-muted) 70%, transparent); border-radius: 3px; color: var(--color-muted); -webkit-box-decoration-break: clone; box-decoration-break: clone; }
+```
+
+Two a page at most, each named in the handoff (`craft.md` § 8).
+
+## A form that posts nowhere yet
+
+```html
+<form class="signup" data-endpoint="" novalidate>
+  <label for="email">Email address</label>
+  <div class="signup__row">
+    <input id="email" name="email" type="email" autocomplete="email" required>
+    <button class="btn" type="submit">Send me the date</button>
+  </div>
+  <p class="signup__help" id="email-help" aria-live="polite"></p>
+</form>
+```
+
+```js
+document.querySelectorAll('form[data-endpoint]').forEach((form) => {
+  const input = form.querySelector('input'), help = form.querySelector('[aria-live]');
+  form.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const ok = input.checkValidity();
+    input.toggleAttribute('aria-invalid', !ok);
+    if (!ok) { input.setAttribute('aria-describedby', help.id); help.textContent = 'That address looks incomplete. Write it as name@example.com.'; input.focus(); return; }
+    if (!form.dataset.endpoint) { help.textContent = 'Nothing was sent: this form is not connected yet.'; return; }
+    fetch(form.dataset.endpoint, { method: 'POST', body: new FormData(form) })
+      .then((r) => { help.textContent = r.ok ? 'Thanks. The date goes to ' + input.value.trim() + '.' : 'That did not go through. Try again in a minute.'; })
+      .catch(() => { help.textContent = 'That did not go through. Try again in a minute.'; });
+  });
+});
+```
+
+```css
+.signup__row { display: flex; gap: var(--space-xs); }
+.signup input { flex: 1; min-width: 0; min-height: 48px; padding: 0 var(--space-md); border: 1px solid var(--color-muted); border-radius: var(--radius-input, var(--radius-pill)); background: var(--color-paper); color: var(--color-ink); outline: 2px solid transparent; outline-offset: -3px; }
+.signup input:focus-visible { outline-color: var(--color-focus); }
+.signup input[aria-invalid] { border-color: var(--color-error); }
+.signup__help { min-height: 1lh; margin-top: var(--space-2xs); font-size: var(--text-sm); color: var(--color-muted); }
+```
+
+## One reveal that survives no script
+
+```html
+<script>document.documentElement.classList.add('js');</script>
+```
+
+```css
+.js [data-reveal] { opacity: 0; transform: translateY(8px); transition: opacity var(--dur-long) var(--ease-out), transform var(--dur-long) var(--ease-out); transition-delay: calc(var(--i, 0) * 40ms); }
+.js [data-reveal].is-in { opacity: 1; transform: none; }
+@media (prefers-reduced-motion: reduce) { .js [data-reveal] { opacity: 1; transform: none; transition: none; } }
+```
+
+```js
+const io = new IntersectionObserver((es) => es.forEach((e) => { if (e.isIntersecting) { e.target.classList.add('is-in'); io.unobserve(e.target); } }), { rootMargin: '0px 0px -10% 0px' });
+document.querySelectorAll('[data-reveal]').forEach((el) => io.observe(el));
+```
+
+Visible with scripting off (62), at its end state under reduced motion, once, and only where the theme lets something move.
+
+## Figures that compare
+
+```css
+.stats { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.stats > * { padding-inline: var(--space-lg); border-left: 1px solid var(--color-rule); }
+.stats > :first-child { padding-left: 0; border-left: 0; }
+.stats b { display: block; font: 600 var(--text-3xl)/1 var(--font-display); font-variant-numeric: tabular-nums; }
+@media (max-width: 60rem) { .stats { grid-template-columns: minmax(0, 1fr); } .stats > * { padding: var(--space-md) 0; border-left: 0; border-top: 1px solid var(--color-rule); } .stats > :first-child { border-top: 0; } }
+```
+
+Only figures the user gave (46a), each with its unit and what it counts.
+
+## A loop that can pause
+
+Anything moving past 5 seconds (a marquee, an ambient loop, a looping video) holds still until the script runs, stops off-screen and under reduced motion, pauses on hover and focus, and carries a visible pause control (18, WCAG 2.2.2).
+
+```html
+<figure data-loop>
+  <!-- the drawing, the loop or the video -->
+  <button class="btn btn--quiet" type="button" data-loop-toggle>Pause</button>
+</figure>
+```
+
+```css
+[data-loop]:not(.is-running), [data-loop]:not(.is-running) *, [data-loop]:not(.is-running) *::before, [data-loop]:not(.is-running) *::after { animation-play-state: paused !important; }
+html:not(.js) [data-loop-toggle] { display: none; }
+@media (prefers-reduced-motion: reduce) { [data-loop-toggle] { display: none; } }
+```
+
+```js
+document.querySelectorAll('[data-loop]').forEach((el) => {
+  const btn = el.querySelector('[data-loop-toggle]');
+  const s = { seen: false, hover: false, focus: false, held: matchMedia('(prefers-reduced-motion: reduce)').matches };
+  const sync = () => {
+    const run = s.seen && !s.hover && !s.focus && !s.held;
+    el.classList.toggle('is-running', run);
+    el.querySelectorAll('video').forEach((v) => (run ? v.play().catch(() => {}) : v.pause()));
+    btn.textContent = s.held ? 'Play' : 'Pause';
+  };
+  btn.addEventListener('click', () => { s.held = !s.held; sync(); });
+  [['pointerenter', 'hover', true], ['pointerleave', 'hover', false], ['focusin', 'focus', true], ['focusout', 'focus', false]].forEach(([t, k, v]) => el.addEventListener(t, () => { s[k] = v; sync(); }));
+  new IntersectionObserver(([e]) => { s.seen = e.isIntersecting; sync(); }).observe(el);
+});
+```
+
+## A way past the nav
+
+```html
+<a class="skip" href="#main">Skip to content</a>
+```
+
+```css
+.skip { position: absolute; left: var(--space-md); top: calc(-1 * var(--space-3xl)); z-index: var(--z-toast); padding: var(--space-xs) var(--space-md); background: var(--color-ink); color: var(--color-paper); }
+.skip:focus-visible { top: var(--space-md); }
+```

package/skills/hallmark/references/redesign.md

@@ -0,0 +1,88 @@
+# Redesign
+
+Loaded only when the user names Hallmark with `redesign` or `audit` (`/hallmark redesign <target>`, *redesign the site with Hallmark*). A request that changes an existing design without naming Hallmark (a restyle, new colours or a new theme, a polish, a redesign, a small edit) never loads this file: it is done as asked, in the project's own system. A redesign is a build whose material is the page that exists: SKILL.md still binds, and this file says what the run keeps, what replaces the Step 1 ask and what the sweep adds. The target is the user's own code (a file, a folder, a route on a dev server); a live URL with no source behind it can only be audited, through `--url`.
+
+## What a redesign keeps
+
+- **The content.** Every fact, claim, name, price, date and quote the page states. Figures, quotes and logos already there are the user's material: carried over as found and listed in the handoff to verify, one a gate doubts (a trend nobody measured, 46a) included. Nothing is added: no action, section, claim or picture the page did not have, beyond what the user hands over and what a gate requires (a pause on a loop, 18; a focus ring). A drawing made from the page's own facts (its channels, its steps, a figure) is composition, and full depth may make one.
+- **The wiring.** Every link, form, field, handler, route, id and test hook; every script, data call and analytics call. Edit markup inside the component that owns it. Never move logic, rename a prop, or drop a `name`, an `id`, a `key`, a `type`, an `href` or a `data-testid` that a script or a test reads. A prop the Floor empties (an emoji passed as an icon) may go with it, named in the handoff. A state the screen has no logic for (a failed load, an undo) is listed for the owner, never built.
+- **The files.** No file deleted, no route removed and no component tree replaced without a file-level plan the user approved, and no test edited to make the redesign pass. Documents in the repo (a README, a prompt, a deck) explain the product; they are not page copy. In a git project, start from a clean tree, `.hallmark/` aside (ask the user to commit or stash; never do it for them), so the redesign is one diff they can read and revert. The stylesheet is the redesign's to edit: the append-only rule guards it from a build, not from its own redesign.
+- **The brand,** when there is one. A brand is chosen: a logo, a colour or a face the project names (a brand file, a logo asset, named tokens, a font file of its own) or the user states. It stays at every depth, its values read from the project's files, never from memory. A framework default or a look the gates name (the purple-to-blue gradient, Inter as the display, a stock swatch) is not a brand: restyle and full replace it, and the Picks block says so in case it was. A locked `design.md` is the system at every depth.
+- **The words,** unless a gate names them. Wording that fails a copy gate (19, 54, 58, 63, 69) is tightened from the facts already on the page, and the handoff lists every changed line, before and after. An eyebrow is never just deleted: where its heading is figurative, the plain label becomes the heading (*Opening hours* over *When to find us* becomes *Opening hours*). Terms, disclaimers and consent text are never reworded. When the user says to keep every word, stamp `copy: verbatim`: 19, 58 and 69 then report as notes.
+
+## Depth
+
+The verb is a **full** redesign: the content and the wiring stay, the system and the composition change. A lighter depth runs only when the same request asks for it in so many words, and the Picks block names the depth:
+
+| Depth | Stays | Changes | Only when the request says |
+| --- | --- | --- | --- |
+| **full** | the content and the wiring | the system and the composition: shape, hero, section objects, chrome | nothing else: it is the verb |
+| **restyle** | the layout | the system: colour, type, radius, shadow, motion, the controls | *keep the layout*, *restyle*, *reskin*, *only the colours and type* |
+| **polish** | the system and the layout | only what a gate names: the tells, contrast, states, motion, tokens | *polish*, *keep our look*, *only fix what looks generated* |
+
+The depths do not blend: a polish that finds the concept wrong says so and recommends the full run, it never smuggles one in.
+
+**Full depth on an app screen** recomposes each screen inside the shell it has: what leads, and how the figures, tables and forms are arranged (`flow.md` § App screens). Routes, destinations and each component's logic stay; there is no hero stage and no hero review.
+
+*From scratch* is a build, not a depth: SKILL.md as written, the old page as its Step 2 inventory, in new files beside the old ones.
+
+## Before
+
+1. Run the pre-flight (Step 0), then list the pages in the target: route, file, and whether each is a page or an app screen (`flow.md` § App screens). In a framework project start the dev server and record through `--url`; the linter does not render the empty shell `index.html` from disk. An unstamped page has no genre: infer it from the page as Step 1 would from a prompt, and say so.
+2. Record the page as it stands:
+
+```
+node <skill-dir>/scripts/sloplint.mjs <target> --genre <genre> --render --before [--url <route> ...] [--scope app]
+```
+
+It prints the findings grouped by gate and writes them to `.hallmark/before.txt`, the screenshots to `.hallmark/before/` and the record to `.hallmark/before.json`: every link, form, field, inline handler, test hook, script tag, selector a script queries, heading and figure. Git ignores the folder's screenshots and records.
+
+3. Look at the screenshots before you weigh the findings, so the linter does not write the verdict, then give the read in four lines: what the page is for (the audience, the one action); what works and stays (at least one thing); what reads as generated (the worst tells, by gate); what is broken.
+
+**`audit <target>` stops here.** It loads `gates.md` § 1, § 4 and § 5, walks the judged gates from the screenshots, and reports the findings by tier with `file:line`, the read, the lightest depth that settles them and what only a deeper one would. It changes none of the project's files.
+
+## The ask
+
+One message replaces the Step 1 ask; skip it when the request already answers it or no one can answer:
+
+> *Before I redesign, three things. 1. **What must stay**: the brand, a section, a page? Say *keep the layout* and I only restyle. 2. **What is wrong with it**, in your words, and the feeling you want instead. 3. **Anything new to show**: screenshots, photos, numbers, a quote. Or say **go ahead** and I will redesign it in full.*
+
+## The plan
+
+The Picks block opens with four rows of its own, and nothing is deleted until the user has seen the Files row:
+
+```markdown
+- **Redesign** · full · 3 pages (/, /pricing, /docs)
+- **Before** · Floor 14 FAIL · Reflex 9 · a centred template in a stock indigo; the pricing table is clear and stays
+- **Keeps** · every link, field and handler · the green and the brand face · the pricing table
+- **Files** · edit: app/page.tsx, app/pricing/page.tsx, app/globals.css · create: app/tokens.css, app/base.css · delete: none
+```
+
+Then the build rows the depth reaches: Theme at restyle and full (dealt, `brand` or locked); Shape, Chrome, Hero, Signature and Sections at full only, where Step 2 runs with the page's own content as its inventory. At polish the block stops after Files. The deal's `--prompt` is the read's first line (what the page is for, in plain nouns), never the page's own copy, which is what the redesign is leaving behind.
+
+## Build
+
+- **Polish** is `flow.md` § The sweep, on the user's own page: fix in place, single elements and tokens, never restructure, under the check stamp with `built: the project · redesign: polish`. It loads `gates.md` § 1 to § 5 and `patterns.md`, `interaction-and-states.md` when the page has a form, the theme file an old stamp names, and from `craft.md` only the section a finding points at.
+- **Where the layout stays** (polish and restyle), the stamp's `redesign:` field tells sloplint to report the layout gates (6b, 8, 9, 32, 42, 44a, 44c, 58, 77, 79) as notes; at polish the spacing and scale gates (24b, 59, 78) too, so a polish does not re-space a site it was asked to keep. Print them for the user with the depth that would settle them; do not rebuild them. At every depth 58 (the screen budget) is a note too: the words are the owner's, and only a copy gate cuts one. In app scope those gates are skipped, so the handoff's Layout row comes from the read and the review. A theme's own composition rules (its do-nots, the dials that vary between pages) yield to a kept layout: the theme lends its system, and every page takes one dial set.
+- **Restyle and full** start from the scaffold, with the depth in the stamp: `theme.mjs scaffold <slug> --redesign <depth>`, or `scaffold --brand --redesign <depth>` for a kept brand, its tokens filled from the palette and faces the pre-flight found (no `check`: the coordinates are the user's); add `--scope app` for app screens. It writes `tokens.css` and `base.css` beside the project's stylesheet and prints the imports that fit it (`export-formats.md` has the Tailwind and shadcn names). Then the shared components and the chrome, then the pages, the most visited first, each swept before the next.
+- **More than one page** at restyle or full: lock the system once the scaffold has run (`design-md.md`). Every page reads it and the variety rule inverts: pages share theme, type and accent, and differ only in shape. One stylesheet for several pages lists a hero posture per route, `hero: Settled (/), Stage (/contact)`. Past three pages, give each page to its own subagent where the harness has them, with `design.md`, the page's files and this file.
+- **Full depth** runs the hero stage and the hero review; polish and restyle skip both. The old sections still sit below the new hero at that stage: the stage judges the first screen alone, and what it reports below the fold waits for the sweep. Gate 8 judges the composition, not the order of the content: a kept sequence in a new composition is waived on the record.
+
+## After
+
+1. The sweep, against the record: `sloplint <target> --genre <genre> --render --kept`. Anything the page had and no longer has is a `FAIL kept` (a link, a form, a field, a handler, a test hook, a script, a selector a script still queries) or a `WARN kept` (a heading, a figure, an image, an id). Restore it, or put it on the record in the stamp: `/* Hallmark · dropped /blog, #team · the user is retiring the blog and the team section */`, or for a line a copy gate named, `/* Hallmark · reworded "Built for modern teams" to "Out of your way" · 19 names the opener */`, or `dropped "<the line>" · 69 names it` for a line a gate cuts whole. The run also writes `.hallmark/compare.html`, the before and after screenshots side by side: give the user its path.
+2. The project's own checks, where it has them: the type check, the build, the tests. A redesign that breaks one is not finished.
+3. The finish review also takes the `before` screenshots and answers what the old page did better (`review-finish.md`). A polish hands it only the full pages at 1440, before and after, and takes at most five findings. A finding that is a plain defect (a misalignment, a broken glyph, a label that lies) is fixed at any depth; one that asks for a new composition joins the layout findings; one that asks for content the page never had goes to the owner in the handoff.
+4. The log entry carries `mode: redesign`, `depth` and `scope` (page, site or app), plus the build's fields at full depth.
+5. The handoff, ahead of the material ask; where the layout stayed it adds a Layout row (the findings only a full redesign would settle):
+
+```
+Redesign · full · 3 pages
+Before   Floor 14 FAIL · Reflex 9
+After    Floor 0 · Reflex 1 waived (47b)
+Kept     14/14 links · 5/5 fields · 9/9 handlers · 11/11 headings · every figure
+Changed  the system and the composition: shape, hero, sections, chrome
+Dropped  none
+Yours    2 claims kept as found ("50,000+ teams", the Acme quote) · 4 lines reworded, listed below
+Compare  .hallmark/compare.html
+```

package/skills/hallmark/references/responsive.md

@@ -0,0 +1,46 @@
+# Responsive
+
+Loaded for an unusual layout. No desktop-only interactions; every page renders without fault from 320 to 1920 CSS pixels.
+
+## What the script checks and what it cannot
+
+sloplint covers the mechanical half at 320, 375, 414, 768, 1024, 1280, 1440 and 1920: horizontal scroll and `overflow-x: clip` (34), wrapping controls (49), image tracks and display heads (50), radio tabs (53), stacked sticky elements (56). Check by eye at each width what it cannot see: every desktop sidebar or filter column collapses into a menu or a disclosure, section heads stack to one column, and a per-theme override carries its own mobile rule.
+
+## Breakpoints
+
+Two, shared by the whole page, in `rem` so they follow the user's font size. The scaffold steps its tokens down at both: under 60rem (about 960px, the layout breakpoint) gutters drop to 24px and the three section gaps to 80, 96 and 120px; under 40rem (about 640px, the type breakpoint) gutters drop to 16px, the section gaps to 56, 72 and 96px, and column gaps to 16px. Write component rules against the same two widths, in one direction for the whole page. Add a third only where the content itself breaks.
+
+- **Under 60rem:** multi-column grids go to one column, tilts and clip effects drop, sticky panes unstick, every hero posture collapses to content height (Poster may stay full-bleed).
+- **Under 40rem:** display sizes step down, margin captions move inline, annotations consolidate.
+
+## Fluid and discrete
+
+`clamp()` for sizes that change continuously (the scale's display tokens already do); media queries for layouts that change discretely. Detect capability with `@media (hover: hover)` and `(pointer: coarse)`, never with width:
+
+```css
+@media (hover: hover) { .link:hover { text-decoration-thickness: 2px; } }
+@media (pointer: coarse) { .btn { min-height: 48px; } }
+```
+
+Body-adjacent UI (meta, nav links, controls) runs larger on a phone and tightens at 60rem (`craft.md` § 9).
+
+## Clickable text never wraps
+
+Buttons, primary nav links and CTAs are single-line at every width from 320 to 1920 (49a); footer links, tabs and breadcrumbs too unless a real phrase cannot shorten (49b). When one wraps, in this order:
+
+1. **Shorten the label.** *Get started free* to *Start free*; *Read the documentation* to *Read the docs*.
+2. **`white-space: nowrap`** on the control, and let the row around it reflow.
+3. **Collapse the row**, not the labels: under 60rem the links that no longer fit go behind a menu, while two or three short ones that fit stay in the bar.
+
+## Units and safe areas
+
+- `dvh` or `svh` for heights that meet mobile browser chrome, never `vh` on a hero (6a); `width: 100%`, never `100vw` (34).
+- With `viewport-fit=cover`, fold the safe area into the gutter token: `--gutter: max(16px, env(safe-area-inset-left))`.
+
+## Tables, images, languages
+
+- **Tables** on a phone keep the column that names the row and the one that acts on it in view: restack each row as a labelled block, or pin the first column (`craft.md` § 9, F25). Ten columns on a phone is a redesign, not a squeeze.
+- **Images:** `srcset` with width descriptors, `<picture>` for a different crop, `width` and `height` attributes on every image, `loading="lazy"` below the fold and never on the LCP element.
+- **Languages:** logical properties (`margin-inline-start`, `padding-block`), room for 30 to 40% longer strings, no hard-coded date or number formats.
+
+Never: device sniffing instead of feature queries, hover-only interactions, breakpoints in `px`.

package/skills/hallmark/references/review-finish.md

@@ -0,0 +1,19 @@
+# Finish review
+
+You are reviewing a built page against a fixed list. You did not build it and will not be told why anything is the way it is. Read the page, not the intent. Your inputs, and nothing else: the screenshots the render tier wrote (the folds at 1280 x 800, 1440 x 900 and 1920 x 1080, the full page at 1440 and at 375), the page's HTML or component source, the theme or idea line from the stamp, on a theme build the theme file and its picture, the hero review's findings with how each was settled, and `gates.md` § 4. Look at the screenshots first; open the HTML only to quote copy or to locate a finding; the linter has already read the CSS. A pinned pane shows once in a full-page shot: the column beside its later screens is the pin, not an empty half. Batch your reads; stop reading by the tenth turn and write.
+
+First line: one of `recapture` (a screenshot is missing, blank or shows the wrong thing; list what to recapture and stop), `rebuild` (the first viewport fails the idea or the theme wholesale), `fix` (findings follow), `ship` (nothing owed).
+
+Then the findings, ranked by cost to the page, at most eight, one line each: the gate or the plain defect, where it is, what you would do. Not findings: a direction you would not have chosen; what the theme file prescribes or refuses (its blooms, a glow on a theme with none); an element the hero review settled, unless you name a new reason. The theme's picture is the bar for finish and never a model: is this page as finished as that one, in a composition of its own?
+
+Scroll the 1440 full page one screen at a time before ranking: a screen with nothing big enough to be its reason (a head and a line adrift, a narrow column beside an empty half, a section head under 40px, an empty coloured box or a drawn illustration where a photograph or the product should be, a row of counting marks) outranks every detail finding (`layout.md` § 8). Then the copy: name any head that would pass unchanged on a competitor's page (`craft.md` § 6).
+
+Then one answer to the question no gate can: does the stamp's idea or theme describe the page in front of you? Name the largest gap, or say there is none.
+
+On a custom run (`theme: custom`) the page owes no shape, composition or hero layout: it was designed from nothing, so judge it as a design, never against `layout.md`. Before the idea line, write two lines of your own from the screenshots: what the page is about, and the one thing a visitor would remember. Then three findings when they fail. **Seen before:** the page, or a section, reads as a template, a catalog theme or a familiar site; name which and where. **Clean:** something is on the page without a job (a device repeated, a decoration, a box around nothing), or a screen has nothing worth looking at. **Carried:** the idea lives in the hero and stops there.
+
+On a redesign you also get the `before` screenshots, and the content is fixed: never ask for copy, an action or a visual the old page did not have. Add one answer: what did the old page do better? Name anything a visitor could do, read or find before that is harder now; if nothing, say so. On a polish you get only the full pages at 1440, before and after: the layout was kept on purpose, so ask one thing, whether anything still reads as machine-made, in at most five findings.
+
+On an app screen (the stamp says `shape: app screen`) there is no hero, fold or section rhythm to judge, and the gates `flow.md` § App screens skips are not findings. Read the full screens at 1440 and 375 and ask what someone fluent in the category would: is the hierarchy clear, is the density even, does every control and table work on a phone, are the states there.
+
+Close with one line naming what must not be diluted while fixing. Where the theme file and its picture disagree, the theme file wins over its picture. Do not fix anything.

package/skills/hallmark/references/review-hero.md

@@ -0,0 +1,20 @@
+# Hero review
+
+You are reviewing the first screen of a page that is still being built. You did not build it and will not be told why anything is the way it is. Your inputs, and nothing else: the four `hero-*` screenshots, the stamp's first two lines, the Picks block's Material and Signature rows, and on a theme build the theme's picture. Batch your reads; stop reading by the tenth turn and write.
+
+First line: `ship` or `fix`.
+
+Then at most five findings, one line each, worst first. Ask:
+
+- Does the headline say something only this product could say, in seven words or fewer?
+- Is the content centred in the screen, or does it stop early over a band of nothing? Is the visual beside the text, a real picture (the user's, a photograph, the product built), and does it hold its half of the screen at 60% of its height or more? Where the shape puts no image in the fold (a Marquee, a Poster or a Banner hero), the type is the visual: does it fill the screen? At 1920 the container and the type hold their 1440 size by rule, so extra air there is not a finding.
+- Does anything read as a template: a centred stack, a pill or a label above the headline, a gradient blob, an empty coloured box where a picture should be, a drawn illustration, a row of counting marks, two filled buttons side by side? A filled primary beside an outlined or text action that goes somewhere else is the control pair, and a sample of the product built in a slot is the product; neither is a finding. Grey bars or outline cards inside a slot are.
+- Is the page's signature, its strongest real thing, on this screen? Delete the picture in your head: if the screen still says the same thing, the picture is too weak or too small.
+- Does the type carry the theme at this size?
+- With the theme's picture: is this first screen as finished as its first screen, in a composition of its own?
+
+On a custom run (`theme: custom`) the composition is free: skip the centred, beside-the-text and 60% questions, and ask instead whether this screen is one you would expect a model to make for this prompt. If it is, say what gives it away.
+
+On a redesign the page's content is fixed and what sits below the first screen is the old page, not yet rebuilt: neither is a finding. Never ask for copy, an action or a visual the page does not have; say in one line what the owner could supply.
+
+What the theme file prescribes (its blooms, its control pair) or refuses is not a finding. Where the theme file and its picture disagree, the theme file wins over its picture. Do not fix anything.

package/skills/hallmark/references/scroll-choreography.md

@@ -0,0 +1,110 @@
+# Scroll choreography: the one earned pattern
+
+The default is still none: the reveal-once in `craft.md` § 5 is the page norm. This file is the exception: a scroll-linked pattern used once, on structure, when the content has a sequence worth pinning or scrubbing. sloplint's F8 counts pattern families and flags a second one.
+
+## Budget
+
+- **One pattern per page.** Two scroll behaviours compete for the same attention.
+- **Never on body text.** Targets are structural: a pinned section, one display element, a 2px spine, figures. Prose never moves under the reader.
+- **Hero entrance rules unchanged.** The page-load orchestration in `craft.md` § 5 stays as is; scroll choreography never replaces it, and no element carries both.
+- **Static end-state mandatory.** Base CSS shows the finished layout. The choreography lives entirely inside `@supports (animation-timeline: view())` and `@media (prefers-reduced-motion: no-preference) and (min-width: 40rem)`; reduced motion, small screens and browsers without support get the complete page.
+- **Order matters:** the `animation` shorthand resets `animation-timeline` and `animation-range`, so declare them after it.
+- **`linear` is correct here:** scrubbing maps scroll distance to progress one to one; an easing curve detaches the page from the thumb.
+- A pattern counts as one of the page's three motion primitives (`microinteractions.md`).
+
+## 1 · Pinned chapter: steps reveal while the section is pinned
+
+The tall track owns a named view-timeline; the pinned pane's steps consume it in slices. (Elements inside a stuck pane cannot drive their own `view()`: they are not moving.)
+
+```html
+<section class="chapter">
+  <div class="chapter__pin">
+    <h2>How it works</h2>
+    <ol class="chapter__steps"><li>…</li><li>…</li><li>…</li></ol>
+  </div>
+</section>
+```
+```css
+.chapter { min-height: 280vh; }                          /* track length = pin duration */
+.chapter__pin { position: sticky; top: calc(var(--banner-height, 0px) + var(--space-xl)); }
+@supports (animation-timeline: view()) {
+  @media (prefers-reduced-motion: no-preference) and (min-width: 40rem) {
+    .chapter { view-timeline: --chapter block; }
+    .chapter__steps li { animation: chapter-step linear both; animation-timeline: --chapter; }
+    .chapter__steps li:nth-child(1) { animation-range: contain 5% contain 30%; }
+    .chapter__steps li:nth-child(2) { animation-range: contain 30% contain 55%; }
+    .chapter__steps li:nth-child(3) { animation-range: contain 55% contain 80%; }
+    @keyframes chapter-step { from { opacity: 0.2; transform: translateY(8px); } to { opacity: 1; transform: none; } }
+  }
+}
+```
+
+## 2 · Scrub-linked headline: one display element, clip wipe
+
+For a mid-page Statement head (`layout.md` § 5), never the hero `h1`, whose entrance is the load reveal. One element a page.
+
+```css
+.statement__head { /* base: fully drawn */ }
+@supports (animation-timeline: view()) {
+  @media (prefers-reduced-motion: no-preference) and (min-width: 40rem) {
+    .statement__head {
+      animation: head-wipe linear both;
+      animation-timeline: view();
+      animation-range: entry 20% cover 45%;
+    }
+    @keyframes head-wipe {
+      from { clip-path: inset(0 100% 0 0); transform: translateX(-0.25em); }
+      to   { clip-path: inset(0 0 0 0); transform: none; }
+    }
+  }
+}
+```
+
+## 3 · Progress spine: `scroll(root)` scaling a 2px rule
+
+Reading progress as a hairline, not a chrome bar. A functional indicator, so `linear` is canon. Hidden below 40rem (it eats the mobile gutter).
+
+```css
+.spine { position: fixed; inset-block: 0; left: max(1rem, 2vw); width: 2px; background: var(--color-rule); }
+.spine::after { content: ""; position: absolute; inset: 0; background: var(--color-accent);
+  transform-origin: top; transform: scaleY(0); }
+@media (max-width: 40rem) { .spine { display: none; } }
+@supports (animation-timeline: scroll()) {
+  @media (prefers-reduced-motion: no-preference) and (min-width: 40rem) {
+    .spine::after { animation: spine-grow linear both; animation-timeline: scroll(root); }
+    @keyframes spine-grow { to { transform: scaleY(1); } }
+  }
+}
+```
+
+## 4 · Sticky diptych: a two-pane pin
+
+The structure is a Split (`layout.md` § 5) with one side pinned: `.sticky-stack { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: var(--gap-columns); }`, `.pane-sticky { position: sticky; top: calc(var(--banner-height, 0px) + var(--space-xl)); align-self: start; z-index: var(--z-sticky); }` (it docks below a sticky nav, 56), `.pane-scroll { display: grid; gap: var(--space-2xl); }`, each figure at 16:10 and 440px tall or more; under 60rem one column and `position: static`. The choreography adds only this: the scrolling figures fade in on their own `view()` (they move, so self-timelines work); the pinned side holds from one diptych to the next.
+
+```css
+/* base: .sticky-stack grid + .pane-sticky pin, above; the pinned side holds down the page */
+@supports (animation-timeline: view()) {
+  @media (prefers-reduced-motion: no-preference) and (min-width: 40rem) {
+    .pane-scroll figure { animation: fig-in linear both; animation-timeline: view();
+      animation-range: entry 0% entry 60%; }
+    @keyframes fig-in { from { opacity: 0.3; transform: translateY(12px); } to { opacity: 1; transform: none; } }
+  }
+}
+```
+
+## JS fallback (optional, shared)
+
+When JS is present and `animation-timeline` is not, the one fallback is the reveal-once in `craft.md` § 5, never a scroll listener or a scrub polyfill:
+
+```html
+<script>
+  if (!CSS.supports('animation-timeline: view()')) {
+    const io = new IntersectionObserver((es) => es.forEach((e) => {
+      if (e.isIntersecting) { e.target.classList.add('is-seen'); io.unobserve(e.target); }
+    }), { rootMargin: '0px 0px -20%' });
+    document.querySelectorAll('[data-reveal]').forEach((el) => io.observe(el));
+  }
+</script>
+```
+
+Pair it with a `--dur-long` `--ease-out` transition to the end state, and hide `[data-reveal]` only under the `.js` class the script adds (62). Without script and without support, the static layout is already the finished page.

package/skills/hallmark/references/texture.md

@@ -0,0 +1,90 @@
+# Texture and print artifacts: a budgeted vocabulary
+
+Loaded only when the picked theme earns texture (affinity table below) or a custom draw's lineage is print. Texture is a treatment with a budget, never ambience: one artifact family per page, tokened opacity, never animated, never under body text at more than a whisper. Grain smeared everywhere is the tic `flow.md` § Harnesses refuses; grain from this file, on a theme that earns it, is craft.
+
+## The budget (binds on every artifact)
+
+- **One artifact family per page.** Grain, halftone, misregistration, scanline or deckle, never two. A risograph print is one family: its grain and its misregistration come from the same drum. A halftone that is a photograph's treatment belongs to the image, not the page, and does not count.
+- **Tokened opacity, declared in the token block:** `--texture-opacity` <= 0.08 page-wide, <= 0.15 scoped to a card or plate. Under running body text, <= 0.05 or nothing. A low-frequency wash (a base frequency of 0.02 or lower: a fibre, a paper tone) tints rather than specks and may run to 0.12 page-wide, with contrast measured on the result.
+- **Never animated.** No drifting grain, no pulsing dots.
+- **`pointer-events: none` and `aria-hidden="true"`** on every overlay; texture never intercepts input, and the retro signal is atmosphere, never a drawn monitor bezel (47a).
+- **Perf:** pure CSS or a data-URI SVG filter; no image requests for texture.
+
+## 1 · Grain (paper)
+
+A speck grain, tokenised:
+
+```css
+:root { --texture-opacity: 0.08; }
+.grained { position: relative; isolation: isolate; }
+.grained::after {
+  content: ""; position: absolute; inset: 0; pointer-events: none; z-index: 1;
+  background-size: 200px 200px; opacity: var(--texture-opacity);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 9 -4'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23g)'/%3E%3C/svg%3E");
+}
+```
+
+The colour matrix turns the noise into discrete specks (alpha is the noise times nine, minus four), so the grain reads at 1x inside the budget; untreated `feTurbulence` at these opacities is a haze nobody sees. On a dark ground the specks must be light: change the matrix's first three rows to `0 0 0 0 1` so each speck is white, keep the opacity. One plate, one accent card, or the page at 0.08 or less when the theme names grain.
+
+## 2 · Halftone (dot field)
+
+A dot screen with a size token:
+
+```css
+:root { --halftone-size: 12px; --halftone-dot: 1.5px; }
+.halftone { background-image: radial-gradient(var(--color-ink) var(--halftone-dot), transparent var(--halftone-dot));
+  background-size: var(--halftone-size) var(--halftone-size); }
+```
+
+Plate fills and section bands. Never under or overlapping type. Dot in ink or one spot colour, never the accent at full field strength.
+
+## 3 · Misregistration (chromatic echo)
+
+Riso's signature, portable to any print-lineage custom run:
+
+```css
+.misreg { position: relative; display: inline-block; isolation: isolate; }
+.misreg::before, .misreg::after {
+  content: attr(data-text); position: absolute; inset: 0; z-index: -1;
+  white-space: nowrap; pointer-events: none;
+}
+.misreg::before { color: var(--color-accent);   transform: translate(-2px, -2px); }
+.misreg::after  { color: var(--color-accent-2, var(--color-focus)); transform: translate(2px, 2px); }
+```
+
+**One focal word per page, in the hero, under the theme's `waive 38iii`; never every heading.** The span is an inline block so the copies sit on the glyphs whatever the head's line-height, and they print behind the ink so the word keeps its colour; only the fringes carry the echoes. The echo colours are the theme's declared spot inks (`--color-accent` and `--color-accent-2` here, or the theme's own echo tokens); the offset stays 1 to 3px (more reads broken, not printed). It may settle once on load over `--dur-long` at most, static under reduced motion; it never loops.
+
+## 4 · Scanline (CRT)
+
+Arcade's recipe; the retro signal is atmosphere, never a drawn monitor bezel (47a):
+
+```css
+:root { --scanline: oklch(from var(--color-ink) l c h / 0.06); }
+body::after { content: ""; position: fixed; inset: 0; z-index: var(--z-raised);
+  pointer-events: none;
+  background: repeating-linear-gradient(transparent 0 2px, var(--scanline) 2px 3px); }
+```
+
+`--scanline` is a page-local decorative token at low alpha. Arcade and arcade-adjacent customs only.
+
+## 5 · Deckle (paper edge)
+
+For plates, tickets, and stubs on print-lineage pages:
+
+```css
+.deckled { box-shadow: inset 0 0 0 1px var(--color-rule);
+  mask-image: radial-gradient(6px at 0 50%, transparent 97%, black);
+  mask-size: 12px 24px; mask-repeat: repeat-y; mask-position: left; }
+```
+
+One edge, one element class per page (a ticket edge, a stamp perforation). Never on cards generally; it is an artifact, not a border style.
+
+## Affinity: who earns texture
+
+A theme earns texture when its Surfaces section names one; a custom draw earns it when its lineage is print (risograph, letterpress, ticket stock, line printer), and then it picks the one artifact that lineage used. The budget above binds every theme, whatever its file says: page-wide grain at 0.08 or less, 0.15 inside one plate, 0.05 or nothing under running text. Examples: Riso (grain and misregistration), Halftone (a dot screen), Paste-up (a fibre wash), Darkroom (film grain), Arcade (scanlines).
+
+**Never:** a texture a theme does not name, grain on a modern-minimal page, two artifact families on one page, or a texture as ambience over everything because the page felt flat.
+
+## Reduced motion and accessibility
+
+The settle-once misregistration and nothing else moves; everything here ships identical under `prefers-reduced-motion: reduce` because nothing animates. Texture never lowers text contrast below the gate-40/41 thresholds: measure contrast on the textured result, not the flat token.