@bongos/core 1.19.460 → 1.19.462

package/modules/ui-design/skills/design-taste-frontend/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: design-taste-frontend
+description: The default taste skill for a landing page, a portfolio, a marketing surface or a redesign of one, on ANY Cloud Bongos instance. Reads the brief and says the design read in one line, sets three dials (variance, motion, density) from named presets, locks one world for the whole page, keeps the hero and the layout disciplined, rations decoration, and ends on a pre-flight the kit measures. Triggers on "design a landing page", "make this not look templated", "taste pass", "anti-slop", "this looks like every AI site", or when /design hands off a marketing surface. Not for dashboards, data tables, wizards, code editors, native mobile or realtime collaboration (those go to /design and the hall's archetypes). Rebuilt in-house from the taste-skill rebuild spec (task 1003325, ADR 0198); the instance's world is the palette and images are hero plates only.
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `taste-skill` entry, "design-taste-frontend v2"), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325); this file implements its requirements from scratch, **no upstream bytes consulted or copied**, and the landing shape (the in-house `skills/<name>/` home, this section in place of a `PROVENANCE.md`) is [ADR 0220](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose: the upstream skill mandated image generation as a first step and accepted seeded placeholder photography; here **imagery is hero plates and hero objects only, by token, and never a step**. Its "foundation" step installed a vendor's design-system package; here **the foundation is the instance's world** (`DESIGN.md` and its pack), and the style library is where variants come from. Its motion rules assumed a script-driven animation stack; here **every rule lives inside the Kill Switch** and nothing moves in JavaScript. Its bans (the long dash, decorative labels) are kept as defaults that an instance's own `DESIGN.md` bans override.
+
+## Scope: when this skill fires, and when it declines
+
+**Fires** on a landing page, a portfolio, a marketing site, a product story page, a pricing page, and on a redesign of any of those (for the audit-first version of a redesign, `redesign-existing-projects` runs first and hands back here).
+
+**Declines, and says so instead of trying anyway:** dashboards and ledgers, data tables, multi-step wizards, editors, native mobile, realtime collaboration surfaces. Those have their own archetypes on this platform (the hall's row and panel archetypes, the hub's card) and the plain `/design` loop; a marketing taste applied to a working surface is how a ledger gets a hero.
+
+## Step 1: read the brief, then say the read in one line
+
+Read, in this order, before any opinion: the page kind; the audience; the vibe words (verbatim, they are the brief's only taste signal); linked references (open them; extract composition, rhythm, density, never a palette); existing brand assets the instance already ships (its plates under `assets/world/`, its mark); the hard constraints (the world file is one: everything the instance's `DESIGN.md` names is a constraint, not a suggestion).
+
+Then write **one line**: `Design read: <page kind> for <audience>, <the one word the vibe reduces to>, <variance/motion/density>.` That line is the contract for the session and goes in the ship notes.
+
+Ask **at most one** clarifying question, and only when the read genuinely forks (two page kinds, two audiences, a vibe word that contradicts the world). A brief that does not fork gets the read and a first render, not a questionnaire.
+
+## Step 2: set the three dials from a preset, never silently
+
+Three numbers, 0 to 10, stated in the read line and restated in a comment at the top of the page's sheet:
+
+| Preset | Variance | Motion | Density | What it means |
+|---|---|---|---|---|
+| Landing / marketing | 6 | 4 | 3 | asymmetric composition, one authored arrival plus slow ambient loops, a lot of air |
+| Portfolio | 7 | 3 | 2 | the work is the composition; the chrome recedes |
+| Product story / pricing | 5 | 3 | 5 | more content per band; still one accent, still hairlines |
+| Reading page (docs, terms) | 2 | 1 | 6 | a measure, a rhythm, almost no motion |
+| Redesign in place | inherit | inherit | inherit | the existing page's numbers, read from the audit, then moved one step at most |
+
+- **Variance** is how far the layout may leave the centred single column: at 0 everything is centred and stacked; from 5 the hero is asymmetric and sections may offset; at 8+ elements may overlap and break the container.
+- **Motion** is capped by the world's grammar before it is capped by the dial: under the chrome world an ambient loop is 20s or slower and there is exactly one authored arrival; a dial above the world's ceiling is clamped to it. Motion 0 is what every page becomes under `prefers-reduced-motion`, so the rest frame at motion 0 is designed first.
+- **Density** is content per band, not padding: it changes how many facts a band carries, never whether the 24px floor holds.
+
+Never run a baseline silently. If the brief gives no signal, pick the preset that matches the page kind, say so in the read line, and move on.
+
+## Step 3: the foundation is the world
+
+The design system for every surface on an instance is that instance's `DESIGN.md` plus its branding pack. Map the brief onto it:
+
+- **The palette** is the fifteen. A variant of the look comes from the style library, `modules/ui-design/styles/<name>/` (render the surface under one with `--style <name>` on the kit to see it); the palette source for a variant is a look's `pack.json`, never a hex chosen for this page. If the brief's vibe wants a colour the world does not have, the answer is a look from the library or an owner decision, not a private token.
+- **The faces** are the pack's two stacks. A brief that names a typeface it wants gets the nearest face the pack already carries, and the ship notes say so.
+- **When the brief names a third-party design system** ("make it feel like <vendor>"), do not install anything: this skill adds no dependency, and a dependency is a task decision the claim's owner takes. Build the direction from web standards inside the world, and label the approximation in a comment in the sheet (`/* an approximation of <vendor>'s rhythm inside the chrome world; not official material */`), never as official.
+- **Where the instance has no `DESIGN.md`**, the neutral pack is the world and the platform floors are the rulebook. Say so in the read line.
+
+## Step 4: lock consistency for the whole page
+
+One world, one accent, one radius scale (the world's `rounded` tier: pill, panel, tile), one mode pair (the pack's light and the sheet's dark twin), one label face. Locked at the top of the sheet in a comment, then held:
+
+- No mid-page inversion. A dark band on a light page, or a light card on a dark page, is the copy-paste accident the redesign audit flags; the chrome world bans a black panel on a light page by name.
+- No accent swap. The accent is the pack's `accent`; a second voice takes `sea` before anything is invented; the hall's fixed verification vocabulary (green, amber, red) is not a palette this skill may borrow.
+- No radius drift. Every rounded thing on the page is one of the three tokens.
+- No face drift. Display, body, label: three roles, two stacks plus the world's label face.
+
+## Step 5: hero discipline
+
+The hero is where a page becomes generic. Hold these:
+
+- **The headline is at most two lines** at 1440 and at 390 (the chrome world's Two-Line Rule). If it wraps to three, the copy is too long or the container is too narrow; widen the container first, then shorten the copy with `copy-desk` (the copy half is theirs; flag, do not rewrite the voice).
+- **The subtext is capped**: two lines, about twenty-four words.
+- **The primary action is visible without scrolling** at 1440x900 and at 390x844. The kit's first shot of every render is that test.
+- **Top padding is capped** at the world's band clamp; a hero that starts below the fold is not a hero.
+- **At most four text elements** in the hero: eyebrow if the world allows one (the chrome world does not, above the h1), headline, subtext, the action pair. Nothing else. A stat, a badge, a pill row and a scroll cue are all the fifth element.
+- **Trust logos leave the hero** and get their own band below it, and only where the instance's `DESIGN.md` does not ban a trust strip outright (the chrome world does).
+
+## Step 6: layout discipline
+
+- **No layout family reused across adjacent sections.** Two-column split, full-bleed band, hairline ledger, tile grid, single measure: each appears once before any repeats, and never twice in a row.
+- **At most two consecutive image-plus-text zigzags.** A third is a template.
+- **A bento grid has exactly as many cells as it has items.** No empty cell, no filler card, no "coming soon" tile. Count them in the sheet comment.
+- **One-line desktop navigation under a height cap**: the world's bar height (64 to 72px in the chrome world; 60 under its breakpoint) and never a second row on desktop.
+- **The container is the world's** (`spacing.container`); the breakpoint is the world's (one, at 900px in the chrome world); the widths the kit renders are the truth (1440 / 390 / 320).
+
+## Step 7: ration the decoration
+
+Small uppercase labels are seasoning. **One eyebrow per three sections**, at most, in the world's label face, and never above the h1 where the world bans it.
+
+Banned outright, as defaults an instance's `DESIGN.md` may only tighten: enumerated section labels ("01 / Features"), scroll cues, locale and time strips, version stamps, decorative status dots, floating badges over hero text, pill tags under the hero, raw statistics inside the hero. The chrome world bans most of these by name; where a world is silent, this list holds.
+
+## Step 8: copy hygiene inside the taste
+
+- **The long dash and its separator variant do not appear in visible copy** where the instance bans them (Cloud Bongos does): not in headlines, captions, buttons, quotes or alt text. The plain hyphen and the minus sign survive. The ledger's quoted titles are normalised at render time rather than edited.
+- No emoji, no exclamation mark in success copy, no placeholder names, no fake round numbers, no invented brands. Fixtures come from `modules/ui-design/kit/fixtures/`, which is a neutral builder and real feed shapes.
+- The voice belongs to `copy-desk`. Flag a string in the ship notes; do not rewrite the product's voice in passing.
+
+## Step 9: imagery, under the owner's rule
+
+Imagery is optional and, where it exists, it is **hero plates and hero objects by token**: the world's rendered plates (`--plate-*` in the chrome world), an owner-supplied `art_url`, a project's own cover. This skill never generates an image as a step, never proposes placeholder photography, and never asks for an image budget.
+
+- A slot with no plate is not a slot: the composition is redesigned without it. An empty labelled slot ("image here") is the generic tell this skill exists to remove.
+- **No product screenshot faked out of styled divs** (the chrome world's ban, and the module's default). A real screenshot is content an owner supplies; a fake one is decoration.
+- No hand-drawn icon paths, no icon set introduced for one page. Where an icon is needed, the world's inline mark or a hairline glyph.
+- A plate is the one place the world allows atmosphere; nothing else is painted.
+
+## Step 10: motion honesty
+
+Every animation on the page is **justifiable in one sentence, written as a CSS comment above it**. If the sentence is "it looks nice", the animation goes.
+
+- Everything moves in CSS, on `transform` and `opacity` (and `filter` on plates where the world does), on the world's curves: an exponential ease-out for entrances, the state curve at 200 to 400ms for hover and press. No spring library, no scroll listener, no component state for a continuous value: motion authored in JavaScript escapes the Kill Switch and is banned on every instance.
+- The two scroll skeletons, where a dial above 5 asks for them, are CSS: a **pinned stack** is `position: sticky` panels in a tall band, and a **horizontal pan** is a sticky band with `animation-timeline: scroll()` behind `@supports`, falling back to a static row. Both are complete compositions at rest.
+- Above motion 2 the page honours `prefers-reduced-motion` by design, not by exception: the Kill Switch at the foot of the token layer kills every animation and transition, and the rest frame you designed at Step 2 is what remains.
+- Ambient loops respect the world's period floor (20s in the chrome world) and move only the plates.
+
+## Pre-flight (a single unticked box means the work is not done)
+
+Run the kit, not your eyes: `node modules/ui-design/kit/render.js --page <path>` (every state, 1440 / 390 / 320, the modes the states file names, audited against the floors, a reduced-motion pass) and `node modules/ui-design/kit/probe.js --page <path>` for the interaction contract. Then tick:
+
+- [ ] **Contrast** measured, not eyeballed: ALL CLEAN in every mode the page serves; the pack floor via `contrast.js`.
+- [ ] **Copy self-audit**: no long dash in visible copy where banned, no emoji, no placeholder names or fake numbers, two-line headline at 1440 and 390.
+- [ ] **Theme and shape locks** held: one accent, one radius scale, one mode pair, no inverted band, no private hex, no page `:root`.
+- [ ] **Imagery sourced by token**: every image is a plate token, an owner asset or absent; no faked screenshot, no labelled empty slot.
+- [ ] **Motion honesty**: every animation has its one-sentence comment; nothing moves in JavaScript; the reduced-motion render is a complete composition.
+- [ ] **Mobile collapse** looked at: the 390 and 320 shots first (the fold, the bar, the bands); nothing scrolls sideways; the 24px floor holds on every control.
+- [ ] **Web vitals by construction**: the LCP element is a plate or the headline, never a script-built node; fonts load with `font-display: swap` and a sized fallback so nothing shifts; live DOM is `createElement` and `textContent`; no layout property animates.
+- [ ] **The read line** from Step 1 and the dials from Step 2 are in the ship notes with the shots you looked at, in which modes.

package/modules/ui-design/skills/design-taste-frontend-v1/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: design-taste-frontend-v1
+description: The earlier generation of the taste skill, preserved under its own name so a task or a builder that names it gets exactly this behaviour while the default (design-taste-frontend) evolves separately. A fixed baseline triple of dials adapted in conversation, stack conventions for a served surface, typography and colour rules read against the instance's pack, the layout bans, full interaction cycles, motion rules inside the Kill Switch, performance guardrails, a named vocabulary of premium patterns and a tile-grid archetype set. Triggers on "design-taste-frontend-v1", "use the v1 taste skill", "the fixed dials", or "the pattern vocabulary". Rebuilt in-house from the taste-skill rebuild spec (task 1003325, ADR 0198); nothing here auto-updates from v2.
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `taste-skill-v1` entry), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325); this file implements its requirements from scratch, **no upstream bytes consulted or copied**; the landing shape is [ADR 0220](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose: the upstream generation was written for a component framework with a motion library; a platform surface here is static markup, one sheet and the instance's transforms, so the stack conventions are restated for that and **every motion rule lives inside the Kill Switch** (the spring, the magnetic hover and the shared-element transition, which need script, are named as not available rather than quietly kept). The typography and colour rules are read **against the instance's pack**: the pack's faces are the faces and the pack's accent is the accent, whatever this skill would have preferred. Imagery follows the owner's rule (hero plates and hero objects only).
+
+## Why v1 is kept
+
+The default skill (`design-taste-frontend`) reads the brief, states a design read and sets its dials from presets. This generation does something narrower and more predictable: it starts from a **fixed baseline** and adapts it in conversation, and it carries a **vocabulary** the default folded into its steps. A task that says "v1" means this file, and this file does not change when the default does. If both are in front of you and the task names neither, use the default.
+
+## The baseline triple
+
+Variance **6**, motion **4**, density **5**. Fixed. Adapt them **conversationally**: when the person you are working with says "calmer", motion drops one; "busier" raises density one; "more editorial" raises variance one. Say the new triple each time it moves. Do not ask anyone to edit this file to change a dial, and do not edit it yourself for a session: the triple is the skill's baseline, the conversation is the override.
+
+The motion value is clamped by the world before the dial applies (the chrome world: ambient loops at 20s or slower, one authored arrival, everything dead under reduced motion), and motion 0 is what every page becomes under `prefers-reduced-motion`, so the rest frame is designed first.
+
+## Stack conventions for a served surface
+
+- **Check the surface's stack before importing anything**: the instance's `package.json`, the directory's nested `CLAUDE.md`, the sheet the page already loads. A platform surface is static HTML served through the instance's transforms, one sheet, and script only for live data (`createElement` / `textContent`, never `innerHTML`). This skill introduces no framework and no library.
+- **If a package is missing, print the install command and stop.** Adding a dependency is a task decision, not a taste decision; the ship notes carry the command, the claim's owner takes it.
+- **Static markup by default; script isolated to leaf behaviour** (a disclosure, a live refresh) and never to motion, because script motion escapes the Kill Switch.
+- **Utility CSS is not assumed.** If a surface already uses one, read its version from the manifest before writing a class; if it does not, write the world's tokens straight.
+- **Breakpoints are the world's** (one, at 900px in the chrome world) and the kit's three widths (1440 / 390 / 320) are the proof; the container is `spacing.container`; a full-height section is the world's floored stage or `100dvh`, never `100vh`.
+
+## Typography rules
+
+- **Display type is large and tight-tracked**: the pack's display face at the world's display weight and tracking (the chrome world: Manrope 300, `-0.042em`, lowercase). A display line is drawing, not a slogan.
+- **Body measure is capped near 65 characters** (`max-width: 62ch` on prose; the chrome world's bands cap at 56 to 62ch).
+- **The pack's body face is the UI face.** A default UI sans is discouraged for premium work only where the pack does not name it; where the pack does, the pack wins.
+- **Serif is not a UI face** on a working surface (a ledger, a settings page, a form). A look from `modules/ui-design/styles/` that carries a serif carries it for display, and the body stack decides the rest.
+- Every real number is `font-variant-numeric: tabular-nums`; a figure that refreshes must not reflow the composition.
+
+## Colour rules
+
+- **One accent, the pack's,** spent only on the pressable and the live (the chrome world's One Warm Thing Rule). Under 80% saturation is the pack author's business, not this page's: the accent is not adjusted per page.
+- **No purple-to-blue glow aesthetic**, no neon-on-near-black HUD, no gradient text. These are bans whichever pack is on.
+- **One palette per project** means the pack, and the pack's neutral ramp is the only ramp: no warm grey on one band and cool grey on the next, because there is only `bg`, `bg-card`, `bg-deep`, `bg-frame` and the inks.
+- Every colour is a `var()` or a `color-mix()` of the fifteen; the dark twin is written twice; a literal is pure black or white with alpha as a scrim, mask or halo, and nothing else.
+
+## Emoji and icons
+
+- **No emoji** in code, markup, copy or alt text. Not as a bullet, not as a status glyph, not in a button label. Cloud Bongos's `DESIGN.md` bans it by name; the default holds on every instance.
+- **Icons come from one small allowed set of families, at one standardised stroke width.** The allowed set on a platform surface is: the world's inline mark (the chrome world's bongo-pair SVG), and one hairline glyph family drawn at a single stroke (`1.5px`, `stroke-linecap: round`) for the few glyphs a page needs (a chevron, an arrow, a magnifier, a close mark). Never two families on one page, never a thick default icon set, never a hand-drawn path introduced for one page. Where a world names its own family, that family is the set.
+- An icon is never the only carrier of meaning: the label is the text, the glyph is the pointer.
+
+## Layout bans
+
+- **No centred hero above variance 5.** At the baseline the hero is asymmetric: the type on one side, the object (a plate, by token) or air on the other.
+- **No three equal feature cards.** Three unequal objects at three sizes read as a constellation; three equal boxes read as a rank, and the chrome world bans the row by name.
+- **No boxed card containers above density 6.** Content is separated by hairlines (`rule-soft`) and negative space; a card is for a surface that carries its own elevation vocabulary, and the chrome world has none.
+
+## Full interaction cycles, not the successful state only
+
+Every interactive component ships all of its states, and the page's states file (`<page>.states.json`) names them so the kit renders each:
+
+- **Loading**: a skeleton shaped like the layout it replaces (the same columns, the same row heights, the ground tone `bg-deep`), never a spinner.
+- **Empty**: a composed empty state that says what will be here and offers the one next action; a feed with nothing collapses its rows, its meter and its sub-line rather than promising six rows that never come.
+- **Error**: inline, beside the thing that failed, in the world's `err` state colour on text, never a modal for a field.
+- **Press**: tactile feedback on `:active` (`transform: scale(.98)` on the state curve); **focus** with the world's two-tone ring; **hover** on anything pressable.
+- Every control clears the 24px floor in both axes, footer links included; primary pills sit at 46 to 48px.
+
+## Motion rules
+
+- **The world's curves are the easing.** Where a world names an entrance curve (the chrome world's exponential ease-out, `cubic-bezier(.16, 1, .3, 1)`) and a state curve, use them; where it names none, a curve with a little overshoot for entrances and a plain ease-out for states. No spring library: a spring is script, and script motion is banned.
+- **Staggered list reveals** are CSS: `animation-delay` from an `--i` custom property set in the markup (`style="--i: 3"`), never a script loop.
+- **Shared-element layout transitions and magnetic hover are not available on this platform.** Both need script driving continuous values; the first is replaced by an instant state change under a 200ms crossfade, the second by the world's hover lift (a 6 to 8px `translateY` over 400ms).
+- Everything is dead under the Kill Switch and the rest frame is the composition.
+
+## Performance guardrails
+
+- Animate **`transform` and `opacity` only** (and `filter` on a plate where the world does). Never a layout property.
+- **Grain and noise overlays** exist only where the world has that material (the expedition look's halftone screen is a look's material, not a default); when they do, they sit on a fixed, `pointer-events: none` pseudo-element.
+- **No arbitrary `z-index`.** A named scale on `body` (`--z-bar`, `--z-band`, `--z-dialog`), reserved for systemic layers.
+- **Full-height sections use dynamic viewport height** (`100dvh`, or the world's floored stage `max(100dvh, 900px)`), never `100vh`.
+- `backdrop-filter` only on a fixed or sticky layer, and only where the world's glass has a blur (light glass over paper is a tint, blur 0).
+
+## The vocabulary of premium patterns
+
+Named so a brief can ask for one and a review can name what is missing. Each is a pattern inside the world, not a component to import:
+
+- **The two-line display**: the h1 as two lines, the second indented, lowercase where the world's display voice is.
+- **The tabular figure**: a real number from the ledger at display weight, tabular, with a caption.
+- **The hairline ledger**: rows built from 1px top rules, baseline-aligned columns, no borders, no boxes.
+- **The door pill**: two equal actions joined in one glass bar, the primary carrying the accent with the world's `accent-on` ink.
+- **The lit rail step**: one step of a pipeline lit in the accent (hairline, dot, name), the rest in ink; exactly one is live.
+- **The leader-line callout**: a 1px diagonal line, a figure, a caption; real numbers only, at most two per surface.
+- **The feathered patch**: a soft patch of the ground behind glyphs that sit on art, so a ground never cuts a hard-edged box out of a plate.
+- **The contact shadow**: the one shadow in a world, and it belongs to the object, not to a component.
+- **The hairline band menu**: a disclosure that unfolds as a full-width band under the bar, over the page, closed by one hairline.
+- **The poster card**: a modal on the card ground closed by one hairline, its regions flat children in the brief's order, every region hiding on null.
+- **Pill or nothing**: every control a full pill (999px), and the one exception the world names.
+
+## The tile-grid archetypes
+
+Motion-first tile grids, each with its collapse under the world's breakpoint:
+
+- **The constellation**: three different objects at deliberately unequal sizes and baseline drops; hover lifts one. Collapses to a vertical stack at unequal sizes, never to three equal circles.
+- **The dense auto-flow**: `grid-auto-flow: dense` with interlocking spans and **zero empty cells**, three to five intentional tiles over eight cluttered ones. Collapses to one column; spans reset.
+- **The hairline ledger grid**: fixed columns (`88px 1fr 152px 96px` in the chrome world), 1px top rules, tabular ids. Collapses to one column per row, the id and the title first.
+- **The five-column rail**: five beats on one rail, one lit; collapses to one column with the hairlines kept.
+
+## Pre-flight (short)
+
+- [ ] **Mobile collapse** looked at in the 390 and 320 shots; nothing scrolls sideways; every archetype collapsed the way its entry says.
+- [ ] **Effect cleanup**: nothing to clean, because nothing moves in script; any live-refresh timer is cleared on navigation.
+- [ ] **State coverage**: every state in the page's states file rendered by `node modules/ui-design/kit/render.js --page <path>` and ALL CLEAN; the interaction contract PASS under `probe.js`.

package/modules/ui-design/skills/high-end-visual-design/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: high-end-visual-design
+description: Makes an interface read as an expensive agency build, inside the instance's world. One texture archetype and one layout archetype per project (never the same pair twice), the container anatomy (a shell and a core with a hairline ring and concentric radii, where the world allows a container at all), the pill button with its nested arrow disc, the spatial rhythm, the motion choreography inside the Kill Switch, the hover physics, the scroll entry, the mobile collapse per archetype and the performance rules, then a pre-output checklist. Triggers on "make it feel premium", "agency-grade", "this looks cheap", "expensive", "high-end", "the polish pass". Rebuilt in-house from the taste-skill rebuild spec (task 1003325, ADR 0198); the fonts are the pack's, the palette is the world's, images are hero plates only.
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `Leonxlnx/taste-skill` @ `<redacted>` (MIT; the `soft-skill` entry, "high-end-visual-design"), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28, so under [ADR 0198](../../../../docs/adr/<redacted>.md) it could land only as a REBUILD-SPEC. The spec is the body of [task 1003325](https://cloudbongos.com/builders#/task/1003325); this file implements its requirements from scratch, **no upstream bytes consulted or copied**; the landing shape is [ADR 0220](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose: the upstream skill specified **the** fonts and shadows that make a site feel expensive; here the fonts are the pack's two stacks and a shadow exists only where the instance's world has one (the chrome world has exactly one, and it belongs to the sculpture). Its texture archetypes become the looks in the style library; its layout archetypes stay free. Its motion (a hamburger morph, a blurred full-screen menu, an 800ms blurred fade-up on scroll) is kept as CSS inside the Kill Switch, and the scroll entry is honest about what a static page can do. Imagery follows the owner's rule: hero plates and hero objects by token, never a step.
+
+## One texture archetype, one layout archetype, per project
+
+Pick **one of each** before anything is drawn, write the pair in the sheet's header comment, and record it in the ship notes. The same pair is never used twice across sibling surfaces of one instance: the second surface that needs "premium" takes a different layout archetype under the same texture, because the texture is the instance's and the layout is yours.
+
+**Texture archetypes** map to the style library, `modules/ui-design/styles/`, and to the world; the pack in force fixes which one you are in:
+
+| Archetype | In this library | What carries it |
+|---|---|---|
+| Dark glass tech | `chrome-world` (the neutral pack) | the void, the glass tokens, one rendered chrome plate, a black type halo |
+| Warm editorial luxury | `expedition` | warm paper, a halftone screen, hairline frames, heavy uppercase display, one lamp yellow as a fill |
+| Soft light structuralism | `grove` | pale sage, soft corners on what holds content, tinted shadows, a sea slab under a band |
+
+A page never switches texture. To see a surface under another texture, render it with `--style <name>` on the kit; adopting one is the owner's `config/branding.json`, not a page.
+
+**Layout archetypes** (the free choice):
+
+- **The asymmetric tile grid**: interlocking spans, zero empty cells, one tile that breaks the container by a gutter.
+- **The depth cascade**: bands that overlap by a step (a negative top margin of `spacing.lg`), the object (a plate, by token) crossing two of them.
+- **The editorial split**: a hard vertical split at the golden-ish 5:7, type on the narrow side, the plate or the air on the wide side, a hairline down the seam.
+
+## The bans
+
+Defaults an instance's `DESIGN.md` may only tighten:
+
+- **The default sans stack** as a display face, unless it is the pack's face (then it is the face; the pack wins).
+- **Thick default icon sets.** One hairline stroke width, the world's inline mark, or no icon.
+- **Plain grey hairline borders** as decoration. A hairline is structure (`rule` / `rule-soft`, tokenised); it separates, it does not box.
+- **Harsh dark drop shadows.** Where the world has a shadow at all, it is tinted with the ink (`color-mix(in srgb, var(--ink) 20%, transparent)`) and it belongs to an object; the chrome world's UI has none.
+- **Edge-glued navbars.** The bar keeps the world's gutter on both sides and one hairline under it.
+- **Symmetric three-column grids** (the three-equal-card row the chrome world bans by name).
+- **Default easing** (`ease`, `linear`, `ease-in-out` on an entrance). The world's curves, or none.
+
+## The container anatomy, where the world allows a container
+
+Where a surface carries a panel (a dialog, the poster card, a settings sheet), a major container is **two concentric shapes**: an outer shell and an inner core.
+
+- The shell: the ground one step above the page (`bg-card`), the world's panel radius (`rounded.panel`), a **hairline ring** in `glass-edge` (dark) / `rule-soft` (light).
+- The core: inset by one spacing step (`spacing.sm`), an **inner highlight** as a 1px inset pure-white line at low alpha in dark (the one legal literal), and an **inner radius mathematically concentric**: `calc(var(--radius-panel) - var(--space-sm))`, never the same radius as the shell.
+- The chrome world has no card vocabulary below the fold (hairlines only); there the anatomy applies to the one thing that is allowed to be a panel, and the sheet says so in a comment. A world that says "no containers" is not overruled by this section.
+
+## The button anatomy
+
+A primary call to action is a **pill** (999px) at 46 to 48px, the accent as the fill and the world's `accent-on` as the ink, and its trailing arrow sits **inside its own circular wrapper**, flush with the pill's inner padding, never a bare glyph beside the label:
+
+```
+[  Open the hall   (→)  ]     the disc: accent-on at 12% over the fill (color-mix), 28px, the glyph centred
+```
+
+The secondary action is the same pill, transparent at rest, glass on hover, no disc. Both clear the 24px floor by construction. A world that joins the two into one bar (the chrome world's door pill) is that world's signature; keep it.
+
+## Spatial rhythm
+
+- **Section padding roughly doubles** the body's rhythm: the world's band clamp is the floor and twice it is the ceiling (`clamp(58px, 8.4vh, 104px)` doubled to `clamp(116px, 16.8vh, 208px)` on a hero-adjacent band in the chrome world); heavy breathing room between chapters, tight rhythm inside one.
+- **Tiny uppercase eyebrows** above major headings, in the world's label face, as a hairline pill or bare: at most one per three sections, and never above the h1 where the world bans it (the chrome world does).
+- The container is `spacing.container`; the gutter is the world's; nothing scrolls sideways at any width.
+
+## Motion choreography, inside the Kill Switch
+
+All CSS, on the world's curves; nothing moves in script; everything dead under `prefers-reduced-motion`, where the rest frame is the complete composition.
+
+- **Easing that simulates mass**: the world's entrance curve (the chrome world's `cubic-bezier(.16, 1, .3, 1)`) for arrivals, the state curve for hover and press. Where a world names none, an exponential ease-out.
+- **The hamburger that morphs into a close mark**: three bars as three pseudo-elements; the `aria-expanded` toggle (state, in script) flips a class; the bars rotate and collapse in CSS over 300ms. Under the switch they swap instantly.
+- **The full-screen blurred menu**: a fixed layer with `backdrop-filter` (blur is allowed here because the layer is fixed), links revealed in a **staggered slide-up** via `animation-delay` from `--i` in the markup. Under the switch the menu is simply open and complete. On the chrome world's apex the menu is a hairline band, not a full-screen layer; the world's component wins.
+
+## Hover physics
+
+Internal kinetic tension instead of a colour swap: on `:hover` the button holds; on `:active` the button **scales down** (`scale(.98)`) while the nested arrow disc **translates diagonally and scales up** (`translate(2px, -2px) scale(1.1)`), both on `transform` only, over 200 to 400ms on the state curve. Focus restates the world's ring. Nothing here needs the pointer's position, so nothing here needs script.
+
+## Scroll entry
+
+Elements arrive with a **slow blurred fade-up over roughly 800ms**: `opacity: 0; translate: 0 16px; filter: blur(6px)` to rest, on the entrance curve.
+
+- Prefer **CSS scroll-driven animation** (`animation-timeline: view()`) behind `@supports`, which needs no script.
+- Where that is unsupported, an `IntersectionObserver` may add **one class**; the motion stays in CSS. The entry state is applied only once the observer is live (a `.js` class on `body`), so a page without script, or with the observer not yet run, shows the composed rest frame and never a hidden element.
+- Never a raw scroll listener, never a continuous value in script.
+- Under the switch there is no entry: every element is at rest.
+
+## Mobile collapse, per archetype
+
+Below the world's breakpoint (900px in the chrome world; the tablet breakpoint elsewhere):
+
+- **Asymmetric tile grid**: spans reset, one column, full width, tiles in reading order.
+- **Depth cascade**: overlaps and negative margins removed; bands stack with the hairline between them; the plate becomes a masthead above the words.
+- **Editorial split**: the seam becomes a hairline between two stacked bands; the narrow side first.
+- Rotations, offsets and overlaps go; a full-height section is `100dvh` or the world's floored stage, never `100vh`; the bar holds one row down to 320px.
+
+## Performance rules
+
+- Animate **`transform` and `opacity` only** (and `filter` on a plate where the world does).
+- **Backdrop blur only on fixed or sticky layers**; light glass over paper is a tint at blur 0, as the world's glass token says.
+- **Noise and grain** only where the world has that material, on a fixed, `pointer-events: none` pseudo-element.
+- **`z-index` reserved for systemic layers** on a named scale on `body`; no arbitrary values.
+- The LCP element is the plate or the headline; fonts have a sized fallback; no layout property animates.
+
+## Pre-output checklist
+
+- [ ] The **archetype pair** is named in the sheet header and the ship notes, and it is not the pair a sibling surface already used.
+- [ ] **Nested shells** on every major container the world allows one on; concentric inner radius; hairline ring; inner highlight in dark.
+- [ ] **Section padding** at or above the world's band clamp; eyebrows rationed; the h1 has none where banned.
+- [ ] **The world's easing** on every transition; no default curve.
+- [ ] **Scroll entry** honest: CSS timeline or one observer class; rest frame complete without script and under the switch.
+- [ ] **Mobile collapse** per archetype, looked at in the 390 and 320 shots.
+- [ ] **The premium impression** judged on the kit's shots (`node modules/ui-design/kit/render.js --page <path>`, ALL CLEAN in every mode the page serves), not on the source; the button's disc and the ring measured, not eyeballed.

package/modules/ui-design/skills/impeccable/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: impeccable
+description: The design-craft method for ANY surface on ANY Cloud Bongos instance, invoked as one skill plus an optional sub-command and an optional target ("impeccable audit /projects", "impeccable polish the hall's ranks page", "impeccable harden the wizard"). Sixteen sub-command playbooks (shape, audit, critique, polish, harden, animate, typeset, colorize, layout, adapt, distill, clarify, onboard, optimize, document, extract) plus the two directions (bolder, quieter), exactly one loaded per request; a bare description with no sub-command is ordinary design work routed to the closest playbook; no argument prints a menu built from live project signals and never auto-runs anything. Carries the craft floor (loaded right before UI is edited, never recited to the user) and the bounded finish (build fully, one render round through the kit, one batch of fixes, at most one confirming round, stop). Triggers on "impeccable", "critique this page", "audit the UI", "polish the whole path", "make it survive long text", "animate this", "tighten the copy", "document the design system", "extract the repeated pattern". Rebuilt in-house from the impeccable rebuild spec (task 1003326, ADR 0198) with no hooks, no bypass agent, no telemetry and no live server; the live loop is the playwright plugin and the headless loop is the module's kit. Web surfaces only; a native mobile target declines to /design.
+---
+
+<!-- BEGIN PLATFORM PREAMBLE · ui-design module · one block, byte-identical in every skill the module ships (vendored or rebuilt in-house) so an upstream refresh is a three-way merge; the source is modules/ui-design/skills/PREAMBLE.md and tests/ui_design_skills.mjs fails on drift -->
+> **Platform preamble — read before any rule below.** This skill ships with the `ui-design` module (vendored from a scanned origin, or rebuilt in-house from a spec) and runs INSIDE an instance's world, which it reads first and never overrides.
+>
+> 1. **Load the world before any taste rule.** `config/branding.json` over `config/branding.neutral.json` (`theme.ui` is the fifteen tokens: <redacted> colours and two font stacks), `config/design-tokens.json` over `config/design-tokens.neutral.json`, and `DESIGN.md` at the repo root: the instance's palette and derived tiers, faces, materials, motion grammar, components, and its Do's and Don'ts. Where an instance has no `DESIGN.md`, the neutral pack is the world and the platform floors in item 6 are the whole rulebook; say so and build to them. Never invent a palette.
+> 2. **The fifteen-token contract is the only colour source.** Every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo. No page `:root` (page tokens live on `body`), and every dark rule is written twice: `:root[data-mode="dark"]` and its `prefers-color-scheme` twin.
+> 3. **A style skill produces variants INSIDE that world, never a second world.** The look this skill carries (its palette, faces, materials, mood boards) is a reference for composition and craft; the instance's tokens and faces replace it. Changing the world is the owner's decision and an ADR, not a session's taste.
+> 4. **Images are for hero plates and hero objects only.** UI is built from templates and the instance's world, not painted; any image-generation step below applies to text-free plates and hero objects, never to controls, cards, text, or a screenshot of a screen.
+> 5. **The instance's taste bans apply and win.** Read them from its `DESIGN.md`. Cloud Bongos's own (no em dash or en dash in visible copy, no emoji, no gradient text, no three-equal-card row, no fake screenshot built from divs) are that instance's, not the module's; where this skill's rules conflict with an instance's bans, the instance wins.
+> 6. **The platform floors hold on every instance** and a `DESIGN.md` may tighten them, never loosen them: every control clears 24px on both sides (primary pills 46–48px); AA in both modes (4.5:1 body text, 3:1 large text and non-text) measured from the real stylesheet; and the Kill Switch, `@media (prefers-reduced-motion: reduce)` at the foot of the token layer killing every animation and transition, no motion authored in JavaScript, and a rest frame that is a complete composition on its own.
+> 7. **Look before you ship.** Render the real surface through the module's kit before and after (`/design` Step 2 and `docs/recipes/ui-look-before-you-ship.md`: every state at 1440 / 390 / 320 in dark and light, audited against the floors); a page with no states file gets one first, and new interactive code ships with a pin in the page's own test file.
+>
+> The rules below are the skill's own. A vendored copy carries a `PROVENANCE.md` beside this file naming the origin, the pinned commit, the licence and the scan verdict it was vendored under; an in-house rebuild names its rebuild spec and its ADR in the section right after this block.
+<!-- END PLATFORM PREAMBLE -->
+
+## Rebuilt from
+
+This skill is an **in-house rebuild**, not a vendored copy. Its documented functionality comes from `pbakaus/impeccable` @ `<redacted>` (Apache-2.0; skill v4.1.x), which `/scan-before-install` reduced to `dangerous` at the default tier on 2026-08-28: three critical findings at the deterministic floor and a panel that upheld PostToolUse and Stop hooks written into five harness configs, a child agent spawned with its permissions bypassed from a loopback HTTP route, a setup directive that overrode the harness's own instructions, a live-server credential embedded in page source, an unverified remote bundle, and default-on telemetry. Under [ADR 0198](../../../../docs/adr/<redacted>.md) that verdict lands a REBUILD-SPEC, never a copy. The spec is the body of [task 1003326](https://cloudbongos.com/builders#/task/1003326), derived from the origin's documentation only; this file and the playbooks under `reference/` implement its requirements from scratch, **no upstream bytes consulted or copied**. The landing shape (the in-house `skills/<name>/` home, this section in place of a `PROVENANCE.md`) is [ADR 0220](../../../../docs/adr/<redacted>.md); the sub-command shape (one skill, one playbook per sub-command, what was kept and what was dropped) is [ADR 0221](../../../../docs/adr/<redacted>.md).
+
+What changed in translation, on purpose. The method's **three persisted homes** (product truth, the visual system, per-surface briefs) are the instance's own files here: product truth is `docs/project-context.template.md` and the identity block of the branding pack, the visual system is the root `DESIGN.md` (and a look's `DESIGN.md` under `modules/ui-design/styles/`), and a surface's brief is the claimed task's body and ship notes. This skill creates none of them and writes the root `DESIGN.md` only through the `document` playbook, as a draft on the claim's branch the owner reviews. Everything the panel flagged is **gone, not disabled**: no hook is written anywhere, no child agent runs with permissions bypassed (a reviewer is an ordinary subagent through the harness's own Agent tool), nothing is reported home, nothing is downloaded, and there is no live helper server. The **live loop** is the playwright plugin (a documented prerequisite) driving the module's stub; the **headless loop** is `kit/render.js` and `kit/probe.js`. The **anti-pattern detector** is not shipped here: task 1003329 lands it as rules in `kit/check-mock.js` and `kit/lib.js`, and until then the floor is what the kit already measures. The **native playbooks** (the two mobile platforms) are not rebuilt: every surface on this platform is a served web page, so a native target declines to `/design` with one line. The `init`, `doctor`, `pin`, `unpin` and installer operations, which existed to write and repair the origin's own config and harness entries, have no counterpart: the materialiser is the install. Imagery follows the owner's rule (hero plates only, task 1003328 for the image family); the palette is the pack and a variant is a look from the style library; every motion rule lives inside the Kill Switch.
+
+## Invocation: one name, one sub-command, one target
+
+`impeccable [<sub-command>] [<target>]` where the target is a page path (`/projects`), a surface (`hall-ui`), a file, or a plain description.
+
+- **A sub-command names a playbook.** Load exactly one: `reference/<sub-command>.md` beside this file. Do not load two, do not load the whole set.
+- **No sub-command, but a description** ("the pricing band feels loud") is ordinary design work: pick the playbook whose "when" line fits, say which you picked in one line, and run it. A new surface or a replacement look is not this skill's playbook; it is `design-taste-frontend` for a marketing surface or the plain `/design` loop for a working one, and a new *world* is the owner's decision and an ADR.
+- **Two playbooks plausibly fit** ("clean this up" could be `distill` or `polish`): ask once, with the two names and one line each. Never guess, never run both.
+- **No argument at all**: print the menu below. Never auto-run a command from the menu.
+- **A native mobile target** (an app for either mobile platform, or cross-platform): decline in one line and route to `/design`. The platform serves web surfaces and the native playbooks were not rebuilt.
+
+## The menu (no argument)
+
+Read four live signals, then print two or three recommended next commands with a one-line reason each, followed by the full list grouped by category. Signals, all read locally and none written:
+
+1. **The world files**: does `DESIGN.md` exist at the repo root; is `config/branding.json` present over the neutral pack; is `docs/project-context.template.md` filled or still the scaffold. A scaffold with no answers recommends `shape` first; a missing `DESIGN.md` alone does not make the project greenfield (the neutral pack is the world).
+2. **The last kit report** for the target, if any: `report.json` under `%TMP%/ui-design-kit/<surface>/<page>/` (or the `--out` dir the last run named). Problems listed recommend `audit` on that page; a clean report with no critique yet recommends `critique`; no report at all recommends `audit`, because the render is the read.
+3. **Dirty files in version control**: `git status --porcelain` over the surfaces (`modules/*/public/`, `src/ui/`, `public*/`). Dirty UI files recommend `polish` on that path before anything new.
+4. **A stub already listening**: `kit/serve.js` prints its port when it starts; a page already served means the live loop (the playwright plugin) is available without a second server. Never start a duplicate on an occupied port.
+
+The full list, grouped:
+
+| Category | Sub-commands |
+|---|---|
+| Discover | `shape`, `critique`, `audit` |
+| Build | `polish`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `adapt`, `distill`, `clarify`, `optimize` |
+| Direction | `bolder`, `quieter` |
+| Record | `document`, `extract` |
+
+## Session setup, once
+
+The setup step is the preamble's world load, done **once per session** and not repeated: the pack, the tokens, the root `DESIGN.md`, and `docs/project-context.template.md` for product truth. The directives that come back are the world's own named rules and its Do's and Don'ts; quote them from the files, never from memory. Then, before editing anything, inspect the target **and at least one source of existing visual truth** for it: the sheet the page loads, a sibling component, the page's states file, or a plate under the instance's assets. A surface is edited only after both have been read.
+
+This skill lives at `modules/ui-design/skills/impeccable/` in the core and at `.claude/skills/impeccable/` once materialised into an instance; the playbooks are always `reference/<name>.md` relative to this file. If a harness has put the file somewhere else, resolve the playbooks relative to wherever this file was read from, and fall back to the module path.
+
+## The three homes, and what they are here
+
+| The method's home | On this platform | Written by |
+|---|---|---|
+| Durable product truth (platform, users, purpose, positioning, constraints, brand commitments, principles, accessibility) | `docs/project-context.template.md` plus the branding pack's identity strings | the owner; `shape` records answers in the task, and only proposes edits to the file |
+| The durable visual system | the root `DESIGN.md`; a look's `DESIGN.md` under `modules/ui-design/styles/<name>/` | the owner; `document` drafts one where none exists, from shipped code, on the claim's branch |
+| The per-surface strategy brief | the claimed task's body and its ship notes (the brief block below) | the session, under the claim |
+
+Never merge them into one file, never create a second copy of any of them. **Product truth is required before new visual work begins**: a scaffold with no answers stops the build and starts `shape`. **An existing look is evidence of what the thing is, never authority over what it becomes**; a page's current sheet tells you the world it was built in, and the world file tells you the rules.
+
+**Refinement or redesign, never a blend.** Refinement keeps identity, content, behaviour and everything out of scope; redesign keeps product truth and function and replaces the look. Name which one the request is in the brief block; refusing to split the difference is the rule. The four starting cases branch every playbook: **full redesign** (product truth stays, the look goes, and a new look is a look from the style library or an owner decision), **inherit an established world** (the instance has a `DESIGN.md`: every decision is a lookup), **extend a partial brand** (a pack but no `DESIGN.md`: the pack's fifteen and the platform floors are the rulebook, and the gaps are named, not filled), **no visual authority at all** (the neutral pack is the world; say so). Scale invention to scope: an extension inherits everything, a new surface in a settled world explores structure only, and a new or replacement world is not a session's call. A local addition (a section, a component, a state) inherits the surface it sits in and is never escalated into an identity exercise.
+
+**The brief block**, written into the ship notes before the first edit and kept current:
+
+```
+Brief: <surface> · <refine|redesign> · case <1-4>
+Mode: <persuade|operate|read|experience> (from the surface, not the product)
+Audience / primary action / proof:
+Constraints (the world's named rules that bind here):
+Direction chosen / memorable moment:
+Open decisions:
+```
+
+The visitor mode is picked per surface (a ledger operates, a landing persuades, a policy page reads), persists only in that surface's brief, and changes what every playbook optimises. A brief that already names an era, a material, a face or a palette **overrides this skill's own saturated-pattern warnings**; steering a clear brief toward the agent's taste is the failure, not the pattern.
+
+## The playbooks
+
+| Sub-command | Playbook | When | Returns |
+|---|---|---|---|
+| `shape` | `reference/shape.md` | before any new work, or when the brief has holes | a confirmed written brief; no code, no persistence |
+| `critique` | `reference/critique.md` | "is this good?" | heuristics on a table, personas walked, a cognitive-load pass, three to five prioritised issues with fixes |
+| `audit` | `reference/audit.md` | "is this correct?" | five dimensions scored, every issue with a file and line, nothing fixed |
+| `polish` | `reference/polish.md` | a whole path before ship | every drift classified and fixed at the narrowest correct level |
+| `harden` | `reference/harden.md` | real data is coming | the surface survives long, empty, foreign, failing and huge |
+| `onboard` | `reference/onboard.md` | first run, empty states, a short tour | the fastest path to first value, skippable, never repeated |
+| `animate` | `reference/animate.md` | motion, delight, an ambitious effect | a motion thesis, one focal moment, a reduced-motion path for everything |
+| `colorize` | `reference/colorize.md` | colour feels off | colour by role inside the fifteen, ratios verified from computed values |
+| `typeset` | `reference/typeset.md` | type feels off | the role scale on the pack's faces, measure and tracking verified |
+| `layout` | `reference/layout.md` | order, grouping, rhythm, density | the page restructured, not rescaled |
+| `adapt` | `reference/adapt.md` | another width or context | restructured per context; native declines |
+| `distill` | `reference/distill.md` | too much | elements, options, copy and code removed; function kept through disclosure |
+| `clarify` | `reference/clarify.md` | copy is unclear | interface copy rewritten by its function, flagged to `copy-desk` |
+| `optimize` | `reference/optimize.md` | it feels slow | the measured bottleneck fixed, not the suspected one |
+| `document` | `reference/document.md` | after the build | the design-system doc drafted from shipped code |
+| `extract` | `reference/extract.md` | a pattern repeats | repeated patterns consolidated into the system, call sites migrated |
+| `bolder` | `reference/bolder.md` | one section falls short of its neighbours | one section raised, nothing else touched |
+| `quieter` | `reference/quieter.md` | too loud | saturation, weight, decoration and motion reduced; hierarchy kept |
+
+Every playbook opens by naming which of the four cases it is running in and which visitor mode the brief holds, ends by handing the result to the finish below, and obeys the preamble: the world first, the fifteen as the only colours, hero plates as the only imagery, the switch as the only motion, the kit as the proof.
+
+## The craft floor
+
+Load this **after direction is settled and immediately before editing UI**; skip it for planning-only work (`shape`, `critique`, `audit`, `document` read it, they do not edit); **never recite it to the user**. It is mechanics, not direction: the floor is what every surface clears, the world is what it becomes.
+
+- **Contrast, on the built result**: body and placeholder text at 4.5:1, large text at 3:1, in both modes, measured (`kit/contrast.js` for the pairs, `render.js` for the page). Secondary text on a coloured surface is tinted from that hue (`color-mix()` of the surface and the ink), never a grey dropped on top.
+- **Depth, in the world's language**: where the world has shadows they carry an offset and a soft blur; a zero-offset coloured halo is decoration, not elevation. Where the world is hairlines by rule (the chrome world), the absence of a shadow is the floor, and a hard zero-blur offset shadow belongs only to a world that chose that language.
+- **Spacing rhythm, from computed values**: tight within a group, generous between groups, more air above a heading than below it, every step on the world's scale.
+- **Type**: prose measure 65 to 75 characters; a display ceiling; a tracking floor at display sizes; balanced headings (`text-wrap: balance`) and pretty prose; no overflow with real copy at 1440, 390 and 320.
+- **Motion**: one authored moment, not scattered effects and not the same entrance on every section; easing out from an already-visible default; everything inside the switch; the rest frame complete.
+- **States**: hover, disabled, loading, error and empty, each named in the page's states file; real content, working controls, responsive composition, a visible keyboard focus ring.
+- **The browser surfaces nobody draws**: `::selection`, `caret-color`, the scrollbar, the focus ring, `text-underline-offset`, `font-variant-numeric: tabular-nums` on data.
+- **Refuse**: identical icon-plus-heading-plus-text card grids as page structure; a card nested in a card; the hero-metric template; decorative section numbering; a kicker or eyebrow above a heading where the world bans one (the chrome world does, above the h1); gradient text; decorative glass and blur; a coloured side stripe above a hairline on a card or callout; emoji or unicode glyphs standing in for a drawn icon set; a system display face as the world's display voice (the pack's faces are the voice); a geometric mask faking an organic cutout.
+- **Then commit.** With every check green, the remaining effort goes to the committed world; when torn between refined and committed, commit.
+
+## The finish
+
+Verification is **bounded passes, never an open loop**, and the budget covers the whole cycle: shots, checks, micro-edits and rebuilds all count against it.
+
+1. **Build fully.** Nothing is inspected half-built.
+2. **Inspect once, batched.** `node modules/ui-design/kit/render.js --page <path>` renders every state at 1440 / 390 / 320 in the modes the states file names and audits each against the floors; `node modules/ui-design/kit/probe.js --page <path>` runs the interaction contract. Desktop and mobile arrive in the same round. Validate the captures before believing them: entrance motion settled (the kit's reduced-motion pass is the rest frame), captured from the document top, at the intended dimensions, and each file opened to confirm it shows what its name claims.
+3. **Fix everything it showed in one batch.** Not one finding at a time.
+4. **Confirm with at most one more round.** Then stop.
+
+**The separate reviewer.** Hand the review to a read-only subagent that did not see the build conversation (the harness's Agent tool, the top-tier model, its ordinary permissions), with an explicit packet: the request, the user's answers, the artifact paths, the shots directory, the brief block, the kit's findings, and the approved mock where one exists. The reviewer runs an **evidence check first** and returns `recapture` when any required capture is missing, blank, mismatched or implausibly sized, rather than scoring on broken evidence. It builds its **own inventory** of the approved mock and classifies each salient element as *match*, *acceptable adaptation*, *missing*, *contradicted* or *added without approval*; a deviation is intentional only when it cites a user answer, the brief, an accessibility need or product truth, and an uncited deviation is a defect. Its disposition is **one of four words, derived from its checks**: `clean`, `recapture`, `defects`, `contradicted`; report that word unchanged and at its true scope (a page, not the site). A **second verdict pass** scores each prior fix *resolved*, *partial* or *unresolved* strictly from new captures, opens no new checks, and treats the builder's narration as non-evidence. When the user supplies evidence that contradicts a verdict, **reopen a fresh review** rather than defending the last one.
+
+**Close.** A source diff pass removes accidental churn, orphaned rules, duplicate values and temporary artifacts; then `document` records the design system from what was built. The platform's own ship-time grader is a second independent reviewer and reads the real committed diff, so the ship notes carry the brief block, the shots looked at and in which modes, and the reviewer's word.
+
+## Not here, and where it went
+
+- **The anti-pattern detector**: task 1003329 lands it as rules in `kit/check-mock.js` and `kit/lib.js`; today `check-mock.js` (the platform rules and the instance's `DESIGN.md` bans over a mock), `render.js`'s floors and `contrast.js` are the deterministic floor. Run it once per review round, treat a clean scan as a floor and never as proof, verify every finding in context and name false positives out loud.
+- **The live loop**: `claude plugin install playwright@claude-plugins-official`, a prerequisite the module never installs, driving `kit/serve.js`'s stub (`SURFACE=<dir or module key>`, `STYLE=<look>`). Variants are states in the states file, rendered by the kit; accepting one is a commit and discarding one is a checkout; there is no in-page overlay, no injected script, no journal, and no leftover to sweep because nothing was injected.
+- **Hooks, the bypass agent, telemetry, the remote bundle, the installer, `doctor`, `pin`, `unpin`**: gone. The ship gate is the sweep; the materialiser is the install; a reviewer runs with ordinary permissions.
+- **The asset producer**: images are hero plates and hero objects by token (task 1003328 for the image family); nothing here generates, crops or cleans an image.
+- **Native mobile**: `/design`, with the one principle that survives the drop stated for the record: the platform governs structure, navigation and interaction, and brand expresses through tint, type, motion and content.