Refresh the Impeccable product experience

Rework the landing page proof, steering demo, feature grid, slop catalog, detector coverage, theming, Live workflow, and responsive behavior.\n\nAI-assisted implementation by OpenAI Codex.

skill/reference/new-work.md

@@ -1,59 +1,81 @@
-# New identity work
+# Surface concept and craft
 
-You are reading this because nothing committed exists yet (greenfield), or the user asked for a redesign that discards the current look. The task is the same either way: invent a visual identity that could not be mistaken for anyone else's, in the grammar of the surface's mode (SKILL.md's Registers section), and build it to the craft floor. SKILL.md's rules all still apply; this file is the process that produces the identity.
+This is the shared task-scoped concept playbook for `craft`, `shape`, and substantial from-scratch surface work. `craft` continues through the contract, build, and finish below. `shape` follows this file through the user's concept choice, then reads [shape.md](shape.md), writes the design brief, and stops before code. PRODUCT.md owns durable product truth; DESIGN.md owns the current user-approved visual world.
 
-## Seed
+If PRODUCT.md or DESIGN.md is missing, stop and complete [init.md](init.md) first. For refinement, init documents coherent incumbent visual code instead of inventing a replacement. For redesign, init replaces the old visual world before returning here; the old system is evidence and anti-reference, not authority.
 
-If the project is brand-new (no committed tokens, fonts, or brand colors found in the code), run `node {{scripts_path}}/palette.mjs` for a brand seed color. The seed exists to break your reflex palette; it does not override the subject. When the subject's world clearly dictates color (an era, a place, a material, a medium), derive the palette from that world and use the seed only to check yourself. Otherwise anchor on it. The palette has exactly two legitimate sources: the seed, or the subject's world. What the category usually looks like is neither, and quietly swapping in the category's habitual palette and theme after drawing a seed is the reflex this step exists to break. Color commits at page scale: fields that own whole regions, not accents scattered over a neutral ground. A dark page with one glowing accent is the category's reflex, not a choice. Use OKLCH throughout. Skip this entirely when the code already has committed brand colors: identity-preservation wins.
+**A committed world does not decide the new surface.** Every case study, dashboard view, feature page, or section still needs an ownable task concept. The job here is to invent that concept with the user without re-rolling the brand.
 
-## Ground it in the subject
+## Name the work
 
-Name one concrete subject, its audience, and the page's single job. The subject's own world (its materials, instruments, artifacts, places, history, vernacular) is where distinctive choices come from. What would this thing look like as a physical object? What did its world look like before the web? A design whose subject appears only in the copy is a template wearing a costume.
+Use the user's intent, not the age of the codebase:
 
-## Decide, then build
+- **Greenfield** creates the first surface inside the world init just established.
+- **Redesign** composes inside the replacement world init just established. Preserve product truth, real content, functionality, and native affordances; do not preserve the discarded look by habit.
+- **Extension** adds a new surface inside the committed world. Preserve its lineage and interaction conventions while giving this task its own composition.
+- **Refinement** belongs to the invoked refinement command, not this full concept flow. Preserve the incumbent world and named scope.
 
-Derive the concept with this procedure, recording each step in your reasoning before the next begins. One: state the product's unique mechanism in one sentence, the thing competitors cannot truthfully claim. Two: competitive analysis; describe the page this category always ships, and the counter-position page a contrarian ships, and treat both structures as off the table. Three: from the audience's world and the subject's cultural home, list seven concrete materials, objects, documents, or rituals they know by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. Four: run `node {{scripts_path}}/concept-seed.mjs` and follow what it prints: it assigns which candidate to build (your top-ranked candidate is what every run would ship; a single ranking is deterministic, so the dice come from outside) and supplies challenger forms to weigh against your list on exactly two axes, audience identification and product clarity. Five: the chosen form supplies the page's structure, reading order, and component conventions; the product supplies every fact. Commit every atom: nav, buttons, inputs, and links are rebuilt in the form's vocabulary, and a stock component inside a committed form is a lapse. The form has its own native arrangement; borrow its skeleton, not just its clothes. Land the first build fully committed; committing is the hard part, and the passes that follow exist to make the committed thing clear and effective, never to dilute it. Conversion conventions live inside the form's own vocabulary: a hero that hooks in one line, a visible primary action, a legible reading order. The chosen form also dictates the first viewport's geometry: render the form at the scale it has in life, edge to edge when that is its nature; embedding it as a panel inside a standard marketing layout forfeits it. Cinematic full-bleed openings, intentionally divergent grids, and color drenched across whole regions are in bounds whenever the form calls for them; on an unattended build, the safe layout is the risk. The form has native motion, what it does in life between states; give the page that motion once, orchestrated, rather than scattered hover effects. <!-- rule:skill-concept-procedure -->
+If “redesign” could mean either a replacement identity or an on-brand structural adjustment, use the structured question tool to resolve that single ambiguity before proceeding. A plain “redesign this page/site” means replacement; “within the current brand/system” means extension or refinement.
 
-Then state the chosen direction as a contract, written as a comment block at the top of the artifact (invisible to visitors, binding for you), five short blocks, two hundred words at most. UNIQUE: the one idea this page owns. NOT-TEMPLATE: how the page's structure differs from the category's standard arrangement, stated plainly and honestly. OWN-WORLD: the palette and component language, specific enough that the components and colors alone, shown without content, would be recognizable as this page's world and nobody else's. STORY: what the visitor understands, believes, and does, from first viewport to action. FIRST VIEWPORT: the exact composition, what is where and at what scale. FORM: the chosen candidate and its position on your ordered list, plus the seed key the script printed. If any block is missing or reads like a mood, the direction isn't decided yet. The build is judged against this contract; delivering different pixels than the contract promises is a defect on whichever side is weaker. When a user can respond and the work is substantial, pause there for confirmation; when the harness has native image generation, follow [codex.md](codex.md)'s mock flow before code. When no user can respond, record the decision in your reasoning and proceed without pausing. Either way the decision comes first; code that precedes a direction is the template reflex in motion. <!-- rule:skill-decide-then-build -->
+## Discover the surface
+
+Name the subject, audience, surface job, visitor mode, real content, and primary action. Read PRODUCT.md and DESIGN.md as anchors, but ask about what is unique to this task. A case-study section, for example, needs the proof available, the transformation it must make legible, the audience's reading order, and the moment worth remembering; the global brand interview cannot answer those.
+
+In an attended run, ask a focused round of no more than three task questions, then wait. Use the structured question tool when available. Do not re-ask durable questions already settled in PRODUCT.md or DESIGN.md. A harness-provided simulated user is attended and must receive the same questions.
+
+For a narrow request whose content, outcome, and constraints are already explicit, assert what you understand and ask the user to confirm or correct it. Do not manufacture an interview when there is no material uncertainty.
+
+## Develop the surface concept
+
+The visual world supplies the vocabulary; the task concept supplies the sentence.
+
+1. **State the mechanism.** In one sentence, name what this surface does, proves, or enables that a neighboring product could not truthfully claim.
+2. **Expose the defaults.** Describe the category's habitual arrangement and the predictable contrarian response. Treat both as warnings, not automatic answers.
+3. **Derive structural material.** From the task's real content, PRODUCT.md's audience world, and DESIGN.md's existing motifs, list five to seven forms, documents, rituals, spatial arrangements, or behaviors that could carry the mechanism. Translate their reading order and relationships, not their costume, into interface structure.
+4. **Break the model's ranking rut.** For substantial greenfield, redesign, or extension work, run `node {{scripts_path}}/concept-seed.mjs`. Use its assigned index to promote one overlooked grounded candidate, and weigh its challengers only on audience identification and product clarity. A challenger may change topology or interaction, but it may not override the current DESIGN.md. Skip the seed for a small extension or when the user has already pinned the surface concept.
+5. **Offer real choices.** Present two or three materially different surface concepts. For each, give the layout or interaction thesis, narrative sequence, first-view or focal moment, signature use, and why it belongs in the committed world. These are not moodboards with different adjectives; the content must be organized or experienced differently.
+6. **Let the user direct.** Ask which concept is closest, what to combine, and what feels wrong. The user may reject all of them. Resolve the chosen concept before code. If one direction is overwhelmingly supported, assert it and ask for confirmation instead of staging a fake menu.
+7. **Probe when pictures would clarify structure.** When the harness has native image generation and the substantial, high-fidelity surface would benefit from a visual test, load [codex.md](codex.md) before writing the direction contract. Its probes stay inside DESIGN.md and pressure-test the shortlisted surface concepts; they never reopen palette, typography, or identity. Skip it for narrow extensions, low-fidelity work, or when the user already supplied an approved comp.
+
+When no human or structured question mechanism exists, follow the same derivation, build the seed's assigned grounded candidate when it survives the two tests, record the decision, and continue. Unattended does not mean unconsidered; external selection is what prevents the model from quietly returning to its own first choice.
+
+For `shape`, stop here after the user selects the concept and continue in [shape.md](shape.md). Do not write a direction contract or implementation.
+
+## Write the direction contract
+
+Before code, write the chosen task direction as a contract of at most 150 words. Place it in an opening HTML comment or framework comment block so the Impeccable Stop hook can audit the render against it. The first 200 characters of the comment must name `DIRECTION CONTRACT`.
+
+Use these six short blocks:
+
+- `UNIQUE`: the surface thesis tied to the product mechanism;
+- `NOT-TEMPLATE`: the category-default arrangement this structure refuses;
+- `OWN-WORLD`: the specific current DESIGN.md invariants, tokens, and materials it uses;
+- `STORY`: what the visitor understands, believes, and does from entry to action;
+- `FIRST VIEWPORT`: the exact composition, hierarchy, and primary action (or the equivalent first task for a product surface);
+- `FORM`: the chosen structural or behavioral form, its signature, and the concept-seed key when one was used.
+
+The contract is not visitor-facing content and not a second design system. It makes the task's promise inspectable. The user's selected concept is the authority; the seed is only provenance. <!-- rule:skill-decide-then-build -->
 
 ## Plan, self-check, build
 
-Plan a compact token system in your reasoning: palette, type, layout concept in one sentence, and a **signature**: the one element this surface will be remembered by, drawn from the subject's world. A signature carries weight: sized and placed so the page organizes itself around it. The layout has exactly two legitimate sources: the concept, or the content's own structure. The category's habitual skeleton is neither, and assembling the usual sections in the usual order after choosing a concept is the same reflex the palette rule breaks, expressed in structure. <!-- rule:skill-layout-source-exclusivity --> Then audit the plan: work through what you'd produce for a similar brief from another client, and wherever the two plans converge (same palette family, same face, same skeleton), that part is your generic default, not a choice. Revise it, then build, deriving every color and type decision from the revised plan.
+Plan how the chosen concept uses the current DESIGN.md's tokens or directions, reusable technical components, imagery language, and motion grammar. In a redesign, replace visual tokens from the discarded system rather than preserving them through implementation convenience. The layout has two legitimate sources: the concept and the content's real structure. The category's habitual skeleton is neither. Compare the plan with what you would produce for a neighboring product; wherever they converge for no product-specific reason, revise the generic part.
 
-**Pace the scroll like a studio.** The scroll is a rhythm, not a stack: alternate full-bleed bands of the palette, vary the treatment from section to section inside the one system (a dense passage earns a quiet one, a graphic section earns a typographic one), ground at least one section in the signature motif as texture, and end anchored by a real close. One spacing rhythm throughout, kept like a promise: sections breathe in large, legible beats, and the space above a heading always exceeds the space below it. A page whose every section wears the same weight and density reads as monotone no matter how strong the concept. <!-- rule:skill-scroll-rhythm -->
+Build the strongest coherent direction once. Commitment means the concept governs the entire requested surface; it does not mean disguising familiar controls as metaphors or violating the design system.
 
-**The first viewport is a thesis, not a header.** The visitor should meet the concept doing its job immediately: the work itself, the product working, the content answering, the task at hand. Generic chrome around a generic promise is the template answer; earn it or replace it. The composition is derived the same way the palette is: if a neighboring product could ship the same arrangement of the same blocks, the viewport isn't composed yet. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood ("clean", "tasteful"), the concept hasn't committed yet.
+**Make the opening a thesis.** The first viewport or first task should demonstrate the product's mechanism, not wrap a generic promise in generic chrome. If someone leaves after that moment, they should remember an idea or interaction, not merely a mood.
 
-**Everything bold, nothing bland.** Bold is not decoration and not clutter; it is commitment to the concept, carried through every section. Commitment takes whatever form the concept and the mode demand: maximal or severely clean, drenched in color or nearly monochrome, copy so precise it stings, the product demonstrating itself, or a system so exact it feels inevitable (a decisive typographic voice, one owned accent, an unmistakable rhythm). A spare page built on one uncompromising idea is bold; a busy page of tasteful defaults is bland. The signature is where the concept peaks, not the only place it lives; cut anything that neither advances the concept nor serves the visitor's mode. Polish is the floor, not the point: when torn between refined and committed, commit.
+**Pace the whole surface.** Long surfaces are a rhythm, not a stack. Vary density, scale, image, and quiet inside DESIGN.md's grammar. A case study should reveal evidence in the order it becomes persuasive; an Operate flow should reveal control in the order the task demands. Cut sections that only repeat claims.
 
-**Prove, don't claim.** A surface earns belief by showing its subject doing its job: the interface at work, the mechanism dramatized, the content delivering, specifics a competitor couldn't copy-paste. The visitor should understand by looking, before reading a word. Sections that restate a claim in different words add length, not substance, and a page that demonstrates everything you discovered while planning reads as cruft: build only the sections a visitor needs to understand, trust, and act.
+**Commit before correcting.** Land the chosen concept at full strength before the finishing pass makes it clear, usable, and effective. Do not weaken the hard creative move in anticipation of a generic “too gimmicky” critique; the measured failure is partial commitment, not excess conviction.
 
-## Commit
+**Make the signature structural.** Use the world's signature where the task concept peaks, at enough scale or consequence that the composition organizes around it. Scattering a motif as decoration is not commitment.
 
-Pick a color strategy before picking colors: Restrained (neutrals + one accent; the default when the visitor came to operate or read) / Committed (one saturated color carries 30-60% of the surface) / Full palette (3-4 named roles) / Drenched (the surface IS the color). Persuade and Experience surfaces have permission for the bolder strategies; take them when the brief allows. Dark vs. light is never a default: write one sentence of physical scene (who uses this, where, under what light, in what mood) and let it force the answer. The warm cream near-white body background is the saturated AI default; where the axis is free, pick a background that is a choice.
+**Prove, don't claim.** Show the mechanism working, the actual artifact, the before-and-after, the data, or the specific content. A surface earns belief through evidence a competitor could not copy-paste.
 
-- Name a real reference before picking a strategy; unnamed ambition becomes beige. <!-- rule:brand-color-named-reference -->
-- Palette IS voice: a calm brand and a restless brand should not share palette mechanics, and each new surface differentiates from the last. <!-- rule:brand-color-palette-is-voice -->
-- When a cultural-symbol palette is the obvious pull, reach past it. Let the cultural reading come from typography, imagery, and copy, not the palette. <!-- rule:brand-color-no-cultural-symbol -->
+For Operate and Read, familiar controls and comprehension remain primary; expression comes from topology, hierarchy, density, rhythm, state, and the system around them. For Persuade and Experience, dramatic pacing and art direction are available when the selected concept earns them, while the primary action and reading order stay clear.
 
-## Type and imagery
-
-Choose faces like objects from the subject's world, in the mode's register: Operate and Read surfaces are well served by system stacks and workhorse UI faces; Persuade and Experience surfaces want faces with a point of view, and these training-data defaults mean you stopped looking: Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter-as-display, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans.
-
-Briefs that imply imagery (food, travel, place, product, fashion) must ship real, verified imagery, searched for the subject's physical object rather than the category; a colored rectangle where a photo belongs reads as incomplete, and one decisive photo beats five mediocre ones. Verify stock URLs resolve before shipping them.
-
-## Calibration
-
-AI-generated interfaces cluster around a few looks regardless of subject: warm cream + high-contrast serif + terracotta accent; near-black + one neon accent (acid green, cyan) + glowing edges; broadsheet-editorial hairlines + italic display serif + small tracked mono labels. All are legitimate when the brief calls for them; the brief always wins. Where the brief leaves the aesthetic free, landing in one of them means your self-check failed. Same one tier deeper: if someone could guess your aesthetic from the category alone, or from category-plus-avoidance, rework until neither answer is obvious.
-
-**Name the aesthetic lane, then test it.** Before committing to moves, say which lane this is (a specimen page, minimal-cool tech, acid maximalism...). Then the inverse test: describe what you're about to build the way a competitor would describe theirs; if that sentence fits the modal page in the category, restart. <!-- rule:brand-typo-pairing-voice --> Currently saturated lanes count as reflexes, not choices, when the brief doesn't require them; the flooded one right now is editorial-typographic (display serif, often italic, small mono labels, ruled separators, monochromatic restraint, no imagery). <!-- rule:brand-typo-reflex-reject-lanes -->
-
-## Persuade and Experience moves
-
-Layout: asymmetric compositions and intentional grid breaks are on the table; fluid spacing with `clamp()` that breathes on larger viewports; for image-led briefs, full-bleed hero imagery with overlaid navigation is a canonical move, letting the photograph be the design. <!-- rule:brand-layout-image-led-hero --> Permissions the Operate world doesn't get: ambitious first-load motion (one orchestrated page-load beats scattered micro-interactions; skipping entrance motion entirely is also a voice), single-purpose viewports (one dominant idea per fold, deliberate pacing), and art direction per section when the narrative demands it; consistency of voice beats consistency of treatment. <!-- rule:brand-permission-first-load-motion -->
+Briefs that depend on imagery ship real, verified imagery. Preserve semantic HTML, familiar interaction behavior, accessibility, performance, responsive behavior, and the project's technical conventions.
 
 ## Finish like a studio
 
-Look at what you built the way a design lead would, with whatever eyes the harness gives you (browser, screenshot tool, or reading the code cold): major sections individually on long pages, mobile and desktop at minimum. Write an honest critique against the brief and the stated direction, patch material defects, and re-inspect; don't invent defects to demonstrate diligence. Then verify against SKILL.md's craft floor and run the detector; a bold page that ships mechanical defects is not done, and neither is a polished page missing something the brief asked for. <!-- rule:skill-finish-like-studio -->
-
-When the harness can run a separate agent, the review above belongs there, not here: hand the reviewer the artifact path, its direction contract, and the detector command, and have it return a short list of material fixes; apply them and finish. A fresh reader catches what the builder's own eyes slide past, and the build thread stays spent on building. <!-- rule:skill-finish-separate-reviewer -->
+Inspect desktop and mobile, write one honest critique against the task brief, DESIGN.md, the user's selected concept, and the direction contract, then patch material defects. Judge the skeleton skin-blind: mentally remove color, type, texture, and concept nouns; if the remaining block arrangement is the category template, rebuild the structure. Run the detector once. On harnesses with a Stop hook, let its contract audit run and fix every real gap it identifies; classify false positives rather than distorting intentional work. Repeat only while a real defect remains. A separate reviewer is optional when the harness provides one and the risk earns the cost. <!-- rule:skill-finish-like-studio -->