howone 0.1.20 → 0.1.23

package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md

@@ -0,0 +1,170 @@
+# Imagery kit — curated abstract assets, hosted, ready
+
+A small set of pre-generated abstract / decorative imagery that any Hallmark output can pull from when a brief allows non-photographic imagery. The kit lives at:
+
+```
+https://www.usehallmark.com/imagery/<category>/<file>
+```
+
+The skill doesn't ship the binaries — it ships the manifest. References are absolute URLs. If the asset is missing (404), the skill falls back to source canon #2 in [`assets.md` § Placeholder strategy](assets.md) (hand-built SVG) without erroring.
+
+**Why this exists.** The v0.9.0 watercolor sprinkle was generated per-emit and was inconsistent. The kit recovers that aesthetic but as discrete, swappable, deliberately-composed assets. Compose with them like a senior frontend engineer: layered transparent PNG behind text, biased off-centre, intentionally large, mix-blend-mode where it earns its place. Not "abstract gradient on top of headline" — that's the AI default.
+
+---
+
+## Categories
+
+| Category | What | Format | Example uses |
+| --- | --- | --- | --- |
+| **watercolor** | Full-bleed soft-edge painterly fields. Warm + cool variants per palette family. | WebP | Section background accent; hero-half flood; behind-quote wash. |
+| **transparent** | Organic blob / brushstroke / stylized mark on transparent background. | PNG | Layered hero composition (large, off-centre, behind text). The masterclass move. |
+| **ornament** | Small hand-drawn stamps, plates, roman numerals, decorative flourishes. | SVG | Beside a quote; in the section-label gutter; closing a letter. |
+| **texture** | Subtle paper, weave, riso-dot, cross-hatch fields. Tile-able. | WebP | Body grain via `mix-blend-mode: multiply`; section-divider banding. |
+| **silhouette** | Abstract bottle / box / device / book / mug / card shapes. | PNG | Empty product slots before user uploads photos; comparison rows. |
+| **pattern** | Repeating motifs that read as fabric / paper / printed material. | WebP | Section-band texture; full-bleed fills behind decorative text. |
+
+**Naming:** `<category>-<palette-family>-<variant>.<ext>` — e.g. `watercolor-warm-01.webp`, `transparent-brush-cool-03.png`, `ornament-stamp-01.svg`, `texture-grain-paper-02.webp`. Palette families: `warm` · `cool` · `neutral` · `chromatic`.
+
+---
+
+## Manifest (placeholder until generation pass ships)
+
+When images land in `site/public/imagery/<category>/`, list them here as a key/value catalogue:
+
+```
+watercolor-warm-01.webp     1600×900   warm orange · cream paper      hero half-flood, atmospheric
+watercolor-cool-01.webp     1600×900   cool blue · greyscale          quote-behind wash
+transparent-brush-warm-01   1200×1200  burnt orange brushstroke       layered hero, off-centre
+transparent-blob-cool-01    1200×1200  cobalt organic shape           layered hero, behind headline
+ornament-stamp-01.svg       inline     ink-only stamp w/ numeral      label-gutter, letter close
+texture-grain-paper-01      512×512    cream paper grain (tileable)   body grain, blend-multiply
+silhouette-bottle-01.png    600×900    abstract bottle, transparent   empty product slot
+silhouette-card-01.png      900×600    abstract product card          comparison row
+pattern-cross-warm-01       400×400    cross-hatch warm (tileable)    section-band texture
+```
+
+The skill picks an asset by matching the active theme's palette family + the brief's tone, then references it by absolute URL. Picking logic lives in Step 4 of [SKILL.md](../SKILL.md) — eyeball the manifest, choose the closest match, fall back if the file 404s.
+
+---
+
+## Usage patterns — how a senior engineer would compose these
+
+### Layered hero composition (the masterclass move)
+
+A transparent abstract object behind hero text. The image is bigger than you think it should be — that's what makes it feel intentional, not decorative.
+
+```css
+.hero { position: relative; isolation: isolate; }
+
+.hero__art {
+  position: absolute;
+  top: 50%;
+  right: -10%;
+  transform: translateY(-50%);
+  width: clamp(60%, 80vh, 1400px);
+  height: auto;
+  z-index: 0;
+  pointer-events: none;
+  /* Optional warmth: */
+  mix-blend-mode: multiply;
+  opacity: 0.85;
+}
+
+.hero__art--bias-left  { right: auto; left: -10%; }
+
+.hero > * { position: relative; z-index: 1; }
+```
+
+Bias to one side (left or right, never centred). The text sits at `z-index: 1`, the art at `z-index: 0`. Test mobile: art may need to scale down or shift to avoid the headline at 320 px.
+
+### Section background wash
+
+A watercolor file as a full-bleed section accent. One section per page, never global.
+
+```css
+.section--wash { position: relative; isolation: isolate; }
+.section--wash::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: url("https://www.usehallmark.com/imagery/watercolor/watercolor-warm-01.webp") center / cover no-repeat;
+  opacity: 0.6;
+  z-index: -1;
+  pointer-events: none;
+}
+```
+
+### Decoration
+
+Inline ornament beside a quote or in the section-label gutter. Small. No border, no shadow, no animation.
+
+```html
+<p class="section-label">
+  <span class="num">02</span>
+  <img class="section-label__ornament" src="…/imagery/ornament/ornament-stamp-01.svg" alt="" aria-hidden="true" />
+  <span>Examples</span>
+</p>
+```
+
+```css
+.section-label__ornament { width: 1.5em; height: auto; vertical-align: middle; }
+```
+
+### Texture overlay
+
+Grain over a solid colour. Always opacity-capped at `0.15`.
+
+```css
+.texture-grain {
+  background-image: url("…/imagery/texture/texture-grain-paper-01.webp"), var(--paper-fill);
+  background-size: 256px 256px, cover;
+  background-blend-mode: multiply;
+  opacity: 1; /* the grain texture is at 0.15 in the source asset */
+}
+```
+
+### Empty state
+
+Generic silhouette in unfilled data slots, greyscale-tinted, with a "Replace with real photo" hint visible to the developer (HTML comment).
+
+```html
+<!-- TODO: Replace with real product photo, target size: 600×900 -->
+<picture class="product-card__photo product-card__photo--empty">
+  <img src="…/imagery/silhouette/silhouette-bottle-01.png" alt="Hand-poured ceramic vessel, studio lighting" />
+</picture>
+```
+
+---
+
+## Anti-patterns
+
+- **Don't use kit imagery as the literal subject.** An abstract bottle is *not* a stand-in for an actual coffee-shop hero — those need photographic placeholders (Picsum / Unsplash). The kit is for atmosphere / composition / decoration, not subject replacement.
+- **Don't layer 3+ kit pieces on one page.** Restraint. One transparent object in the hero + one wash in a later section is the cap.
+- **Don't apply the same watercolor wash to multiple sections.** It's a section accent, not a global treatment.
+- **Don't use kit imagery in modern-minimal genre** (Stripe / Linear / ElevenLabs school). That genre's whole point is the absence of decorative imagery.
+- **Don't centre the layered hero art.** Centred behind text is the AI-default move. Bias to one side, off-axis.
+- **Don't use mix-blend-mode without testing on the active paper.** `multiply` over a dark canvas inverts; `screen` over light paper washes out. Eyeball the result per theme.
+
+---
+
+## Generation pipeline (out-of-band, one-time)
+
+The kit is generated once per palette family, post-processed, and committed to the marketing site's public folder:
+
+```
+site/public/imagery/
+  ├── watercolor/        ~6 files × 4 palette families = 24 WebPs
+  ├── transparent/       ~6 files × 4 palette families = 24 PNGs
+  ├── ornament/          ~8 SVGs (palette-agnostic, use currentColor)
+  ├── texture/           ~6 tile-able WebPs
+  ├── silhouette/        ~6 PNGs (palette-agnostic, transparent)
+  └── pattern/           ~6 tile-able WebPs
+```
+
+**Tooling.** Nanobanana 2 / Recraft V4 with reference images. Prompt seed-list per category lives at the top of each file's directory in a `prompts.md` (one-line prompts, results pinned by seed for reproducibility).
+
+**Post-processing.** Trim, transparent-background where applicable, colour-balance against Hallmark's OKLCH palette tokens, save as WebP for size + PNG where alpha matters. Ornaments as inline SVG so they inherit `currentColor`.
+
+**Total target weight.** ≤ 5 MB across all categories. Each individual file ≤ 200 KB. Lossy WebP at q=80 unless the image needs lossless (ornaments → SVG; transparents → PNG with `pngquant`).
+
+**Re-generation.** Treat the kit as a refreshable batch, not a one-off. When the palette catalogue changes (new theme, new accent hue), re-generate the relevant palette family. Manifest above is the spec; assets are the deliverable.

