@prestyj/cli 5.5.0 → 5.7.0

package/assets/skills/evidence-led-ui/references/production-contract.md

@@ -0,0 +1,120 @@
+# Production UI Contract
+
+## Contents
+
+1. Semantics and interaction architecture
+2. Accessibility beyond contrast
+3. Forms, errors, and user control
+4. Responsive and international resilience
+5. Performance and visual stability
+6. Modern platform features and progressive enhancement
+7. Tokens and component contracts
+8. Trust, privacy, and high-consequence flows
+9. Native mobile and adaptive windows
+10. Conditional content types
+11. Required release evidence
+
+This is a binding, pass/fail quality floor for implemented web and native UI. Apply every relevant section. Mark a section not applicable only when the product surface genuinely does not contain that behavior. A visual-rubric score cannot compensate for a contract failure.
+
+## 1. Semantics and interaction architecture
+
+- Use native elements and platform controls before custom widgets. A navigation action is a link; an in-place action is a button. Preserve meaningful headings, landmarks, lists, tables, labels, and DOM reading order.
+- Add ARIA only when native semantics are insufficient. Custom dialogs, menus, tabs, comboboxes, trees, grids, and similar composite widgets must follow the matching WAI-ARIA Authoring Practices pattern and keyboard model.
+- Keep visual, DOM, focus, and screen-reader order aligned. CSS reordering must not create a different task sequence.
+- Modal work uses the platform dialog primitive when suitable; non-modal top-layer content uses the Popover API when suitable. Manage initial focus, containment for modal UI, Escape/close behavior, background inertness, and focus return. A popover does not automatically supply menu or dialog semantics.
+- Preserve browser and platform navigation. Meaningful destinations and shareable state need stable URLs or routes; Back, Forward, refresh, deep links, and native back behavior must not discard work or trap the user.
+
+## 2. Accessibility beyond contrast
+
+WCAG 2.2 Level AA is the web conformance floor. Project, platform, legal, or contractual requirements may be stricter.
+
+- Keep a visible focus indicator and ensure sticky headers, footers, cookie bars, drawers, and overlays do not obscure the focused control.
+- WCAG 2.2 Target Size (Minimum) is 24 by 24 CSS pixels with defined exceptions. Default touch-oriented web controls to a 44 by 44 CSS-pixel hit area where layout permits. Native work follows its platform target guidance, such as 44 by 44 points on Apple platforms and 48 by 48 density-independent pixels in Material guidance.
+- Provide a single-pointer alternative for every non-essential drag interaction. Reordering also needs keyboard and assistive-technology operation.
+- Do not require users to re-enter information already supplied in the same process when it can be selected or populated. Preserve data across validation errors and recoverable navigation.
+- Authentication must work with password managers, copy/paste, and accessible alternatives. Do not make memory, transcription, puzzles, or blocked paste the only route unless an applicable exception is verified.
+- Announce important asynchronous status and validation changes without moving focus unnecessarily. Do not rely on color, motion, position, or an icon alone to communicate meaning.
+- Verify text resizing to 200%, reflow at 320 CSS pixels where WCAG applies, keyboard operation, reduced motion, and forced-colors/high-contrast behavior.
+
+Automated accessibility tooling is a defect detector, not proof of conformance. Manual keyboard, focus, zoom/reflow, and assistive-technology checks remain required for relevant flows.
+
+## 3. Forms, errors, and user control
+
+- Every control has a persistent programmatic label. Associate help, units, requirements, and errors with the field; placeholder text is an example, never the only label.
+- Use the correct input type, `autocomplete`, `inputmode`, and semantic grouping. Keep browser autofill, password-manager, paste, and native validation affordances working unless the product has a verified reason to replace them.
+- Validate at a helpful time. Do not show errors before the user can reasonably act. On submit, summarize errors when the form is long, focus or link to the first problem, preserve values, and explain how to recover.
+- Async actions expose pending, success, failure, retry, and duplicate-submission behavior. Do not silently lose work or replace the whole layout with a spinner.
+- Match safeguards to consequence. Prefer undo for cheap reversible actions; use explicit confirmation for destructive, expensive, security-sensitive, or irreversible actions. State the object and consequence in concrete language.
+
+## 4. Responsive and international resilience
+
+- Use viewport queries for page composition and container queries for reusable components when the support policy permits. Use Grid, Flexbox, and `subgrid` to maintain key lines instead of JavaScript layout or breakpoint-specific duplication.
+- Prefer logical properties and flow-relative alignment. Declare document language and direction, use locale-aware number/date/plural formatting, and avoid sentence construction by string concatenation.
+- Test right-to-left layout when localization is relevant, long German-like expansion, short labels, CJK text, long unbroken values, dynamic type or 200% text, and missing media. Essential content must not depend on truncation.
+- Account for safe areas, on-screen keyboards, dynamic viewport units, orientation, window resizing, no-hover input, coarse pointers, and split-screen or large-screen layouts where the platform can expose them.
+- Avoid fixed heights for content-bearing regions. Preserve reading and action order when columns collapse or modules move.
+
+## 5. Performance and visual stability
+
+For web surfaces, use current Core Web Vitals as the shared target at the 75th percentile, segmented by mobile and desktop: LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1. Use field data when available and project-appropriate lab checks to prevent regressions.
+
+- Reserve media and embed dimensions. Provide responsive image sources and sizes; do not lazy-load the likely LCP image; lazy-load suitable below-the-fold media.
+- Load only used font families, scripts, styles, and weights. Make the selected loading strategy explicit and test fallback layout shift.
+- Keep initial JavaScript and hydration proportional to the interaction. Prefer CSS for layout and visual state; avoid main-thread work that delays input feedback.
+- Skeletons match final geometry. Loading, font swaps, banners, validation, and async results must not unexpectedly move the current target.
+- Animate named properties only. When movement is necessary, prefer compositor-friendly properties and avoid layout-thrashing animation, while still obeying the no-generic-hover-lift and reduced-motion rules.
+- Record a measured result or an honest unverified status. A Lighthouse score alone is not field performance evidence.
+
+## 6. Modern platform features and progressive enhancement
+
+- Set a browser and device support policy from project evidence. Prefer features in the project's Baseline/support range; use feature detection and a simpler fallback for newer capabilities.
+- Use native `dialog`, Popover, `inert`, constraint validation, and other platform primitives when their semantics match the job and the support policy allows them. Do not choose a new API merely because it is fashionable.
+- Treat View Transitions and similar enhancements as optional continuity layers. Navigation and state changes must still work without them and under reduced motion.
+- Preserve the essential task when scripts, media, fonts, animation, clipboard access, or a preferred input mode are unavailable whenever progressive enhancement is feasible for the product.
+
+## 7. Tokens and component contracts
+
+- Reuse the host system first. For a net-new scalable system, separate primitive values from semantic roles and component tokens; define modes without duplicating meaning.
+- The Design Tokens Community Group 2025.10 format is a stable interoperability option, not a W3C Standard and not a mandatory migration target. Use it only when tools need a portable source of truth.
+- Each shared component documents anatomy, semantic element, variants, sizes, content limits, states, keyboard behavior, responsive behavior, and accessibility name/description rules.
+- Keep one source of truth. Generated platform outputs must not become competing hand-edited token stores.
+
+## 8. Trust, privacy, and high-consequence flows
+
+- Do not use deceptive hierarchy, disguised ads, preselected consent, confirm-shaming, forced continuity, hidden costs, or an easier opt-in than opt-out path.
+- Show total cost, renewal terms, data use, permissions, and destructive consequences before commitment. Keep consent granular and revocable where the product requires it.
+- Do not expose secrets or sensitive personal data in screenshots, examples, analytics labels, URLs, notifications, or error copy.
+- High-consequence health, finance, safety, identity, and legal interfaces require domain review, conservative defaults, traceable calculations, and clear escalation or correction routes.
+
+## 9. Native mobile and adaptive windows
+
+- Follow current Apple Human Interface Guidelines or Material/Android guidance for the actual target instead of styling a web layout to resemble a phone.
+- Respect system bars, safe areas, Dynamic Type or platform font scaling, platform navigation/back behavior, input methods, permissions, haptics, and reduced-motion/accessibility settings.
+- Build adaptive layouts for compact, medium, expanded, resizable, split-screen, keyboard, pointer, and touch contexts that the target platform supports.
+- Prefer platform components and conventions unless a custom control has a tested product need and complete accessibility behavior.
+
+## 10. Conditional content types
+
+- Data visualization provides a text summary or accessible data alternative, meaningful names, keyboard access where interactive, non-color encoding, readable labels, and truthful scales.
+- Tables use actual table semantics when relationships are tabular. Dense grids need an explicit keyboard and virtualization accessibility strategy.
+- Search, filtering, pagination, and master-detail layouts preserve useful query/selection state and orientation. On narrow screens, keep decision-critical detail and the primary action visible or one obvious action away; do not strand the initial state at a list when task completion requires its detail. Announce result changes appropriately and distinguish no results from errors and first-use emptiness.
+- AI, chat, and agent surfaces distinguish user, model, tool, source, pending, completed, interrupted, and failed content. Streaming work provides stop/cancel and recovery, preserves useful partial output, and avoids announcing every token to assistive technology.
+- Consequential AI actions expose scope and destination before execution, request confirmation or permission at the point of risk, show progress and outcome, support correction or undo where possible, and never imply certainty, provenance, or successful action without evidence.
+- Media surfaces provide captions or transcripts when required, meaningful alternatives, keyboard-operable controls, no surprise audio, and motion/autoplay behavior that respects user preferences.
+- If multiple themes are supported, use semantic tokens and native `color-scheme` behavior, prevent a wrong-theme flash where feasible, persist the user's explicit choice, and verify contrast, focus, media, and system-control rendering in every mode.
+
+## Required release evidence
+
+For every broad implementation, record:
+
+1. representative desktop and narrow/mobile renders, plus native/adaptive sizes when applicable;
+2. primary-flow keyboard completion, visible focus, focus return, and no obscured focus;
+3. project accessibility-tool output plus manual semantics and status review;
+4. 200% text, 320 CSS-pixel reflow where applicable, longest content, and one localization stress case;
+5. reduced-motion and forced-colors/high-contrast results where supported;
+6. loading, empty, error, retry, disabled, success, destructive, and offline/slow-network states that apply;
+7. route, refresh, deep-link, Back/Forward or native-back behavior that applies;
+8. measured performance evidence or an explicit unverified item with the exact missing measurement;
+9. the project's supported browser, device, and input matrix.
+
+A small component records only applicable evidence, but semantics, keyboard/focus, content extremes, and relevant states cannot be skipped. Report contract failures plainly and fix them before calling broad UI work complete.

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

