@prestyj/cli 5.28.0 → 5.29.0

package/assets/skills/evidence-led-ui/SKILL.md

@@ -1,158 +1,100 @@
 ---
 name: evidence-led-ui
-description: Use for web/mobile UI creation, redesign, visual polish, accessibility work, and UI review, including small styling fixes and changes to focus, control states, borders, or dropdown icons. Use the small-edit path for narrow changes. Exclude behavior-only wiring unrelated to visual states, copy-only changes, database/API schemas, CLI output, standalone image/SVG generation, and description-only tasks.
+description: Use when building or changing web/mobile UI: net-new screens or pages, redesigns, design systems, visual polish, UI review, and mid-build edits touching colour, type, spacing, icons, focus/hover/selected states, borders, dropdown icons, motion, or UI copy layout. Also use when output looks generic or AI-made. Small styling fixes take the small-edit path. Do NOT use for behavior-only wiring with no visual state, copy-only text changes, database/API schemas, CLI output, or standalone image generation; speed/bundle work is lean, legal/privacy review of public pages is compliance-guard.
 license: See LICENSES.md
-compatibility: Full review requires filesystem inspection and rendered screenshots; web research and browser/device tooling are optional and unavailable checks must be reported honestly.
+compatibility: Full review requires filesystem inspection and rendered screenshots (deferred `screenshot` tool); web research and device tooling are optional and unavailable checks must be reported as unverified.
 ---
 
 # Evidence-Led UI
 
-Use this skill for web or mobile interface creation, redesign, implementation, styling, and review.
+Pick your mode, then follow only that section:
 
-## Small-edit path
-
-For a narrow styling or control-state fix, skip the broad design workflow, not verification:
-
-1. Read the shared primitive, tokens, state rules, and affected callers. Reproduce the reported sequence before editing.
-2. For focus, borders, glass effects, or dropdown icons, read `references/craft-rulings.md` § Control icon insets and § No sticky pointer focus. Identify the rule drawing the defect before adding an override.
-3. Fix the shared owner, not each screen. Check affected variants and remove superseded local treatments within scope. Any supporting copy added or changed must pass § Copy must earn its space in `references/craft-rulings.md`; small edits must not accumulate redundant descriptions.
-4. Run the applicable interaction regression matrix in the craft rulings using the project's browser checks or manual browser verification. Screenshots alone cannot pass interaction checks. Report actual evidence and any unverified platform.
-
-## Governing rule
-
-Inspect before inventing. Preserve the project's visual language unless the user explicitly requests a redesign. Treat corpus findings as conditional observations, not official brand truth, universal rules, or a house style.
-
-Aesthetic distinction is contextual. Semantic structure, operability, responsive stability, performance, honest content, accessibility, and user trust are the non-negotiable floor.
-
-## Binding craft defaults
-
-Apply these on every UI task. Read `references/craft-rulings.md` when implementing or reviewing their details.
-
-- **No emoji UI:** Never use emoji as icons, bullets, status marks, or decoration unless explicitly requested. Reuse the project icon system; otherwise use one coherent icon package.
-- **Uniform geometry:** Align containers, columns, section edges, baselines, dividers, control heights, and repeated component anatomy. Break alignment only for a clear content reason.
-- **One shared content rail:** Default navigation, header, main content, footer, and adjacent sections to the same max-width, inline gutters, and breakpoint padding. Full-bleed backgrounds may differ, but their inner content edges must align. Any different width or offset needs an explicit user or content reason, never one-off margin or padding.
-- **No edge-hugging control icons:** Select, dropdown, and combobox chevrons and other trailing icons need a deliberate inline-end inset plus enough reserved text padding for the icon and gap. They must never touch the control edge or overlap content; use logical properties so the anatomy also works in RTL.
-- **Reuse first:** Search for existing components, variants, tokens, utilities, icon wrappers, focus rings, and motion curves before creating new ones.
-- **Purposeful feedback:** Relevant hover, focus, press, selected, expanded, loading, success, and error states need clear feedback. Avoid abrupt changes when a short transition improves continuity.
-- **No soft semantic tint-on-tint:** Do not default badges, buttons, toasts, cards, selected states, or icon medallions to a low-opacity semantic-color background with saturated same-hue text or icons, with or without a matching border. Unless the user explicitly requests that treatment or an established system must be preserved, choose a product-specific alternative rather than imposing one universal replacement style.
-- **Focus is not selection or decoration:** Diagnose the actual painted layer before changing it. Reuse one shared focus treatment, separate from glass borders/reflections and selected, expanded, or error states. Do not stack local rings on it. Prevent stale pointer-originated highlights without blurring controls, suppressing keyboard focus, or removing legitimate state cues. Prefer native `:focus-visible` behavior; custom modality handling requires a reproduced platform defect and the regression matrix in `references/craft-rulings.md`.
-- **No generic hover lift:** Do not default to `translateY`, bobbing, floating, or scale-up on hover. Prefer color, border, underline, icon fill, opacity, or restrained shadow changes.
-- **No `transition: all`:** Name transition properties, reuse duration/easing tokens, and provide a reduced-motion path.
-- **Intentional type:** Reuse the existing type system. For net-new web work, select an appropriate modern family or pairing; do not use Arial, Helvetica, or bare `system-ui` as the aesthetic direction.
-- **WCAG 2.2 Level AA is the accessibility floor:** Every web UI and complete user flow must meet every applicable Level A and Level AA success criterion, not a hand-picked subset. Native apps apply WCAG2ICT where relevant plus current platform accessibility requirements. Stricter project, contract, platform, or jurisdiction rules win; accessibility cannot be traded for aesthetics, scope, delivery speed, or a higher rubric score.
-- **No unsupported accessibility claims:** Treat ADA as an equal-access legal obligation, not a badge earned by Lighthouse, axe, or another scanner. Never label a UI `ADA compliant` or `WCAG conformant` from source review or automated checks alone; a claim requires a defined scope, per-criterion evidence, manual keyboard and assistive-technology testing, and qualified legal or product-owner review when legal compliance is asserted.
-- **Measured contrast:** Meet WCAG 2.2 contrast for text, controls, icons, focus, and meaningful graphics. Muted text must remain readable.
-- **Consistent flow:** Repeated navigation and actions keep the same order, labels, icons, placement, and behavior across sections and pages.
-- **Copy must earn its space:** Start with clear labels, controls, and relevant status, not automatic subtitles, helper paragraphs, or footer notes. Supporting text must add information needed here that the interface does not already communicate. Remove repetition, show state-specific guidance when needed, and move optional detail into contextual help. Keep essential instructions and consequences visible before action. Reduce unnecessary copy before compressing layout; verify reading effort in the rendered UI. See `references/craft-rulings.md` § Copy must earn its space.
-- **No generated em dashes:** Do not write em dashes in user-facing UI copy unless explicitly requested or exact supplied source text must remain unchanged.
-
-## Reference map
-
-Resolve every path from the installed skill root. Load only what the task needs:
-
-- `references/craft-rulings.md`: implementation detail for the binding defaults above.
-- `references/ui-libraries.md`: real Bklit/Kokonut component discovery/adoption and Motion APIs. Read for relevant React UI creation after checking existing project UI; use deferred `ui_registry` and `ui_adopt` rather than inventing a library lookalike.
-- `references/production-contract.md`: binding pass/fail semantics, WCAG/ADA accessibility, forms, performance, resilience, platform, trust, AI, media, theme, and release checks. Read its accessibility sections for every implemented or reviewed UI; read the full contract for broad features, behavior changes, forms, navigation, data/AI interfaces, native work, performance work, or release review.
-- `references/archetypes.md`: surface-specific direction and relevant source slugs. Read for net-new UI, redesigns, or unresolved visual direction.
-- `references/observed-patterns.md`: measured corpus observations. Read only sections that answer a real design question.
-- `references/anti-defaults.md`: transferable AI-generated patterns to challenge. Read for broad visual work or generic-looking output.
-- `references/quality-rubric.md`: rendered scoring and revision gate. Read before critiquing broad output.
-- `references/methodology.md`: extraction method, denominators, and limitations. Read only to audit evidence.
-- `references/provenance.md` and `LICENSES.md`: sources, licenses, standards status, and Refero boundaries.
-
-Do not load `data/observations.json` or the raw corpus by default. Open a raw source only to audit one claim or inspect one selected exemplar. Never load the full corpus into context.
-
-## Workflow
+| Situation | Mode | Go to |
+| --- | --- | --- |
+| One control, state, border, icon inset, focus bug, or token tweak | Small edit | § Small-edit path |
+| New screen/page/component, redesign, or "make it look less generic" | Build | § Build loop |
+| "Review this UI", audit screens or flows, pre-ship look | Review | § Review mode |
 
