howone 0.1.19 → 0.1.22

package/templates/vite/.howone/skills/hallmark/references/microinteractions.md

@@ -0,0 +1,260 @@
+# Microinteractions
+
+The single biggest gap in 2026's anti-slop canon. Most skills correct typography and colour; very few correct *the small, repeated moments where an interface either feels designed or feels generated.* This file is the correction.
+
+A microinteraction is one event with four parts: trigger → rules → feedback → loops/modes (Saffer). Get any of those wrong and the interface feels uncrafted. Ship them all right and the interface feels *made* — even when nothing else is unusual.
+
+## Principles
+
+- **Motion has intent or motion is cut.** Every animation must clarify, guide, or confirm. If you cannot name what a transition communicates, it is decoration. Decoration is slop.
+- **Silent success.** A successful action does *not* deserve a "Done!" toast. If the user sees the result, they don't need a confirmation. Reserve toasts for failures and for actions that hide their own effect.
+- **Optimism with rollback.** Update the UI immediately on user action. Send the request in the background. If it fails, animate the rollback and offer Undo. Round-trip latency is a perception killer.
+- **Restraint, not restraint-as-personality.** Hallmark is not "no motion." Hallmark is *the right motion in the right place.* A drag handle that springs into focus on grab is good. A page where every card pulses on hover is slop.
+- **Reduced motion is a first-class state, not an afterthought.** Every interaction defines its reduced-motion behaviour explicitly. Default is: collapse spatial motion to opacity crossfade, keep duration ≤ 150ms, preserve functional state changes.
+- **Keyboard first, hover second.** Every hover affordance has a focus equivalent. No interaction is hover-only.
+
+## When to ship motion by default
+
+The skill biases toward motion-cut. But certain archetypes feel **broken without** motion — they're so visually busy (or so number-led) that complete stillness reads as a screenshot rather than an interface. For these archetypes, ship 2–3 small purposeful microinteractions automatically, without waiting for the user to ask.
+
+**Default-on archetypes:** Bento Grid · Stat-Led · Workbench · Marquee Hero · Conversational FAQ
+
+**Default-off archetypes:** Editorial · Manifesto · Letter · Quote-Led · Type Specimen · Long Document · Index-First · Letter
+
+For default-on, pick **two or three** from this menu (never more than three primitives per page):
+
+| Microinteraction | When to ship | Recipe |
+| --- | --- | --- |
+| **Number reveal** | Stat-Led hero, headline numbers anywhere | IntersectionObserver fires on viewport entry; `requestAnimationFrame` counts from 0 to target over 1.2–1.6 s with `--ease-out`. Reduced-motion: skip animation, render final value. |
+| **Pricing card lift** | Pricing tier cards | `translateY(-3px)` + shadow upgrade on `:hover`, 180 ms `--ease-out`. Active state: drop back to `translateY(0)` over 60 ms (the press). |
+| **CTA hover lift** | Primary CTA buttons | `translateY(-1.5px)` + background-fade. 200 ms `--ease-out`. Active state at 60 ms. |
+| **Marquee scroll** | Marquee Hero, customer-logo strip | `@keyframes marquee` `translateX(-100%)` over 40–60 s, infinite. Pauses on hover. Reduced-motion: stops the scroll, shows the first three items. |
+| **Stagger reveal** | Testimonials, feature cards, gallery | IntersectionObserver fires on each card; 100 ms stagger; opacity 0 → 1 + `translateY(8px → 0)`; `--ease-out` 400 ms. **One-shot only — never re-fires on scroll.** |
+| **Recommended-tier pulse** | The middle pricing tier | One-shot `@keyframes pulse-border` 2 s, runs once on viewport entry. Subtle: opacity 0.4 → 1 → 0.4 on the border. Don't loop. |
+| **Caret blink** | *Inside* a typed command (install code, terminal nav, code mockup) — never as standalone decoration | `@keyframes blink` 1 s steps(2) infinite on a 1ch-wide block, placed at the end of a typed command line so it reads as a "you'd type next" affordance. Reduced-motion: solid block, no blink. **Hard rule:** the caret must sit inside `<pre class="code">…▮</pre>` or an N8 Terminal nav line — never as a standalone `<span>` floating in a hero. |
+| **Number tick on data update** | Dashboard live values | See *Number tick* recipe below. |
+
+### Hard rules for default-on motion
+
+1. Every animation respects `prefers-reduced-motion: reduce` — either skip entirely or run at 0.01 s.
+2. **No more than three distinct animation primitives per page.** A counter + a hover-lift + a marquee = three. Don't add a fourth. The temptation to layer "just one more" is the slop pull.
+3. No scroll-linked animations on viewports below 40 rem (existing mobile rule, [`component-cookbook.md` § Mobile collapse](component-cookbook.md)).
+4. No animation longer than 2 s except continuous loops (marquee, ambient breathing, caret blink).
+5. The "if I removed this animation, would anyone notice?" test still applies — but for the default-on set, the answer is "yes, the page would feel screenshot-stiff and the brand would feel thin."
+
+### What never gets default motion
+
+- Body text reveals on scroll. Reading is not a cinematic experience.
+- Background gradient shifts. Distracting.
+- Cursor followers. Always slop.
+- Section-by-section fade-up-stagger. Pick one orchestrated entrance, not twelve.
+- Tab content sliding sideways. Crossfade only (see Tab change recipe below).
+
+When the page is default-off (Editorial, Manifesto, etc.), motion is *opt-in* — the user must ask. Stillness is the brand on those pages.
+
+## The timing canon
+
+Pick from these durations. Do not invent new ones.
+
+| Bucket | Use for |
+| --- | --- |
+| **80–120 ms** | Instant feedback (button press tick, checkbox state, keystroke echo). The brain reads anything in this window as immediate. |
+| **150–200 ms** | Hover state transitions, focus rings appearing, single-property fades, tooltip appears (with delay before — see below). |
+| **250–300 ms** | Modal / dropdown / sheet opens, content fades in, validation icon scales in, tab content crossfade. |
+| **400–500 ms** | Toast slides in, page-load section reveal, complex multi-property transitions, accordion open. |
+| **0 ms** | The right answer surprisingly often. Focus state, keyboard navigation, error appearance — many things should not animate at all. |
+
+Exit durations are 60–75% of the corresponding entrance. A 300ms enter pairs with a 200ms exit. Never the reverse.
+
+## The easing canon
+
+Three curves cover ~90% of UI motion. Tokenise them and never freestyle.
+
+```css
+:root {
+  /* Entering elements — decelerate into place */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+
+  /* Exiting elements — accelerate away */
+  --ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+
+  /* State toggles — symmetrical */
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+  /* Material 3 standard alternative — slightly less aggressive */
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+Spring physics replaces eases for **physical** interactions only — drag-and-drop release, swipe-to-dismiss, picker wheel snap, satisfying button press scale-bounce. Otherwise: ease.
+
+| Spring config | Feel | Use for |
+| --- | --- | --- |
+| `stiffness: 50, damping: 20` | Gentle, no overshoot | Calm reveals; almost an ease |
+| `stiffness: 180, damping: 22` | Snappy, slight overshoot | Drag release; toggle handle |
+| `stiffness: 280, damping: 26` | Stiff, minimal bounce | Picker snap; haptic-like button press |
+| `stiffness: 400, damping: 40` | Very stiff, no bounce | Position corrections; not a spring per se |
+
+**Banned curves:** `ease` (the browser default — flat and uncrafted), `linear` except for progress bars and infinite loaders, anything with overshoot above ~110% (`cubic-bezier(0.34, 1.56, 0.64, 1)` and friends). Bounce is dated and signals templated work.
+
+## Recipes
+
+Each recipe: trigger, what changes, duration, easing, accessibility note. If a recipe is missing here, return to the principles and derive it from them.
+
+### Button press
+
+Trigger: pointer down. Changes: `transform: scale(0.98)` on press, base styling on release. Duration: 100ms in, 150ms out. Easing: in `--ease-in`, out `--ease-out`. A11y: focus ring stays visible; never animate the focus ring's existence.
+
+```css
+.btn {
+  transition: background-color var(--dur-short) var(--ease-out),
+              transform 100ms var(--ease-out);
+}
+.btn:hover { background: var(--color-ink); color: var(--color-paper); }
+.btn:active { transform: translateY(1px); }
+.btn:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 3px; }
+```
+
+### Input focus + label float
+
+Trigger: focus event. Changes: border-bottom colour, label slides up + shrinks, optional subtle background tint. Duration: 200ms. Easing: `--ease-out`. **Critical:** the change happens *before* the user types — Stripe / Linear use this to confirm the field is alive. A11y: `:focus-visible` only, not `:focus`; respect reduced-motion by removing the slide and keeping only the colour change.
+
+### Form validation
+
+Trigger: blur after the field has been touched once (the "touched" pattern), then re-validate on every input. Never validate on every keystroke from the start — it's hostile. Changes: icon scales in (200ms `--ease-out`), border tints, helper text replaces. Three-part error message: what broke, why, how to fix.
+
+### Toast notification
+
+Trigger: action completes (or fails). Stack at one viewport corner; new toasts push existing ones in one direction; existing toasts do **not** reposition when a new one arrives. Duration: 400ms slide-in `--ease-out`, 4–6s dwell, 300ms slide-out `--ease-in`. Pause auto-dismiss on hover/focus. **Use sparingly:** if the action's effect is visible (a row was deleted; you can see the row is gone), no toast. Errors *always* get a toast with retry/undo.
+
+### Modal open / close
+
+Trigger: explicit user action (click, key shortcut). Backdrop fades 300ms `--ease-out`. Content scales 0.96 → 1.0 + opacity 0 → 1, 300ms `--ease-out`. Close: 220ms `--ease-in`, scale 1.0 → 0.98, opacity → 0. Use the native `<dialog>` element — it handles focus trap and `::backdrop` for free. `inert` on background. First focus to first interactive element, not the close button. Reduced motion: opacity-only crossfade, 150ms.
+
+### Dropdown / menu
+
+Trigger: click or key shortcut. Open: 180ms `--ease-out`, optional 30ms-stagger items if there are ≤ 8 of them. Close: 140ms `--ease-in`. Light-dismiss on outside click and Escape. Use the Popover API where available. Anchor positioning: flip when within 16px of viewport edge.
+
+### Tooltip
+
+Trigger: mouse hover (with **800–1000ms delay** to prevent flash on casual movement) OR keyboard focus (with **0ms delay** — keyboard users reached this deliberately, never delay them). Animation: 150ms `--ease-out` opacity. WCAG 1.4.13: tooltip must be hoverable (you can move pointer onto it without it disappearing), persistent (doesn't disappear on accidental movement), and dismissible (Escape).
+
+### Tab change
+
+Trigger: click or arrow-key. Underline slides `transform: translateX()` + width transition, 250ms `--ease-out`. Outgoing content fades 100ms `--ease-in`, incoming fades 150ms `--ease-out` with a 50ms delay. **Never animate the tab content's height** — animate `grid-template-rows: 0fr → 1fr` if the tabs change height.
+
+### Number tick
+
+Trigger: data loaded. Counter increments from 0 to value over 400ms with `--ease-out` applied to the *value*, not the element. Use `Intl.NumberFormat` for locale-correct separators. A11y: announce the final value with `aria-live="polite"`, *not* every tick. Reduced motion: skip the tick, show the final value.
+
+### Copy-to-clipboard
+
+Trigger: click. Changes: button label swaps to "Copied" with a check icon; revert after 2.5s. **No toast.** The label change *is* the feedback. Restore on `mouseleave` if user moves away sooner.
+
+```js
+btn.addEventListener("click", async () => {
+  await navigator.clipboard.writeText(value);
+  btn.dataset.state = "copied";
+  setTimeout(() => delete btn.dataset.state, 2500);
+});
+```
+
+```css
+.copy-btn[data-state="copied"] .copy-btn__label::after { content: "  ✓  Copied"; }
+.copy-btn[data-state="copied"] .copy-btn__label > * { opacity: 0; }
+```
+
+### Drag handle
+
+Trigger: hover (after **1–2s delay** — Notion's pattern). Changes: handle reveals via opacity transition, cursor switches to `grab`. On grab: cursor `grabbing`, ghost element at 50% opacity follows pointer, drop indicator (1px line, accent colour) tracks the nearest valid drop target. Spring stiffness 280 / damping 26 on release-snap. A11y: arrow-key reorder when the row is focused; announce drag state with `aria-live`.
+
+### Optimistic update with rollback
+
+Trigger: any action with a known-correct local prediction (toggle, like, archive, reorder). Changes: state mutates immediately; the row visibly updates. Async request fires. On success: nothing happens — silent success is the marker of taste. On failure: 200ms colour rollback animation + a toast with one Undo button. The toast does not auto-dismiss while the user might still want it.
+
+```js
+const prevState = item.completed;
+item.completed = !prevState; render();
+try {
+  await api.update(item);
+} catch {
+  item.completed = prevState; render();
+  toast({ tone: "error", message: "Couldn't save.", action: { label: "Try again", run: retry } });
+}
+```
+
+### Search-as-you-type
+
+Trigger: input event. Debounce by 250ms before requesting; while debouncing, show a subtle indicator (border opacity or label colour shift). Highlight matches in results with `<mark>`. A11y: announce result count with `aria-live="polite"` after debounce settles, never per keystroke.
+
+### Command palette navigation
+
+Trigger: ⌘K or `/`. Open: instant, no animation. Arrow-keys move selection — **the indicator transitions** between rows (120ms `--ease-out` on the highlight's `transform: translateY()`), but the items themselves don't move. Enter selects. Escape closes. Items stagger-fade in on first open only, never on filter change. The text input stays focused throughout. This is the Linear / Raycast / Vercel pattern.
+
+### Page-load reveals
+
+One orchestrated entrance. Stagger by DOM index, capped at ~500ms total. Use `IntersectionObserver`, never scroll listeners. After first reveal, no more on-scroll animations — let the page just *be there*. Theme-specific themes (Atelier, Salon, Newsprint) skip reveals entirely; that is correct, not a bug.
+
+## The named tells (what AI defaults produce)
+
+These are the microinteraction signatures of generated code. The slop test in [`SKILL.md`](../SKILL.md) checks for them; treat any one as a critical finding.
+
+1. **`transition-all`.** Every property animating, including ones that should be instant (visibility, display, focus rings). Always specify the properties. The class is banned in Hallmark output.
+2. **Universal `hover:scale-105`.** Every card lifts on hover, with no shadow change, no easing specified, no purpose. AI's reflexive "make it interactive" gesture.
+3. **Bouncy overshoot easings.** `cubic-bezier(0.34, 1.56, 0.64, 1)` and friends on UI elements. Tasteless 2018-throwback. Reserve overshoots for genuine physical interactions (drag release).
+4. **Multiple simultaneous hover effects.** A card that translates, scales, shadows, colour-shifts, and rotates on hover. Pick *one* signal.
+5. **Animated gradient backgrounds on hover.** The gradient slides through colour space. Distracting, expensive, communicates nothing.
+6. **Glow halos on text.** Heavy `text-shadow` for "neon" — destroys contrast, hurts legibility.
+7. **Cursor-follower dots.** A trailing dot that lags behind the pointer. Adds nothing; triggers vestibular issues.
+8. **Custom cursors on every interactive element.** Conflicts with OS conventions; users learn nothing about what's clickable.
+9. **Auto-rotating carousels with no controls.** WCAG 2.2.2 violation. Always.
+10. **Parallax on scroll.** Different layers moving at different speeds. Vestibular trigger; rarely serves the content.
+11. **`transition` applied to layout properties.** Animating `width`, `height`, `padding`, `margin`, `top`, `left`. Triggers reflow on every frame. Use `transform` or `grid-template-rows: 0fr → 1fr`.
+12. **Universal scroll-triggered fade-up-stagger.** Every section fades in on intersection. Page never settles. Pick *one* orchestrated entrance.
+13. **Celebratory success toasts.** "Done!" when the user just saved a thing they can see was saved. Silent success is taste.
+14. **Confirmation dialogs for reversible actions.** "Are you sure you want to delete this?" Replace with optimistic delete + Undo toast.
+15. **Spinners with no minimum visible time.** Spinner flashes on/off when the action completes in 80ms. Either delay showing it (150ms) or set a minimum visible duration (300ms).
+16. **Tooltips with the same delay on hover and focus.** Hover should delay 800–1000ms; focus should appear immediately. They are different intents.
+17. **Focus rings that animate in.** The ring fades in over 200ms, leaving keyboard users without an indicator at the start of the transition. Focus rings appear instantly. Always.
+18. **Color-only state change.** A field turns red on error with no icon, no text, no border style change. Fails WCAG 1.4.1 and is unreadable for ~8% of men.
+19. **Toasts that move existing content.** New toast pushes the page down; dismissed toast lets it spring back. Stack toasts; don't shift layout.
+20. **Hover delays on touch.** A `:hover` state that the touch user can never reach because there's no equivalent focus / tap behaviour.
+
+## Theme-aware microinteractions
+
+Microinteractions adapt to the theme. The same button press is louder in Brutal than in Atelier. Apply a multiplier per theme:
+
+| Theme | Duration scale | Easing flavour | Notes |
+| --- | --- | --- | --- |
+| Specimen | 1.0× | `--ease-out` | Default. Restrained. |
+| Midnight | 0.9× | `--ease-out` | Snappy, technical. |
+| Brutal | 0.75× | `--ease-out` (sharper) | Fast, decisive. No spring. |
+| Garden | 1.2× | `--ease-out` | Calm. Springs welcome. |
+| Atelier | 1.3× | `--ease-out` (very gentle) | Generous; almost no movement. |
+| Newsprint | 0× | none | Static. Print metaphor. |
+| Terminal | 0× | none, except caret blink *inside* a typed command (N8 nav, install code) | Print + monospace metaphor. **No standalone blinking cursor** — see the Caret blink row above. The caret only blinks where the user would type. |
+| Manifesto | 0.7× | `--ease-out` (sharp) | Snap into place. |
+| Salon | 1.4× | `--ease-out` (very gentle) | Softest. |
+| Linen | 1.2× | `--ease-out` | Calm. |
+| Almanac | 0.85× | `--ease-out` | Functional, like a reference book. |
+| Sport | 0.7× | `--ease-out` (sharp) | Quick, italic-energy. |
+
+If the theme has duration scale `0×`, you do not animate. The page does not move. That is a deliberate design choice; it is not broken.
+
+## Accessibility ground truth
+
+Every recipe in this file must pass these checks before shipping.
+
+- **`prefers-reduced-motion: reduce`** is honoured. Spatial motion collapses to opacity crossfade ≤ 150ms. Functional state changes (progress bars, spinners) slow but remain.
+- **Focus rings** are 2–3 px, ≥ 3:1 contrast, never animated in/out, present on every interactive element via `:focus-visible`.
+- **Hit targets** ≥ 44 × 44 CSS px on touch surfaces.
+- **No reliance on colour alone** for state. Pair with icon, text, or pattern.
+- **No flashing** above 3 Hz. Even subtle pulse animations need rate caps.
+- **Keyboard equivalents** for every hover affordance. No exceptions.
+- **`aria-live`** on async state updates, but `polite` not `assertive` unless safety-critical.
+
+## When in doubt, cut
+
+Most pages have too much motion, not too little. Before shipping, walk through every animation in your output and ask: *what would happen if this animation were instant?* If the answer is "nothing — the user wouldn't notice", remove the animation. If the answer is "the user would lose information about what changed", keep it.
+
+Reaching for a static answer is a sign of taste. Reaching for more motion is the AI default.

package/templates/vite/.howone/skills/hallmark/references/motion.md

@@ -0,0 +1,109 @@
+# Motion
+
+Most AI-generated motion is scattered — hover lifts on every card, fade-in on every scroll, bouncing icons. Quiet it. One orchestrated moment beats ten small ones.
+
+> For per-interaction recipes (button press, focus, modal, toast, optimistic update, command palette, drag handle, etc.), see [`microinteractions.md`](microinteractions.md). This file is the *language* of motion; that file is the *vocabulary*.
+
+## Principles
+
+- **Animate only `transform` and `opacity`.** These are GPU-composited; they don't trigger layout. Anything else is a performance bug waiting.
+- **Duration is three buckets.** Micro (100–150ms), minor (200–300ms), major (300–500ms). Exits are ~75% of the enter.
+- **Easing is exponential ease-out.** Elements coming in slow down into place. Elements leaving accelerate away.
+- **Motion serves perception.** If you can't explain what a transition communicates, cut it.
+- **Reduced motion is non-optional.** `@media (prefers-reduced-motion: reduce)` collapses all spatial motion to opacity crossfade.
+
+## Easings
+
+Use these three. Name them as tokens.
+
+```css
+:root {
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);        /* elements entering */
+  --ease-in:  cubic-bezier(0.7,  0, 0.84, 0);       /* elements leaving  */
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);    /* state toggles     */
+}
+```
+
+`ease`, `ease-in-out` (default), `cubic-bezier(0.25, 0.1, 0.25, 1)` — these are the browser defaults and they read as uncrafted.
+
+## Durations
+
+```css
+:root {
+  --dur-micro: 120ms;   /* button press, toggle tick, color shift  */
+  --dur-short: 220ms;   /* hover lift, tooltip, menu open          */
+  --dur-long:  420ms;   /* modal, drawer, accordion, page reveal   */
+}
+```
+
+Exits use roughly 75% of the enter:
+
+```css
+.menu.is-open  { transition: transform var(--dur-short) var(--ease-out); }
+.menu.is-close { transition: transform calc(var(--dur-short) * 0.75) var(--ease-in); }
+```
+
+## Page-load orchestration
+
+One sequence on page load. Stagger by DOM index using a CSS custom property, not by JS.
+
+```html
+<section style="--i: 0">…</section>
+<section style="--i: 1">…</section>
+<section style="--i: 2">…</section>
+```
+
+```css
+.reveal {
+  opacity: 0;
+  transform: translateY(8px);
+  animation: reveal var(--dur-long) var(--ease-out) forwards;
+  animation-delay: calc(var(--i, 0) * 60ms);
+}
+@keyframes reveal {
+  to { opacity: 1; transform: none; }
+}
+```
+
+Cap total stagger at ~500ms. Beyond that the page feels slow to settle.
+
+## Scroll-linked motion
+
+- Use IntersectionObserver, **never** `scroll` event listeners.
+- Use it only for *reveal once* effects. No parallax. No scroll-scrubbed animations unless there is a specific reason.
+- Every scroll-triggered motion must have a reduced-motion fallback.
+
+## State transitions
+
+- Button hover / active: micro duration, `--ease-out`, `transform: translateY(-1px)` on hover, `translateY(0)` on active. Never a `box-shadow` transition on hover on a dark background (glow effect).
+- Menu / tooltip / dropdown: short duration, `--ease-out` on open, `--ease-in` on close. Use the popover API or `inert` to manage focus.
+- Modal: long duration, scale-in (0.96 → 1) + opacity crossfade. Backdrop fades in at the same duration.
+- Accordion: animate `grid-template-rows: 0fr` → `grid-template-rows: 1fr` (not `height`). With `--ease-in-out`.
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 150ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 150ms !important;
+  }
+  .reveal { animation: reveal-reduced 150ms linear forwards; }
+  @keyframes reveal-reduced { to { opacity: 1; transform: none; } }
+}
+```
+
+Functional motion (progress bars, loading spinners, skeletons) still runs — just slower.
+
+## Bans
+
+- `ease` (browser default, mediocre).
+- `linear` on anything except progress bars and ticking loaders.
+- Bounce / elastic / overshoot on UI elements. Dated; signals "template".
+- Animating `width`, `height`, `top`, `left`, `margin`, `padding`.
+- `will-change` set preemptively across a whole class. Only on the element, only while it's animating.
+- Parallax.
+- Custom cursors.
+- Scroll-driven animations without a reduced-motion fallback.
+- Infinite loops (other than functional loaders) — they pull the eye and never let go.

