@prestyj/cli 5.5.0 → 5.7.0

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

@@ -0,0 +1,203 @@
+# Anti-Defaults
+
+## Contents
+
+- Purpose and review method
+- Template composition: centered gradient hero, glass cards, equal card grids, eyebrows, metric blocks, pills, 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.
+
+## 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.

package/assets/skills/evidence-led-ui/references/archetypes.md

@@ -0,0 +1,97 @@
+# Archetype Guidance
+
+## How to choose
+
+Choose the archetype by the screen’s job, not the company category. A developer company’s billing console is application UI; its API reference is documentation; its launch page is marketing/brand. Hybrid screens may borrow one secondary archetype, but one must lead.
+
+All coverage and counts come from `data/observations.json`, commit `664b3e78fd1a298ba11973822da988483256d4b4`, extraction version 1. Each section names two aligned references and one contrast. References are observational analyses, not templates to copy.
+
+Every archetype also follows `craft-rulings.md`: no emoji UI, one coherent icon family, uniform key lines, reuse of local primitives, purposeful non-abrupt feedback without generic hover lift, intentional typography, measured contrast, consistent flow, and no generated em dashes in UI copy. Every implemented surface must also pass the applicable `production-contract.md` checks; archetype evidence never overrides semantics, accessibility, resilience, performance, platform, or trust requirements.
+
+## Marketing and brand
+
+**Coverage:** **29/74 documents**. Dark **17/29**, mixed **7/29**, light **5/29**; motion mentioned in **19/29**. This is the largest and most technology-heavy group, so avoid exporting its conventions to product screens.
+
+**Design read:** Establish one claim, one audience, and one conversion. Let content cadence determine whether the composition is cinematic, editorial, demonstrative, or direct.
+
+**Direction:** Use a strong typographic or media hierarchy, variable section rhythm, and one subject-specific signature. Motion may stage narrative transitions, but it must not delay comprehension or interaction. Keep conversion hierarchy unmistakable.
+
+**Aligned evidence:** `apple`, `sanity`. **Useful contrast:** `figma`.
+
+**Reject:** A centered gradient headline, generic dashboard mockup, three equal feature cards, and floating glass shapes that could advertise any SaaS.
+
+## Application UI
+
+**Coverage:** **7/74 documents**. Focus mentioned in **7/7**, disabled state in **6/7**, motion in **5/7**, keyboard language in only **1/7**. The sample is small and still based on public-site analyses.
+
+**Design read:** Name the repeated task, frequency, consequence of error, user expertise, and information that must remain visible while acting.
+
+**Direction:** Optimize stable navigation, predictable control placement, concise hierarchy, and fast state recognition. Use density appropriate to task frequency. Keep decorative layers behind the work surface. Add keyboard and loading/empty behavior even though the corpus documents it poorly.
+
+**Aligned evidence:** `linear.app`, `superhuman`. **Useful contrast:** `intercom`.
+
+**Reject:** Marketing-scale headings, scroll-led reveals, and oversized cards that turn repeated work into a tour.
+
+## Dashboards and data-dense tools
+
+**Coverage:** **5/74 documents**. Dense language in **4/5**, focus in **5/5**, keyboard in **3/5**, error in **5/5**. Theme is dark **3/5**, light **1/5**, mixed **1/5**; the denominator is too small to prescribe a theme.
+
+**Design read:** Identify the decision the dashboard supports, update frequency, comparison axis, alert severity, and the smallest unit users scan repeatedly.
+
+**Direction:** Build a scan path before styling cards. Prefer alignment, separators, restrained surface steps, and semantic status encoding. Preserve row/column context, expose units, support keyboard navigation, and make filters visibly affect results. Charts should answer named questions rather than fill grid slots.
+
+**Aligned evidence:** `airtable`, `sentry`. **Useful contrast:** `miro`.
+
+**Reject:** Random metric tiles, equal visual weight for all data, unlabeled sparklines, and decorative gradients that compete with status colors.
+
+## Commerce and marketplaces
+
+**Coverage:** **12/74 documents**. Theme is light **5/12**, dark **4/12**, mixed **3/12**; subtle-shadow policy appears in **8/12**; loading in **3/12** and empty state in **1/12**. Coverage spans retail, fintech, travel, and payments, so transaction risk varies widely.
+
+**Design read:** Resolve discovery versus purchase, inventory variability, trust burden, comparison behavior, and the role of imagery.
+
+**Direction:** Make product evidence, price, availability, trust, and primary transaction action legible in that order. Let imagery dictate card geometry when imagery is decision-critical. Use material softness only when it supports tactility or approachability. Design unavailable, loading, saved, and failure states explicitly.
+
+**Aligned evidence:** `airbnb`, `nike`. **Useful contrast:** `binance`.
+
+**Reject:** Generic product cards with fake ratings, identical crops, hidden fees, or a brand accent applied equally to navigation, price, badges, and purchase action.
+
+## Editorial and content
+
+**Coverage:** **5/74 documents**. Asymmetry appears in **3/5**, full-bleed composition in **4/5**, motion in **1/5**, sharp-corner language in **3/5**. This is a small sample dominated by technology and media.
+
+**Design read:** Name the reading mode, expected session length, content hierarchy, recirculation goal, and whether imagery or text carries authority.
+
+**Direction:** Design reading rhythm through measure, leading, headline contrast, captions, metadata, and deliberate interruption. Use asymmetry when it clarifies editorial priority. Keep controls quiet and persistent enough to support progress, saving, or navigation.
+
+**Aligned evidence:** `wired`, `theverge`. **Useful contrast:** `spotify`.
+
+**Reject:** SaaS feature cards, pill labels on every taxonomy term, animated ornaments beside long-form copy, and uniform modules that erase editorial priority.
+
+## Documentation and developer tools
+
+**Coverage:** **16/74 documents**. Dark **11/16**, mixed **4/16**, light **1/16**; sidebar language **8/16**; focus **13/16**; keyboard language **0/16**. The category is well represented but heavily biased toward developer marketing surfaces.
+
+**Design read:** Determine whether the user is learning, looking up, debugging, or copying; identify versioning, code-language, and navigation depth.
+
+**Direction:** Prioritize information scent, stable navigation, readable prose measure, copyable code, visible current context, and search. A technical accent or monospace register can support meaning, but code should not become decoration. Add keyboard access and command discoverability despite the corpus gap.
+
+**Aligned evidence:** `mintlify`, `vercel`. **Useful contrast:** `hashicorp`.
+
+**Reject:** Terminal theater, fake logs, neon syntax everywhere, hidden navigation, and dark mode chosen solely to look “developer.”
+
+## Mobile and native surfaces
+
+**Coverage:** **0/74 documents**. The corpus cannot support a quantitative mobile/native house style.
+
+**Design read:** Resolve platform, input mode, reach zones, navigation convention, offline behavior, permissions, interruption, and whether the surface is phone, tablet, watch, or desktop native.
+
+**Direction:** Preserve the project’s platform conventions and native controls. Use official platform guidance and rendered/device testing as primary evidence. Borrow only content hierarchy and brand semantics from the closest corpus archetype. Plan touch, keyboard, pointer, dynamic type, safe areas, orientation, and reduced motion as applicable.
+
+**Aligned evidence:** none in this corpus. **Closest structural references:** `airbnb`, `superhuman`. **Useful contrast:** `apple` marketing analysis, which must not be mistaken for native UI guidance.
+
+**Reject:** Shrinking a desktop web composition into a phone viewport or inventing gestures without discoverable alternatives.
+
+## Cross-archetype rule
+
+Select **two aligned references and one contrast**, then write why each is relevant to this exact screen. If the same palette, radius, font stack, composition, or motion policy survives unchanged across unrelated briefs, the thesis is under-specified.