-### 1. Inspect the project
+Every mode obeys § Binding defaults. Preserve the project's visual language unless the user asked for a redesign.
 
-Inspect the nearest relevant routes, real content, shared components, semantic controls, tokens, theme, typography, icons, motion, screenshots, tests, responsive conventions, and existing states.
-
-Reuse the local system. Do not add a design library merely to obtain a look. For a net-new project with no neighbors, derive direction from the brief and matching archetype rather than choosing a fashionable default.
-
-### 2. Write a design read
-
-Resolve:
-
-- **Surface:** marketing, application UI, dashboard/data-dense, commerce/marketplace, editorial/content, documentation/developer tool, mobile/native, or one named hybrid with a clear leader.
-- **Audience:** user, expertise, environment, and access needs.
-- **Single job:** the one outcome this screen must make easiest.
-- **Task and risk:** frequency, decision cost, error cost, and time pressure.
-- **Content:** real hierarchy, density, variability, media, data, and longest plausible values.
-- **Platform:** viewport/window, input modes, support policy, navigation behavior, and framework conventions.
-- **Constraints:** existing tokens/assets, redesign scope, performance limits, and required tone.
-
-Infer missing facts from the project and state the inference. Ask only when code cannot resolve a genuine product or taste decision.
-
-### 3. Select evidence only when it helps
-
-For broad net-new work or a redesign, read the matching archetype and usually choose two aligned source slugs plus one contrast. Record why each applies.
-
-For a small change in an established system, local components and tokens may be sufficient. A frequency can support investigation, not automatically become a recommendation. Prefer local product evidence, then archetype evidence, then corpus-wide frequency.
-
-Refero is optional. Use it only through an authorized Refero MCP or user-provided authorized export. Do not scrape Refero, call undocumented endpoints, or access disallowed routes.
-
-### 4. Form one design thesis
-
-State one compact direction:
-
-- semantic color/type/icon/spacing/grid/motion roles and a reuse map;
-- first glance, second glance, primary action, and supporting evidence;
-- composition and uniform alignment rules;
-- reasons for borders, surfaces, shadows, blur, gradients, or imagery;
-- feedback, duration/easing, resting behavior, and reduced-motion equivalent;
-- one memorable device grounded in the subject, content, or interaction.
-
-One thesis leads. Do not combine several aesthetic directions into a mood-board compromise.
+## Small-edit path
 
-### 5. Run the anti-default check
+Skip the design workflow, not verification:
 