package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md

@@ -0,0 +1,207 @@
+# Interaction and states
+
+Every interactive element has eight states. Most AI-generated UI styles two (default, hover) and forgets the rest. That's where interfaces break.
+
+## The eight states
+
+| State | When | Treatment |
+| --- | --- | --- |
+| Default | At rest | Base styling |
+| Hover | Pointer over (only with `@media (hover: hover)`) | Small shift: colour, 1px translate, subtle border |
+| Focus | Keyboard or programmatic focus | Visible ring, `:focus-visible` |
+| Active / Pressed | During press | Pressed-in: darker, translate(0 1px) |
+| Disabled | Not interactive | Reduced opacity (0.5) + `cursor: not-allowed` + `aria-disabled` |
+| Loading | Processing | Inline spinner or progress, label stays readable |
+| Error | Failed state | Red border, error icon, message, `aria-invalid` |
+| Success | Completed | Green check, confirmation, auto-dismiss |
+
+If any of these is missing on a production element, the element isn't finished.
+
+## Focus rings
+
+Visible, always, on every interactive element. The default focus ring most browsers give you is fine; a custom one is better.
+
+```css
+:focus { outline: none; }
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+  border-radius: inherit;
+}
+```
+
+Requirements:
+
+- 2–3px, ≥ 3:1 contrast against both element and page.
+- 2px offset from the element.
+- `:focus-visible`, not `:focus`, so it's keyboard-only.
+- Never `outline: none` without a replacement. `outline: none` with no other focus style is the most common accessibility bug and an immediate audit failure.
+
+## Hit targets
+
+Minimum 44×44 CSS px for any touch-reachable element. Use padding or an `::before` overlay to expand the hit target without changing visual size:
+
+```css
+.icon-btn {
+  position: relative;
+}
+.icon-btn::before {
+  content: "";
+  position: absolute;
+  inset: -12px;
+}
+```
+
+## Forms
+
+- Labels above inputs. Visible. Never placeholder-as-label.
+- Placeholders show format, not instruction. `Placeholder: 01 Jan 2026`, not `Placeholder: Enter your birth date`.
+- Helper text below input. Error text replaces helper text.
+- Validate on **blur**, not on every keystroke. Revalidate on change once the field has been blurred once (the "touched" pattern).
+- Error message: (1) what broke, (2) why, (3) what to do. One sentence if possible.
+- Associate errors with `aria-describedby`. Set `aria-invalid="true"` on the field.
+- Required fields marked with `aria-required`, never with colour alone.
+- Disable the submit button only when the form is in a known-invalid or in-flight state. Never on idle.
+
+## Input field states — the exhaustive checklist
+
+This is where the most "almost right" UIs lose. An input field with two states (default + hover) and a different border-width on focus reads as a default settings page — the geometry shifts, the eye notices, the page feels untuned. Every text input, textarea, select, and combobox must satisfy every rule below.
+
+### The no-layout-shift rule
+
+**Border thickness is constant across every state.** Default · hover · focus · error · disabled — the `border-width` value never changes. Layout shift on focus is a tell. State changes go to `background-color`, `outline`, or `box-shadow`, never to `border-width`.
+
+```css
+.input {
+  border: 1px solid var(--color-rule-2);   /* 1px, always — every state */
+  outline: 2px solid transparent;          /* reserved slot for focus ring; no shift on activate */
+  outline-offset: 1px;
+}
+```
+
+The outline starts transparent at 2 px so when the focus ring appears, the box geometry is already correct. No layout shift. No paint thrash.
+
+### State-by-state recipe
+
+| State | Treatment | Why |
+| --- | --- | --- |
+| **Default** | `border: 1px solid var(--color-rule-2)` · `background: var(--color-paper)` · placeholder in `var(--color-muted)` | Visible field, readable empty signal |
+| **Hover** | `background: var(--color-paper-2)` (4–6 % darker than paper) · border unchanged | Subtle background shift, no border flash. Border colour changing alone is missable. |
+| **Focus** | `outline: 2px solid var(--color-focus)` · `outline-offset: 1px` · border may deepen to `var(--color-ink-2)` but width stays 1 px | Outline is the focus signal; never animated; ≥ 3:1 contrast against page AND field. |
+| **Active / typing** | Same as focus. Don't add a separate "typing" state. | Focus already says "active here". A second signal is noise. |
+| **Filled** | Same as default — the value carries the state. Optionally a subtle ink-2 border to visually distinguish from empty. | Don't fight the user's content with a styled chrome change. |
+| **Disabled** | `opacity: 0.55` · `cursor: not-allowed` · placeholder `var(--color-rule-2)` · `aria-disabled="true"` · `tabindex="-1"` | Three independent signals (opacity + cursor + colour) so no single channel carries the whole load. |
+| **Error** | `border-color: var(--color-error, oklch(58% 0.20 25))` · helper-text replaced by error message · `aria-invalid="true"` · small ⚠ glyph at right edge | Border colour flip is OK *because* helper-text and aria signal it too. Never colour alone. |
+| **Success** | Subtle accent-coloured border (3 % chroma above default) · small ✓ glyph · auto-clear if user re-edits | Quiet; success doesn't deserve celebration unless it was hard. |
+| **Loading** (validating, async) | Inline spinner at the right edge replacing the standard glyph slot · field stays editable but submit disabled | Don't lock the user out of the field. They may want to fix what they typed. |
+
+### Heights and rhythm
+
+- **Input height = button height.** A page with 44 px buttons and 38 px inputs feels untuned. Pick one base height (44 px is the touch-target floor) and apply it to every text input AND every adjacent button.
+- **Vertical padding = `(height − line-height-px) / 2`.** No magic numbers.
+- **Right-edge slot reserved.** Every input reserves a ~24 px right-edge slot for an optional clear button, error glyph, or loading spinner. If unused, the slot sits empty — never reflow on icon appearance.
+
+### Labels, helper, error
+
+- **Label above** the input, 4–8 px gap. Never inline (placeholder-as-label is a tell).
+- **Helper text below**, ~4 px gap. Same `font-size` as the label, lower visual weight.
+- **Error replaces helper** — same position, same size, error colour. Never both at once (causes vertical jump on validation).
+- **Helper has stable height.** Reserve a 1-line height even when empty, so adding an error doesn't push the page down. CSS: `min-height: 1lh` on the helper container.
+
+### Don't, list
+
+- Don't transition `border-width`, `padding`, or `height` on any state. Always layout-shift.
+- Don't transition the focus ring's `opacity` or `transform`. Focus must be instant.
+- Don't put hover effects inside `@media (hover: hover)` — wait, *do* put them inside `@media (hover: hover)` so touch users don't get stuck states.
+- Don't disable the field as a way to indicate "wait, loading" — use a loading state with the field still editable.
+- Don't change `cursor` on `:focus`. The pointer is already a beam; don't fight it.
+- Don't use `outline: none` on focus without an explicit replacement.
+
+### Specific control overrides
+
+- **Textarea.** Same rules as input, plus `resize: vertical` (never `none`, never `both` on a small textarea), `min-height: 6rem` for multi-line UX.
+- **Select.** Custom-styled `<select>` only if you can replicate native a11y (keyboard, screen-reader). Otherwise leave it native and style the wrapper.
+- **Checkbox / radio.** Use `accent-color: var(--color-accent)` for cheap correct styling on modern browsers; only build a custom one when the design requires it. If custom: still a 1 px outline-offset focus ring.
+- **Toggle / switch.** It IS a checkbox. Same a11y rules. The visual design doesn't change the contract.
+- **Range / slider.** The thumb gets focus state, not the track. Thumb hit-target ≥ 44 px even if visual size is smaller (use a transparent expansion).
+- **File input.** Always wrap in a styled label. Native `<input type="file">` is unstyleable; the label is the surface.
+- **Combobox / search.** Listbox sits below, `aria-expanded` mirrors visibility, arrow-keys cycle, Enter selects, Escape closes — and the listbox doesn't push page content (use `position: absolute` + a parent `position: relative`).
+
+## Modals and overlays
+
+- Use the native `<dialog>` element. It handles focus trap, escape to close, and `::backdrop` styling for free.
+- Set `inert` on the page content behind a modal so tab order doesn't leak.
+- Close on: escape key, backdrop click, explicit close button.
+- First focus goes to the first interactive element, not the close button.
+
+## Dropdowns, tooltips, popovers
+
+- Use the Popover API (`popover` attribute). It handles light-dismiss, stacking, and escape for free, and works in every modern browser.
+- Position with CSS Anchor Positioning where it's available; fall back to `position: fixed` + `getBoundingClientRect()`.
+- Never put a dropdown inside an `overflow: hidden` container without escape. It will clip.
+- Flip when near the viewport edge.
+
+## Undo over confirm
+
+- For reversible actions, skip the confirm dialog. Do the thing. Show a toast with an Undo button for 5–10 seconds.
+- For destructive, irreversible actions (delete account, drop table), keep the confirm — and make the user type the thing being destroyed, not just click "OK".
+
+## Loading and empty states
+
+- **Skeleton** screens over spinners for content that has a predictable shape (lists, cards, tables).
+- **Inline spinners** for in-button state. Replace the label, don't add beside it.
+- **Empty states** always have: an illustration or icon (a small one), a one-line explanation of why it's empty, an action to fix it.
+- Never show a generic "No results" with no context.
+
+## Bans
+
+- Placeholder-as-label.
+- Hover-only functionality (touch users can't hover).
+- Focus rings removed without replacement.
+- Confirmation dialogs for low-stakes actions.
+- Touch targets < 44px.
+- Custom cursors on interactive elements.
+- Disabled elements with no explanation of why they're disabled.
+- Colour-only error states.
+- Spinners where a skeleton would show layout.
+
+---
+
+## Contrast discipline
+
+Hallmark output must pass slop-test gates 46–50 before shipping. Compute contrast for every `(color, background-color)` pair on the page. The common failures Hallmark output trips on:
+
+1. **Text on a flipped surface.** `.section--ink { background: var(--color-ink); }` flips the surface dark; nested text still inherits `color: var(--color-ink)` → ink-on-ink. Fix: any rule that sets a dark `background` must *also* set `color: var(--color-paper)` in the same rule.
+2. **Button text on accent fill.** `background: var(--color-accent); color: white;` — but white is 4.5:1 against this accent only if `--color-accent` is dark enough. Use `var(--color-accent-ink)` instead, which the theme guarantees passes ≥ APCA Lc 60.
+3. **Muted text on tinted paper.** `color: var(--color-muted); background: var(--color-paper-3);` — both mid-lightness, often falls below 4.5:1. Use `--color-neutral` (darker) or lift the background to `--color-paper`.
+4. **Focus ring on accent-coloured button.** `outline: 2px solid var(--color-focus);` on a button whose fill is `--color-accent` — if `--color-focus = --color-accent`, the ring vanishes. Use the contrast pair: `--color-focus` set to a colour with ≥ 3:1 against both the element and the page.
+
+### Computation
+
+For each `(text-colour, background-colour)` pair the page actually renders:
+
+- Run **APCA Lc** (preferred — perceptual) or **WCAG 2.1 ratio**.
+- Pre-check: if both are in OKLCH with `|L_a − L_b| < 50 %`, flag for full check.
+- Body text passes at **APCA Lc ≥ 60** ≈ WCAG 4.5:1.
+- Large text / focus rings / icons pass at **APCA Lc ≥ 45** ≈ WCAG 3:1.
+
+### Token contract
+
+Every theme MUST define `--color-accent-ink` — the text colour to use whenever `--color-accent` fills a surface that carries text. The accent-ink colour is verified ≥ APCA Lc 60 against the accent at the time the theme is built. Hallmark code that uses `background: var(--color-accent)` must also set `color: var(--color-accent-ink)`. Falling back to hardcoded `color: white` is a tell — the theme's accent could be a light colour, and white-on-light is the bug.
+
+### When the surface flips
+
+The rule: **any rule that overrides `background-color` must also state the appropriate `color`.** Don't rely on inheritance for surface-flipping classes. Example:
+
+```css
+/* WRONG — text inherits color: var(--color-ink); section is now dark; ink-on-ink */
+.section--manifesto { background: var(--color-ink); }
+
+/* RIGHT */
+.section--manifesto {
+  background: var(--color-ink);
+  color: var(--color-paper);
+}
+```
+
+Same applies to per-theme overrides like `[data-theme="manifesto"] .vs__col:first-child { background: var(--color-ink); }` — set `color: var(--color-paper)` at the same time, OR declare the rule on a parent and let descendants inherit explicitly.

package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md

@@ -0,0 +1,111 @@
+# Layout and space
+
+Layout is where "AI-generated" gets caught. Equal columns, everything centred, every card identical — these are the tells.
+
+## Principles
+
+- A layout has a **primary axis**. Left-biased, right-biased, top-heavy, or bottom-weighted. Centre-biased is a default, not a choice.
+- **Asymmetry reads as intentional.** Symmetry reads as generated. When in doubt, shift.
+- **Spacing is a scale, not a value.** Pick one scale. Use it everywhere. Don't type raw px.
+- **Varied spacing.** If every gap is 24px, the page is a template. Mix small, medium, and large gaps within the same layout.
+- **Break the grid on purpose.** A page with one element crossing the grid is stronger than a page that never does.
+
+## The spacing scale
+
+4pt base. Nine steps. Named by role, not size.
+
+```css
+:root {
+  --space-3xs: 0.125rem;  /*  2px */
+  --space-2xs: 0.25rem;   /*  4px */
+  --space-xs:  0.5rem;    /*  8px */
+  --space-sm:  0.75rem;   /* 12px */
+  --space-md:  1rem;      /* 16px */
+  --space-lg:  1.5rem;    /* 24px */
+  --space-xl:  2.5rem;    /* 40px */
+  --space-2xl: 4rem;      /* 64px */
+  --space-3xl: 6rem;      /* 96px */
+  --space-4xl: 9rem;      /* 144px */
+}
+```
+
+- Use `gap` for sibling spacing. It's cleaner than stacked margins, it participates in flex/grid, and it collapses predictably.
+- Use `margin` only for optical adjustments or breaking out of the flow. Never `margin` for a list of siblings.
+
+## Grids
+
+- **Prefer CSS Grid** for page layout, **Flexbox** for component internals.
+- `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive grids without media queries.
+- **Don't default to 3 columns of equal cards with icon-above-heading-above-copy.** This is *the* AI feature-grid. Break it: vary column widths with `grid-template-columns: 1.2fr 1fr 0.8fr`, or use a 12-column underlying grid and give each item a different span, or use 4-up with a 2-span hero, etc.
+- Use **named grid areas** for complex layouts and rename them at breakpoints.
+
+## Asymmetry techniques
+
+- **Wide left margin.** Treat the left as a permanent negative space — narrow column of labels, wide column of content. **Labels must NOT be section eyebrows / numbers paired with the heading** — that's gate-66-banned. Reserve this technique for body-level micro-labels (caption, footnote, date) alongside body copy.
+- **Hanging headers.** ⚠️ **Opt-in only.** Section labels sit in the left margin; content flows to the right. Permitted only when the user explicitly asks for an editorial / hanging-header layout AND no eyebrow / number / chapter tag sits in the left margin. The eyebrow-left / heading-right pattern is banned by slop-test gate 66 — it's the most reliable templated-editorial AI tell. Default to a stacked single-column section head.
+- **Offset grids.** Odd columns wider than even. Or the other way.
+- **Grid-breaks.** One element that deliberately extends past a column boundary: a pull-quote, a photograph, a rule, a number.
+- **Generous top, tight bottom** (or vice-versa). Sections don't need to be evenly padded.
+
+## Depth
+
+- Depth is **weight and scale**, not shadow. A heavier weight, a larger size, a warmer hue — these create hierarchy better than drop shadows.
+- If you use shadow, use one:
+  - **Whisper** — `0 1px 2px oklch(20% 0.01 <hue> / 0.05)` for hovering cards.
+  - **Hairline** — `0 0 0 1px oklch(30% 0.01 <hue> / 0.06)` as an alternative to a 1px border.
+- Never stack multiple shadows. Never use a coloured glow on a light background.
+- Z-index has **six levels, named.** Don't freestyle numbers.
+
+```css
+:root {
+  --z-base:     1;
+  --z-raised:   10;
+  --z-dropdown: 100;
+  --z-sticky:   200;
+  --z-modal:    400;
+  --z-toast:    500;
+  --z-tooltip:  600;
+}
+```
+
+## Bans
+
+- **Centre-aligned everything.** Headings + body + CTA all centred is the landing-page template every LLM emits.
+- **`min-height: 100vh` hero with one centred sentence.** Stop.
+- **Card-in-card.** A bordered container inside a bordered container. Pick one.
+- **Identical feature grid.** Three columns, three icons, three two-line headings, three three-line bodies. Change *something*.
+- **Equal padding on everything.** If the card padding equals the section padding equals the page padding, the rhythm is flat.
+- **`z-index: 9999`** and other ad-hoc z values. Use the scale.
+- **Shadow-on-dark accidental glow.** A drop shadow on a dark card creates a glow; that's wrong.
+
+## Page-edge clipping
+
+The clipped-edge enrichment archetype (E1) — and any other deliberately overflowing element (full-bleed marquee, oversized headline that exceeds the viewport on small screens, a tilted figure that pushes past a column) — needs a parent that *visually* shows the overflow without letting the document scroll horizontally.
+
+The default is unsafe: a `width: calc(100% + 12vw)` figure inside a section with `overflow: visible` makes the document scroll horizontally on every viewport. The page feels broken on touch devices. Slop-test gate 36 fails on this.
+
+**Always pair clipped-edge with a global clip.** At the top of the stylesheet:
+
+```css
+html { overflow-x: clip; }
+body { overflow-x: clip; }   /* fallback for older Safari */
+```
+
+Use `overflow-x: clip` rather than `overflow-x: hidden`:
+
+- `clip` preserves `position: sticky` and `position: fixed` on descendants.
+- `hidden` creates a new scroll container, which breaks sticky and can trap focus on overflowing inputs.
+
+The clipped-edge mockup keeps its visual extension; the page no longer scrolls horizontally. Same pattern works for full-bleed marquees, oversized headlines, and any deliberately-decorative overflow.
+
+The hero or section that *contains* the overflowing element keeps `overflow: visible` (so the figure renders past the parent edge); the global clip on `html` and `body` is the only safety net needed.
+
+## When in doubt
+
+If the layout looks fine but flat, do one of these before shipping:
+
+1. Add one break-out element.
+2. Unbalance a column width.
+3. Move the primary CTA out of the centre.
+4. Remove a card and replace it with negative space.
+5. Change one section's padding so the rhythm is uneven.

package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md

@@ -0,0 +1,35 @@
+## 01 · Bento Grid
+
+Modular blocks of varying sizes laid out as an irregular grid. Each block is a feature, a quote, an image, a stat. Visual rhythm comes from size variation, not card uniformity.
+
+- **Heading:** centered display in a fixed-height hero (not full viewport).
+- **Body:** asymmetric grid — 8–15 blocks of mixed spans (1×1, 2×1, 1×2, 2×2).
+- **Divider:** consistent 12–24 px gap; no rules; the grid itself is the rhythm.
+- **Button:** outlined chip on the hero; tile-internal CTAs as typographic links.
+- **Image:** tightly cropped inside individual blocks; never full-bleed.
+- **Reveal:** none, or a subtle one-shot fade on grid-tile entry.
+
+Reach for it when the brief is "many small things to show", a feature page, a SaaS landing, or anywhere users have multiple equally-valid entry points.
+
+Avoid when the message is a single hero idea — Bento spreads attention; one-idea pages need Marquee or Stat-Led.
+
+Reference: Apple in-page sections, Framer feature pages, Tailwind UI templates.
+
+**Sample opening lines** (imitate the *specificity*, not the wording):
+> *"Tracejam · v0.4 · for SREs. Distributed tracing that explains itself."* — paraphrased from real observability tools
+> *"Resend is the email API for developers. Send transactional and marketing emails at scale."* — resend.com
+> *"The product development system for teams and agents."* — linear.app
+
+```html
+<header class="hero-fixed">…</header>
+<section class="bento">
+  <article class="cell span-2x2">…</article>  <!-- hero feature -->
+  <article class="cell span-1x1">…</article>
+  <article class="cell span-2x1">…</article>  <!-- wide stat -->
+  <article class="cell span-1x2">…</article>  <!-- tall image -->
+  <article class="cell span-1x1">…</article>
+  <article class="cell span-1x1">…</article>
+</section>
+```
+
+---

package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md

@@ -0,0 +1,34 @@
+## 02 · Long Document
+
+Reads like a memo, a letter, or a journal entry. No marketing structure. Continuous prose with inline section heads. The page is *literature* about the product.
+
+- **Heading:** inline with body — section heads emerge from the paragraph flow as small caps or bold short phrases.
+- **Body:** single column, generous line-height (1.65+), measure 60–65ch.
+- **Divider:** negative space; the gap is the divider; occasionally a centered ornament for emphasis.
+- **Button:** typographic link inside a paragraph, not a separate block.
+- **Image:** inline, sized to text measure; never full-bleed.
+- **Reveal:** none. The page is just *there*.
+
+Reach for it for case studies, founder posts, mission pages, products whose sale is *philosophical*. The brief is "tell a story", not "list features".
+
+Avoid when there's a single decisive action to take — Long Document hides CTAs, which is wrong for transactional pages.
+
+Reference: Frank Chimero's site, destroytoday.com, long-form Substack essays in product disguise.
+
+**Sample opening lines** (imitate the *specificity*, not the wording):
+> *"Saturday, 6:14 a.m. The dough went in at midnight."* — opens with a time-stamp; the brand introduces itself as a moment in the day
+> *"A monthly art publication featuring contributions by some of the most engaged thinkers working today."* — e-flux.com/journal
+> *"We design everything for everyone."* — pentagram.com — refusal of the verb, treats design as universal practice
+
+```html
+<article class="prose">
+  <p class="lede">…</p>
+  <p>…</p>
+  <h2 class="inline">A small heading.</h2>
+  <p>…</p>
+  <blockquote>…</blockquote>
+  <p>… <a href="">read more →</a> …</p>
+</article>
+```
+
+---

package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md

@@ -0,0 +1,31 @@
+## 03 · Marquee Hero
+
+The hero IS the page above the fold. A single bold statement or visual fills the viewport. No subhead, no CTA in fold. Below the fold the page becomes something else (a list, a grid, prose).
+
+- **Heading:** display fills the fold — 8–14 vw type, hugging the viewport edges.
+- **Body:** below-fold becomes a list of work or a single content block; the hero doesn't continue.
+- **Divider:** a thick rule between hero and below-fold, OR a hard colour change.
+- **Button:** none in fold; first CTA arrives below.
+- **Image:** none in fold (typography is the visual), OR a single full-bleed photograph as the fold *background*.
+- **Reveal:** the fold is static; below-fold may sweep in horizontally.
+
+Reach for it when the brand or person *is* the message — designer/director portfolios, indie products with a single declarative voice, any "this is who we are" page.
+
+Avoid for products whose value requires explanation in seconds. Marquee makes the user scroll before they understand.
+
+Reference: 14islands.com, destroytoday.com, many design studio homepages.
+
+**Sample opening lines** (imitate the *specificity*, not the wording):
+> *"Type, set with care."* — Hallmark Specimen — refusal of the verb, treats type as material
+> *"A studio for what's next."* — italic editorial display, names the practice without explaining it
+> *"Design like print: warm, off-register, intentional."* — Hallmark Riso — declarative, three modifiers, full stop
+
+```html
+<section class="marquee">
+  <h1 class="display-xxl">A statement.</h1>
+</section>
+<hr class="rule-thick" />
+<section class="below-fold">…</section>
+```
+
+---

package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md

@@ -0,0 +1,32 @@
+## 04 · Stat-Led
+
+The hero is a giant number — a metric, a count, a percentage. Everything that follows supports or qualifies it. Data is the narrative.
+
+- **Heading:** numeric display (8–12 rem), tabular figures, small qualifier line below.
+- **Body:** sections each anchored by a supporting stat or chart.
+- **Divider:** hairline rules between stat blocks; tabular-nums everywhere.
+- **Button:** outlined chip aligned beneath the qualifier.
+- **Image:** charts and small data-viz; no photography.
+- **Reveal:** number-tick on the hero figure — counter from 0 to target over ~500 ms.
+
+Reach for it when the brief is "we have proof in numbers" — enterprise/B2B, fundraising platforms, climate or impact pages.
+
+Avoid for products without a defensible single metric. A fake big number is worse than no number.
+
+Reference: Ahrefs, Stripe Sessions stat blocks, climate-impact dashboards, venture firm portfolio pages.
+
+**Sample opening lines** (imitate the *specificity*, not the wording — the number does the work):
+> *"+47% · faster · decide late."* — italicised number, three-word qualifier
+> *"4 seconds. From the alert link to the slow span."* — pairs the number with what it bought
+> *"434 total posts. New CSS you feel like you could use today."* — adam argyle, nerdy.dev — the count grounds the page in real volume
+
+```html
+<section class="stat-hero">
+  <div class="figure tnum">99.97<span class="unit">%</span></div>
+  <p class="qualifier">uptime across 2026, measured externally.</p>
+  <a class="cta-outline">Read the report →</a>
+</section>
+<section class="supporting-stats">…</section>
+```
+
+---

package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md

@@ -0,0 +1,32 @@
+## 05 · Workbench
+
+Product screenshots in frames are the primary content. The page is a guided tour of the app in use. Less marketing copy, more "here's what you do with it."
+
+- **Heading:** small, functional — workbench pages don't shout.
+- **Body:** sequence of screenshot blocks, each with a short caption and an inline annotation arrow.
+- **Divider:** the screenshot frame *is* the divider; sections separate by gap and frame.
+- **Button:** sticky-bottom CTA bar after the third screenshot ("Try it →"), once context is built.
+- **Image:** central — browser/device frames around real product captures, with annotation arrows.
+- **Reveal:** type-unmask on captions; screenshots load instantly.
+
+Reach for it for SaaS, developer tools, IDE extensions — anywhere seeing the product in motion is the sale.
+
+Avoid when the product is conceptual or services-led. Workbench needs a UI to show.
+
+Reference: Linear.app, Vercel, Raycast, Arc Browser.
+
+**Sample opening lines** (imitate the *specificity*, not the wording — the page walks the user through):
+> *"$ streampipe parse access.log --filter status=5xx | jq"* — open on a real command, not a marketing claim
+> *"Read anything that emits lines. Files, pipes, sockets, kubectl logs."* — names the inputs, refuses abstraction
+> *"Open the trace, find the span, fix the regression. No glossary required."* — three concrete verbs, then a refusal
+
+```html
+<header class="lite">…</header>
+<section class="screenshot-frame">
+  <figure><img src="step-1.png" /><figcaption>Open a project.</figcaption></figure>
+</section>
+<section class="screenshot-frame">…</section>
+<aside class="sticky-cta">Try it free →</aside>
+```
+
+---