package/templates/vite/.howone/skills/hallmark/references/preview-examples.md

@@ -0,0 +1,49 @@
+# Preview-block worked examples
+
+Four sample Step 5 preview blocks for the model to imitate, varied across macrostructure types. Load this file only when picking an unusual macrostructure or custom theme and the bullet-list spec in `SKILL.md § 5. Preview` doesn't give enough scaffolding on its own. Most builds don't need to read this file.
+
+---
+
+*Long Document (editorial, motion-cut):*
+> **Hallmark · v1.0.0**
+>
+> - **Macrostructure** · Long Document
+> - **Theme** · Linen (cool slate paper · steel-blue accent · geometric sans)
+> - **Enrichment** · Tier-B hand-built SVG (a 60-line coffee bean with `@property --rise` 6 s breathing-loop)
+> - **Sections** · Masthead · Letter · Three Notes · Visit · Colophon
+> - **Motion** · breathing-loop on bean only (respects `prefers-reduced-motion`)
+> - **Slop test** · 69 / 69 ✓
+> - **Diversification** · first run for this project
+
+*Bento Grid (SaaS, motion-on):*
+> **Hallmark · v1.0.0**
+>
+> - **Macrostructure** · Bento Grid
+> - **Theme** · Linen (cool slate paper · steel-blue accent · geometric sans)
+> - **Enrichment** · E1 Clipped-Edge Demo Video, Tier-A CSS-art trace waterfall
+> - **Sections** · Hero · 6-tile Bento (stat · sparkline · quote · code · integrations · spotlight) · Index Footer
+> - **Motion** · counter · pricing-lift · CSS marquee on integrations strip
+> - **Slop test** · 69 / 69 ✓
+> - **Diversification** · differs from Plain on paper hue (light-cool vs pure-white) + accent (indigo vs ink-blue)
+
+*Manifesto (declarative, no enrichment):*
+> **Hallmark · v1.0.0**
+>
+> - **Macrostructure** · Manifesto
+> - **Theme** · Manifesto (dark · Inter Tight 900 · single red bleed)
+> - **Enrichment** · none (typography only — voice carries the brand)
+> - **Sections** · Masthead · Title · Five Declarations · Bleed Band · What We Refuse · Working Rules · Practice · Reading · Colophon
+> - **Motion** · none — typography only
+> - **Slop test** · 69 / 69 ✓
+> - **Diversification** · differs from Linen on paper band (dark vs light) + display style (display-heavy vs geometric-sans)
+
+*Custom (Coffeebox archival café):*
+> **Hallmark · v1.0.0**
+>
+> - **Macrostructure** · Long Document
+> - **Theme** · custom (vibe: "archival warmth, hand-set, no varnish" · paper oklch(94% 0.020 65) · accent oklch(58% 0.16 35) terracotta · Fraunces italic display + Source Serif 4 body)
+> - **Enrichment** · Tier-A pure-CSS coffee bean (60-line SVG, breathing-loop optional)
+> - **Sections** · Masthead · Letter · Three Notes · Visit · Colophon
+> - **Motion** · breathing-loop on bean (with reduced-motion fallback)
+> - **Slop test** · 69 / 69 ✓
+> - **Diversification** · custom axes: light / italic-serif / chromatic-terracotta — differs from previous catalog Linen on accent hue + display style