-For broad visual work, read `references/anti-defaults.md`. Flag emoji UI, mixed icon families, arbitrary misalignment, duplicated local styling, abrupt interaction, generic hover lift, soft semantic tint-on-tint treatments, generic type, generated em dashes, centered gradient heroes, glass cards, equal card grids, decorative eyebrows, random metric blocks, ubiquitous pills, dark-premium assumptions, fake terminals, floating screenshots, bento layouts, ambient motion, icon medallions, and invented proof.
+1. Read the shared primitive, tokens, state rules, and callers. Reproduce the reported sequence before editing.
+2. Focus, borders, glass, or dropdown icons: read `references/craft-rulings.md` § Control icon insets and § No sticky pointer focus. Find the rule that paints the defect before adding an override.
+3. Fix the shared owner, not each screen. Check variants; remove superseded local treatments in scope. Added copy must pass § Copy must earn its space.
+4. Run the applicable interaction regression matrix in `references/craft-rulings.md` via browser checks. Screenshots alone cannot pass interaction checks. Report actual evidence and unverified platforms.
 
-Keep a flagged pattern only after completing: **“This belongs because…”** with a product-specific reason. Replace choices that could survive unchanged in an unrelated product.
+## Build loop
 
-### 6. Plan the complete task flow
+One design thesis, one author. Do not blend directions.
 
-Plan only relevant states, but include the complete primary path and recovery:
+1. **Inspect.** Read nearest routes, components, tokens, type, icons, motion, and states. Reuse the local system; add no library just for a look. React and nothing local fits: read `references/ui-libraries.md` and use `ui_registry`/`ui_adopt` (via `tool_search`) for real Bklit/Kokonut source, never a lookalike.
+2. **Content first.** Write real headline, labels, section copy, and realistic data (longest, empty, 0/1/many) before layout. Rank it. Delete sections with nothing true to say. Never invent metrics, testimonials, logos, or ratings; label fixtures. Details: `references/direction.md` § 1.
+3. **Read the job.** Surface type, audience, single job, risk, platform, constraints. Infer from the project and state the inference; ask only for genuine taste or product decisions. Net-new or redesign: read the matching section of `references/archetypes.md`.
+4. **Write the thesis** using the template in `references/direction.md` § 2: signature, type roles, OKLCH colour tokens with intended contrast pairs, spacing/density, radius/material, imagery, motion, rejected defaults. Broad work goes in `DESIGN.md`.
+5. **Slop check the thesis** against `references/anti-defaults.md`. Every tell is replaced or justified with "This belongs because…". Run the neighbour test (§ 7 there).
+6. **Plan states:** loading, empty, error, retry, success, disabled, destructive; hover, focus-visible, press, selected, expanded, pending; keyboard order, overlays, narrow/wide, reduced motion, zoom/reflow, long and localized text. Apply the accessibility sections of `references/production-contract.md`; the full contract for forms, navigation, data/AI, native, or release work.
+7. **Implement** the complete flow with real content. Decision-critical information and the primary action stay visible or one obvious action away on desktop and mobile.
+8. **Verify rendered output** (§ Rendered verification loop).
 
-- loading, empty, error, retry, offline, success, disabled, and destructive outcomes;
-- hover, focus-visible, press, selected, expanded, and pending feedback;
-- keyboard order, accessible names/status, overlay focus, and drag alternatives;
-- pointer-versus-keyboard focus behavior, including native popup dismissal and clicks onto non-focusable space;
-- narrow, intermediate, desktop, wide/resizable, pointer, touch, and no-hover behavior;
-- reduced motion, forced colors, zoom/reflow, long/localized/RTL text, missing media, and realistic data extremes;
-- text alternatives and media equivalents, landmarks/headings, language, labels/instructions/errors, status announcements, timing, flashing, and sensory-independent instructions where applicable.
+## Rendered verification loop
 
-For every UI, read and apply the accessibility sections of `references/production-contract.md`. For broad behavior, forms, navigation, native, data/AI, performance, or release work, apply the full contract. A visual score cannot compensate for a relevant contract failure.
+1. Load `screenshot` via `tool_search`. Capture desktop (~1440 px) and mobile (~390 px), plus key states.
+2. Compare each capture against the written thesis line by line, then against `references/anti-defaults.md`.
+3. Score with `references/quality-rubric.md`. Measure contrast of real rendered pairs; record pass/fail/unverified for applicable contract checks.
+4. Fix the weakest criterion and every contract failure. Remove one decorative idea that does not serve the job. Re-capture.
+5. Stop after one revision unless the gate still fails. Gate: **20/24 or higher**, no zero in accessibility, consistency and flow, responsive behaviour, state completeness, or content authenticity, and no applicable WCAG A/AA failure. Small components: 2 on every applicable floor criterion.
 
-### 7. Document broad work
+No screenshot tool or browser available: say so, mark visual checks unverified, never claim the look was verified.
 
-For a broad page, multi-screen feature, or redesign, create or update `DESIGN.md` with the design read, evidence, thesis, semantic tokens, reused primitives, craft system, components/states, responsive behavior, and applicable production checks. Keep a small component plan in work notes instead.
+## Review mode
 
-### 8. Implement the product
+Inspect code and rendered output. Return findings ordered by impact, each with screenshot or file:line evidence, label (`RUNTIME` observed, `CODE` read in source, `DEDUCED`, `SNAPSHOT` dated source), and the fix. Separate floor defects (accessibility, states, broken layout) from aesthetic opportunities (slop tells). Recommend one resolved direction.
 
-Use real project content and data. Label fixtures honestly. Never invent testimonials, customer logos, ratings, metrics, or claims as fact.
+## Binding defaults
 