@@ -0,0 +1,117 @@
+# Provenance and Boundaries
+
+## Contents
+
+- Included corpus and nature of observations
+- Refero boundary
+- Accessibility standards
+- UI craft research
+- Production-practice research
+- Design-process references
+- Skill-architecture research
+- Refresh policy
+
+## Included corpus
+
+- **Source:** [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md)
+- **Pinned commit:** [`664b3e78fd1a298ba11973822da988483256d4b4`](https://github.com/VoltAgent/awesome-design-md/tree/664b3e78fd1a298ba11973822da988483256d4b4)
+- **Archive:** `https://codeload.github.com/VoltAgent/awesome-design-md/tar.gz/664b3e78fd1a298ba11973822da988483256d4b4`
+- **Retrieved:** 2026-07-13
+- **License:** MIT, copyright 2026 VoltAgent; retained at `corpus/awesome-design-md/LICENSE`
+- **Included:** all 74 `design-md/*/DESIGN.md` files present in the pinned archive
+- **Excluded:** upstream previews, screenshots, media, fonts, website assets, private requests, and non-`DESIGN.md` content
+
+Every copied document has its own SHA-256, category, byte count, and parser status in `data/corpus-manifest.json`. The analyzer verifies hashes before producing observations.
+
+The pinned archive contains 74 documents. This differs from both the initial planning estimate of 75 and the upstream README badge of 73 at that commit. The manifest records the discrepancy rather than silently modifying the corpus.
+
+## Nature of the observations
+
+The upstream files analyze public brand and product surfaces. They are not official design-system publications from the named brands and do not grant rights to brand names, trademarks, proprietary fonts, or media. This skill uses them as observational text evidence, not as authority to reproduce a brand.
+
+The derived references are an original synthesis. Quantitative claims point to the pinned commit and deterministic extraction; judgment and runtime recommendations are stated separately.
+
+## Refero boundary
+
+[`styles.refero.design`](https://styles.refero.design/) advertises a DESIGN.md reference library and a Refero MCP. No Refero pages, files, API responses, screenshots, or metadata are copied into this skill.
+
+As fetched on 2026-07-13, [`styles.refero.design/robots.txt`](https://styles.refero.design/robots.txt):
+
+- disallows named AI agents—including GPTBot, ClaudeBot, anthropic-ai, and Google-Extended—from `/`;
+- allows the general user agent but disallows `/api/`, `/admin/`, `/extract/`, and `/playground/`.
+
+Therefore this skill must not bulk-scrape Refero, call undocumented Refero endpoints, or mirror its catalog. Refero may be used only through an authorized Refero MCP or a user-provided export the user is entitled to share. Live access is optional; the skill works without it.
+
+## Accessibility standards
+
+- **Conformance floor:** [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), W3C Recommendation dated 12 December 2024 in the current W3C publication fetched 2026-07-13.
+- **Not the conformance target:** [W3C Accessibility Guidelines (WCAG) 3.0](https://www.w3.org/TR/wcag-3.0/) is a W3C Working Draft dated 3 March 2026. W3C says publication as a Working Draft does not imply endorsement and that it is inappropriate to cite as anything other than work in progress.
+
+Project or jurisdictional requirements may exceed this floor. Use the current official standard and product-specific accessibility requirements at implementation time.
+
+## UI craft research checked 14 July 2026
+
+The binding rulings in `references/craft-rulings.md` use these current sources:
+
+- [WCAG 2.2 SC 1.4.3, Contrast Minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html): 4.5:1 normal text and 3:1 large text;
+- [WCAG 2.2 SC 1.4.11, Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): 3:1 for meaningful control/state/graphic cues;
+- [WCAG 2.2 SC 2.3.3, Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html): unnecessary interaction motion can be disabled and user reduced-motion preferences should be supported;
+- [WCAG 2.2 SC 3.2.3, Consistent Navigation](https://www.w3.org/WAI/WCAG22/Understanding/consistent-navigation.html) and [SC 3.2.4, Consistent Identification](https://www.w3.org/WAI/WCAG22/Understanding/consistent-identification.html): repeated navigation order and repeated function identity stay predictable;
+- [Lucide accessibility guidance](https://lucide.dev/guide/advanced/accessibility): visible labels in most cases, consistent icon usage, contrast, keyboard feedback, accessible icon buttons, and 44 by 44 target wrappers;
+- [Material Symbols guide](https://developers.google.com/fonts/docs/material_symbols): coherent variable fill, weight, grade, and optical-size axes, plus subset guidance;
+- [Carbon motion](https://carbondesignsystem.com/elements/motion/overview/): productive versus expressive motion, named easing roles, and duration scaled to motion size;
+- [Carbon 2x Grid](https://carbondesignsystem.com/elements/2x-grid/overview/): shared units, key lines, consistent padding, and breakpoint integrity;
+- [Google Fonts CSS API](https://developers.google.com/fonts/docs/getting_started) and [web.dev font practices](https://web.dev/articles/font-best-practices): explicit families/weights, `font-display`, early discovery, preconnect for third-party origins, and layout-shift testing;
+- [Google Fonts metadata](https://fonts.google.com/metadata/fonts), fetched 14 July 2026: current family availability and popularity ordering used for the inspiration list.
+
+The motion recommendations were also checked against the pinned local corpus. Several observed systems use color, underline, border, surface, icon, or opacity feedback instead of generic scale/translate hover lift. These remain independent observations, not official brand guidance.
+
+Refero content was not accessed for this update because no authorized Refero MCP or user-provided export was available. The existing Refero boundary remains unchanged.
+
+## Production-practice research checked 14 July 2026
+
+The pass/fail contract in `references/production-contract.md` was checked against current primary guidance:
+
+- [What's New in WCAG 2.2](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/) and the linked Understanding documents: focus not obscured, target size minimum, dragging alternatives, redundant entry, and accessible authentication;
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) and its dialog, menu button, combobox, and keyboard-interface patterns: native semantics first and complete keyboard/focus behavior for custom composites;
+- [WAI Forms Tutorial](https://www.w3.org/WAI/tutorials/forms/): labels, grouping, instructions, validation, notifications, and accessible custom controls;
+- the [WHATWG HTML Standard for dialog](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element) and [popover](https://html.spec.whatwg.org/multipage/popover.html), plus [MDN Popover API guidance](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API): modal versus non-modal top-layer behavior and the semantics authors must still provide;
+- [web.dev Web Vitals](https://web.dev/articles/vitals): current LCP, INP, and CLS thresholds and 75th-percentile field measurement; [LCP optimization](https://web.dev/articles/optimize-lcp), [MDN lazy loading](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Lazy_loading), and the existing font sources support the media/font performance rules;
+- [web.dev Baseline](https://web.dev/baseline), [MDN container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries), [subgrid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Subgrid), [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values), and [forced colors](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors): support-policy-led progressive enhancement and resilient layout;
+- [W3C Internationalization Quick Tips](https://www.w3.org/International/quicktips/): Unicode, language declaration, semantic content, and international layout/content preparation;
+- [Design Tokens Format Module 2025.10](https://www.designtokens.org/TR/2025.10/format/): a stable DTCG Final Community Group Report and interoperability option that is explicitly not a W3C Standard;
+- current [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) and [Android adaptive-layout guidance](https://developer.android.com/develop/ui/compose/layouts/adaptive): platform controls, accessibility settings, safe areas, resizable/adaptive windows, and native conventions;
+- [W3C Ethical Web Principles](https://www.w3.org/TR/ethical-web-principles/) and the [FTC dark-pattern report](https://www.ftc.gov/reports/bringing-dark-patterns-light): user control, privacy, non-deceptive consent, and avoidance of manipulative flows;
+- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html): current authentication and credential-flow constraints where a UI exposes those features;
+- [OpenAI Apps SDK UX principles](https://developers.openai.com/apps-sdk/concepts/ux-principles) and the [Microsoft HAX Toolkit](https://www.microsoft.com/en-us/haxtoolkit/): focused conversational value, clear action boundaries, privacy, expectation-setting, recovery from AI failure, and human oversight for AI-facing surfaces.
+
+These are implementation references, not claims that every listed browser API or platform convention applies to every project. The local support matrix, product requirements, and stricter jurisdictional obligations decide applicability.
+
+## Design-process references consulted
+
+The synthesis considered public patterns from:
+
+- [Anthropic `frontend-design`](https://github.com/anthropics/skills/tree/main/skills/frontend-design): brief-first direction and deliberate visual choices;
+- [Leonxlnx `taste-skill`](https://github.com/Leonxlnx/taste-skill): detection of recurring generic landing-page patterns;
+- [NextLevelBuilder `ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill): broad heuristic/reference organization.
+
+No source skill text is bundled or renamed. This skill rejects fixed palette/font/radius bans, perpetual-motion defaults, and landing-page rules applied to product UI. See `LICENSES.md` for attribution status.
+
+## Skill-architecture research checked 14 July 2026
+
+The package structure was checked against the [Agent Skills specification](https://agentskills.io/specification), [Anthropic skill-authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md), [OpenAI Skills guidance](https://platform.openai.com/docs/guides/tools-skills), and [Agent Skills evaluation guidance](https://agentskills.io/skill-creation/evaluating-skills): loader-visible name/description metadata, a concise directly actionable `SKILL.md`, references one level from the root, focused on-demand documents, self-contained scripts, explicit validation, and evaluation-driven iteration. The installed EZ Coder loader reads `name` and `description`; the portable `license` and `compatibility` fields are retained for other Agent Skills clients and safely ignored by EZ Coder.
+
+`SKILL.md` remains below the recommended 500-line limit. Reference files over 100 lines include a contents overview so an agent preview exposes the file's scope. Detailed corpus data stays out of runtime context unless a specific claim requires it. The existing external A/B artifacts are unscored and predate the current contracts, so they are benchmark inputs rather than evidence that the current skill improves quality.
+
+## Refresh policy
+
+A corpus refresh must be explicit:
+
+1. choose and record a new upstream commit;
+2. replace only the licensed `DESIGN.md` snapshot and upstream license;
+3. regenerate every hash and parser status;
+4. rerun analysis and inspect changed denominators/outliers;
+5. update synthesis claims and examples;
+6. rerun validation.
+
+Do not fetch “latest” silently at runtime. Reproducibility is more important than invisible freshness.

package/assets/skills/evidence-led-ui/references/quality-rubric.md

@@ -0,0 +1,126 @@
+# Rendered UI Quality Rubric
+
+## Contents
+
+- Scoring and independent production-contract gate
+- Criteria 1–4: specificity, hierarchy, composition, consistency and flow
+- Criteria 5–8: typography, material logic, state completeness, responsive behavior
+- Criteria 9–12: accessibility, motion, content authenticity, visual distinctiveness
+- Required critique loop
+
+## Scoring
+
+Capture the implemented UI at a representative desktop viewport and a narrow mobile viewport. Score each criterion **0, 1, or 2** from rendered evidence, not source-code intent.
+
+- **0 — broken or absent:** blocks completion, contradicts the brief, or has no evidence.
+- **1 — usable but generic/incomplete:** the core works, but hierarchy, states, or specificity remain weak.
+- **2 — resolved:** clear, product-specific, responsive, and testable.
+
+Maximum: **24 points**. Ship broad UI work only at **20/24 or higher**, with no zero in accessibility, consistency and flow, responsive behavior, state completeness, or content authenticity, and only after the applicable checks in `production-contract.md` pass. The contract is an independent release gate; rubric points cannot offset semantics, accessibility, performance, resilience, or trust failures. A small component may score only applicable criteria, but every applicable quality-floor criterion must score 2 and its contract checks must pass.
+
+## 1. Brief specificity
+
+- **0:** Audience, task, and single job are unclear.
+- **1:** Screen addresses the requested domain but could serve a neighboring product unchanged.
+- **2:** Hierarchy, controls, content, and signature visibly support the named audience and job.
+
+**Test:** Cover the logo. State the product and task from the screenshot alone.
+
+## 2. Information hierarchy
+
+- **0:** Primary action or reading order is ambiguous.
+- **1:** A primary path exists, but multiple elements compete at the same level.
+- **2:** First glance, second glance, and action sequence are deliberate; subordinate content remains available without competing.
+
+**Test:** At 50% zoom or with a blurred screenshot, identify the first three attention stops.
+
+## 3. Composition
+
+- **0:** Layout breaks, clips, ignores shared key lines, or relies on arbitrary modules.
+- **1:** Grid is stable but generic, repetitive, or weakly related to content; some section edges or component geometry drift.
+- **2:** Scale, key lines, alignment, whitespace, and asymmetry/symmetry express content relationships and remain deliberate across viewports.
+
+**Test:** Draw vertical and horizontal guides through major regions. Shared edges, baselines, dividers, and repeated component anatomy should align unless an exception communicates real hierarchy.
+
+## 4. Consistency and flow
+
+- **0:** Repeated functions change labels, icons, placement, geometry, or behavior; sections/pages feel independently invented.
+- **1:** Most patterns repeat, but spacing cadence, icon treatment, controls, actions, or section transitions contain visible inconsistencies.
+- **2:** Existing primitives are reused; one icon family, spacing rhythm, component anatomy, navigation order, action placement, and surface logic carry through the full flow.
+
+**Test:** Compare adjacent sections and pages side by side. Trace one repeated action through every occurrence, then inspect container edges, control heights, icon weight, spacing, borders, labels, and state behavior.
+
+## 5. Typography
+
+- **0:** Text is unreadable, clipped, visually generic by neglect, or lacks a usable hierarchy.
+- **1:** Type is legible but role assignment, family choice, measure, leading, loading, fallback, or pairing is inconsistent.
+- **2:** Display, body, utility, and code roles are intentional; the chosen family/pairing fits the product; line lengths, wrapping, localization, requested weights, fallback metrics, and loading behavior are resolved.
+
+**Test:** Inspect the longest real heading and paragraph at desktop and mobile. Disable web fonts, throttle loading, and compare fallback layout shift. Confirm every loaded family/style/weight has a used role.
+
+## 6. Material and surface logic
+
+- **0:** Borders, shadows, blur, gradients, and radii conflict or obscure content.
+- **1:** Treatments are consistent but decorative or over-applied.
+- **2:** Every surface has a clear containment/elevation reason; radius vocabulary is constrained by component role; effects reinforce subject matter.
+
+**Test:** Name why each elevation level exists. Remove any level without a distinct reason.
+
+## 7. State completeness
+
+- **0:** A critical loading, empty, error, focus, form, offline, or disabled state is missing, unusable, loses work, or changes abruptly without adequate feedback.
+- **1:** Happy-path interaction works, but secondary states, feedback, timing, recovery, or layout continuity are generic or incomplete.
+- **2:** Relevant loading, empty, error, validation, retry, offline, focus, hover/press, selected, expanded, pending, disabled, destructive, and success states are coherent, preserve work and layout, and provide purposeful feedback.
+
+**Test:** Trigger each relevant state with realistic content length and failure wording. Confirm preservation, recovery, duplicate-submission behavior, status announcement, and that any transition improves continuity rather than decoration.
+
+## 8. Responsive behavior
+
+- **0:** Content clips, overlaps, becomes unreachable, breaks reading/focus order, or loses its primary action.
+- **1:** Layout stacks but hierarchy, density, localization, navigation, or input behavior degrades.
+- **2:** Mobile, intermediate, wide, and resizable layouts deliberately recompose; target sizes, ordering, sticky regions, safe areas, input modes, content priority, and localization remain sound.
+
+**Test:** Inspect at 320px, a representative phone width, 768px, and a wide desktop width; zoom browser text to 200% where applicable; stress long text and one RTL/localization case; verify no-hover and coarse-pointer behavior.
+
+## 9. Accessibility quality floor
+
+- **0:** Keyboard path, focus, semantics, contrast, labels, icon meaning, status, drag-only operation, or target sizes block use.
+- **1:** Basics exist but focus order/visibility, text/non-text contrast, motion, icon labels, status cues, composite-widget behavior, forced colors, or assistive naming has gaps.
+- **2:** Native semantics or verified APG behavior, visible and unobscured focus, keyboard operation, meaningful labels/status, WCAG 2.2 target minimums with platform-appropriate touch targets, reduced motion, forced colors, text contrast of at least 4.5:1 (3:1 for large text), and meaningful non-text contrast of at least 3:1 are verified.
+
+**Test:** Complete the primary task by keyboard; inspect accessible names and status; verify overlay focus and drag alternatives; measure text, icon, control, and focus contrast; run project accessibility tooling; test 200% text/reflow, `prefers-reduced-motion`, and forced colors; verify color is not the only cue.
+
+## 10. Motion purpose
+
+- **0:** Relevant interaction feedback is missing or abrupt, or motion distracts, loops, shifts layout, uses generic hover lift, relies on `transition: all`, or ignores reduced motion.
+- **1:** Motion is restrained but timing, easing, property choice, or state coverage is inconsistent.
+- **2:** Every relevant interaction has purposeful feedback; named properties and shared tokens communicate state or continuity; resting surfaces are calm; generic lift is absent; reduced motion preserves meaning.
+
+**Test:** For every transition, finish “This feedback explains…” and identify the property, duration, easing token, and reduced-motion behavior. Remove movement without an answer.
+
+## 11. Content authenticity
+
+- **0:** Fabricated claims, metrics, testimonials, logos, ratings, or misleading product states appear as real.
+- **1:** Content is plausible but generic, repetitive, visibly placeholder-like, or inconsistent with the product voice.
+- **2:** Copy and data are real, supplied, or honestly labeled fixtures; labels, units, dates, errors, and punctuation follow one product voice; generated UI copy avoids em dashes unless explicitly allowed.
+
+**Test:** Trace every factual claim and number to project content, user input, or an explicitly marked fixture. Search generated UI copy for em dashes and verify every retained one is required source text or explicitly requested.
+
+## 12. Visual distinctiveness
+
+- **0:** Screen is indistinguishable from a generic template, uses emoji or mixed icon styles, or could belong to an unrelated AI-generated product.
+- **1:** Brand tokens are present, but typography, composition, icon language, and motifs remain transferable.
+- **2:** One coherent icon family and intentional typography support a memorable signature that emerges from the subject, content, or interaction without compromising usability.
+
+**Test:** Remove logo and accent color. Identify the remaining product-specific signature, type voice, and icon language.
+
+## Required critique loop
+
+1. Capture desktop and mobile screenshots.
+2. Score every applicable criterion and record one line of evidence per score.
+3. Run the applicable `production-contract.md` checks and record pass, fail, or a specific unverified item.
+4. Identify the lowest-scoring criterion; ties resolve in this order: accessibility, consistency and flow, state completeness, responsive behavior, hierarchy, authenticity, then aesthetics.
+5. Remove one unnecessary decorative idea.
+6. Revise the weakest criterion and every contract failure.
+7. Re-capture, re-score, and re-check affected contract evidence.
+8. Report the final score and any unverified item honestly.