diff --git a/.claude/skills/VENDORED.md b/.claude/skills/VENDORED.md index d1536ea0..0a68d659 100644 --- a/.claude/skills/VENDORED.md +++ b/.claude/skills/VENDORED.md @@ -1,13 +1,13 @@ # Vendored skills Copied from [gabrielbr/Gabriel-Deisgn-System](https://github.com/gabrielbr/Gabriel-Deisgn-System) -`.claude/skills/` at **design system 0.31.0**, as its AGENTS.md requires of every +`.claude/skills/` at **design system 0.31.1**, as its AGENTS.md requires of every app on the boilerplate. AGENTS.md here ("Four skills on every screen and flow") says when to use them. | Skill | Source | Version | Licence | |---|---|---|---| | `ux-user-flows/` | The owner's claude.ai skill, via the design system (copied there 2026-11-04) | — | The owner's | -| `impeccable/` | [pbakaus/impeccable](https://github.com/pbakaus/impeccable), `plugin/skills/impeccable` at `f5c80432f883a0ee437735305eafc2a9e1bdb7a0` | skill 4.8.0, launcher 0.1.18 | Apache-2.0 (`impeccable/LICENSE`, `impeccable/NOTICE.md`) | +| `impeccable/` | [pbakaus/impeccable](https://github.com/pbakaus/impeccable), `plugin/skills/impeccable` at `d41d9860b0094dcb68030657da63461212835aaa` | skill 4.9.2, launcher 0.1.25 | Apache-2.0 (`impeccable/LICENSE`, `impeccable/NOTICE.md`) | | `graphic-design-fundamentals/` | The owner's claude.ai skill, via the design system (copied there 2026-11-01) | — | The owner's | | `less-is-more/` | The design system (0.29.0) | 1.0 | The owner's | @@ -17,3 +17,5 @@ Notes `reference/android.md`. Its `detect` scanner is for web code and does not apply. - Don't edit these copies. A skill changes in the design-system repo first; its CHANGELOG entry (a patch release) says to re-copy, and this file's version line moves with it. +- Impeccable is kept at its latest release (the owner's rule, 2026-11-16): updated in the design + system first, then re-copied here the same day. Don't run `npx impeccable update` in this repo. diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index ded40d5a..4bc5510b 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -1,7 +1,7 @@ --- name: impeccable -description: "Use when the user wants to design, redesign, shape, critique, audit, polish, simplify, harden, animate, or otherwise improve a frontend interface: websites, landing pages, dashboards, product UI, components, forms, settings, onboarding, empty states, and native iOS or Android screens. Handles UX review, hierarchy, layout, typography, color, motion, UX copy, accessibility, responsive behavior, edge cases, and capturing or documenting design systems (DESIGN.md, tokens). Also for making bland UI bolder, loud UI quieter, or ambitious visual effects. Not for backend-only or non-UI tasks." -version: 4.8.0 +description: "Use to design, redesign, critique, audit, polish or animate a frontend: websites, landing pages, dashboards, app UI, components, native iOS/Android screens, or a design system (DESIGN.md)." +version: 4.9.2 user-invocable: true argument-hint: "[shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · init|document|extract|live|generate] [target]" license: Apache 2.0 @@ -17,7 +17,7 @@ Core principles: ## Setup 1. Run `"${CLAUDE_SKILL_DIR}/scripts/impeccable" context` once per session, where `${CLAUDE_SKILL_DIR}` is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project. Every `"${CLAUDE_SKILL_DIR}/scripts/impeccable" ` command in this skill and its references resolves against that base directory. In reference files, replace the skill-base-dir placeholder with this directory before running commands; it is not a shell variable. On a Windows shell without `sh`, call `& "${CLAUDE_SKILL_DIR}/scripts/impeccable.cmd"` instead. The launcher runs a self-contained binary that ships next to it or is downloaded once on first run; no Node or other runtime is required. Pass a named source file or route as `--target `. It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable; follow its directives and do not rerun it. -2. Load the request's playbook: its Commands-table reference for an explicit/implied sub-command, or [reference/new-work.md](reference/new-work.md) for a new surface or replacement visual world. Inspect target and incumbent visual truth before editing. When the app cannot run, start with committed visual-regression goldens or screenshot fixtures; verify target and freshness against current tokens, CSS, components, or assets, resolve conflicts, and compare theme/variant captures. +2. Load the request's playbook: its Commands-table reference for an explicit/implied sub-command, or [reference/new-work.md](reference/new-work.md) for a new surface, a replacement visual world, or a build from an approved comp. Some playbooks come in parts; read the part this request needs in the same step, not when the playbook later mentions it: [reference/new-work-world.md](reference/new-work-world.md) when a visual world is created or replaced (a redesign, a new look, or no established world), [reference/new-work-comp.md](reference/new-work-comp.md) for a build from an approved comp or on a comp-led build path, and [reference/critique-rubric.md](reference/critique-rubric.md) for a critique whose Assessment A runs in this context (a native platform, or no sub-agent tool); a delegated Assessment A gets the rubric's path in its prompt instead. Inspect target and incumbent visual truth before editing. When the app cannot run, start with committed visual-regression goldens or screenshot fixtures; verify target and freshness against current tokens, CSS, components, or assets, resolve conflicts, and compare theme/variant captures. 3. After resolving analysis and direction, read [reference/craft-floor.md](reference/craft-floor.md) immediately before any UI edit, including small refinements. It carries the quality floor, the absolute bans, and the reflexes no detector catches. Do not load it for planning-only work. **Launcher unavailable:** On refusal or failure, send a separate message **before the next tool call**: “Context loading did not run; I’ll read the existing project context directly.” Then read existing PRODUCT.md and DESIGN.md without inventing missing context, follow applicable steps 2–3, including reading [reference/craft-floor.md](reference/craft-floor.md) immediately before any UI edit, and continue through permitted tools. This applies to planning and editing; launcher failure alone does not block either. @@ -85,4 +85,6 @@ After init writes PRODUCT.md, resume without rerunning `impeccable context`; ini **Doctor:** `/impeccable doctor` reports and repairs drift between this project's Impeccable artifacts (PRODUCT.md, DESIGN.md and its sidecar, config, surface briefs, the hook) and what this version reads. Load [reference/doctor.md](reference/doctor.md) when the user invokes it, or when they ask what is out of date, stale, or needs refreshing. A `CONTEXT_STALE` directive in Setup's output is the cheap subset of the same report; act on it there per its own instructions rather than running doctor unasked. +**Foundations:** `/impeccable foundations` runs `"${CLAUDE_SKILL_DIR}/scripts/impeccable" foundations` and walks the user through the product-foundations roadmap (secrets, 404 page, icons, CI and more); `/impeccable foundations ` fixes that one item. Load [reference/foundations.md](reference/foundations.md) when the user invokes it. + **Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks. The one exception is a finding marked `auto`, which the next write to that file performs anyway. \ No newline at end of file diff --git a/.claude/skills/impeccable/reference/adapt.md b/.claude/skills/impeccable/reference/adapt.md index cabc0fde..6b1a6d06 100644 --- a/.claude/skills/impeccable/reference/adapt.md +++ b/.claude/skills/impeccable/reference/adapt.md @@ -161,7 +161,7 @@ Choose appropriate breakpoints: ### Navigation Adaptation - Transform complex nav to hamburger/drawer on mobile -- Bottom nav bar for mobile apps +- Bottom nav bar for mobile web - Persistent side navigation on desktop - Breadcrumbs on smaller screens for context @@ -229,7 +229,7 @@ Don't chase device sizes; let content tell you where to break. Start narrow, str /* Device supports hover */ @media (hover: hover) { - .card:hover { transform: translateY(-2px); } + .card:hover .card-surface { transform: translateY(-2px); } /* Lift a child; the card stays the hit area */ } /* Device doesn't support hover (touch) */ diff --git a/.claude/skills/impeccable/reference/animate.md b/.claude/skills/impeccable/reference/animate.md index 4ae4cc5f..473336f0 100644 --- a/.claude/skills/impeccable/reference/animate.md +++ b/.claude/skills/impeccable/reference/animate.md @@ -60,6 +60,10 @@ Timing should express distance and consequence: Exit faster than entrance. Use natural deceleration such as `cubic-bezier(0.16, 1, 0.3, 1)` for confident arrivals; do not use bounce or elastic curves by reflex. Long feedback feels like latency. +## Hover + +Hover motion never moves a neighbor or takes its pointer target. Keep the hovered element still and let a child carry the motion (`.card:hover .card-surface { transform: translateY(-2px) }`). An element that moves itself slides out from under a pointer near its edge and flickers. Optional previews wait for the pointer to settle: for a CSS reveal, set `transition-delay` on the hover state only, so leaving is not delayed. + ## Implement to the runtime - Use CSS transitions and keyframes for declarative state and bounded sequences. @@ -78,6 +82,19 @@ Every web animation needs a `prefers-reduced-motion` path with an intentional al ## Verify +On the web, capture implemented motion before calling it smooth. Use the skill-internal measuring verb (not a separate user command), once normally and once with reduced motion, with the same URL, interaction, and region: + +```sh +"/scripts/impeccable" motion-capture --click '' --region '' --out-dir .impeccable/review/motion/normal +"/scripts/impeccable" motion-capture --click '' --region '' --reduced-motion --out-dir .impeccable/review/motion/reduced +``` + +For keyboard or multi-step interactions pass `--steps ` instead of `--click`, such as `[{"click":"#toggle"},{"press":"Enter"}]`; steps are click, hover, press (navigation keys), and wait (milliseconds). Capture each entrance and exit separately: for an exit, `--setup ` runs the same kind of steps and lets them settle before the first frame, such as opening the panel whose close is under review. The fixed capture points are before, first animated, evenly spaced middle, last animated, and settled frames. Inspect each directory's frame PNGs, `filmstrip.png`, and `report.json` before sending it: blank, wrong-region, stale, or missing evidence requires recapture. The report's limitations are unmeasured checks, not a clean result. Never judge motion by a single element or a single screenshot. + +Spawn the shipped `impeccable-motion-reviewer` fresh (`impeccable_motion_reviewer` in Codex; `/impeccable-motion-reviewer` in Cursor; on GitHub Copilot say "Use the impeccable-motion-reviewer agent"), with no forked conversation history. Pass the original request, the motion thesis above, both capture directories (plus entrance and exit captures where applicable), DESIGN.md's motion rules if any, and the craft-floor reference path. The reviewer has no browser and reviews only the provided evidence. Never read its agent definition before spawning; the harness loads it. Wait with one long timeout; verify a disposition-first return with `continuity`, `craft`, `reduced_motion`, `material_fixes`, and `keep`. Respawn an empty or incomplete return once with the same packet. Only when the harness has no subagent capability, run a separate fresh pass from [degraded/motion-reviewer.md](degraded/motion-reviewer.md), and disclose the substitution at finish. + +Act on the disposition. **recapture:** repair the named evidence and request a full review; invalid evidence binds no verdict. **fix:** apply the ordered material fixes in one batch, recapture normal and reduced motion over the same files, and continue the same reviewer for a verdict pass scoring each fix resolved, partial, or unresolved. Without continuation, pass the prior findings and new captures to a fresh reviewer. **ship:** report that word at the scope the reviewer actually checked. Two rounds maximum (initial review, then post-fix verdict); stop if a round resolves nothing. Report remaining fixes or missing evidence honestly at the ceiling; never turn a partial or unresolved verdict into a claim of smoothness. + - The focal motion is specific to the selected world and surface. - Every supporting animation explains feedback, state, or relationship. - Interruption and repeated use behave correctly. diff --git a/.claude/skills/impeccable/reference/audit.md b/.claude/skills/impeccable/reference/audit.md index b082c5a6..3311de95 100644 --- a/.claude/skills/impeccable/reference/audit.md +++ b/.claude/skills/impeccable/reference/audit.md @@ -53,7 +53,14 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the - **Text scaling**: Layouts that break when text size increases - **Missing breakpoints**: No mobile/tablet variants -**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch) +On RTL-declared pages, each of the following is a signal to verify the rendered result, not a defect in itself; flag only where the rendering is actually wrong: +- **Physical directional properties**: `margin-left/right`, `padding-left/right`, `text-align: left/right`, `float: left/right`, `border-left/right` where logical equivalents (`margin-inline-start/end`, `padding-inline-start/end`, `text-align: start/end`, `float: inline-start/end`, `border-inline-start/end`) would be expected. A direction-scoped override like `[dir="rtl"] .x { margin-right:1rem }` is correct only when it also clears the conflicting base property (e.g. `margin-left: 0`); without that, both margins apply +- **Physical positioning on positioned elements**: `left:` or `right:` instead of `inset-inline-start` / `inset-inline-end`. Note: `left:50%; transform:translateX(-50%)` is a direction-agnostic centering pattern that works correctly in both LTR and RTL; replacing `left` with `inset-inline-start` there breaks the centering because `translateX` is physical and does not mirror +- **Directional icons and assets**: arrows, chevrons, and navigation icons that point the wrong direction for the reading order. An RTL-only page may ship assets already drawn correctly without a `[dir="rtl"]` flip; verify the rendered icon rather than assuming a missing `transform: scaleX(-1)` is a defect + +**RTL scope**: flag physical directional properties only on pages that declare `dir="rtl"` on the `` or `` element. A `lang` attribute alone does not set direction (browsers take direction from `dir`, never from `lang`), but treat an RTL-script `lang` (`ar`, `fa`, `ur`, `ps`, `ckb`, `he`, `yi`, `ug`, `sd`, `dv`) without an explicit `dir` as a signal worth noting. + +**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch). On RTL-declared pages, reduce by 1 for pervasive rendered RTL failures ### 5. Implementation Integrity (CRITICAL) @@ -137,3 +144,7 @@ Keep P3s few: a long tail of minor issues buries the ones that matter. - Skip positive findings (celebrate what works) - Forget to prioritize (everything can't be P0) - Report false positives without verification + +## Save the Report + +After the report is delivered, save a copy so the findings outlive this conversation: write it, from the score table through Recommended Actions, to a temp file, then run `"/scripts/impeccable" audit-storage write "" ` and delete the temp file. The helper prints the path it wrote, which you mention in one line; `REPORTS OFF:` means the project opted out, and you mention nothing. Saving never replaces delivering: the user reads the report in chat first. diff --git a/.claude/skills/impeccable/reference/audit.native.md b/.claude/skills/impeccable/reference/audit.native.md index 2f5ac514..e34fc1a0 100644 --- a/.claude/skills/impeccable/reference/audit.native.md +++ b/.claude/skills/impeccable/reference/audit.native.md @@ -137,3 +137,7 @@ Keep P3s few: a long tail of minor issues buries the ones that matter. - Skip positive findings (celebrate what works) - Forget to prioritize (everything can't be P0) - Report false positives without verification + +## Save the Report + +After the report is delivered, save a copy so the findings outlive this conversation: write it, from the score table through Recommended Actions, to a temp file, then run `"/scripts/impeccable" audit-storage write "" ` and delete the temp file. The helper prints the path it wrote, which you mention in one line; `REPORTS OFF:` means the project opted out, and you mention nothing. Saving never replaces delivering: the user reads the report in chat first. diff --git a/.claude/skills/impeccable/reference/critique-rubric.md b/.claude/skills/impeccable/reference/critique-rubric.md new file mode 100644 index 00000000..525c60a3 --- /dev/null +++ b/.claude/skills/impeccable/reference/critique-rubric.md @@ -0,0 +1,496 @@ +# Critique rubric + +Assessment A's rubric in [critique.md](critique.md): cognitive load, the heuristic scores, and personas. The score bands and P0 to P3 severity stay in critique.md, where the report uses them. + +### Cognitive Load Assessment + +Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. + +--- + +#### Three Types of Cognitive Load + +##### Intrinsic Load: The Task Itself +Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. + +**Manage it by**: +- Breaking complex tasks into discrete steps +- Providing scaffolding (templates, defaults, examples) +- Progressive disclosure: show what's needed now, hide the rest +- Grouping related decisions together + +##### Extraneous Load: Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly.** It's pure waste. + +**Common sources**: +- Confusing navigation that requires mental mapping +- Unclear labels that force users to guess meaning +- Visual clutter competing for attention +- Inconsistent patterns that prevent learning +- Unnecessary steps between user intent and result + +##### Germane Load: Learning Effort +Mental effort spent building understanding. This is *good* cognitive load; it leads to mastery. + +**Support it by**: +- Progressive disclosure that reveals complexity gradually +- Consistent patterns that reward learning +- Feedback that confirms correct understanding +- Onboarding that teaches through action, not walls of text + +--- + +#### Cognitive Load Checklist + +Evaluate the interface against these 8 items: + +- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? +- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? +- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? +- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? +- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? +- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? +- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? +- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? + +**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). + +--- + +#### The Working Memory Rule + +**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). + +At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: +- **≤4 items**: Within working memory limits, manageable +- **5–7 items**: Pushing the boundary; consider grouping or progressive disclosure +- **8+ items**: Overloaded; users will skip, misclick, or abandon + +**Practical applications**: +- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu +- Navigation menus: ≤5 top-level items (group the rest under clear categories) +- Long-form articles: one reading path; gather related links into a single block at the end instead of scattering them mid-flow +- Documentation sidebars: ≤4 sibling choices visible per level before grouping kicks in +- Portfolio and gallery indexes: one decision per screen (which piece to open), not filter, sort, and tag controls all at once + +--- + +#### Common Cognitive Load Violations + +##### 1. The Wall of Options +**Problem**: Presenting 10+ choices at once with no hierarchy. +**Fix**: Group into categories, highlight recommended, use progressive disclosure. + +##### 2. The Memory Bridge +**Problem**: User must remember info from step 1 to complete step 3. +**Fix**: Keep relevant context visible, or repeat it where it's needed. + +##### 3. The Hidden Navigation +**Problem**: User must build a mental map of where things are. +**Fix**: Always show current location (breadcrumbs, active states, progress indicators). + +##### 4. The Jargon Barrier +**Problem**: Technical or domain language forces translation effort. +**Fix**: Use plain language. If domain terms are unavoidable, define them inline. + +##### 5. The Visual Noise Floor +**Problem**: Every element has the same visual weight; nothing stands out. +**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. + +##### 6. The Inconsistent Pattern +**Problem**: Similar actions work differently in different places. +**Fix**: Standardize interaction patterns. Same type of action = same type of UI. + +##### 7. The Multi-Task Demand +**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). +**Fix**: Sequence the steps. Let the user do one thing at a time. + +##### 8. The Context Switch +**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. +**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. + +### Heuristics Scoring Guide + +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest: a 4 means genuinely excellent, not "good enough." + +#### Nielsen's 10 Heuristics + +##### 1. Visibility of System Status + +Keep users informed about what's happening through timely, appropriate feedback. + +**Check for**: +- Loading indicators during async operations +- Confirmation of user actions (save, submit, delete) +- Progress indicators for multi-step processes +- Current location in navigation (breadcrumbs, active states) +- Form validation feedback (inline, not just on submit) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No feedback; user is guessing what happened | +| 1 | Rare feedback; most actions produce no visible response | +| 2 | Partial; some states communicated, major gaps remain | +| 3 | Good; most operations give clear feedback, minor gaps | +| 4 | Excellent; every action confirms, progress is always visible | + +##### 2. Match Between System and Real World + +Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. + +**Check for**: +- Familiar terminology (no unexplained jargon) +- Logical information order matching user expectations +- Recognizable icons and metaphors +- Domain-appropriate language for the target audience +- Natural reading flow (left-to-right, top-to-bottom priority) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Pure tech jargon, alien to users | +| 1 | Mostly confusing; requires domain expertise to navigate | +| 2 | Mixed; some plain language, some jargon leaks through | +| 3 | Mostly natural; occasional term needs context | +| 4 | Speaks the user's language fluently throughout | + +##### 3. User Control and Freedom + +Users need a clear "emergency exit" from unwanted states without extended dialogue. + +**Check for**: +- Undo/redo functionality +- Cancel buttons on forms and modals +- Clear navigation back to safety (home, previous) +- Easy way to clear filters, search, selections +- Escape from long or multi-step processes + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Users get trapped; no way out without refreshing | +| 1 | Difficult exits; must find obscure paths to escape | +| 2 | Some exits; main flows have escape, edge cases don't | +| 3 | Good control; users can exit and undo most actions | +| 4 | Full control; undo, cancel, back, and escape everywhere | + +##### 4. Consistency and Standards + +Users shouldn't wonder whether different words, situations, or actions mean the same thing. + +**Check for**: +- Consistent terminology throughout the interface +- Same actions produce same results everywhere +- Platform conventions followed (standard UI patterns) +- Visual consistency (colors, typography, spacing, components) +- Consistent interaction patterns (same gesture = same behavior) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Inconsistent everywhere; feels like different products stitched together | +| 1 | Many inconsistencies; similar things look/behave differently | +| 2 | Partially consistent; main flows match, details diverge | +| 3 | Mostly consistent; occasional deviation, nothing confusing | +| 4 | Fully consistent; cohesive system, predictable behavior | + +##### 5. Error Prevention + +Better than good error messages is a design that prevents problems in the first place. + +**Check for**: +- Confirmation before destructive actions (delete, overwrite) +- Constraints preventing invalid input (date pickers, dropdowns) +- Smart defaults that reduce errors +- Clear labels that prevent misunderstanding +- Autosave and draft recovery + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Errors easy to make; no guardrails anywhere | +| 1 | Few safeguards; some inputs validated, most aren't | +| 2 | Partial prevention; common errors caught, edge cases slip | +| 3 | Good prevention; most error paths blocked proactively | +| 4 | Excellent; errors nearly impossible through smart constraints | + +##### 6. Recognition Rather Than Recall + +Minimize memory load. Make objects, actions, and options visible or easily retrievable. + +**Check for**: +- Visible options (not buried in hidden menus) +- Contextual help when needed (tooltips, inline hints) +- Recent items and history +- Autocomplete and suggestions +- Labels on icons (not icon-only navigation) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Heavy memorization; users must remember paths and commands | +| 1 | Mostly recall; many hidden features, few visible cues | +| 2 | Some aids; main actions visible, secondary features hidden | +| 3 | Good recognition; most things discoverable, few memory demands | +| 4 | Everything discoverable; users never need to memorize | + +##### 7. Flexibility and Efficiency of Use + +Accelerators, invisible to novices, speed up expert interaction. + +**Check for**: +- Keyboard shortcuts for common actions +- Customizable interface elements +- Recent items and favorites +- Bulk/batch actions +- Power user features that don't complicate the basics + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | One rigid path; no shortcuts or alternatives | +| 1 | Limited flexibility; few alternatives to the main path | +| 2 | Some shortcuts; basic keyboard support, limited bulk actions | +| 3 | Good accelerators; keyboard nav, some customization | +| 4 | Highly flexible; multiple paths, power features, customizable | + +##### 8. Aesthetic and Minimalist Design + +Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. + +**Check for**: +- Only necessary information visible at each step +- Clear visual hierarchy directing attention +- Purposeful use of color and emphasis +- No decorative clutter competing for attention +- Focused, uncluttered layouts + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Overwhelming; everything competes for attention equally | +| 1 | Cluttered; too much noise, hard to find what matters | +| 2 | Some clutter; main content clear, periphery noisy | +| 3 | Mostly clean; focused design, minor visual noise | +| 4 | Perfectly minimal; every element earns its pixel | + +##### 9. Help Users Recognize, Diagnose, and Recover from Errors + +Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. + +**Check for**: +- Plain language error messages (no error codes for users) +- Specific problem identification ("Email is missing @" not "Invalid input") +- Actionable recovery suggestions +- Errors displayed near the source of the problem +- Non-blocking error handling (don't wipe the form) + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | Cryptic errors; codes, jargon, or no message at all | +| 1 | Vague errors; "Something went wrong" with no guidance | +| 2 | Clear but unhelpful; names the problem but not the fix | +| 3 | Clear with suggestions; identifies problem and offers next steps | +| 4 | Perfect recovery; pinpoints issue, suggests fix, preserves user work | + +##### 10. Help and Documentation + +Even if the system is usable without docs, help should be easy to find, task-focused, and concise. + +**Check for**: +- Searchable help or documentation +- Contextual help (tooltips, inline hints, guided tours) +- Task-focused organization (not feature-organized) +- Concise, scannable content +- Easy access without leaving current context + +**Scoring**: +| Score | Criteria | +|-------|----------| +| 0 | No help available anywhere | +| 1 | Help exists but hard to find or irrelevant | +| 2 | Basic help; FAQ or docs exist, not contextual | +| 3 | Good documentation; searchable, mostly task-focused | +| 4 | Excellent contextual help; right info at the right moment | + +### Persona-Based Design Testing + +Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. + +**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags, not generic concerns. + +--- + +#### 1. Impatient Power User: "Alex" + + +**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. + +**Behaviors**: +- Skips all onboarding and instructions +- Looks for keyboard shortcuts immediately +- Tries to bulk-select, batch-edit, and automate +- Gets frustrated by required steps that feel unnecessary +- Abandons if anything feels slow or patronizing + +**Test Questions**: +- Can Alex complete the core task in under 60 seconds? +- Are there keyboard shortcuts for common actions? +- Can onboarding be skipped entirely? +- Do modals have keyboard dismiss (Esc)? +- Is there a "power user" path (shortcuts, bulk actions)? + +**Red Flags** (report these specifically): +- Forced tutorials or unskippable onboarding +- No keyboard navigation for primary actions +- Slow animations that can't be skipped +- One-item-at-a-time workflows where batch would be natural +- Redundant confirmation steps for low-risk actions + +--- + +#### 2. Confused First-Timer: "Jordan" + +**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. + +**Behaviors**: +- Reads all instructions carefully +- Hesitates before clicking anything unfamiliar +- Looks for help or support constantly +- Misunderstands jargon and abbreviations +- Takes the most literal interpretation of any label + +**Test Questions**: +- Is the first action obviously clear within 5 seconds? +- Are all icons labeled with text? +- Is there contextual help at decision points? +- Does terminology assume prior knowledge? +- Is there a clear "back" or "undo" at every step? + +**Red Flags** (report these specifically): +- Icon-only navigation with no labels +- Technical jargon without explanation +- No visible help option or guidance +- Ambiguous next steps after completing an action +- No confirmation that an action succeeded + +--- + +#### 3. Accessibility-Dependent User: "Sam" + +**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. + +**Behaviors**: +- Tabs through the interface linearly +- Relies on ARIA labels and heading structure +- Cannot see hover states or visual-only indicators +- Needs adequate color contrast (4.5:1 minimum) +- May use browser zoom up to 200% + +**Test Questions**: +- Can the entire primary flow be completed keyboard-only? +- Are all interactive elements focusable with visible focus indicators? +- Do images have meaningful alt text? +- Is color contrast WCAG AA compliant (4.5:1 for text)? +- Does the screen reader announce state changes (loading, success, errors)? + +**Red Flags** (report these specifically): +- Click-only interactions with no keyboard alternative +- Missing or invisible focus indicators +- Meaning conveyed by color alone (red = error, green = success) +- Unlabeled form fields or buttons +- Time-limited actions without extension option +- Custom components that break screen reader flow + +--- + +#### 4. Deliberate Stress Tester: "Riley" + +**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. + +**Behaviors**: +- Tests edge cases intentionally (empty states, long strings, special characters) +- Submits forms with unexpected data (emoji, RTL text, very long values) +- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs +- Looks for inconsistencies between what the UI promises and what actually happens +- Documents problems methodically + +**Test Questions**: +- What happens at the edges (0 items, 1000 items, very long text)? +- Do error states recover gracefully or leave the UI in a broken state? +- What happens on refresh mid-workflow? Is state preserved? +- Are there features that appear to work but produce broken results? +- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? + +**Red Flags** (report these specifically): +- Features that appear to work but silently fail or produce wrong results +- Error handling that exposes technical details or leaves UI in a broken state +- Empty states that show nothing useful ("No results" with no guidance) +- Workflows that lose user data on refresh or navigation +- Inconsistent behavior between similar interactions in different parts of the UI + +--- + +#### 5. Distracted Mobile User: "Casey" + +**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. + +**Behaviors**: +- Uses thumb only; prefers bottom-of-screen actions +- Gets interrupted mid-flow and returns later +- Switches between apps frequently +- Has limited attention span and low patience +- Types as little as possible, prefers taps and selections + +**Test Questions**: +- Are primary actions in the thumb zone (bottom half of screen)? +- Is state preserved if the user leaves and returns? +- Does it work on slow connections (3G)? +- Can forms use autocomplete and smart defaults? +- Are touch targets at least 44×44pt? + +**Red Flags** (report these specifically): +- Important actions positioned at the top of the screen (unreachable by thumb) +- No state persistence; progress lost on tab switch or interruption +- Large text inputs required where selection would work +- Heavy assets loading on every page (no lazy loading) +- Tiny tap targets or targets too close together + +--- + +#### Selecting Personas + +Choose personas based on the interface type: + +| Interface Type | Primary Personas | Why | +|---------------|-----------------|-----| +| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | +| Dashboard / admin | Alex, Sam | Power users, accessibility | +| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | +| Onboarding flow | Jordan, Casey | Confusion, interruption | +| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | +| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | + +--- + +#### Project-Specific Personas + +If PRODUCT.md has a `## Users` section (written by `impeccable init`), derive 1–2 additional personas from it and from `## Brand Commitments`: + +1. Read the target audience description +2. Identify the primary user archetype not covered by the 5 predefined personas +3. Create a persona following this template: + +``` +##### [Role]: "[Name]" + +**Profile**: [2-3 key characteristics derived from PRODUCT.md] + +**Behaviors**: [3-4 specific behaviors based on the described audience] + +**Red Flags**: [3-4 things that would alienate this specific user type] +``` + +Only generate project-specific personas when PRODUCT.md describes real users. Don't invent audience details; use the 5 predefined personas when no context exists. diff --git a/.claude/skills/impeccable/reference/critique.md b/.claude/skills/impeccable/reference/critique.md index 2e00cbf0..c7dc4403 100644 --- a/.claude/skills/impeccable/reference/critique.md +++ b/.claude/skills/impeccable/reference/critique.md @@ -38,7 +38,7 @@ Sub-agent gate (all harnesses): - Unless a harness-specific gate below overrides this, spawn A and B as two isolated, parallel sub-agents whenever a sub-agent/Task tool is exposed. This is the default and is mandatory; do not run them inline because it is faster. - Desktop apps (see **Desktop apps** under Assessment B) are the one exception to parallel: both sub-agents would drive the app's single window at once. Seed the window, spawn A, wait until it has finished and put the window back, then spawn B. They are still two isolated sub-agents, so this is not the degraded path. - "Unavailable" means exactly one thing: no sub-agent/Task tool is exposed in this session (or, on harnesses that ask, the user declined). It does not mean inconvenient. -- If and only if sub-agents are unavailable, fall back sequentially: finish and record Assessment A, then run Assessment B, then synthesize, and emit the degraded banner. +- If and only if sub-agents are unavailable, fall back sequentially: read [critique-rubric.md](critique-rubric.md) now, finish and record Assessment A, then run Assessment B, then synthesize, and emit the degraded banner. - Whichever path you take, declare it in the report header (see Report header provenance). Skipping sub-agents without the banner is the most common failure of this command. If browser automation is available, each assessment creates its own new tab. Never reuse an existing tab, even if it is already at the right URL. Desktop apps are the exception (see **Desktop apps** under Assessment B). @@ -50,9 +50,13 @@ Read relevant source files and visually inspect the live page when browser autom Evaluate: - **Design specificity**: Is the composition, interaction, and visual language grounded in this product, or could an unrelated product use it unchanged? Make this judgment before seeing detector output. - **Holistic design**: hierarchy, IA, emotional fit, discoverability, composition, typography, color, accessibility, states, copy, and edge cases. -- **Cognitive load**: consult the [Cognitive Load Assessment](#cognitive-load-assessment) section below; report checklist failures and decision points with >4 visible options. +- **Cognitive load**: consult the Cognitive Load Assessment in [critique-rubric.md](critique-rubric.md); report checklist failures and decision points with >4 visible options. - **Emotional journey**: peak-end rule, emotional valleys, reassurance at high-stakes moments. -- **Nielsen heuristics**: consult the [Heuristics Scoring Guide](#heuristics-scoring-guide) section below; score all 10 heuristics 0-4, marking any heuristic the mode-applicability rule allows as `n/a` instead of forcing a number. +- **Nielsen heuristics**: consult the Heuristics Scoring Guide in [critique-rubric.md](critique-rubric.md); score all 10 heuristics 0-4, marking any heuristic the mode-applicability rule allows as `n/a` instead of forcing a number. + +- **Persona red flags**: select personas with the Selecting Personas table in [critique-rubric.md](critique-rubric.md), plus 1-2 project-specific ones from PRODUCT.md's `## Users` when it has one, and walk each through the primary action. + +Read critique-rubric.md as part of Assessment A. When a sub-agent runs A, give it the file's path so it reads the rubric itself, and the parent does not load it. When A runs in this context (native critiques, or the single-context fallback), read the rubric here before scoring. Return: design-specificity verdict, heuristic scores, cognitive load, emotional journey, 2-3 strengths, 3-5 priority issues, persona red flags, minor observations, and provocative questions. @@ -108,7 +112,7 @@ The report's first line MUST declare how the assessments were run, so a degraded - Native: `Method: design review only (detector not applicable, native platform)` #### Design Health Score -> *Consult the [Heuristics Scoring Guide](#heuristics-scoring-guide) section below.* +> *Use Assessment A's scores; the bands are under [Scoring the report](#scoring-the-report) below.* Present the Nielsen's 10 heuristics scores as a table: @@ -158,9 +162,9 @@ For each issue, tag with **P0-P3 severity** (see [Issue Severity below](#issue-s - **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset) #### Persona Red Flags -> *Consult the [Personas reference](#persona-based-design-testing) below.* +> *Use Assessment A's persona red flags; it selected the personas from [critique-rubric.md](critique-rubric.md).* -Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `impeccable init`, also generate 1-2 project-specific personas from the audience/brand info. +Assessment A selected 2-3 personas most relevant to this interface type (the selection table in critique-rubric.md). If PRODUCT.md has a `## Users` section, also generate 1-2 project-specific personas from it and from `## Brand Commitments`. For each selected persona, walk through the primary user action and list specific red flags found: @@ -210,7 +214,7 @@ Skip this step if the Setup slug was null (vague or root-level target). IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ "/scripts/impeccable" critique-storage write "" ``` - `max_score` is the applicable maximum from the heuristic table (40 when every heuristic applied), so a later run can tell a renormalized total from a full one. For a local file target, the helper also records an exact content fingerprint so polish can distinguish the assessed bytes from later edits without relying on Git state or timestamps. The helper prints the absolute path it wrote. Leave that file on disk. Polish closes it; this run does not. + `max_score` is the applicable maximum from the heuristic table (40 when every heuristic applied), so a later run can tell a renormalized total from a full one. For a local file target, the helper also records an exact content fingerprint so polish can distinguish the assessed bytes from later edits without relying on Git state or timestamps. The helper prints the absolute path it wrote. Leave that file on disk. Polish closes it; this run does not. `REPORTS OFF:` instead means the project opted out of saved reports: skip the trend read and carry on. 3. **Delete the temp body file** after the write attempt completes, whether the write succeeded or failed. If deletion fails, mention `temp-file cleanup failed: ` briefly in the final output, but do not block the critique. @@ -289,324 +293,9 @@ After presenting the summary, tell the user: ## Reference Material -The sections below were previously separate reference files (`cognitive-load.md`, `heuristics-scoring.md`, `personas.md`). They live inline now so the critique flow has all its deep context in one place. - -### Cognitive Load Assessment - -Cognitive load is the total mental effort required to use an interface. Overloaded users make mistakes, get frustrated, and leave. This reference helps identify and fix cognitive overload. - ---- - -#### Three Types of Cognitive Load +Assessment A scores against [critique-rubric.md](critique-rubric.md): the cognitive load checklist, the heuristic scoring guide, and the personas. The report uses the bands and severities below. -##### Intrinsic Load: The Task Itself -Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. - -**Manage it by**: -- Breaking complex tasks into discrete steps -- Providing scaffolding (templates, defaults, examples) -- Progressive disclosure: show what's needed now, hide the rest -- Grouping related decisions together - -##### Extraneous Load: Bad Design -Mental effort caused by poor design choices. **Eliminate this ruthlessly.** It's pure waste. - -**Common sources**: -- Confusing navigation that requires mental mapping -- Unclear labels that force users to guess meaning -- Visual clutter competing for attention -- Inconsistent patterns that prevent learning -- Unnecessary steps between user intent and result - -##### Germane Load: Learning Effort -Mental effort spent building understanding. This is *good* cognitive load; it leads to mastery. - -**Support it by**: -- Progressive disclosure that reveals complexity gradually -- Consistent patterns that reward learning -- Feedback that confirms correct understanding -- Onboarding that teaches through action, not walls of text - ---- - -#### Cognitive Load Checklist - -Evaluate the interface against these 8 items: - -- [ ] **Single focus**: Can the user complete their primary task without distraction from competing elements? -- [ ] **Chunking**: Is information presented in digestible groups (≤4 items per group)? -- [ ] **Grouping**: Are related items visually grouped together (proximity, borders, shared background)? -- [ ] **Visual hierarchy**: Is it immediately clear what's most important on the screen? -- [ ] **One thing at a time**: Can the user focus on a single decision before moving to the next? -- [ ] **Minimal choices**: Are decisions simplified (≤4 visible options at any decision point)? -- [ ] **Working memory**: Does the user need to remember information from a previous screen to act on the current one? -- [ ] **Progressive disclosure**: Is complexity revealed only when the user needs it? - -**Scoring**: Count the failed items. 0–1 failures = low cognitive load (good). 2–3 = moderate (address soon). 4+ = high cognitive load (critical fix needed). - ---- - -#### The Working Memory Rule - -**Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). - -At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: -- **≤4 items**: Within working memory limits, manageable -- **5–7 items**: Pushing the boundary; consider grouping or progressive disclosure -- **8+ items**: Overloaded; users will skip, misclick, or abandon - -**Practical applications**: -- Action buttons: 1 primary, 1–2 secondary, group the rest in a menu -- Navigation menus: ≤5 top-level items (group the rest under clear categories) -- Long-form articles: one reading path; gather related links into a single block at the end instead of scattering them mid-flow -- Documentation sidebars: ≤4 sibling choices visible per level before grouping kicks in -- Portfolio and gallery indexes: one decision per screen (which piece to open), not filter, sort, and tag controls all at once - ---- - -#### Common Cognitive Load Violations - -##### 1. The Wall of Options -**Problem**: Presenting 10+ choices at once with no hierarchy. -**Fix**: Group into categories, highlight recommended, use progressive disclosure. - -##### 2. The Memory Bridge -**Problem**: User must remember info from step 1 to complete step 3. -**Fix**: Keep relevant context visible, or repeat it where it's needed. - -##### 3. The Hidden Navigation -**Problem**: User must build a mental map of where things are. -**Fix**: Always show current location (breadcrumbs, active states, progress indicators). - -##### 4. The Jargon Barrier -**Problem**: Technical or domain language forces translation effort. -**Fix**: Use plain language. If domain terms are unavoidable, define them inline. - -##### 5. The Visual Noise Floor -**Problem**: Every element has the same visual weight; nothing stands out. -**Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. - -##### 6. The Inconsistent Pattern -**Problem**: Similar actions work differently in different places. -**Fix**: Standardize interaction patterns. Same type of action = same type of UI. - -##### 7. The Multi-Task Demand -**Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). -**Fix**: Sequence the steps. Let the user do one thing at a time. - -##### 8. The Context Switch -**Problem**: User must jump between screens/tabs/modals to gather info for a single decision. -**Fix**: Co-locate the information needed for each decision. Reduce back-and-forth. - ---- - -### Heuristics Scoring Guide - -Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest: a 4 means genuinely excellent, not "good enough." - -#### Nielsen's 10 Heuristics - -##### 1. Visibility of System Status - -Keep users informed about what's happening through timely, appropriate feedback. - -**Check for**: -- Loading indicators during async operations -- Confirmation of user actions (save, submit, delete) -- Progress indicators for multi-step processes -- Current location in navigation (breadcrumbs, active states) -- Form validation feedback (inline, not just on submit) - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | No feedback; user is guessing what happened | -| 1 | Rare feedback; most actions produce no visible response | -| 2 | Partial; some states communicated, major gaps remain | -| 3 | Good; most operations give clear feedback, minor gaps | -| 4 | Excellent; every action confirms, progress is always visible | - -##### 2. Match Between System and Real World - -Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. - -**Check for**: -- Familiar terminology (no unexplained jargon) -- Logical information order matching user expectations -- Recognizable icons and metaphors -- Domain-appropriate language for the target audience -- Natural reading flow (left-to-right, top-to-bottom priority) - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Pure tech jargon, alien to users | -| 1 | Mostly confusing; requires domain expertise to navigate | -| 2 | Mixed; some plain language, some jargon leaks through | -| 3 | Mostly natural; occasional term needs context | -| 4 | Speaks the user's language fluently throughout | - -##### 3. User Control and Freedom - -Users need a clear "emergency exit" from unwanted states without extended dialogue. - -**Check for**: -- Undo/redo functionality -- Cancel buttons on forms and modals -- Clear navigation back to safety (home, previous) -- Easy way to clear filters, search, selections -- Escape from long or multi-step processes - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Users get trapped; no way out without refreshing | -| 1 | Difficult exits; must find obscure paths to escape | -| 2 | Some exits; main flows have escape, edge cases don't | -| 3 | Good control; users can exit and undo most actions | -| 4 | Full control; undo, cancel, back, and escape everywhere | - -##### 4. Consistency and Standards - -Users shouldn't wonder whether different words, situations, or actions mean the same thing. - -**Check for**: -- Consistent terminology throughout the interface -- Same actions produce same results everywhere -- Platform conventions followed (standard UI patterns) -- Visual consistency (colors, typography, spacing, components) -- Consistent interaction patterns (same gesture = same behavior) - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Inconsistent everywhere; feels like different products stitched together | -| 1 | Many inconsistencies; similar things look/behave differently | -| 2 | Partially consistent; main flows match, details diverge | -| 3 | Mostly consistent; occasional deviation, nothing confusing | -| 4 | Fully consistent; cohesive system, predictable behavior | - -##### 5. Error Prevention - -Better than good error messages is a design that prevents problems in the first place. - -**Check for**: -- Confirmation before destructive actions (delete, overwrite) -- Constraints preventing invalid input (date pickers, dropdowns) -- Smart defaults that reduce errors -- Clear labels that prevent misunderstanding -- Autosave and draft recovery - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Errors easy to make; no guardrails anywhere | -| 1 | Few safeguards; some inputs validated, most aren't | -| 2 | Partial prevention; common errors caught, edge cases slip | -| 3 | Good prevention; most error paths blocked proactively | -| 4 | Excellent; errors nearly impossible through smart constraints | - -##### 6. Recognition Rather Than Recall - -Minimize memory load. Make objects, actions, and options visible or easily retrievable. - -**Check for**: -- Visible options (not buried in hidden menus) -- Contextual help when needed (tooltips, inline hints) -- Recent items and history -- Autocomplete and suggestions -- Labels on icons (not icon-only navigation) - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Heavy memorization; users must remember paths and commands | -| 1 | Mostly recall; many hidden features, few visible cues | -| 2 | Some aids; main actions visible, secondary features hidden | -| 3 | Good recognition; most things discoverable, few memory demands | -| 4 | Everything discoverable; users never need to memorize | - -##### 7. Flexibility and Efficiency of Use - -Accelerators, invisible to novices, speed up expert interaction. - -**Check for**: -- Keyboard shortcuts for common actions -- Customizable interface elements -- Recent items and favorites -- Bulk/batch actions -- Power user features that don't complicate the basics - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | One rigid path; no shortcuts or alternatives | -| 1 | Limited flexibility; few alternatives to the main path | -| 2 | Some shortcuts; basic keyboard support, limited bulk actions | -| 3 | Good accelerators; keyboard nav, some customization | -| 4 | Highly flexible; multiple paths, power features, customizable | - -##### 8. Aesthetic and Minimalist Design - -Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. - -**Check for**: -- Only necessary information visible at each step -- Clear visual hierarchy directing attention -- Purposeful use of color and emphasis -- No decorative clutter competing for attention -- Focused, uncluttered layouts - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Overwhelming; everything competes for attention equally | -| 1 | Cluttered; too much noise, hard to find what matters | -| 2 | Some clutter; main content clear, periphery noisy | -| 3 | Mostly clean; focused design, minor visual noise | -| 4 | Perfectly minimal; every element earns its pixel | - -##### 9. Help Users Recognize, Diagnose, and Recover from Errors - -Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. - -**Check for**: -- Plain language error messages (no error codes for users) -- Specific problem identification ("Email is missing @" not "Invalid input") -- Actionable recovery suggestions -- Errors displayed near the source of the problem -- Non-blocking error handling (don't wipe the form) - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | Cryptic errors; codes, jargon, or no message at all | -| 1 | Vague errors; "Something went wrong" with no guidance | -| 2 | Clear but unhelpful; names the problem but not the fix | -| 3 | Clear with suggestions; identifies problem and offers next steps | -| 4 | Perfect recovery; pinpoints issue, suggests fix, preserves user work | - -##### 10. Help and Documentation - -Even if the system is usable without docs, help should be easy to find, task-focused, and concise. - -**Check for**: -- Searchable help or documentation -- Contextual help (tooltips, inline hints, guided tours) -- Task-focused organization (not feature-organized) -- Concise, scannable content -- Easy access without leaving current context - -**Scoring**: -| Score | Criteria | -|-------|----------| -| 0 | No help available anywhere | -| 1 | Help exists but hard to find or irrelevant | -| 2 | Basic help; FAQ or docs exist, not contextual | -| 3 | Good documentation; searchable, mostly task-focused | -| 4 | Excellent contextual help; right info at the right moment | - ---- +### Scoring the report #### Score Summary @@ -636,184 +325,3 @@ Tag each individual issue found during scoring with a priority level: | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | **Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1. - ---- - -### Persona-Based Design Testing - -Test the interface through the eyes of 5 distinct user archetypes. Each persona exposes different failure modes that a single "design director" perspective would miss. - -**How to use**: Select 2–3 personas most relevant to the interface being critiqued. Walk through the primary user action as each persona. Report specific red flags, not generic concerns. - ---- - -#### 1. Impatient Power User: "Alex" - -**Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. - -**Behaviors**: -- Skips all onboarding and instructions -- Looks for keyboard shortcuts immediately -- Tries to bulk-select, batch-edit, and automate -- Gets frustrated by required steps that feel unnecessary -- Abandons if anything feels slow or patronizing - -**Test Questions**: -- Can Alex complete the core task in under 60 seconds? -- Are there keyboard shortcuts for common actions? -- Can onboarding be skipped entirely? -- Do modals have keyboard dismiss (Esc)? -- Is there a "power user" path (shortcuts, bulk actions)? - -**Red Flags** (report these specifically): -- Forced tutorials or unskippable onboarding -- No keyboard navigation for primary actions -- Slow animations that can't be skipped -- One-item-at-a-time workflows where batch would be natural -- Redundant confirmation steps for low-risk actions - ---- - -#### 2. Confused First-Timer: "Jordan" - -**Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. - -**Behaviors**: -- Reads all instructions carefully -- Hesitates before clicking anything unfamiliar -- Looks for help or support constantly -- Misunderstands jargon and abbreviations -- Takes the most literal interpretation of any label - -**Test Questions**: -- Is the first action obviously clear within 5 seconds? -- Are all icons labeled with text? -- Is there contextual help at decision points? -- Does terminology assume prior knowledge? -- Is there a clear "back" or "undo" at every step? - -**Red Flags** (report these specifically): -- Icon-only navigation with no labels -- Technical jargon without explanation -- No visible help option or guidance -- Ambiguous next steps after completing an action -- No confirmation that an action succeeded - ---- - -#### 3. Accessibility-Dependent User: "Sam" - -**Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. - -**Behaviors**: -- Tabs through the interface linearly -- Relies on ARIA labels and heading structure -- Cannot see hover states or visual-only indicators -- Needs adequate color contrast (4.5:1 minimum) -- May use browser zoom up to 200% - -**Test Questions**: -- Can the entire primary flow be completed keyboard-only? -- Are all interactive elements focusable with visible focus indicators? -- Do images have meaningful alt text? -- Is color contrast WCAG AA compliant (4.5:1 for text)? -- Does the screen reader announce state changes (loading, success, errors)? - -**Red Flags** (report these specifically): -- Click-only interactions with no keyboard alternative -- Missing or invisible focus indicators -- Meaning conveyed by color alone (red = error, green = success) -- Unlabeled form fields or buttons -- Time-limited actions without extension option -- Custom components that break screen reader flow - ---- - -#### 4. Deliberate Stress Tester: "Riley" - -**Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. - -**Behaviors**: -- Tests edge cases intentionally (empty states, long strings, special characters) -- Submits forms with unexpected data (emoji, RTL text, very long values) -- Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs -- Looks for inconsistencies between what the UI promises and what actually happens -- Documents problems methodically - -**Test Questions**: -- What happens at the edges (0 items, 1000 items, very long text)? -- Do error states recover gracefully or leave the UI in a broken state? -- What happens on refresh mid-workflow? Is state preserved? -- Are there features that appear to work but produce broken results? -- How does the UI handle unexpected input (emoji, special chars, paste from Excel)? - -**Red Flags** (report these specifically): -- Features that appear to work but silently fail or produce wrong results -- Error handling that exposes technical details or leaves UI in a broken state -- Empty states that show nothing useful ("No results" with no guidance) -- Workflows that lose user data on refresh or navigation -- Inconsistent behavior between similar interactions in different parts of the UI - ---- - -#### 5. Distracted Mobile User: "Casey" - -**Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. - -**Behaviors**: -- Uses thumb only; prefers bottom-of-screen actions -- Gets interrupted mid-flow and returns later -- Switches between apps frequently -- Has limited attention span and low patience -- Types as little as possible, prefers taps and selections - -**Test Questions**: -- Are primary actions in the thumb zone (bottom half of screen)? -- Is state preserved if the user leaves and returns? -- Does it work on slow connections (3G)? -- Can forms use autocomplete and smart defaults? -- Are touch targets at least 44×44pt? - -**Red Flags** (report these specifically): -- Important actions positioned at the top of the screen (unreachable by thumb) -- No state persistence; progress lost on tab switch or interruption -- Large text inputs required where selection would work -- Heavy assets loading on every page (no lazy loading) -- Tiny tap targets or targets too close together - ---- - -#### Selecting Personas - -Choose personas based on the interface type: - -| Interface Type | Primary Personas | Why | -|---------------|-----------------|-----| -| Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | -| Dashboard / admin | Alex, Sam | Power users, accessibility | -| E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | -| Onboarding flow | Jordan, Casey | Confusion, interruption | -| Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | -| Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | - ---- - -#### Project-Specific Personas - -If `CLAUDE.md` contains a `## Design Context` section (generated by `impeccable init`), derive 1–2 additional personas from the audience and brand information: - -1. Read the target audience description -2. Identify the primary user archetype not covered by the 5 predefined personas -3. Create a persona following this template: - -``` -##### [Role]: "[Name]" - -**Profile**: [2-3 key characteristics derived from Design Context] - -**Behaviors**: [3-4 specific behaviors based on the described audience] - -**Red Flags**: [3-4 things that would alienate this specific user type] -``` - -Only generate project-specific personas when real Design Context data is available. Don't invent audience details; use the 5 predefined personas when no context exists. diff --git a/.claude/skills/impeccable/reference/degraded/documenter.md b/.claude/skills/impeccable/reference/degraded/documenter.md index d1640cc0..2090bd8b 100644 --- a/.claude/skills/impeccable/reference/degraded/documenter.md +++ b/.claude/skills/impeccable/reference/degraded/documenter.md @@ -9,7 +9,7 @@ Complete the check within your turn ceiling. Batch Reads, take `reference/docume ## Input Contract -Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; the boundary to write at (project or app root); and, when a DESIGN.md already exists there, the user's choice for it (refresh, overwrite, or merge), the answer `reference/document.md` requires before any rewrite, which the parent collects. A merge preserves confirmed incumbent decisions and reconciles them with the build. +Expect: the project root; the artifact path(s); the direction contract text (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM); PRODUCT.md path; the path to the skill's `reference/document.md`; the boundary to write at (project or app root); and, when a DESIGN.md already exists there, the user's choice for it (refresh, overwrite, or merge), the answer `reference/document.md` requires before any rewrite, which the parent collects. On a seeded world's first build the parent passes refresh without asking; that counts as the choice. A merge preserves confirmed incumbent decisions and reconciles them with the build. ## Workflow diff --git a/.claude/skills/impeccable/reference/degraded/finish-reviewer.md b/.claude/skills/impeccable/reference/degraded/finish-reviewer.md index b5023c11..b2cc1cce 100644 --- a/.claude/skills/impeccable/reference/degraded/finish-reviewer.md +++ b/.claude/skills/impeccable/reference/degraded/finish-reviewer.md @@ -19,7 +19,7 @@ Expect: the original request; the confirmed user answers; the artifact path(s); 1. **Persistence.** PRODUCT.md exists. On a comp-led build, `.impeccable/build/state.json` exists and every phase before `review` is `closed` or explicitly `skipped`; an open or failed phase is a material finding. A comp-led config with no state file, or a state whose `comps` phase is neither `closed` nor `skipped`, means the comp round was skipped and the build ran from a world description alone, a material finding that outranks craft; a phase closed with a `forced` record is disclosed as a material finding unless the user downgraded the comp in words the packet quotes; a state file whose `hero.gate.score` sits under 0.72, or a missing state file, means the reproduction ran unproven, a material finding, and `.impeccable/review/hero-repro.png` must exist either way. When DESIGN.md predates this build (an extension or redesign), it matches the built world; on a new world it is written after this review by the documenter, so its absence here is not a finding. When comp-round comps exist under `.impeccable/mocks/`, an approval record exists too: the surface brief naming the approved comp, or an `approved` flag in its sidecar. Comp-round comps with no recorded pick mean the approval point was skipped, a material finding. Files under `.impeccable/mocks/decision/` are exempt: they are the direction round's dealt hand, produced before any comp round, and imply no approval whatever the build path; a code-led build has no comp round at all. 2. **Fidelity.** Start from the measurement, then judge what it cannot: read `.impeccable/review/diff/final/report.json` (and hero) first; every region scored `missing` or `contradicted` is a matrix row in that state unless the paired crop under `regions/` shows the score is wrong, and you say why; a region scored `match` still gets your eye for lettering character and material, which the numbers do not measure. Then, against your own element inventory of the approved comp, never against the contract's summary of it: topology, reading order, focal scale, overlaps and z-order, density, signature geometry, the primary action's treatment (a CTA the comp physically works, dissolves, or stamps is a signature element; its plain-rectangle rendition is contradicted), navigation items and icons, headline levels and scale relationships. Classify every salient element: match, acceptable adaptation, missing, contradicted, or added without approval. Three rows are mandatory in every matrix. TYPE: the display lettering's character, compression, width, weight, contrast, terminals, against the comp's; a face of a different character is contradicted however the layout matches. MATERIAL: an element rendered as flat CSS or clean vector where the comp shows painted, textured, dimensional, or photographic material is contradicted regardless of placement; medium is part of the promise. GROUND: the page field's value and temperature against the comp's, sampled from pixels on both sides when tooling allows rather than judged from memory, and read as the net on-screen result where a texture or tile paints over the base color; a ground warmer or cooler than the comp's is contradicted however faithfully the layout matches, and drift toward the rendition prior (warm cream on light grounds, blue-black slate on dark) is the direction to hunt. With no approved comp, TYPE and MATERIAL do not lapse: judge them against the contract's OWN-WORLD and the world's real materials, and treat faked physicality (CSS bevels, embossing, stamped-metal or chalk effects imitating a material the page never renders) as contradicted on its face; imitation material is the single most reliable mark of machine-made design. GROUND narrows rather than lapses: with no comp to sample, a color OWN-WORLD names is the target and the same warmer-or-cooler judgment applies; when OWN-WORLD names none, there is no GROUND authority, and the review says so in place of a verdict, because a target the reviewer invents turns the check into taste. A critique-reference comp on such a build is provocation, not spec: no element matrix, no adaptation citations, no asset obligations; its one contribution is what the image dared that the build did not, and dares worth adopting enter material_fixes as ordinary ordered fixes. An adaptation counts as intentional only when it cites the user answer, surface brief, accessibility need, or product truth that forced it; an uncited deviation is a defect. A missing signature element, a changed topology, or content added without approval fails fidelity and outranks every craft point in material_fixes. When MATERIAL is contradicted on the focal element, or contradiction is the page rather than the exception, stop ordering repairs: make the first material fix a rebuild directive naming the comp regions to re-derive and the assets to produce; a list of patches against a rejected page launders the rejection into an approval. A fix that requires producing an asset says so explicitly ("produce: as a raster asset"), never phrased as a style adjustment the parent will answer with CSS. The comp is the spec for composition, topology, element inventory, density, lettering character, and material; it is not a pixel spec for semantics, accessibility, or responsive reflow, and that allowance covers translation, never replacement. 3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition. -4. **Contract, promise by promise.** First verify FORM carries the seed reference the concept roll printed (`seed:` and 16 hex), corroborated against the roll output the parent saw or with `impeccable concept-seed --check-seed ` (exit 0 means this machine rolled it). A raw seed key in FORM is itself a material fix: the brief is committed, and the key must not be. `seed: none (unavailable)` stands only when the roll printed SEED REFERENCE unavailable, which `--check-seed none` confirms with exit 0. Any other contract with no reference, or one neither source corroborates, means the roll was skipped, a material fix ahead of any craft point. Then, for each of the five blocks: does the render keep the promise? Apply the memory test to the first viewport. +4. **Contract, promise by promise.** First verify FORM carries the seed reference the concept roll printed (`seed:` and 16 hex), corroborated against the roll output the parent saw or with `impeccable concept-seed --check-seed ` (exit 0 means this machine rolled it). A raw seed key in FORM is itself a material fix: the brief is committed, and the key must not be. `seed: none (unavailable)` stands only when the roll printed SEED REFERENCE unavailable, which `--check-seed none` confirms with exit 0. `seed: none (pinned)` stands only when the original request or the confirmed user answers pin both the direction's world and its first-surface experience, in the words FORM quotes; never judge it with `--check-seed`, which cannot see a pin and reports `none` as a skipped roll. A picture or metaphor alone pins neither. Any other contract with no reference, or one neither source corroborates, means the roll was skipped, a material fix ahead of any craft point. Then, for each of the five blocks: does the render keep the promise? Apply the memory test to the first viewport. 5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every raster region of the spec shipped as its plate (the spec names the file; the page references it; the region's diff row is not `missing`), not a gradient, an inline SVG, or a many-vertex `clip-path` standing in for it, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind a wash is a compliance token, not a shipped material, and the detector's `buried-raster` and `organic-clip-path` findings in the packet are material fixes. 6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp: the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and on those harnesses a banned element you miss ships. @@ -27,7 +27,7 @@ Do not run a second detector pass; mechanical findings belong to the parent's ho ## Disposition -The first line of your return is `disposition: recapture`, `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. These four words are the whole vocabulary; never invent another. The word is derived, never felt: recapture when the evidence check failed, rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it. +The first line of your return is `disposition: recapture`, `disposition: rebuild`, `disposition: fix`, or `disposition: ship`. These four words are the whole vocabulary; never invent another. The word is derived, never felt: recapture when the evidence check failed, rebuild when the rebuild-directive condition fired, fix when material_fixes is non-empty, ship only when material_fixes is empty and the matrix holds no contradicted or missing row. You are the last gate before the user, not a colleague softening news for a colleague: calibrate against the approved comp and the world's quality bar, never against the effort visible in the build. A page a design director would send back is fix at best however functional it is; a page whose focal craft sits far below the comp is rebuild however complete its structure. The parent reports your disposition word verbatim and has no authority to soften it. ## Output Contract diff --git a/.claude/skills/impeccable/reference/degraded/motion-reviewer.md b/.claude/skills/impeccable/reference/degraded/motion-reviewer.md new file mode 100644 index 00000000..422b5c0b --- /dev/null +++ b/.claude/skills/impeccable/reference/degraded/motion-reviewer.md @@ -0,0 +1,29 @@ + +This harness has no subagent capability, so you are running this role inline. Step fully out of the work you just finished, adopt only this file's instructions for the pass, and disclose the substitution in one line of your closing message to the user, outside the output contract. Where the text below addresses a parent agent, you are both parties: produce the full output contract first, then act on it yourself. + +# Impeccable Motion Reviewer + +You are fresh eyes on implemented motion. Edit nothing; the parent applies your fixes. You have no browser: never render, screenshot, serve, or open a page, and use Bash only to inspect the provided evidence files, never to run page code or captures. + +Read the normal and reduced-motion filmstrips and boundary frames first, then their reports, the motion thesis, and the supplied rules. Batch reads. Stop reading by roughly the tenth turn and write the complete output contract; name unread or missing inputs without pretending to have checked them. + +## Input Contract + +Expect the original request; the motion thesis from animate's plan (focal moment, continuity, feedback, budget); capture directories for the same interaction in normal and reduced motion under `.impeccable/review/motion/`; DESIGN.md's motion rules if present; and the skill's `reference/craft-floor.md` path. Each directory contains `report.json`, numbered frame PNGs, `filmstrip.png`, and a self-contained `index.html` scrubber. The report names frame paths, phases, times, geometry, animation timing, findings, and measurement limitations; its `setup` lists any steps that reached the starting state, as an exit capture needs. Passed paths are authoritative; never invent filenames. The parent also supplies entrance and exit captures when both exist, and timing/easing/stagger information for effects the engine cannot measure. Missing design rules are not a defect; missing required capture evidence is. + +## Checks, in order + +0. **Evidence.** Both normal and reduced-motion reports must exist, parse, and describe the same interaction and region. Confirm the reduced report says `reducedMotion: true`. Every referenced frame must exist, decode, have consistent dimensions, and show the claimed state. Require before, first, middle, last animated, and settled frames. Blank, half-loaded, wrong-region, stale, missing, or incomplete evidence requires `disposition: recapture`; list exact files and the evidence needed under material_fixes and stop substantive judgment. A partial recording cannot earn ship. Treat report limitations as unmeasured checks; when the provided pixels cannot answer a material check, request evidence rather than assume it passed. +1. **Continuity.** Read every report finding. Each is a material fix unless the frames prove it wrong; cite the counterevidence explicitly when rejecting one. Compare before against first, every middle against its neighbors, and last animated against settled. Inspect the entire region: content replacement during a morph, cross-fade at frame zero, sibling occlusion or stacking changes, clipping, late hover/focus lifts, and interruption artifacts. Explicitly check these five failure shapes and cite their frames: repeated CSS entrances on existing content (`entrance-replay`); old/new opacity sums below 0.95 or above 1.05 across multiple samples, including plus-lighter over an opaque isolated layer (`crossfade-dip`); old-only or new-only content whose animation outlasts surrounding motion (`orphan-linger`); a top item that swaps when transition layers disappear (`end-paint-swap`); and a shadow switched off at the start or on at the end (`start-jump`/`end-jump`, property `box-shadow`). Check shadow and opacity boundaries even when the boxes align. Confirm old/new fades preserve both brightness and legibility; complementary opacity alone does not prove correct compositing. The numbers cannot see all pseudo-element paint, masks, text texture, or attention shifts. A smooth box trajectory alone proves nothing. During View Transitions the underlying new DOM is not the painted frame; judge the captured old/new layers in the PNGs. +2. **Craft.** Judge duration against distance and consequence: 100–150 ms immediate feedback; 150–300 ms routine state change; 300–500 ms layout, overlay, or view transition; 500–800 ms deliberately authored focal entrance. These are context-sensitive ranges, not automatic failures. Exits should be faster than entrances. Arrivals should decelerate naturally; bounce and elastic need a reason. Check one focal moment, quiet supporting motion, and bounded total sibling stagger. Apply the thesis, DESIGN.md rules, and craft floor. Cite frames and report times; do not invent timing the captures do not measure. +3. **Reduced motion.** Compare matching normal/reduced states. Spatial movement should be removed or substantially reduced, while state, feedback, and meaning remain visible. Full-length movement is a fix even if it seems smooth. A shorter duration alone does not prove reduced spatial motion; examine distance and the frame sequence. An opacity or color alternative can preserve meaning without moving the interface. + +## Output Contract + +First line: `disposition: ship|fix|recapture`, with exactly one word selected. Then exactly five sections: `continuity`, `craft`, `reduced_motion`, `material_fixes`, `keep`. Material fixes are ordered by impact and each cites frame paths or indices and times, including both captures where relevant. A recapture lists missing or invalid evidence there and marks the substantive sections unreviewable. Keep names what must survive the fixes. No praise or summary prose. + +Derive the disposition: recapture for invalid or insufficient evidence; fix for any material finding; ship only with valid evidence and no material fixes. Never soften a finding because the implementation took effort. Report limits of the verdict's scope. + +## Verdict Pass + +After a fix batch, re-read the reports and the exact recaptured frame paths. The parent's account of the edits is not evidence. Score each prior material fix resolved, partial, or unresolved, citing the new frames, and name at most three regressions introduced by the batch. Do not start a new hunt. Keep the same disposition-first five-section contract; material_fixes contains the scored list and remaining work. A partial or unresolved fix forbids ship. Invalid recaptures require recapture and a full review on valid evidence, never a scoring pass over broken frames. A ship here covers the scored fixes, not an unbounded whole-surface approval. \ No newline at end of file diff --git a/.claude/skills/impeccable/reference/distill.md b/.claude/skills/impeccable/reference/distill.md index d7c525d9..212a91f0 100644 --- a/.claude/skills/impeccable/reference/distill.md +++ b/.claude/skills/impeccable/reference/distill.md @@ -48,7 +48,7 @@ Systematically remove complexity across these dimensions: - **Remove redundancy**: If it's said elsewhere, don't repeat it here ### Visual Simplification -- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors +- **Reduce color palette**: Keep 1-2 decorative or brand colors plus neutrals, not 5-7; keep semantic colors (success, warning, error) and pair each with a non-color cue - **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights - **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function - **Flatten structure**: Reduce nesting, remove unnecessary containers; never nest cards inside cards diff --git a/.claude/skills/impeccable/reference/document.md b/.claude/skills/impeccable/reference/document.md index 879ba4e8..94c66de7 100644 --- a/.claude/skills/impeccable/reference/document.md +++ b/.claude/skills/impeccable/reference/document.md @@ -68,7 +68,9 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask with the AskUserQuestion tool and wait for the answer before continuing. The choice is refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask with the AskUserQuestion tool and wait for the answer before continuing. The choice is refresh, overwrite, or merge. The one exception is the first build on a seeded world (below): the choice is refresh, with no question. + +A DESIGN.md written by `impeccable world` carries a `world: ""` line in its frontmatter, and its sidecar carries a `seededFrom` object. Both name the catalog world this system grew from, and both survive every choice: copy the `world:` line into the new frontmatter unchanged, and copy `seededFrom` into the regenerated sidecar. This provenance does not forbid an explicit request from the person for a redesign or a different world, which follows the redesign flow in [new-work.md](new-work.md). A world that replaced the seeded one (its direction roll passed `--replace-world`) is the one case where both are dropped, or every later roll settles on the old world again. They are the one frontmatter key and the one sidecar key kept outside the schemas below. ## Two paths diff --git a/.claude/skills/impeccable/reference/foundations.md b/.claude/skills/impeccable/reference/foundations.md new file mode 100644 index 00000000..baa2c12f --- /dev/null +++ b/.claude/skills/impeccable/reference/foundations.md @@ -0,0 +1,44 @@ +# /impeccable foundations + +Walk the user through the product foundations every shipped project needs, and fix one at a time. This is a roadmap, not a design task: do not redesign anything on the way. + +## Without an argument: the roadmap + +Run: + +``` +"/scripts/impeccable" foundations +``` + +It checks the project's own files (and runs the design detector) offline and prints a count, the **Next up** item with why it matters, and every other item: `✓` in place, `✗` to fix, `·` not checked (it needs the network, or the project gives no evidence either way). Pass a path for one app in a monorepo. + +Relay the count and the Next up item in two or three sentences, then offer to fix that item now. List the other `✗` items in one line by name. Do not explain the `·` items unless asked. If it prints `Nothing to check yet`, say so and stop. If the next item is `secrets-out-of-repo`, the output names the file and line of each key: never print, copy or quote the key itself. + +## With an id: fix that one item + +`/impeccable foundations ` fixes one item. Read what "done" means for that id below, look at the project to find the smallest change that gets there, make it in the project's own stack and conventions, then re-run `"/scripts/impeccable" foundations --json` and confirm `items[""]` is `"checked"`. If it is, say so in one short line and name the new Next up. If it is still `"failing"`, say what the check still misses and fix that; do not game the check with an empty file or a stub that does nothing. If the id is absent from `items` (the CLI can't judge it here: `real-packages`, `current-dependencies`, or contrast in an app whose components only the regex engine reads), verify the definition below yourself, say what you checked, and don't claim the CLI confirmed it. + +Ask before anything that needs the user: an account (Sentry, a host), a key, legal wording, or a product decision. Write placeholders they must fill in only when they agree, and say exactly which lines. + +## What "done" means + +Web items (`app-icons`, `not-found-page`, `social-previews`, `legal-pages`, `error-tracking`) need a web UI. Server frameworks need markup templates or served markup pages; an API-only server sends none of them. Rails with `config.api_only = true` is never web. + +- **secrets-out-of-repo**: no tracked file holds a private key or a key in a known format. Public Firebase client config does not count as a Google-key leak; other key formats in that file still count. Tracked env files fail on real values under `_`-separated secret name segments (KEY, SECRET, TOKEN, PASSWORD, PASSWD, PWD, CREDENTIAL, PRIVATE), or URLs with passwords. Public-prefixed names, variable references and obvious placeholders do not count. A DSN or URL without a password is not secret evidence. Example/sample/template env files do not count as tracked env leaks. Move real secrets to an untracked env file or the host's secret store. Rotate any exposed credential; deleting it does not remove it from history. Never repeat its value. +- **readable-contrast**: the detector finds no low-contrast text in the full scan. Run `"/scripts/impeccable" detect --json .`, fix each `low-contrast` finding at its token or style, and prefer darkening a shared token over one-off overrides. A pass is sent only when every page's styles are in the files scanned: a page that runs a script, or takes a stylesheet from another host (linked or `@import`ed), sends nothing, and so does a project too large to walk in full. +- **no-generic-ai-patterns**: the detector finds none of its generic-AI pattern rules. Fix the findings from `"/scripts/impeccable" detect --json .` in the project's own design language; PRODUCT.md and DESIGN.md say what that is. +- **not-found-page**: the framework's own not-found page exists: Next `app/not-found.tsx` (or `pages/404`), SvelteKit `src/routes/+error.svelte`, Nuxt `error.vue`, Astro or Gatsby `src/pages/404`, Remix or React Router an `ErrorBoundary` in `app/root` or a `$.tsx` splat route, a client-routed SPA a catch-all `path="*"` route, a static or Hugo or Jekyll site a `404.html`. It says what happened and links home, in the product's voice. +- **app-icons**: a favicon and a large app icon, as image files in the public folders (including `public/icons/`, `static/icons/`, `public/images/`), or local images linked by `rel="icon"`, `rel="apple-touch-icon"` or a web manifest. Source components do not count. Ask for the logo if there is none; never invent a brand mark. +- **social-previews**: a share image in `og:image`, `twitter:image`, framework metadata (including Nuxt `ogImage` and Next `generateMetadata` with `openGraph.images`), or an `opengraph-image` file. `twitter:card` alone and comments do not count. Aim for 1200×630. +- **legal-pages**: a privacy page and a terms page, as routes or files named `privacy` and `terms` (or `tos`), linked from the footer. Draft them only if the user asks, mark them as drafts for their review, and never present generated text as legal advice. +- **readme-runs**: notes-only repos send nothing. Otherwise, install and run commands for this project appear in README code blocks or code spans, and every named package script exists. Scaffolding commands such as `npx create-next-app` do not count. +- **ci-runs-tests**: a CI command runs tests on pushes or pull requests. Common package managers and test runners count; comments do not. Notes-only repos send nothing. Missing CI, checkout/setup alone, or only recognised non-test commands (install, build, lint, format, typecheck, deploy, echo) fails. An unclassified command sends nothing. +- **design-tokens**: a project colour custom property is defined and used through `var()`, or there is a recognised tokens file or theme source. Unused definitions and third-party variables do not count. HTML entities are not hex colours. +- **reduced-motion**: motion has a real reduced-motion guard. CSS animation, transitions, Web Animations, Svelte directives, Motion components and Tailwind `animate-*` count as motion; commented guards do not. +- **real-packages**: not checked by the CLI (needs the network). Confirm each dependency exists on its registry and is the package you meant. +- **dependency-scanning**: Dependabot (`.github/dependabot.yml`) or Renovate is configured for the project's package managers. +- **error-tracking**: an error-tracking SDK (Sentry, Bugsnag, Rollbar, Honeybadger, Highlight, LogRocket, Datadog RUM) is a dependency and initialised at the app's entry. The user creates the account; read the DSN from the environment. +- **reversible-migrations**: every migration has a down step the tool can run: knex, Sequelize, TypeORM or umzug files export `down`, Rails uses `def change` or `def down`, Laravel has `down()`, golang-migrate has a `.down.sql` beside each `.up.sql`, dbmate and goose have a non-empty down section. +- **no-giant-files**: no hand-written source file is over 1,000 lines. Split along the seams the file already has; change no behaviour while doing it. +- **current-dependencies**: not checked by the CLI (needs the network). `npm outdated` or the ecosystem's equivalent shows what is far behind. +- **infrastructure-as-code**: the hosting setup lives in the repo (`wrangler.toml`, `vercel.json`, a `Dockerfile`, Terraform, and the like). A package library without app evidence and a notes-only repo send nothing when hosting config is absent. An Expo app uses `eas.json`, and fails without it; a bare React Native app without one sends nothing. diff --git a/.claude/skills/impeccable/reference/hooks.md b/.claude/skills/impeccable/reference/hooks.md index 0a5b4d8b..49087736 100644 --- a/.claude/skills/impeccable/reference/hooks.md +++ b/.claude/skills/impeccable/reference/hooks.md @@ -2,7 +2,7 @@ Manage the **design detector hook** for the current project. -The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code, Codex, Cursor, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Grok Build fires the same PostToolUse scan to mark touched files, then surfaces findings on Stop `additionalContext`. Do not expect a Grok per-edit reminder: Grok discards that stdout. On Hermes Agent the per-edit findings arrive inside the `write_file` or `patch` tool result itself, as its `impeccable` field. +The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, and plain `.ts` and `.js` in a project with a PRODUCT.md, DESIGN.md or `.impeccable` folder). Claude Code, Codex, Cursor, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Grok Build fires the same PostToolUse scan to mark touched files, then surfaces findings on Stop `additionalContext`. Do not expect a Grok per-edit reminder: Grok discards that stdout. On Hermes Agent the per-edit findings arrive inside the `write_file` or `patch` tool result itself, as its `impeccable` field. The detector rules run in two tiers. The per-edit hook surfaces only the immediate tier: mechanical, unambiguous problems worth interrupting an edit for, such as broken images, overflowing content, contrast and legibility failures, gradient text, glow shadows, and design-system drift. Everything else (copy cadence, palette and typography taste, layout rhythm) is deferred to a deep pass on the `Stop` hook event, which runs the full rule set over every UI file touched in the session and surfaces the remaining findings once, deduplicated against what the per-edit pass already reported. A session with nothing left to report stops silently. Set `hook.perEditRules` to `"all"` in `.impeccable/config.json` to restore the full rule set on every edit. The Stop deep pass is wired for Claude Code, Codex, and Grok Build, which dispatch a native `Stop` hook event, and for Hermes Agent, whose plugin sends it from `pre_verify`. Cursor does not get one (its `stop` hook can only answer with a follow-up user message), and GitHub Copilot's stop-style events do not feed context back to the model, so they keep the full detector per edit. Grok also fires an observe-only Stop with `reason: "shutdown"` after `end_turn`; skip that one, scan only `end_turn`. @@ -14,19 +14,25 @@ Declare server-side template extensions under **`detector.extensions`** when the Manual `"/scripts/impeccable" detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `"/scripts/impeccable" detect --no-config ...` for a raw detector run that ignores project config/context. Use `"/scripts/impeccable" ignores ...` for direct CLI CRUD on the same detector ignores. -Supported harnesses: Claude Code (`.claude/settings.local.json` for a project-scope install; `~/.claude/settings.json` for a user-scope install; a project hook moved into shared `.claude/settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project), Cursor (`.cursor/hooks.json` in the project), Grok Build (`.grok/hooks/impeccable.json` in the project; requires `/hooks-trust` or `--trust`), GitHub Copilot (`.github/hooks/impeccable.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read), and Hermes Agent (the `impeccable-design-hook` plugin in `~/.hermes/plugins/`; the user enables it once with `hermes plugins enable impeccable-design-hook`; a project install's launcher runs only in a project Hermes trusts, via `hermes skills trust`). For the Copilot CLI, repo-level hooks fire once `.github/hooks/impeccable.json` is committed to the repository's default branch. +Supported harnesses: Claude Code (`.claude/settings.local.json` for a project-scope install; `$CLAUDE_CONFIG_DIR/settings.json` for a user-scope install, defaulting to `~/.claude/settings.json`; a project hook moved into shared `.claude/settings.json` is honored in place too), Codex (`.codex/hooks.json` in the project; `$CODEX_HOME/hooks.json`, default `~/.codex/hooks.json`, for a user-scope install), Cursor (`.cursor/hooks.json` in the project; `~/.cursor/hooks.json` for a user-scope install), Grok Build (`.grok/hooks/impeccable.json` in the project, which requires `/hooks-trust` or `--trust`; the personal `~/.grok/hooks/impeccable.json` for a user-scope install), GitHub Copilot (`.github/hooks/impeccable.json` in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read), and Hermes Agent (the `impeccable-design-hook` plugin in `~/.hermes/plugins/`; the user enables it once with `hermes plugins enable impeccable-design-hook`; a project install's launcher runs only in a project Hermes trusts, via `hermes skills trust`). For the Copilot CLI, repo-level hooks fire once `.github/hooks/impeccable.json` is committed to the repository's default branch. On **Cursor**, the hook runs on `postToolUse` for the `Write` tool (every agent file edit) and returns its reminder as `additional_context`, which Cursor adds after the tool result. Projects set up before this ran a `preToolUse` gate (`hook-before-edit`) that blocked bad writes before they landed; that gate still works until `hooks on`, `impeccable update`, or `impeccable doctor --fix` moves the entry to `postToolUse`. Gemini installs session and completion hooks in `.gemini/settings.json`, merged into the settings already there (comments are tolerated; a commented file is backed up to `settings.json.bak` before the rewrite, and a file that is not valid JSON is left alone). It does not install a per-edit detector hook. The `BeforeTool` hook only rewrites shell commands that run `build-phase`, and only on macOS and Linux; on Windows (where Gemini runs hooks through PowerShell) no session id reaches the shell, so a comp build is not tied to the session and the completion reminder stays silent. +When there is no project Claude skill, `hooks on` looks for `skills/impeccable/scripts/impeccable` inside `CLAUDE_CONFIG_DIR` (default `~/.claude`) and writes the hook into that account's `settings.json`, using the installed launcher's absolute path. Relative account directories resolve against the caller's working directory. An explicit account directory is exclusive: another account's default skill and settings are never substituted. Status and context read the same account settings. If no design harness can be wired, `hooks on` says so, reports skipped invalid settings or the missing skill lookup paths, and gives the next step. + +Status checks the current event entries and matchers in each manifest, including the Stop pass where supported. Claude Code counts as wired when either project settings file (or its user settings file) contains the current entries. A legacy command, partial manifest, or missing file is reported as not wired. If enabled in config but no design harness is wired, status says so and gives `impeccable hooks on` as the repair command. An installed and enabled Hermes design-hook plugin also counts as wired; `on` acknowledges it without changing the plugin configuration. Wiring confirms the manifest entries; harness trust requirements and session reloads still apply. + +When `hook.consent` is `"accepted"` in the project's `config.local.json` and the hook is enabled, `impeccable context` restores missing or stale entries for installed harness skills and reports repairs in one line. Shared config consent does not authorize this write. Automatic repair preserves unrelated settings and hooks and leaves malformed manifests alone. Without local consent, context writes no manifests and keeps `MANUAL_DETECTOR_REQUIRED`, naming the missing or stale harness wiring. Explicitly disabled hooks stay disabled. + ## Routing The first argument is the action. Defaults to `status`. | Action | What it does | |---|---| -| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. | +| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override, and actual manifest wiring for each harness. | | `on` | Set `enabled: true` in `.impeccable/config.json`, record local hook consent as accepted, and install/repair provider hook manifests when the skill is installed. | | `off` | Set `enabled: false` in `.impeccable/config.json`. | | `ignore-rule ` | Append `` to `detector.ignoreRules`; for `overused-font`, requires `--all-values`. Suppresses the rule across the whole project. | @@ -46,7 +52,7 @@ The first argument is the action. Defaults to `status`. ``` 3. If `` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/impeccable hooks on`." -4. If `` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write on a UI file." On Hermes Agent, `on` cannot install or enable the plugin: if `impeccable context` reported `MANUAL_DETECTOR_REQUIRED`, tell the user to run `npx impeccable install` and then `hermes plugins enable impeccable-design-hook` instead. +4. If `` is `on`, report what the command installed or repaired. If no installed skill folders were found or settings were skipped, surface that result and do not claim the hook will run. Otherwise note that the harness must load the updated settings (and satisfy any trust requirements) before it runs. On Hermes Agent, `on` cannot install or enable the plugin: if `impeccable context` reported `MANUAL_DETECTOR_REQUIRED`, tell the user to run `npx impeccable install` and then `hermes plugins enable impeccable-design-hook` instead. 5. If `` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/config.json`; add `--local` only when the user explicitly asks for a private exception. 6. If `` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question. @@ -56,7 +62,7 @@ The hook itself never writes ignore config; every exception goes through `impecc - **Real design problem**: fix it. Never add an ignore to skip a fix or to push a blocked write through. - **Confident false positive or sanctioned exception**: persist the narrowest ignore yourself and disclose it in your reply. The bar is evidence you can name: an intentional demo or fixture, documentation of bad design, literal or domain-appropriate motion (a ball that bounces), or a choice the user already confirmed. Put that evidence in `--reason` as `""`; write "user confirmed" only when the user actually did. -- **Unsure**: leave the finding standing and ask the user in one line. Ask once; a one-line question costs less than the hook re-firing on every later edit. +- **Unsure**: leave the finding standing and give the reason in one line. Ask the user only when you genuinely cannot decide. Self-serve stops at `ignore-value`. `ignore-file` and `ignore-rule` silence too much to add on your own judgment; ask the user first. @@ -106,7 +112,7 @@ Example whole-file exception, for a file that is out of scope entirely: - Do not edit the launcher or the binary behind `impeccable hook` and `impeccable hook-before-edit` from this flow. Those are skill plumbing. - When a user asks how far to trust the hook, say it runs the engine unsandboxed with the agent's environment and network access (in the Copilot cloud agent too, once `.github/hooks/impeccable.json` is committed), and that the launcher checks a downloaded engine against `/scripts/engine-checksums.txt` before its first run; **never** call it sandboxed. - The hook never blocks an edit; it emits a post-edit reminder. (A Cursor project still on the old `preToolUse` gate can block a write until its manifest is migrated.) Disabling stops the reminders. -- The hook is bundled with the Impeccable skill. Project installs use `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `.github/hooks/impeccable.json`, and `.gemini/settings.json`; a user-scope Claude install uses `~/.claude/settings.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/impeccable.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly. +- The hook is bundled with the Impeccable skill. Project installs use `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `.github/hooks/impeccable.json`, and `.gemini/settings.json`; a user-scope Claude install uses the active account's `$CLAUDE_CONFIG_DIR/settings.json` (default `~/.claude/settings.json`), and a user-scope Codex, Cursor or Grok install uses `~/.codex/hooks.json`, `~/.cursor/hooks.json` or `~/.grok/hooks/impeccable.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/impeccable.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly. ## Failure modes diff --git a/.claude/skills/impeccable/reference/init.md b/.claude/skills/impeccable/reference/init.md index d1b8f01c..de74bfa5 100644 --- a/.claude/skills/impeccable/reference/init.md +++ b/.claude/skills/impeccable/reference/init.md @@ -121,6 +121,8 @@ Then configure live mode when useful: skip native or non-runnable projects and l Summarize captured and deliberately undecided facts. Do not offer DESIGN.md merely because it is missing. +Tell the user once which files to commit: PRODUCT.md, DESIGN.md, `.impeccable/config.json`, `.impeccable/surfaces/`, `.impeccable/design.json`, `.impeccable/live/config.json`, and `.impeccable/critique/ignore.md`. A blanket `.impeccable/` ignore hides them from teammates and other worktrees. The runtime directories (`questions/`, `mocks/`, `review/`, critique snapshots) ignore themselves, and `.impeccable/config.local.json` stays on the developer's machine. + Recommend the next action from the actual project state: - Empty or early project: ask naturally for the surface to be built, or use `/impeccable shape ` when the user wants a confirmed brief without implementation. New-work will establish a visual world only when the requested work needs one. diff --git a/.claude/skills/impeccable/reference/live-setup.md b/.claude/skills/impeccable/reference/live-setup.md index 816b34ad..2a94b4a9 100644 --- a/.claude/skills/impeccable/reference/live-setup.md +++ b/.claude/skills/impeccable/reference/live-setup.md @@ -68,7 +68,7 @@ Output `{ shape, signals }`; the shape names the *patch mechanism*, so one templ > > It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n] -On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`. +On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`. The helper's port is not known until the first successful boot, so the allowance names 8400, the helper's first choice; if that boot then reports a different `serverPort` (another project's helper held 8400), add that port to the same allowance before picking. ### append-arrays diff --git a/.claude/skills/impeccable/reference/live.md b/.claude/skills/impeccable/reference/live.md index 8483b862..07fa163c 100644 --- a/.claude/skills/impeccable/reference/live.md +++ b/.claude/skills/impeccable/reference/live.md @@ -8,10 +8,10 @@ Live editing requires a local checkout; injection into deployed production sites ## The contract (read once) -Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins. +Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins. One exception: a printed `live-wrap` with an empty `--element-id` and an empty `--classes` follows the bare-element rule in the wrap step instead (drop both, pass `--query`). -1. `impeccable live`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `"/scripts/impeccable" live --target ` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root. -2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once. +1. `impeccable live --allow-missing-context --dev-url --auto-config`: boot (always with all three flags; see Start). If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and add `--target `; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root. +2. Open the page. This is how to find its URL wherever the boot's `_instructions` say to open a `pageFiles` page. `devUrl` is the origin of a running dev server: append the route the request names, or the path that serves the target `pageFiles` entry; a bare `devUrl` is the root page only. When `devUrl` is null the boot says which case this is. `pageUrls` lists ready `file://` URLs for a static folder: open the one for the target page. `devCommand` names the project's dev script: the probe may simply have missed a server on an unlisted port or on HTTPS, so check the terminal output, the dev config's port, and any open tab first, and start `devCommand` in the background only when nothing is running, wait for it to print its URL, then boot again. With neither field, find the app's URL the same way before starting anything. Never use `serverPort`; it's the helper, not the app. Always tell the user the URL in one line, so they can open it themselves when you have no browser tool, and on a project's first Live session add the first move in the same breath: click anything on the page, say what to change, press Go (Pick is already on in a browser's first session; later it is the crosshair in the bar at the bottom of the page). **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if no URL can be found, ask the user once. 3. Poll loop with the default long timeout (600000 ms). Run `impeccable live-poll` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `impeccable live-poll` to reconnect. 4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant. 5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack. @@ -54,14 +54,20 @@ LOOP: ## Start ```bash -"/scripts/impeccable" live +"/scripts/impeccable" live --allow-missing-context --dev-url --auto-config ``` -Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `impeccable surface-brief` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent. +Output JSON: `{ ok, serverPort, serverToken, configCreated, pageFiles, roots, targetPath, devUrl, pageUrls, devCommand, contextMissing, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `devUrl` is the running dev server that serves the page, or null when none answered; `pageUrls` or `devCommand` then name the next step (step 2). `contextMissing` lists PRODUCT.md or DESIGN.md when absent: Live never waits on init or document. Work from the page as below, and offer `init` or `document` after the session, not before it. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `impeccable surface-brief` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent. `serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry. -If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config. +A plain page needs no setup: when the app root holds an `index.html` page shell (Vite, React, or a plain HTML folder) with no CSP, the boot writes the one-line config itself and reports `configCreated: true`. Tell the user once that `.impeccable/live/config.json` was added, and carry on. + +If output is `{ ok: false, error: "config_invalid", message, path }`, the config at `path` exists but `message` names what is wrong with it: repair that field in the existing file ([live-setup.md](live-setup.md) describes each field), keep every other field as it is, and boot again. Never replace the file with the common-case config below. + +If output is `{ ok: false, error: "config_missing", path }`, the boot could not decide alone. A static folder whose page has another name takes one step: when `"/scripts/impeccable" detect-csp` reports `shape: null`, write `{"files":[".html"],"insertBefore":"","commentSyntax":"html","cspChecked":true}` at the boot's reported `path` and boot again. Anything else (another framework, a CSP, several HTML files): read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config. + +On `no_page`, tell the person in one sentence that there is nothing for Live to open yet. Offer to build the first page with `/impeccable craft ` and start Live on it once it exists. Do not create a page unless the person asks for one. ## Recovery commands @@ -93,7 +99,7 @@ Speed matters; the user is watching the selected element. Reuse preflight metada --element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT" ``` -`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched. +`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`: splice variants into `wrapperBlock` at the marker and replace `[replaceStartLine, replaceEndLine]` with the spliced block in ONE edit, exactly as the wrap section describes; when `replaceEndLine < replaceStartLine` this is a pure insertion that removes nothing. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched. ### Replace mode (default) @@ -113,7 +119,15 @@ When `event.scaffold` is present, the helper already found the source and comput "/scripts/impeccable" live-wrap --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET" ``` -Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow. +Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, and without it a class locator lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow. + +An element with neither an id nor classes (a bare `