-Reuse dependencies and primitives. Use one coherent icon system. Meet every applicable WCAG 2.2 Level A and AA criterion across the complete flow, including its states and responsive variants. Maintain semantic controls, visible keyboard focus, keyboard operation, assistive-technology output, measured contrast, readable line lengths, stable adaptive layout, and reduced-motion support. Pointer interaction must not leave a false focus, active, or selected-looking highlight behind. Implement the complete planned flow, not only its first screenshot.
+Details and fixes: `references/craft-rulings.md`.
 
-The representative initial state must keep decision-critical information and the primary action visible or one obvious action away on desktop and mobile. Preserve selected context through master-detail recomposition. Keep demo, debug, and state-switching controls subordinate and non-obscuring.
+- **No emoji UI.** One coherent icon family; reuse the project's.
+- **Uniform geometry and one content rail.** Shared max-width, gutters, and breakpoint padding for nav, header, main, footer. Break alignment only for a stated content reason.
+- **Control icon insets.** Chevrons and trailing icons get a deliberate inline-end inset plus reserved text padding; never touch the edge or overlap text; logical properties for RTL.
+- **Reuse first.** Existing components, variants, tokens, focus rings, motion curves before new ones.
+- **Focus is not selection or decoration.** Diagnose the painted layer; one shared focus treatment separate from borders, glass, selected, expanded, error. No stacked rings. Prefer native `:focus-visible`; custom modality handling needs a reproduced defect and the regression matrix.
+- **No soft semantic tint-on-tint** unless requested or required by an existing variant.
+- **Motion:** no generic hover lift, no `transition: all`, named properties, tokens, reduced-motion path.
+- **Intentional type and colour:** see `references/direction.md`. Not Inter/violet-gradient by default on brand surfaces.
+- **Copy must earn its space.** No automatic subtitles, helper paragraphs, or footer notes; supporting text adds information the interface lacks. Named-outcome CTAs.
+- **No em dashes in UI copy** unless requested or exact supplied copy.
+- **WCAG 2.2 Level AA is the accessibility floor** for every applicable A/AA criterion across complete flows; native apps add WCAG2ICT and platform rules. Stricter project or legal rules win. Accessibility is never traded for aesthetics or speed.
+- **No unsupported accessibility claims.** Never say `ADA compliant`, `WCAG conformant`, or "accessible" from source review or scanners; that needs a defined scope, per-criterion evidence, manual keyboard and assistive-technology testing, and owner/legal review. Dated legal context: `references/production-contract.md` § 2.
 
-### 9. Critique rendered output once
+## Scaling: one agent or several
 
-Capture representative desktop and narrow/mobile output. Score broad work with `references/quality-rubric.md`, record applicable production checks as pass/fail/unverified, remove one unnecessary decorative idea, revise the weakest criterion and any contract failure, then re-capture.
+| Situation | Policy |
+| --- | --- |
+| Small edit, build, redesign | Main thread only. One thesis, one author; never split a design across children. |
+| Review of one or two flows you can render and read yourself | Main thread only. |
+| Review of many screens/flows, or several apps | Build a ledger: rows = flows/screens × {slop tells, states, accessibility contract, responsive}. Fan out read-only general-purpose children (they have the `skill` tool), one per disjoint flow, all in ONE `spawn_agent` call, ≤ 6 per wave. |
+| A dated legal or platform claim needs checking | One `researcher` child. |
 
-Default to one critique-and-revision cycle. Run another only when evidence still fails the score or production gate. If a check is unavailable, report it as unverified instead of looping or substituting more polish.
+Each child brief contains: the absolute skill root path (the `Skill root directory` shown when this skill loaded), files to read (`references/anti-defaults.md`, `references/quality-rubric.md`, the accessibility sections of `references/production-contract.md`), the flow's routes and how to run the app, the ledger rows it owns, the instruction to capture desktop and mobile screenshots with the `screenshot` tool, the evidence labels, and the output schema: findings (screen, screenshot or file:line, label, severity, fix) plus explicit `checked` and `not checked` lists. Children do not edit.
 
-Broad work is complete at **20/24 or higher**, with no zero in accessibility, consistency and flow, responsive behavior, state completeness, or content authenticity, and only after applicable production checks pass. Any applicable WCAG Level A or AA failure blocks completion regardless of score. A small component must score 2 on every applicable quality-floor criterion and pass its accessibility contract checks.
+Merge: a failed, timed-out, or silent row is `not checked`, never clean. Re-open each reported file:line or re-capture before reporting it. Large pre-ship reviews get one fresh verifier child that tries to disprove the findings. Fixes stay on the main thread (or `bee` children on strictly disjoint files) against the single thesis; run checks once after merging.
 
-## Review-only mode
+## Reference map
 
-Inspect the project and rendered output. Return findings ordered by impact, cite screenshot/code evidence, name the matching archetype when relevant, and recommend one resolved direction. Distinguish quality-floor defects from aesthetic opportunities.
+Load only what the task needs; resolve paths from the skill root.
 
-## Evidence discipline
+- `references/direction.md`: content-first, thesis template, type, OKLCH colour, spacing, imagery, motion, verified Baseline features, INP practice.
+- `references/anti-defaults.md`: slop tells with replacement moves and the neighbour test.
+- `references/craft-rulings.md`: icons, geometry, insets, focus vs selection, regression matrix, type loading, contrast, copy rules.
+- `references/production-contract.md`: pass/fail semantics, WCAG/ADA/EAA context, forms, performance, platform, trust, AI, release evidence.
+- `references/quality-rubric.md`: rendered scoring gate.
+- `references/ui-libraries.md`: Bklit/Kokonut adoption and Motion APIs.
+- `references/archetypes.md`: surface-specific direction and corpus source slugs.
+- `references/observed-patterns.md`: measured corpus observations; read only the section that answers a question; keep numerator/denominator with any claim.
+- `references/methodology.md`, `references/provenance.md`, `LICENSES.md`: method, sources, standards status, licences, Refero boundary.
 