package/templates/vite/.howone/skills/hallmark/references/responsive.md

@@ -0,0 +1,138 @@
+# Responsive
+
+Mobile-first. Content-driven breakpoints. No desktop-only interactions.
+
+## Mobile — non-negotiable
+
+Every Hallmark output must render flawlessly at **320 px, 375 px, 414 px, and 768 px** CSS-pixel widths. Eyeball each viewport before marking the output complete:
+
+- No horizontal scroll (slop-test gate 36)
+- No clickable text wrapping to two lines (gate 59)
+- No image-bearing grid pushing the layout past viewport — use `minmax(0, 1fr)`, never bare `1fr`, on tracks containing images (gate 61)
+- Root carries `overflow-x: clip` on both `html` and `body` — never `hidden` (gate 62)
+- Display headers wrap inside long words via `overflow-wrap: anywhere; min-width: 0` (gate 63)
+- Section heads collapse to one column on mobile across every theme variant — per-theme overrides need a matching mobile rule (gate 64)
+- No scroll-jump on radio-tab clicks — radios in normal flow OR JS guard with `focus({ preventScroll: true })` (gate 65)
+
+This is a hard floor, not a wish list. A page that fails any of these on any of those four widths is not done. The slop-test gates listed run automatically — keep this checklist near the screen while building.
+
+## Principles
+
+- Base styles are for the smallest viewport. `min-width` media queries add as you go up. Never `max-width` as the primary direction.
+- Breakpoints are where the *content* breaks, not where a device sits. If the headline reflows awkwardly at 720px, that's a breakpoint — regardless of what the Tailwind defaults say.
+- Use `pointer` and `hover` media queries instead of width to detect *interaction capability*.
+
+## Breakpoints
+
+Three or four, content-driven. As a default:
+
+```css
+@media (min-width: 40rem) { /* ~640px — tablet, small laptop */ }
+@media (min-width: 60rem) { /* ~960px — desktop baseline */ }
+@media (min-width: 90rem) { /* ~1440px — wide */ }
+```
+
+Use `rem` so the breakpoints respect the user's font size.
+
+## Fluid scaling
+
+Prefer `clamp()` for sizes that change continuously; use media queries for layouts that change discretely.
+
+```css
+h1 { font-size: clamp(2.5rem, 4vw + 1rem, 6rem); }
+.container { padding-inline: clamp(1rem, 4vw, 4rem); }
+```
+
+## Pointer and hover queries
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .card:hover { transform: translateY(-2px); }
+}
+@media (pointer: coarse) {
+  .btn { min-height: 48px; }
+}
+```
+
+Never build a mouse-hover interaction that has no touch equivalent.
+
+## Clickable text — never wraps
+
+Buttons, primary nav links, footer links, tab labels, breadcrumbs, and CTAs must read as **single-line affordances at every viewport between 320 px and 1920 px**. A button or nav link wrapping to two lines looks broken — visitors read it as a styling error, not as intentional. The shortest fix is almost always to shorten the label.
+
+```css
+/* Affordances are single-line — let the parent reflow, not the label. */
+.btn,
+.nav__link,
+.foot__link,
+.cta {
+  white-space: nowrap;
+}
+```
+
+```css
+/* When the row can't fit, collapse the row, not the labels. */
+@media (max-width: 40rem) {
+  .nav__rail { display: none; }      /* desktop nav hides */
+  .nav__sheet-toggle { display: grid; } /* mobile menu shows */
+}
+```
+
+**Order of fixes**, when something does wrap:
+
+1. **Shorten the label.** *"Get started free"* → *"Start free"*. *"Read the documentation"* → *"Read docs"*. *"Schedule a demo"* → *"Book demo"*. Most CTA labels are 30–40 % longer than they need to be.
+2. **`white-space: nowrap`** on the affordance, let the parent flex/grid reflow.
+3. **`hidden=until-found`** the lowest-priority nav item at narrow widths (it remains in DOM for find-in-page and SEO).
+4. **Collapse the nav** into a sheet / off-canvas / disclosure menu below a content-driven breakpoint.
+
+**Never:** let a primary CTA or top-level nav link wrap. Long footer-link labels can wrap *only* in a footer column where wrapping is part of the column's rhythm — not in the inline footer link strip (Ft2).
+
+This is gate **59** in [`slop-test.md`](slop-test.md). Audit any output that ships interactive affordances and confirm none wrap at the breakpoints listed above.
+
+## Viewport units
+
+- Use `dvh` / `svh` / `lvh` instead of `vh` for heights that interact with mobile chrome.
+- Never `width: 100vw`. Use `width: 100%` with padding; `100vw` includes the scrollbar on desktop and causes overflow.
+
+## Safe areas
+
+For iOS notch / Android navigation bars:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+```css
+body {
+  padding-inline: max(1rem, env(safe-area-inset-left));
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+## Tables on small screens
+
+Tables of data that won't fit: collapse to cards. Use `display: block` on `<tr>` and `data-label` attributes keyed from `<th>`, rendered via `::before`. Or, the better option: redesign the data for small screens — tables are rarely the right mobile representation.
+
+## Images
+
+- `srcset` with width descriptors for responsive sizing.
+- `<picture>` for art direction (different crop at different widths).
+- `loading="lazy"` on anything below the fold.
+- `width` and `height` attributes on every image, always, to avoid CLS.
+
+## Internationalisation
+
+- Reserve 30–40% extra horizontal space for German, Russian, and Finnish translations.
+- Use logical properties: `margin-inline-start`, `padding-block`, `border-inline-end`. Not `margin-left` etc. RTL comes for free.
+- Don't hard-code language-specific punctuation or date formats.
+
+## Bans
+
+- Desktop-first media queries (`max-width: 768px` as the primary direction).
+- `vh` on full-height layouts (use `dvh`).
+- `100vw` widths.
+- Device-sniffing UA strings instead of feature queries.
+- Hover-only interactions.
+- Ignoring `prefers-color-scheme` when the app claims to support dark mode.
+- Fixed pixel breakpoints that don't respect `rem`.
+- Tables of 10+ columns on mobile without a redesign.