`, the usual first pick on a fresh page) leaves both flags out; the tag alone locates it: + +```bash +"/scripts/impeccable" live-wrap --id EVENT_ID --count EVENT_COUNT --tag "h1" --text "TEXT_SNIPPET" +``` + +A tag alone never lands on the first match: when the tag repeats and `--text` does not single out one element, or the element shares a source line with other markup (`reason: "shared_line"`), wrap exits `element_ambiguous`; follow the fallback flow as above. Short text settles it only when it is one element's whole text. Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to. @@ -196,7 +210,7 @@ Complete HTML replacement of the original element per variant, not a CSS-only pa ``` -Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected. +Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one, and close it with `cssAuthoring.styleClose` (`` on `.vue`). **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected. For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in the [repo agent template](https://github.com/pbakaus/impeccable/blob/8dac6ae7e020c43ab10ce9b41939f6fd42627b96/tests/live-e2e/agent.mjs) is a faithful template. @@ -256,7 +270,7 @@ If wrap or generation fails after the browser flipped to GENERATING, tell the ** When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it. 1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template. -2. **Preview in the served file**: manually write the same wrapper scaffold `impeccable live-wrap` produces into the file the browser actually loaded, moving the element itself into the original slot: `
THE ELEMENT, UNCHANGED
`. Insert your variant divs after the marker, then `--reply EVENT_ID done --file `. Never drop the original slot: discard restores the element from it and refuses a wrapper without one. This edit is temporary; a regen wiping it is fine. +2. **Preview in the served file**: manually write the same wrapper scaffold `impeccable live-wrap` produces into the file the browser actually loaded, moving the element itself into the original slot: `
THE ELEMENT, UNCHANGED
`. Insert your variant divs after the marker, then `--reply EVENT_ID done --file `. Put the start marker and the end marker each on a line of its own: accept replaces whole lines from marker to marker, so a marker that shares its line with other markup takes that markup with it (in a one-line or minified file, break the line around the element first). Never drop the original slot: discard restores the element from it and refuses a wrapper without one. This edit is temporary; a regen wiping it is fine. 3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file. 4. **On discard**, just remove the temporary wrapper. @@ -269,18 +283,18 @@ Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already - `handled: true, carbonize: false`: nothing to do; poll again. - `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it. - `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll. -- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `impeccable live-accept` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `impeccable live-status` and tell the user. Anything else: report briefly, run `impeccable live-status` first. +- `handled: false, mode: "error"`: **do not hand-edit the file**, with one exception. `source_locked`: rerun the same `impeccable live-accept` command (idempotent) until the publisher releases. `markers_share_line`: a session marker comment shares its line with other markup and nothing was written; move each marker onto a line of its own (the only edit allowed), then rerun the same command. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `impeccable live-status` and tell the user. Anything else: report briefly, run `impeccable live-status` first. - `handled: false` without `mode`: manual cleanup: read file, find markers, edit. ### Required after accept (carbonize) `carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll: -1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `` with a `