-- Keep a numerator/denominator or numeric sample count with every corpus claim.
-- Treat source slugs as observations of selected public surfaces, not official systems or permission to reproduce a brand.
-- Never recommend a color, font, radius, theme, or layout solely because it is frequent.
-- State corpus gaps plainly. Mobile/native has zero direct documents in this snapshot; use platform guidance and device testing.
-- If local evidence conflicts with corpus evidence, follow the product and record why.
+Never load `data/observations.json` or the raw `corpus/` into context; open one raw source only to audit one claim. Corpus frequencies are observations of public surfaces, not brand truth or a reason to pick a colour, font, or layout. Mobile/native has no corpus documents; use platform guidance. Refero only through an authorized MCP or user export.

package/assets/skills/evidence-led-ui/references/anti-defaults.md

@@ -1,211 +1,110 @@
-# Anti-Defaults
+# Slop Tells and Replacement Moves
 
 ## Contents
 
-- Purpose and review method
-- Template composition: centered gradient hero, glass cards, equal card grids, eyebrows, metric blocks, pills, soft semantic tint-on-tint treatments, dark-premium assumptions, huge type, fake terminals, floating screenshots, and bento layouts
-- Decoration and truth: ambient motion, icon medallions, false authenticity, emoji, and mixed icon language
-- Craft regressions: generic hover lift, abrupt states, accidental misalignment, reimplemented local styling, generic type, and generated em dashes
-- Final anti-default review
-
-## Purpose
-
-An anti-default is not a ban. It is a prompt to prove that a visual choice belongs to this product, audience, content, and archetype. A choice passes when changing it would weaken the screen’s job or subject-specific identity.
-
-For every flagged pattern, write one sentence: **“This belongs because…”** If the sentence only says “modern,” “premium,” “clean,” “engaging,” or “on brand,” replace the choice.
-
-## Centered gradient hero
-
-**AI tell:** Centered oversized headline, violet/blue glow, two CTAs, product screenshot floating below.
-
-**Default action:** Build hierarchy from the actual claim, proof, and product behavior; choose composition after content.
-
-**Legitimate when:** The brand owns the gradient or light behavior, the page has one conversion job, and the centered pause supports the narrative. `stripe` and `framer` are relevant evidence; neither makes the pattern universal.
-
-## Generic glass cards
-
-**AI tell:** Translucent rounded rectangles with blur and hairlines layered over decorative color fields.
-
-**Default action:** Use a clear material model—flat canvas, tonal surface, border, or measured elevation—with one reason for each layer.
-
-**Legitimate when:** Content conceptually sits over live media/map/video, temporary overlays need context, or translucency is an established local platform material.
-
-## Equal three-card feature grid
-
-**AI tell:** Three interchangeable icon-title-copy cards used because the viewport divides neatly.
-
-**Default action:** Rank the content, then let importance and relationship determine module size and sequence.
-
-**Legitimate when:** Exactly three peer choices exist, comparison is the user’s task, and equal weight is truthful.
-
-## Decorative eyebrow label
-
-**AI tell:** Uppercase mono text above every heading, often paired with a dot or rule, regardless of content.
-
-**Default action:** Remove it unless it names useful hierarchy, sequence, category, status, or technical context.
-
-**Legitimate when:** Editorial taxonomy, step labels, system state, or a real dual-register type system makes the eyebrow informative.
-
-## Random metric blocks
-
-**AI tell:** Large percentages and counts inserted to make a page look credible or data-rich.
-
-**Default action:** Show only metrics with a source, unit, time frame, comparison, and decision consequence.
-
-**Legitimate when:** The metric is auditable and answers a question central to the screen, such as current capacity, conversion, latency, or balance.
-
-## Ubiquitous pills
-
-**AI tell:** Navigation, buttons, filters, badges, cards, and inputs all become capsules.
-
-**Default action:** Reserve full pills for roles that benefit from compact enclosure or toggle/tag semantics; use a smaller local radius vocabulary elsewhere.
-
-**Legitimate when:** The project already uses an orbital/capsule motif, a control’s variable label length needs it, or tactile consumer friendliness is a deliberate material rule.
-
-## Soft semantic tint-on-tint
-
-**AI tell:** Badges, buttons, toasts, cards, selected states, status rows, and icon medallions repeatedly use low-opacity semantic-color backgrounds with saturated same-hue text or icons, sometimes with a matching border. Component libraries often name this formula `soft`, `subtle`, `surface`, or `tonal`.
-
-**Default action:** Replace the formula, then derive the new treatment from the product's actual aesthetic and component role. A neutral surface with one semantic marker, a solid fill with neutral high-contrast text, monochrome styling, product accent, typography, or another coherent local material model can work; none is the universal replacement.
-
-**Legitimate when:** The user explicitly requests tint-on-tint or exact reuse of an established design-system variant is required by scope. Unlike most patterns in this file, this is a binding craft default rather than a pattern justified by generic claims such as `clean`, `friendly`, or `modern`.
-
-## Dark equals premium
-
-**AI tell:** Near-black canvas, purple glow, thin gray borders, and muted text chosen without product evidence.
-
-**Default action:** Choose theme from environment, content, task duration, contrast needs, imagery, and existing brand.
-
-**Legitimate when:** Media needs darkness, the tool is used in low-light environments, the brand is dark-first, or the existing product already supports a tested dark theme.
-
-## Huge type equals distinction
-
-**AI tell:** 96–160px headline doing all the visual work while content hierarchy remains shallow.
-
-**Default action:** Establish contrast through wording, measure, weight, width, placement, and surrounding scale before increasing size.
-
-**Legitimate when:** The surface is campaign/editorial, the phrase is short, localization is tested, and the type itself is the subject or signature.
-
-## Fake terminal or code theater
-
-**AI tell:** Decorative prompts, logs, monospace labels, and syntax colors on any developer-facing page.
-
-**Default action:** Use real commands, code, output, errors, and copy behavior—or use ordinary product evidence.
-
-**Legitimate when:** The user’s task genuinely involves code/CLI output and the example is accurate, selectable, versioned, and useful.
-
-## Floating product screenshot
-
-**AI tell:** Perspective-tilted dashboard image with glow, no readable details, and no relationship to the claim.
-
-**Default action:** Show a focused, legible product state tied to the adjacent proof, or demonstrate the interaction directly.
-
-**Legitimate when:** Spatial overview matters, the screenshot is current and honest, and perspective does not hide evidence users need to judge.
-
-## Bento by default
-
-**AI tell:** Every feature becomes a differently sized rounded tile, producing visual variety without semantic structure.
-
-**Default action:** Map module size to priority, content type, and reading order; simplify any tile that exists only to fill a gap.
-
-**Legitimate when:** The screen is genuinely an overview of heterogeneous modules and tile persistence supports scanning or rearrangement.
-
-## Ambient perpetual motion
-
-**AI tell:** Marquees, floating particles, pulsing glows, or auto-rotating cards that continue without user intent.
-
-**Default action:** Keep the resting screen still; animate state change, spatial continuity, feedback, or a finite narrative beat.
-
-**Legitimate when:** Motion is the content (audio, time, live system activity), remains comprehensible when paused, and has a reduced-motion alternative.
-
-## Generic icon medallions
-
-**AI tell:** Every section starts with a line icon inside the same tinted rounded square.
-
-**Default action:** Remove icons that repeat the heading; use diagrams, imagery, or symbols only where recognition becomes faster.
-
-**Legitimate when:** Icons support repeated navigation, status scanning, compact controls, or a real category system.
-
-## False authenticity
-
-**AI tell:** Invented testimonials, logos, avatars, customer counts, ratings, or precise business data.
-
-**Default action:** Use real project content; if unavailable, label honest illustrative content plainly and avoid claims.
-
-**Legitimate when:** The user explicitly supplies approved fixtures or asks for a clearly marked prototype dataset.
-
-## Emoji used as interface imagery
-
-**AI tell:** Emoji stand in for icons, status marks, bullets, empty-state art, or section decoration, producing platform-dependent color and inconsistent geometry.
-
-**Default action:** Reuse the project's icon system or one coherent icon package, with accessible labels and consistent optical sizing.
-
-**Legitimate when:** The user explicitly requests emoji, emoji is the actual content being entered or discussed, or exact supplied source copy must retain it.
-
-## Mixed or improvised icon language
-
-**AI tell:** Package icons, hand-drawn SVGs, text glyphs, and platform symbols appear together with mismatched stroke, fill, weight, and bounding boxes.
-
-**Default action:** Select one installed family and one wrapper component. Normalize size, stroke/fill, color, target, label, and state treatment.
-
-**Legitimate when:** A required third-party brand mark or native platform symbol carries meaning that the product icon family cannot replace.
-
-## Generic hover lift
-
-**AI tell:** Cards and buttons jump upward, scale, bob, or float on every hover regardless of material or task.
-
-**Default action:** Use a short background, border, underline, icon-fill, opacity, or restrained shadow transition. Keep geometry stable.
-
-**Legitimate when:** Spatial movement communicates actual drag, depth, stacking, or physical direct manipulation, and reduced motion removes non-essential travel.
-
-## Abrupt interactive states
-
-**AI tell:** Hover, press, expand, selection, loading, success, and error snap with no continuity or acknowledgement.
-
-**Default action:** Give every relevant state clear feedback and transition interpolable properties with shared duration/easing tokens. Keep focus visible immediately.
-
-**Legitimate when:** Reduced-motion preference, urgent safety feedback, or an inherently discrete state requires an immediate change; meaning must still remain clear.
-
-## Accidental misalignment
-
-**AI tell:** Almost-shared edges, drifting section widths, mismatched card padding, uneven control heights, and dividers that miss neighboring boundaries.
-
-**Default action:** Establish key lines, grid, spacing tokens, component anatomy, and responsive alignment before adding decoration.
-
-**Legitimate when:** A deliberate editorial or media break communicates hierarchy and remains visibly intentional across viewports.
-
-## Reimplemented local styling
-
-**AI tell:** A new button, modal, card, status color, icon wrapper, or focus ring duplicates an existing project primitive with slightly different values.
-
-**Default action:** Reuse the existing component or extend its documented variant API. Add a new primitive only for a genuinely different semantic role.
-
-**Legitimate when:** The project has no suitable primitive or reuse would corrupt semantics; document the new role and make it reusable.
-
-## Generic type by neglect
-
-**AI tell:** Net-new aesthetic work ships with Arial, Helvetica, or bare `system-ui` because typography was never designed.
-
-**Default action:** Reuse the product type system or choose an intentional, efficiently loaded family/pairing from `craft-rulings.md`. Assign clear display, body, utility, and technical roles.
-
-**Legitimate when:** The existing system requires it, native platform fidelity is the goal, network/self-hosted fonts are prohibited, or performance evidence favors the established stack.
-
-## Generated em dash voice
-
-**AI tell:** UI headings, descriptions, empty states, and helper text repeatedly use em dashes as an LLM writing habit.
-
-**Default action:** Rewrite with a period, comma, colon, parentheses, or two sentences.
-
-**Legitimate when:** The user explicitly wants em dashes or exact supplied, quoted, brand, or legal copy must remain unchanged.
-
-## Anti-default review
-
-Before implementation, flag every pattern above that appears in the thesis. Keep a flagged choice only with its one-sentence product-specific justification.
-
-After the first screenshot:
-
-1. Cover the logo and product name. Identify what still makes the screen specific.
-2. Remove one decorative idea and compare hierarchy.
-3. Replace one block of generic copy with real content.
-4. Check whether the signature survives mobile without becoming clutter.
-5. If another unrelated product could use the same screenshot unchanged, revise the weakest area.
+1. How to use this list
+2. Composition tells
+3. Colour, type, and surface tells
+4. Content and copy tells
+5. Motion and interaction tells
+6. Craft regressions
+7. Calibration: the default clusters
+8. Final slop review
+
+## 1. How to use this list
+
+A tell is not a ban. It is a choice that appears whatever the subject, so it signals "nobody decided this". Where the user's brief or the existing product pins down a direction, follow it exactly, even if it matches a tell. Where an axis is free, do not spend it on a tell.
+
+For each tell found in a plan or render, apply the replacement move, or keep it only if the "Keep when" condition holds and you write one sentence: **"This belongs because…"** naming the product, audience, or content reason. "Modern", "premium", "clean", "engaging", or "on brand" is not a reason.
+
+Run the list twice: on the written design thesis before code, and on desktop + mobile screenshots after.
+
+## 2. Composition tells
+
+| Tell | Replacement move | Keep when |
+| --- | --- | --- |
+| Centered gradient hero: oversized centered headline, violet/blue glow, two CTAs, floating screenshot below | Open with the most characteristic thing in the subject's world: real product state, real data, a working demo, a strong photograph, or a plain typographic claim. Choose alignment after content. | The brand owns the gradient/light, the page has one conversion job, and the centered pause serves the narrative. |
+| Three equal icon-title-copy feature cards | Rank the content; give the main point more space; show the feature working; use a list or table for true peers. | Exactly three peer choices exist and comparison is the task. |
+| Bento grid by default | Map module size to priority and reading order; use a sequence or list otherwise. | A genuine overview of heterogeneous modules that users scan or rearrange. |
+| SaaS card kit: everything in identical rounded cards, one radius, same soft grey shadow | Group with whitespace and alignment. Containers only for real objects (selectable, draggable, separate records). Radius varies by role. | The items really are separate records. |
+| Decorative eyebrow: tracked ALL-CAPS or mono label above every heading | Delete it. | It names real taxonomy, step, status, or technical context. |
+| Numbered markers (01 / 02 / 03) on non-sequential content | Remove numbers. | The content is a real sequence: steps, timeline, ranking. |
+| Big-number stat strip ("10x faster", "99.9%", "50k+") | Show a sourced metric with unit, time frame, and consequence, or remove it. | The metric is auditable and central to the screen's decision. |
+| Floating tilted screenshot or fake dashboard mockup | Real UI at readable scale, cropped to the part that proves the adjacent claim. | Spatial overview matters, the image is current, perspective hides nothing. |
+| Fake terminal or code theatre | Real, copyable, versioned commands and output, or ordinary product evidence. | The user's task is genuinely code/CLI. |
+| Pills everywhere: nav, buttons, filters, badges, inputs | Pills for toggles/tags only; a small radius vocabulary elsewhere. | The product already uses a capsule motif deliberately. |
+| Icon medallion: line icon in the same tinted square above every section | Remove icons that repeat the heading. | Icons speed navigation, status scanning, or a real category system. |
+| Logo wall of invented or unlicensed customers | Real, permitted logos, or no social proof. | Supplied and approved. |
+
+## 3. Colour, type, and surface tells
+
+| Tell | Replacement move | Keep when |
+| --- | --- | --- |
+| Purple/indigo/violet gradient as the default brand; Tailwind `indigo-500`/`violet-600` primary | Derive the hue from the subject, materials, or existing brand; build an OKLCH ramp (`references/direction.md` § Colour). | The existing brand is that hue. |
+| Out-of-box shadcn/Tailwind look: `slate`/`zinc` greys, `rounded-lg` everywhere, `ring-2 ring-offset-2`, default button set | Keep primitives for behaviour; restyle tokens: neutrals tinted toward the brand hue, a deliberate radius scale, the project's own focus treatment. | The project already ships that look; then preserve it. |
+| Inter, Geist, or bare `system-ui` as the whole aesthetic; Arial/Helvetica by neglect | Choose a family or pairing for this subject (`references/direction.md` § Type). | The existing system uses it, native fidelity is the goal, webfonts are prohibited, or it is dense app chrome. |
+| One headline word accented in gradient, italic, or colour | Let the whole headline carry the treatment, or make emphasis carry meaning (a value, a name). | The accented word is data. |
+| Glass cards: blurred translucent panels over colour blobs | One clear material model (flat, tonal, bordered, or measured elevation), one reason per layer. | Content sits over live media/map/video, or translucency is the local platform material. |
+| Dark equals premium; near-black `#0B0B0B`/`#111` with one acid-green or vermilion accent | Choose theme from environment, task duration, and media. If dark, tune OKLCH neutrals and measure contrast in both themes. | Media needs darkness, low-light use, or a tested dark-first brand. |
+| Warm cream (~`#F4F1EA`) + high-contrast serif + terracotta (~`#D97757`) | Anthropic names this its own Claude-interaction look; on a user's brief it reads as a tell. Choose another direction. | The brief asks for it. |
+| Broadsheet pastiche: hairline rules, zero radius, dense columns | Editorial structure only for editorial content. | The surface is editorial. |
+| Soft semantic tint-on-tint (low-opacity hue bg + same-hue text/icon/border) | `references/craft-rulings.md` § No soft semantic tint-on-tint. This one is a binding default, not a style preference. | The user requests it or scope requires reusing an existing variant. |
+| Huge type (96–160px) as the only idea | Build contrast from wording, measure, weight, width, and placement before size. | Campaign/editorial, short phrase, localization tested, type is the signature. |
+| Monospace for small data labels by reflex | Mono only for code and IDs; tabular numerals of the body face for figures. | Technical context the user reads as code. |
+
+## 4. Content and copy tells
+
+| Tell | Replacement move | Keep when |
+| --- | --- | --- |
+| Lorem ipsum or "Feature one / Feature two" in review | Write real copy first (content-first rule in SKILL.md). | Never in review; label fixtures as fixtures. |
+| Fake metrics, testimonials, ratings, avatars, customer names, precise business data | Real content, or plainly labelled example data, or omit. | The user supplies approved fixtures or asks for a clearly marked prototype dataset. |
+| Generic CTAs: "Get started", "Learn more", "Submit", "Unlock the power of…" | Name the outcome ("Create invoice", "Book a table"). Keep the verb through the flow ("Publish" → toast "Published"). | Never as a default. |
+| Hype voice: "seamless", "effortless", "supercharge", "next-level", "revolutionize" | Say what it does in the user's own words. | Supplied brand copy. |
+| Middle-dot meta strings, `WORD — fragment` labels, `→` on every link | Plain sentence-case labels; arrows only where direction is literal. | Supplied copy. |
+| Emoji as icons, bullets, status, empty-state art | One coherent icon family (`references/craft-rulings.md` § 1). | Requested, or emoji is the content itself. |
+| Placeholder illustration: blob people, abstract 3D shapes, generic stock, unrelated generated hero art | Real product imagery, photography, data, or no image. | Requested and appropriate to the subject. |
+| Subtitle under every heading restating it | `references/craft-rulings.md` § Copy must earn its space. | It adds information needed here. |
+| Em dashes in UI copy | Full stop, comma, colon, parentheses, or two sentences. | Requested, or exact supplied/quoted/legal copy. |
+| Apologetic or vague errors ("Oops! Something went wrong") | Say what happened and how to fix it; no apology. | Never. |
+
+## 5. Motion and interaction tells
+
+| Tell | Replacement move | Keep when |
+| --- | --- | --- |
+| Fade-and-slide-up on every section as it scrolls in | At most one orchestrated moment; content readable with motion off. | A single deliberate narrative beat. |
+| Hover lift, bob, or scale on every card/button | Colour, border, underline, icon-fill, opacity, or restrained shadow; stable geometry. | Movement communicates real drag, depth, or direct manipulation. |
+| Ambient perpetual motion: particles, gradient drift, marquees, auto-rotating cards | Still resting screen; animate state change only. Pause control if > 5 s. | Motion is the content (audio, time, live activity) and works paused. |
+| `transition: all` | Name properties; shared duration/easing tokens. | Never. |
+| Abrupt state swaps; layout shift on load | Short transitions on interpolable properties; skeletons matching final geometry; focus visible immediately. | Reduced motion or urgent feedback needs an instant change. |
+| Whole card clickable with nested buttons | One link target per card, or explicit buttons; never nested interactive elements. | Never. |
+
+## 6. Craft regressions
+
+Treat each as a tell when found in a render; fixes live in `references/craft-rulings.md`:
+
+- accidental misalignment and drifting content rails;
+- a local button, modal, card, status colour, or focus ring duplicating an existing primitive with slightly different values;
+- mixed icon families (package icons, hand-drawn SVG, text glyphs together);
+- sticky pointer focus, stacked focus rings, edge-hugging dropdown chevrons.
+
+## 7. Calibration: the default clusters
+
+Generated UI clusters into a few looks that appear whatever the subject (SNAPSHOT/DEDUCED; sources in `references/provenance.md` § Slop-tell sources). Recognise them in your own plan:
+
+1. Purple-to-blue SaaS: centered hero, glow, Inter, three feature cards, logo wall, three-tier pricing.
+2. shadcn default: zinc greys, `rounded-lg` cards, outline buttons, four KPI cards over a line chart.
+3. Dark "premium": near-black, one neon accent, glass cards, grid-line background, mono labels.
+4. Warm editorial: cream, serif display, terracotta accent, hairline rules.
+5. Template chrome: ALL-CAPS eyebrows, middle-dot meta, `→` on links, emoji section markers.
+
+Ask: "Would I produce this same plan for a neighbouring product?" If yes, change the most transferable axis (usually colour, type, or hero composition) and state what changed and why.
+
+## 8. Final slop review
+
+On the rendered desktop and mobile screenshots:
+
+1. Cover the logo and accent colour. Can you still name the product and task?
+2. Does any tell from §§ 2–5 remain without a "This belongs because…" sentence?
+3. Is every number, quote, and logo traceable to real content or labelled as a fixture?
+4. Is there exactly one memorable device, with everything around it quiet, and does it survive mobile without clutter?
+5. Remove one decorative element. If the screen did not get worse, leave it removed.