Add workflow infrastructure — ESLint, Prettier, Husky, Vitest, 7 new skills
Phase 1: Session log archived (1096→91 lines), D031 token access convention
Phase 2: ESLint v9 + Prettier + jsx-a11y, initial config and lint fixes
Phase 3: 7 new skills (polish, harden, normalize, clarify, typeset, quieter, adapt)
+ Vercel reference docs, updated audit/review-component refs
Phase 4: Husky + lint-staged pre-commit hooks, preflight updated to 8 checks
Phase 5: Vitest + Testing Library + /write-tests skill
- Badge.tsx colour maps unified to CSS variables (D031)
- 5 empty interface→type alias fixes (Switch, Radio, Divider, IconButton, Link)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
150
.claude/skills/clarify/SKILL.md
Normal file
150
.claude/skills/clarify/SKILL.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: clarify
|
||||
description: Information hierarchy improvement — evaluates whether primary actions are visible, decision points are clear, content grouping is logical, and labels are unambiguous.
|
||||
user-invocable: true
|
||||
argument-hint: "[component or area to clarify]"
|
||||
---
|
||||
|
||||
Evaluate and fix information hierarchy, cognitive load, and decision clarity. Unlike audit/critique which only assess, **clarify finds AND fixes issues**. This skill is critical for flows, forms, and any interface where users must make decisions.
|
||||
|
||||
**Target:** $ARGUMENTS
|
||||
|
||||
## Preparation
|
||||
|
||||
1. Read `docs/design-system.md` for FA design conventions
|
||||
2. Read `docs/memory/decisions-log.md` for design rationale
|
||||
3. Read the target component/area source files and stories
|
||||
4. Reference `docs/reference/impeccable/cognitive-load.md` for the 8-item checklist and violation patterns
|
||||
5. Reference `docs/reference/impeccable/heuristics-scoring.md` for scoring criteria
|
||||
|
||||
**FA context**: Funeral Arranger serves families in grief or distress. Cognitive capacity is reduced under grief — working memory shrinks, decision fatigue sets in faster, and tolerance for ambiguity drops to near zero. Clarity is not a nice-to-have, it is the primary design requirement. No jargon. No ambiguity. No unnecessary choices. Every screen should answer: "What am I looking at? What should I do? What happens next?"
|
||||
|
||||
## Phase 1: Cognitive Load Assessment
|
||||
|
||||
Run the 8-item checklist from `docs/reference/impeccable/cognitive-load.md` against the target:
|
||||
|
||||
| # | Check | Pass/Fail | Notes |
|
||||
|---|-------|-----------|-------|
|
||||
| 1 | **Single focus**: Can the user complete their primary task without distraction? | | |
|
||||
| 2 | **Chunking**: Is information in digestible groups (<=4 items per group)? | | |
|
||||
| 3 | **Grouping**: Are related items visually grouped (proximity, borders, shared background)? | | |
|
||||
| 4 | **Visual hierarchy**: Is it immediately clear what is most important? | | |
|
||||
| 5 | **One thing at a time**: Can the user focus on one decision before the next? | | |
|
||||
| 6 | **Minimal choices**: Are decisions simplified (<=4 visible options at any decision point)? | | |
|
||||
| 7 | **Working memory**: Does the user need to remember info from a previous screen? | | |
|
||||
| 8 | **Progressive disclosure**: Is complexity revealed only when needed? | | |
|
||||
|
||||
**Scoring**: 0-1 failures = low cognitive load (good). 2-3 = moderate (address soon). 4+ = high cognitive load (critical fix needed).
|
||||
|
||||
## Phase 2: Clarity Checks
|
||||
|
||||
Evaluate each dimension. **Fix issues as you find them.**
|
||||
|
||||
### 1. Primary Action Visibility
|
||||
|
||||
The most important action on any screen should be identifiable within 2 seconds.
|
||||
|
||||
- [ ] **One primary action**: There is exactly one visually dominant CTA per view
|
||||
- [ ] **Visual weight**: The primary action has the strongest visual weight (size, colour, contrast)
|
||||
- [ ] **Position**: The primary action is in a predictable location (bottom of form, right of button group)
|
||||
- [ ] **No competition**: Secondary actions are visually subordinate (outlined or text style, not filled)
|
||||
- [ ] **Label clarity**: The CTA label says what will happen ("Continue to payment" not "Next" or "Submit")
|
||||
|
||||
**FA-specific**: For stepped flows (arrangement, funeral finder), the primary CTA must always be visible without scrolling. Smart defaults should pre-fill where possible to reduce friction.
|
||||
|
||||
### 2. Decision Point Clarity
|
||||
|
||||
At every point where the user must choose:
|
||||
|
||||
- [ ] **<=4 options visible**: If more exist, group under categories or use progressive disclosure
|
||||
- [ ] **Recommended option**: When appropriate, visually highlight the recommended choice
|
||||
- [ ] **Clear labels**: Every option has an unambiguous label — the user should never wonder "what does this mean?"
|
||||
- [ ] **Consequence preview**: The user can see what choosing each option will lead to
|
||||
- [ ] **Reversibility signal**: If a choice can be changed later, say so ("You can change this later")
|
||||
|
||||
**FA-specific**: Pricing decisions are high-anxiety. Show what is included, not just the price. For service options, group by category (venue, ceremony, extras) rather than showing a flat list.
|
||||
|
||||
### 3. Content Grouping
|
||||
|
||||
Related information should be visually grouped:
|
||||
|
||||
- [ ] **Proximity**: Related items are physically close together
|
||||
- [ ] **Separation**: Unrelated groups have clear visual separation (whitespace, dividers, card boundaries)
|
||||
- [ ] **Labels**: Each group has a clear heading that describes its contents
|
||||
- [ ] **Consistency**: Same type of grouping used for same type of content throughout
|
||||
|
||||
### 4. Label Clarity
|
||||
|
||||
For every label, heading, and piece of instructional text:
|
||||
|
||||
- [ ] **Unambiguous**: Could not be misinterpreted by a reasonable person
|
||||
- [ ] **Action-oriented**: Buttons describe what they do, not what they are
|
||||
- [ ] **Jargon-free**: No funeral industry jargon unless unavoidable (and defined inline if so)
|
||||
- [ ] **Consistent**: Same concept uses the same word everywhere (not "funeral" in one place and "service" in another for the same thing)
|
||||
- [ ] **Concise**: Labels are as short as possible while remaining clear
|
||||
|
||||
**FA-specific**: Avoid euphemistic language that creates ambiguity. "Funeral service" is clearer than "farewell ceremony." Be direct but warm.
|
||||
|
||||
### 5. Information Hierarchy
|
||||
|
||||
The visual presentation should match the importance of information:
|
||||
|
||||
- [ ] **Reading order**: The most important information comes first (top, left)
|
||||
- [ ] **Size signals importance**: Larger text = more important
|
||||
- [ ] **Colour signals importance**: Brand/accent colour draws the eye to what matters
|
||||
- [ ] **Redundancy eliminated**: No information is repeated without purpose
|
||||
- [ ] **Noise removed**: Every element earns its place — nothing decorative without function
|
||||
|
||||
### 6. Navigation Clarity
|
||||
|
||||
The user should always know where they are and how to move:
|
||||
|
||||
- [ ] **Current location visible**: Active states, breadcrumbs, or step indicators show position
|
||||
- [ ] **Next step obvious**: The path forward is clear without thinking
|
||||
- [ ] **Back path clear**: The user can always go back without losing work
|
||||
- [ ] **Progress visible**: Multi-step flows show progress (step 2 of 4)
|
||||
|
||||
## Phase 3: Cognitive Load Violations Scan
|
||||
|
||||
Check for common cognitive load violations (from `docs/reference/impeccable/cognitive-load.md`):
|
||||
|
||||
1. **Wall of Options** — 10+ choices with no hierarchy. **Fix**: Group, highlight recommended, use progressive disclosure.
|
||||
2. **Memory Bridge** — Must remember info from step 1 to complete step 3. **Fix**: Keep context visible or repeat it.
|
||||
3. **Hidden Navigation** — Must build a mental map. **Fix**: Show current location always.
|
||||
4. **Jargon Barrier** — Technical/domain language forces translation effort. **Fix**: Plain language, define terms inline.
|
||||
5. **Visual Noise Floor** — Every element has the same visual weight. **Fix**: Clear hierarchy — one primary, 2-3 secondary, rest muted.
|
||||
6. **Inconsistent Pattern** — Similar actions work differently in different places. **Fix**: Standardise interaction patterns.
|
||||
7. **Multi-Task Demand** — Must process multiple simultaneous inputs. **Fix**: Sequence the steps.
|
||||
8. **Context Switch** — Must jump between screens to gather info for one decision. **Fix**: Co-locate information.
|
||||
|
||||
## Clarification Report
|
||||
|
||||
After fixing issues, present:
|
||||
|
||||
### Cognitive Load Score
|
||||
|
||||
**Checklist failures**: X/8
|
||||
**Rating**: Low / Moderate / High
|
||||
|
||||
### What Was Clarified
|
||||
|
||||
For each fix:
|
||||
- **Area**: What was changed
|
||||
- **Problem**: What was unclear or overloaded
|
||||
- **Fix**: What was done to clarify
|
||||
- **Rationale**: Why this improves the experience for FA's users
|
||||
|
||||
### Clarity Wins
|
||||
|
||||
Note areas that are already well-structured — reinforce good patterns.
|
||||
|
||||
### Remaining Concerns
|
||||
|
||||
Note any structural clarity issues that require architectural changes beyond this skill's scope.
|
||||
|
||||
**NEVER**:
|
||||
- Add jargon or technical language — always simplify
|
||||
- Present more than 4 options at a decision point without grouping
|
||||
- Remove information that users need — clarify means restructure, not delete
|
||||
- Change component behaviour or API — only change presentation, labels, grouping, and hierarchy
|
||||
- Use ambiguous labels ("Submit", "Click here", "Next") when specific labels are possible
|
||||
Reference in New Issue
Block a user