package/assets/skills/evidence-led-ui/references/craft-rulings.md

@@ -0,0 +1,167 @@
+# Interface Craft Rulings
+
+## Contents
+
+1. Icons, never emoji
+2. Uniform geometry and alignment
+3. Reuse before invention
+4. Motion without generic hover lift
+5. Typography and Google Fonts loading
+6. Contrast as a release requirement
+7. Consistency and flow
+8. UI copy punctuation
+9. Final craft check
+
+These are binding defaults for UI implementation and review. They reflect Nolan's product taste, current accessibility guidance, current web-font delivery guidance, established design-system motion/grid practices, and the pinned observational corpus. Override one only when the user explicitly requests the exception or the existing product has a stronger documented rule.
+
+## 1. Icons, never emoji
+
+Do not use emoji as interface icons, bullets, status marks, empty-state decoration, or visual shorthand unless the user explicitly requests emoji.
+
+1. Inspect the project for an existing icon system and reuse it.
+2. If none exists and adding a dependency is allowed, choose one coherent stack-specific package. Default to Lucide for a restrained line system. Use Material Symbols when variable fill/weight/optical sizing fits an existing Google/Material language. Use Phosphor when the product needs a broader weight range and a softer illustrative voice.
+3. Do not mix icon families within one product surface.
+4. Do not hand-draw substitute SVGs when the selected package already has the icon.
+5. Match icon stroke/fill weight, optical size, control size, and color role across repeated components.
+6. Prefer visible text beside unfamiliar actions. Decorative icons are hidden from assistive technology. Icon-only buttons receive an accessible name on the button, a visible tooltip where useful, and at least a 44 by 44 CSS-pixel target.
+
+Lucide's current accessibility guidance recommends visible labels in most cases, consistent icon treatment, keyboard access, adequate contrast, and a 44 by 44 target wrapper. Material Symbols provides variable fill, weight, grade, and optical-size axes; use those axes systematically rather than mixing arbitrary styles.
+
+## 2. Uniform geometry and alignment
+
+Uniformity means shared geometry, not equal visual importance.
+
+- Establish container edges, columns, gutters, spacing tokens, control heights, border positions, and text baselines before styling individual sections.
+- Repeated sections align to the same key lines. Cards in the same family share padding, header placement, border treatment, and action placement.
+- Vertical dividers meet related horizontal boundaries cleanly. Avoid one-pixel drift, almost-aligned edges, arbitrary indents, and section widths that change without a content reason.
+- Use one spacing rhythm. Prefer existing project tokens; otherwise derive a compact 4 or 8 pixel scale appropriate to density.
+- Preserve alignment through responsive recomposition. Mobile may change order or layout, but repeated controls and content edges remain internally consistent.
+- Break the grid only to express real hierarchy, media behavior, or editorial emphasis. A deliberate exception should be visible as an exception, not look accidental.
+
+Carbon's grid guidance uses consistent mini-unit multiples, key lines, fixed padding within breakpoints, and type aligned to box padding. Apply the principle through the project's own grid rather than copying Carbon's exact values.
+
+## 3. Reuse before invention
+
+Before creating any token, component, style, or interaction:
+
+1. Search the project for the same semantic role.
+2. Reuse the existing component and variant when it meets the need.
+3. Extend the nearest primitive when the need is genuinely new.
+4. Create a new primitive only when reuse or extension would distort semantics.
+
+Do not duplicate button systems, card shells, form controls, modal behavior, status colors, spacing scales, icon wrappers, focus rings, or motion curves. Reuse class utilities and design tokens where they already exist. Same function means same label, icon, accessible name, state treatment, and placement across pages.
+
+## 4. Motion without generic hover lift
+
+Every interactive component must provide clear feedback for relevant hover, focus, press, selected, expanded, loading, success, and error states. Feedback should not feel abrupt when an interpolated transition improves comprehension.
+
+Default motion behavior:
+
+- Do not use generic `translateY` hover lift, bobbing, floating, card jumping, or indiscriminate scale-up.
+- Prefer background, foreground, border, underline, icon fill/weight, opacity, and restrained shadow transitions.
+- Press feedback should feel connected to activation. Prefer color, inset, fill, or a brief controlled compression only when it matches the material model.
+- Animate state and continuity, not decoration. Do not add ambient or perpetual motion to make a static layout feel designed.
+- Never use `transition: all`. Name the properties that are allowed to interpolate.
+- Avoid animating layout properties such as `width`, `height`, `top`, and `left` unless spatial change is the meaning and performance is verified.
+- Keep focus indication immediate and visible. A transition must never delay awareness of keyboard focus.
+
+Reuse existing motion tokens first. If none exist, begin with these restrained bands, then tune by component size and distance:
+
+| Role | Typical duration | Use |
+|---|---:|---|
+| Immediate micro-feedback | 70 to 110 ms | button, toggle, icon fill, press |
+| Standard state change | 140 to 200 ms | color, border, background, small disclosure |
+| Entrance or panel continuity | 180 to 240 ms | menu, popover, drawer, inserted feedback |
+| Exit | 120 to 180 ms | dismissal and removal |
+
+For a neutral productive curve, Carbon documents `cubic-bezier(0.2, 0, 0.38, 0.9)` for standard productive motion, with separate entrance and exit curves. Use local easing when available.
+
+The pinned observational corpus supports restrained hover treatment: Tesla and Lamborghini explicitly prefer color-only interactions over scale/translate; Vercel uses underline or surface changes; Linear uses a controlled color/surface state; Sanity uses a consistent interactive color. These are observations of selected surfaces, not universal brand rules. Refero content was not accessed because no authorized Refero MCP or user-provided export was available.
+
+Reduced motion is mandatory. Under `prefers-reduced-motion: reduce`, remove non-essential travel, parallax, scale, and spatial choreography. Preserve state feedback through immediate color, border, text, icon, or opacity changes. WCAG 2.2 SC 2.3.3 treats disabling non-essential interaction animation as the accessible direction.
+
+## 5. Typography that carries intent
+
+Reuse the project's established type system first. For net-new web work without an established type system, choose an intentional family or pairing that matches the subject, language coverage, density, and reading mode.
+
+Do not choose Arial, Helvetica, or a bare `system-ui` stack as the visible design direction for net-new aesthetic work. They remain acceptable technical fallbacks and may remain correct for an existing system or native-platform surface.
+
+### Current Google Fonts inspiration
+
+The following families were present in Google Fonts metadata fetched 14 July 2026. Popularity positions in that metadata included DM Sans 23, Manrope 37, Lora 43, Bricolage Grotesque 45, Plus Jakarta Sans 51, Space Grotesk 79, Instrument Serif 92, Geist 125, IBM Plex Mono 129, Source Serif 4 133, Instrument Sans 140, Newsreader 148, Geist Mono 149, and DM Mono 168. Popularity is discovery evidence, not a command to use the highest-ranked family.
+
+| Pairing | Best fit | Role split |
+|---|---|---|
+| Instrument Sans + Instrument Serif | editorial brands, culture, thoughtful commerce | sans for UI/body, serif for display or pull quotes |
+| Manrope + IBM Plex Mono | precise product UI, operations, technical SaaS | sans for interface, mono for data and technical labels |
+| Plus Jakarta Sans + Source Serif 4 | trustworthy services, education, research | sans for navigation/UI, serif for long reading |
+| DM Sans + DM Mono | clean application UI, data products | sans for hierarchy, mono for identifiers and code |
+| Space Grotesk + Newsreader | modern editorial/product hybrids | grotesk for display/UI, serif for narrative |
+| Bricolage Grotesque + Lora | playful or crafted consumer products | expressive sans for display, serif for supporting warmth |
+| Geist + Geist Mono | restrained developer tools | sans for UI, mono for code/data |
+| Noto Sans + Noto Serif | multilingual products | broad-script sans/serif system |
+
+Use one family when role, weight, width, size, and tracking provide enough hierarchy. Add a second family only for a clear role contrast. Two families are usually sufficient; a third requires a specific content role.
+
+### Loading Google Fonts
+
+When network font loading is acceptable, connect the selected pair through the Google Fonts CSS API. Request only used families, styles, scripts, and weights. Use `display=swap`, preconnect to both Google Fonts origins, and test fallback metrics and layout shift.
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&family=Instrument+Serif:ital@0;1&display=swap"
+/>
+```
+
+Do not connect Google Fonts when privacy, offline operation, CSP, performance budgets, or project policy prohibit third-party font requests. Self-host approved WOFF2 files instead. Google and web.dev guidance recommends early discovery, preconnect for third-party font origins, explicit `font-display`, limited variants, and testing cumulative layout shift.
+
+## 6. Contrast is a release requirement
+
+Never use faint light-gray text on white, faint dark-gray text on black, or low-contrast borders/icons merely to look refined.
+
+- Normal text meets at least 4.5:1 against its actual background.
+- Large text meets at least 3:1.
+- Meaningful icons, control boundaries, focus indicators, and graphical objects meet at least 3:1 against adjacent colors.
+- Muted, secondary, placeholder, metadata, and disabled text remain intentionally legible. Disabled controls have a WCAG exception, but their meaning should not disappear.
+- Do not round a failing ratio upward. W3C explicitly notes that 4.499:1 fails 4.5:1.
+- Aim above the minimum for small, thin, long-form, or mission-critical text. Verify computed colors rather than judging from a screenshot alone.
+- Do not use color as the only status cue. Pair color with text, shape, icon, or pattern.
+
+## 7. Consistency and flow
+
+A polished interface feels like one system from section to section, component to component, and page to page.
+
+- Repeated navigation stays in the same relative order.
+- Repeated functions keep the same component, label, icon, accessible name, and state behavior.
+- Page templates share container widths, header logic, spacing cadence, and section transitions.
+- A section should hand off to the next through intentional spacing, border, surface, continuation, or hierarchy. Avoid random background bands and arbitrary rhythm resets.
+- Keep primary action placement predictable within a flow. Do not move the same action between card header, footer, and floating affordance without a reason.
+- Preserve user orientation during loading, filtering, navigation, and responsive changes.
+- Review adjacent screens together, not as isolated screenshots.
+
+WCAG 2.2 SC 3.2.3 requires repeated navigation to keep the same relative order, and SC 3.2.4 requires components with the same function to be identified consistently. These accessibility requirements also reduce visual and cognitive friction for everyone.
+
+## 8. UI copy punctuation
+
+Do not generate em dashes in user-facing UI copy unless the user explicitly requests them or supplied brand/source copy already uses them and must remain unchanged.
+
+Prefer a period, comma, colon, parentheses, or a rewritten sentence. Preserve exact quoted or legal source text. This is a product voice ruling, not a claim that em dashes are inaccessible.
+
+## Final craft check
+
+Before calling UI work complete, verify:
+
+- no emoji used as UI imagery;
+- one coherent icon family, with accessible names and target sizes;
+- shared key lines, control heights, spacing, borders, and component geometry;
+- existing components/tokens reused before new ones were created;
+- every relevant interaction has purposeful, non-abrupt feedback;
+- no generic hover lift or `transition: all`;
+- reduced motion preserves state meaning;
+- typography is intentional, loaded efficiently, and stable during fallback;
+- all text and meaningful non-text contrast is measured;
+- repeated navigation/actions remain consistent across sections and pages;
+- generated UI copy contains no em dashes unless explicitly allowed.

package/assets/skills/evidence-led-ui/references/methodology.md

@@ -0,0 +1,72 @@
+# Corpus Methodology
+
+## Scope
+
+This skill analyzes the MIT-licensed public `DESIGN.md` snapshot from [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) at commit `664b3e78fd1a298ba11973822da988483256d4b4` (retrieved 2026-07-13).
+
+The archive contains **74/74 discovered `design-md/*/DESIGN.md` files**. The approved planning estimate said 75, while the upstream README badge at the pinned commit says 73 and omits the present `slack` file. Archive-tree enumeration is the authoritative count for this snapshot.
+
+These files are independent analyses of public websites. They are not official brand design systems, and a frequency in this corpus is not a universal design rule.
+
+## Deterministic extraction
+
+Run:
+
+```bash
+node scripts/analyze-corpus.mjs
+```
+
+The analyzer uses only Node.js standard-library APIs. It checks every source against the SHA-256 in `data/corpus-manifest.json`, parses Markdown headings and optional YAML-like frontmatter, updates parser status in the manifest, and writes `data/observations.json` deterministically.
+
+After any skill-package change, run `node scripts/validate-skill.mjs`. The validator checks frontmatter, progressive-disclosure structure, linked files, corpus hashes and totals, generated evidence consistency, fixture divergence, source boundaries, binding craft rules, and the production-contract release gate.
+
+At extraction version 1, **64/74 documents** use frontmatter plus prose and **10/74** use numbered prose without frontmatter. All **74/74** are parsed; unsupported files would be retained with an explicit reason rather than silently dropped. Counts come from `data/observations.json`, source commit `664b3e…`, extraction version 1.
+
+## What the parser measures
+
+- **Color:** hexadecimal values, nearby semantic role language, accent count, surface ladder, HSL distributions, hue bins, and semantic-state mentions. It never averages colors into a recommended hex value.
+- **Typography:** family strings, display/body/utility/code role language, font sizes, weights, tracking, line-height, and explicit line-length guidance.
+- **Layout:** declared spacing scales, inferred 4/5/8px bases only when scale evidence has at least 60% coverage, section spacing, max-width declarations, density language, and named composition patterns.
+- **Shape and material:** radius values tied to radius language, pill/sharp-corner mentions, borders, dividers, shadows, blur, gradients, imagery, and surface-separation language.
+- **Components and states:** buttons, inputs, cards, navigation, tables, CTA language, hover, focus, press/active, disabled, loading, empty, error, and semantic color states.
+- **Motion and access:** motion terms, durations, easing, reduced-motion language, accessibility, focus, keyboard, and contrast language.
+- **Rules and motifs:** explicit do/do-not lines and sentences that identify a signature, motif, or defining characteristic.
+
+## Statistics and missing data
+
+Numeric outputs use min, first quartile, median, third quartile, max, and an explicit sample count. Frequencies always store `{ count, denominator }`. Unknown values remain `null`, `false`, or empty arrays and do not enter numeric sample counts.
+
+Hue is reported in 30-degree bins because linear averaging is invalid across the 0°/360° boundary. Color recommendations must use semantic role and brief fit, never a corpus-average color.
+
+Co-occurrences mean two terms or policies appeared in the same analysis; they do not prove a causal design relationship. Representative slugs are the most extraction-complete records, not quality rankings. Contrasts are selected from a non-dominant inferred theme.
+
+## Categories and archetypes
+
+The manifest preserves the ten upstream README groupings, including the two-file Retro Web section, and marks the present-but-uncatalogued `slack` file separately instead of inventing an upstream category. The analyzer separately maps documents into six usable product archetypes plus a zero-coverage mobile/native category:
+
+- marketing/brand;
+- application UI;
+- dashboards/data-dense tools;
+- commerce/marketplaces;
+- editorial/content;
+- documentation/developer tools;
+- mobile/native (**0 documents**).
+
+This mapping is analytical judgment, recorded explicitly in `scripts/analyze-corpus.mjs`; it is not supplied by upstream. A source appears in exactly one analytical archetype so denominators remain auditable.
+
+## Known limitations
+
+- The corpus overrepresents technology marketing and developer products: marketing/brand has **29/74 documents**, while editorial has **5/74** and mobile/native has **0/74** (commit `664b3e…`, extraction v1).
+- Mention detection records what an analysis discusses, including prohibitions. Policy classifiers distinguish direct “no shadows/gradients” language from subtle treatment where possible, but nuanced prose still needs human review.
+- Font-family counts include fallbacks and substitutes; they are evidence of documented vocabulary, not the number of fonts loaded by a website.
+- Radius vocabularies can include component exceptions. Use the component rule and local project token set before the corpus-wide distribution.
+- The files describe selected public surfaces, often marketing pages, not every state in the underlying product.
+- No screenshots, brand assets, paid files, private requests, fonts, website media, or Refero data are included.
+
+## Product-owner rulings and production standards versus corpus evidence
+
+`references/craft-rulings.md` contains Nolan's binding product defaults for emoji, icons, alignment, reuse, motion, UI punctuation, typography, contrast, consistency, and flow. `references/production-contract.md` contains the separate pass/fail implementation floor for semantics, accessibility, forms, resilience, performance, platform behavior, tokens, trust, and verification. Neither document presents its requirements as corpus frequencies. `references/provenance.md` records the current standards and implementation sources that support them.
+
+## How to use the evidence
+
+Select the matching archetype first. Read corpus-wide findings only as context, inspect two aligned sources and one useful contrast, then test the choice against the actual product brief and existing project. If the local product contradicts the corpus, the product wins.

package/assets/skills/evidence-led-ui/references/observed-patterns.md

@@ -0,0 +1,68 @@
+# Observed Patterns
+
+## Evidence key
+
+Unless a paragraph says otherwise, every count below comes from `data/observations.json`, source commit `664b3e78fd1a298ba11973822da988483256d4b4`, extraction version 1. Fractions are **observed documents / relevant documents**; numeric distributions state their sample count. These are observations, not defaults.
+
+## Theme is conditional, not a premium preset
+
+The inferred primary theme is dark in **40/74**, mixed in **19/74**, and light in **15/74** analyses. The skew reflects a corpus rich in developer tools, AI products, and cinematic brands. Commerce is much less one-sided—light **5/12**, dark **4/12**, mixed **3/12**—so “dark equals premium” is not supported as a cross-product rule.
+
+Aligned dark references: `sanity`, `voltagent`. Useful light contrast: `airbnb`.
+
+## Surface separation favors restraint
+
+Shadow policy is classified as subtle in **45/74**, absent in **28/74**, and merely mentioned in **1/74** analyses. This is stronger evidence for restrained elevation than for one universal “no shadows” rule. Use borders, tonal steps, spacing, or subtle shadows according to material logic and information density.
+
+Examples: `vercel` and `linear.app` use precise containment; `airbnb` shows where soft elevation remains appropriate for a tactile consumer marketplace.
+
+## Gradients are disputed, not forbidden
+
+Gradients are positively mentioned in **35/74**, directly discouraged in **23/74**, and unclassified in **16/74** analyses. A blanket gradient ban contradicts the corpus. Gradients earn their place when they carry brand, light, depth, data, or media meaning; they fail when they merely signal “modern AI.”
+
+Aligned use: `stripe`, `framer`. Contrast: `vercel`.
+
+## Accent count is a range, not a palette recipe
+
+Per-document accent-role extraction has **74 samples**: Q1 **3**, median **5**, Q3 **8**. These counts include shades and semantic variants, so they do not imply five competing CTA colors. Build a semantic hierarchy—canvas, surface, text, border, action, status—then reserve the highest-chroma signal for the screen’s single job.
+
+The hue corpus is intentionally not averaged. Role and contrast matter more than a synthetic “average blue.”
+
+## Spacing scales converge more than compositions
+
+A spacing base was inferable in **73/74** documents: Q1 **4px**, median **4px**, Q3 **8px**. Section-spacing extraction has **434 samples**: Q1 **24px**, median **40px**, Q3 **64px**. Treat this as evidence for a coherent scale, not permission to paste a 4px system over an existing project.
+
+Grid language appears in **73/74** analyses, full-bleed composition in **54/74**, single-column behavior in **44/74**, sidebars in **27/74**, asymmetry in **10/74**, split layouts in **10/74**, and masonry in **1/74**. “Uses a grid” is therefore not a signature. The signature must come from content-specific composition inside the grid.
+
+## Radius is component-specific
+
+Extracted radius values have **764 samples**: Q1 **4px**, median **12px**, Q3 **24px**. Pill language appears somewhere in **73/74**, while sharp-corner language appears in **16/74**. Because these counts include both uses and warnings, neither pills nor square corners should become a global default.
+
+Constrain the local vocabulary by component role: controls may be compact, media cards may follow imagery, and badges may be pill-shaped without making every container a capsule. `kraken` explicitly limits buttons to 12px; `sanity` contrasts pill CTAs with 3–6px utility surfaces; `tesla` is a sharp, reduced contrast.
+
+## Typography separation is selective
+
+Explicit display/body family separation appears in **11/74** analyses. Font-family vocabulary per document has **74 samples** with median **4**, but that number includes fallbacks and suggested substitutes. The useful lesson is to assign roles deliberately, not to load four fonts.
+
+Use a second family when it creates a subject-specific register, such as editorial versus utility, human versus technical, or display versus code. Keep one family when weight, width, scale, and tracking already provide sufficient hierarchy. Compare `sanity` (display plus mono technical voice) with `mastercard` (one-font discipline). For net-new type inspiration and current Google Fonts pairings, use `craft-rulings.md`; do not convert corpus frequency into a generic font default.
+
+## Motion is underdocumented
+
+Motion language appears in **41/74** analyses. Only **11 extracted duration samples** exist, with Q1 **200ms**, median **200ms**, and Q3 **225ms**. Reduced-motion language appears in **0/74**. That zero is a corpus gap, not evidence that reduced-motion support is optional.
+
+Default to no ambient motion, not no feedback. Every relevant interaction should acknowledge hover, focus, press, selection, expansion, loading, success, or error without an abrupt or generic jump. Prefer short color, border, underline, icon, opacity, or restrained shadow transitions over scale/translate hover lift, and always provide a reduced-motion path.
+
+## Interaction coverage drops after the happy path
+
+Mentions by state are: pressed/active **67/74**, error **62/74**, focus **61/74**, hover **57/74**, disabled **46/74**, loading **8/74**, empty **1/74**. Keyboard language appears in only **8/74** analyses.
+
+The corpus is strongest on styling and weak on product-state completeness. Implementation must add loading, empty, keyboard, and reduced-motion behavior even when the selected reference is silent.
+
+## Archetype differences matter
+
+- Application UI documents mention focus in **7/7** and motion in **5/7**; use interaction precision, not a landing-page spectacle.
+- Dashboard/data-dense documents mention focus in **5/5** and keyboard behavior in **3/5**; prioritize scan paths and operability.
+- Documentation/developer-tool documents are dark in **11/16**, but one is light and four are mixed; dark remains a tendency, not a requirement.
+- Editorial/content documents mention motion in only **1/5** and asymmetry in **3/5**; pacing and hierarchy matter more than animated chrome.
+- Commerce/marketplace documents show the broadest theme split and use subtle shadow policy in **8/12**; imagery, trust, and transaction clarity determine material treatment.
+- Marketing/brand has **29/74** documents, so its patterns must not leak unexamined into product UI.