claude-code-workflow 7.2.26 → 7.2.28

package/.claude/skills/team-uidesign/roles/implementer/role.md

@@ -34,6 +34,18 @@ Translate design tokens and component specifications into production code. Gener
   - `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
   - `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
   - `README.md`: Token usage guide
+- **Color tokens**: generate OKLCH values in CSS custom properties (no hex/rgb)
+- **Motion tokens**: generate easing + duration custom properties + reduced-motion query:
+  ```css
+  --easing-default: cubic-bezier(0.25, 1, 0.5, 1);
+  --duration-instant: 100ms;
+  --duration-fast: 150ms;
+  /* ... */
+  @media (prefers-reduced-motion: reduce) { /* ... */ }
+  ```
+- **Spacing**: 4pt scale custom properties (--space-0 through --space-24)
+- Z-index tokens: generate semantic z-index custom properties (`--z-dropdown` through `--z-tooltip`)
+- Dark mode: ensure dark theme uses lighter surfaces for depth, reduced font weight references
 - All color tokens must have both light and dark values
 - Semantic token names must match design token definitions
 
@@ -44,9 +56,16 @@ Translate design tokens and component specifications into production code. Gener
   - `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
   - `{ComponentName}.test.tsx`: Basic render + state tests
   - `index.ts`: Re-export
-- Requirements: no hardcoded colors/spacing (use design tokens), implement all 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
+- Requirements: no hardcoded colors/spacing (use design tokens), implement **all 8 states**, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
+- **Focus**: use `:focus-visible` not bare `:focus`. Spec: `outline: 2px solid var(--color-primary); outline-offset: 2px; border-radius: inherit`
+- **Hover**: wrap in `@media(hover:hover)` guard
+- **Animation**: transform+opacity only (NEVER width/height/margin/padding), use motion tokens for easing and duration, add reduced-motion fallback via `@media (prefers-reduced-motion: reduce)`
+- **Touch targets**: 44x44px minimum for all interactive elements, 8px gap between adjacent targets
 - Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
-- Check implementation against design intelligence anti_patterns
+- Responsive images: use `srcset` with width descriptors + `sizes` attribute for content images. Use `<picture>` for art direction
+- Input method: beyond `@media(hover:hover)`, also use `@media(pointer:coarse)` for touch-specific adjustments (larger targets, simpler hover alternatives)
+- UX writing: implement button labels, error messages, empty states as specified in component spec. No generic "OK/Cancel"
+- Check implementation against design intelligence anti_patterns and `specs/anti-patterns.md`
 
 ## Phase 4: Validation & Output
 
@@ -64,9 +83,12 @@ Translate design tokens and component specifications into production code. Gener
 |-------|---------------|
 | File existence | At least 3 files per component (component, style, index) |
 | No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
-| Focus styles | `:focus` or `:focus-visible` defined |
+| focus_visible_used | Uses `:focus-visible` not bare `:focus` |
 | Responsive | `@media` queries present |
 | Anti-pattern clean | No violations of design intelligence anti_patterns |
+| no_layout_animations | No width/height/margin/padding animations (transform+opacity only) |
+| reduced_motion_present | `@media (prefers-reduced-motion: reduce)` exists in stylesheets |
+| touch_targets | Interactive elements >= 44x44px (min-width/min-height or padding) |
 
 3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
    - Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back

package/.claude/skills/team-uidesign/roles/researcher/role.md

@@ -31,6 +31,11 @@ Analyze existing design system, build component inventory, assess accessibility
 
 3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns
 4. Read industry context from session config (industry, strictness, must-have features)
+5. **Context-First Protocol**: Before any design work, ensure these are known (extract from task description, or ask coordinator to clarify):
+   - **Target audience**: Who uses it, in what context? (e.g., developers, end users, admins)
+   - **Use cases**: What jobs are they doing? (e.g., data entry, monitoring, content creation)
+   - **Brand personality**: How should it feel? (e.g., professional, playful, technical, luxurious)
+   - If not provided in task description, flag as `context_missing` in output — designer cannot make good decisions without this
 
 ## Phase 3: Research Execution
 
@@ -41,6 +46,8 @@ Execute 4 analysis streams:
 - Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
 - Map color palette, typography scale, spacing system
 - Find component library usage (MUI, Ant Design, shadcn, custom)
+- Check dark mode implementation quality: surface hierarchy, font weight adjustments, accent desaturation
+- Check z-index patterns: arbitrary values vs semantic scale
 - Output: `<session>/research/design-system-analysis.json`
 
 **Stream 2 -- Component Inventory**:
@@ -63,11 +70,22 @@ Execute 4 analysis streams:
 - Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
 - Output: `<session>/research/design-intelligence.json`
 
-Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.
+**Stream 5 -- Visual Quality Baseline**:
+- Scan for AI slop tells (reference `specs/anti-patterns.md`): check for P1 items (AI color palette, gradient text, glassmorphism, all-buttons-primary, pure black/white)
+- Check color system: OKLCH usage, pure black/white (`#000`/`#fff`), tinted neutrals (chroma 0.005-0.01), 60-30-10 distribution
+- Check typography: font choices (flag Inter/Roboto/Open Sans/Lato/Montserrat/Arial), modular scale presence, fluid `clamp()` usage
+- Check spacing: 4pt scale adherence, `gap` vs `margin` usage ratio, nested cards detection
+- Check motion: easing values (flag `bounce`/`elastic`/`linear`/`ease`), `prefers-reduced-motion` query presence, `will-change` in CSS (should not be permanent)
+- Check interaction states: count distinct states per interactive component (target: 8 per `specs/design-standards.md`)
+- Check UX writing quality: generic button labels (OK/Submit/Cancel), error messages without fix guidance, empty states without actions
+- Check dark mode: pure black backgrounds, non-desaturated accents, same font weights as light
+- Output: `<session>/research/visual-quality-baseline.json`
+
+Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count, visual_quality_score.
 
 ## Phase 4: Validation & Output
 
-1. Verify all 4 output files exist and contain valid JSON with required fields:
+1. Verify all 5 output files exist and contain valid JSON with required fields:
 
 | File | Required Fields |
 |------|----------------|
@@ -75,6 +93,7 @@ Compile research summary metrics: design_system_exists, styling_approach, total_
 | component-inventory.json | components array |
 | accessibility-audit.json | wcag_level |
 | design-intelligence.json | _source, design_system |
+| visual-quality-baseline.json | slop_tells, color_system, typography, spacing, motion, interaction_states |
 
 2. If any file missing or invalid, re-run corresponding stream
 

package/.claude/skills/team-uidesign/roles/reviewer/role.md

@@ -27,39 +27,41 @@ Audit design tokens and component specs for consistency, accessibility complianc
 
 ## Phase 3: Audit Execution
 
-Score 5 dimensions on 1-10 scale:
+Score 8 dimensions on 0-4 scale (reference `specs/scoring-guide.md`). Total: 0-32.
 
 | Dimension | Weight | Focus |
 |-----------|--------|-------|
-| Consistency | 20% | Token usage, naming conventions, visual uniformity |
-| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast |
-| Completeness | 20% | All states defined, responsive specs, edge cases |
-| Quality | 15% | Token reference integrity, documentation clarity, maintainability |
-| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence |
+| Anti-AI-Slop | 10% | AI slop tells detection (reference `specs/anti-patterns.md`) |
+| Color Quality | 15% | OKLCH usage, tinted neutrals, 60-30-10, WCAG AA contrast, token hierarchy, dark mode surface hierarchy (lighter = higher elevation), dangerous color combinations (gray-on-color, red-green, yellow-white) |
+| Typography Quality | 15% | Distinctive fonts, modular scale, fluid clamp(), line-height, reading width, OpenType features usage (tabular numbers for data, proper ligatures) |
+| Spacing & Layout | 12.5% | 4pt scale, rhythm variation, gap over margin, no nested cards, touch targets |
+| Motion & Animation | 10% | Transform+opacity only, exponential easing, duration tokens, reduced-motion |
+| Interaction States | 15% | All 8 states, focus-visible, focus ring spec, loading/error/success, UX writing quality: button labels (verb+object), error messages (what+why+fix), empty states |
+| Visual Hierarchy | 10% | Squint test, single primary CTA, progressive disclosure, size/weight hierarchy |
+| Responsive | 12.5% | Fluid design, container queries, mobile requirements, adapt don't hide |
 
-**Token Audit**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates.
+**Token Audit**: OKLCH color values, tinted neutrals (chroma 0.005-0.01), no pure black/white, semantic token hierarchy (primitive->semantic->component), theme completeness (light+dark), contrast ratios (text >= 4.5:1, large text >= 3:1), distinctive font choice, modular scale ratio, fluid clamp() values, 4pt spacing scale, motion easing + duration tokens, reduced-motion strategy.
 
-**Component Audit**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions.
+**Component Audit**: All 8 interaction states present, `:focus-visible` (not bare `:focus`), hover in `@media(hover:hover)`, active `scale(0.97)`, loading/error/success states with ARIA, touch targets >= 44x44px, token references resolve, CTA hierarchy (primary/secondary/tertiary), no layout property animations.
 
-**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns).
-
-**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)`
+**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns), anti-pattern scan across all outputs.
 
 **Signal determination**:
 
 | Condition | Signal |
 |-----------|--------|
-| Score >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) |
-| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) |
-| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
+| Score >= 26 AND no dimension at 0 | `audit_passed` (GC CONVERGED) |
+| Score >= 20 AND no dimension at 0 | `audit_result` (REVISION NEEDED) |
+| Score < 20 OR any dimension at 0 | `fix_required` (CRITICAL) |
 
 ## Phase 4: Report & Output
 
 1. Write audit report to `<session>/audit/audit-{NNN}.md`:
-   - Summary: overall score, signal, critical/high/medium counts
+   - Summary: overall score (out of 32), signal, rating band (Excellent/Good/Acceptable/Poor/Critical)
    - Sync Point Status (if applicable): PASSED/BLOCKED
-   - Dimension Scores table (score/weight/weighted per dimension)
-   - Critical/High/Medium issues with descriptions, locations, fix suggestions
+   - 8-Dimension Scores table: Anti-AI-Slop, Color Quality, Typography Quality, Spacing & Layout, Motion & Animation, Interaction States, Visual Hierarchy, Responsive (each 0-4 with weight and weighted score)
+   - P0/P1/P2/P3 issues with descriptions, locations, fix suggestions, mapped to dimensions
+   - Anti-pattern detections (reference `specs/anti-patterns.md` item numbers)
    - GC Loop Status: signal, action required
    - Trend analysis (if audit_history exists): improving/stable/declining
 

package/.claude/skills/team-uidesign/specs/anti-patterns.md

@@ -0,0 +1,211 @@
+# AI Slop Detection Catalog
+
+20 anti-patterns that signal AI-generated or low-effort design. Reference this during research (visual quality baseline), design (avoidance), review (scoring), and implementation (validation).
+
+## Severity Guide
+
+| Severity | Meaning | Scoring Impact |
+|----------|---------|----------------|
+| P1 | Major -- immediately recognizable as AI slop | Dimension score capped at 1 |
+| P2 | Minor -- common AI default, degrades quality | Dimension score capped at 2 |
+| P3 | Polish -- subtle tell, acceptable in early iterations | Dimension score capped at 3 |
+
+---
+
+## 1. AI Color Palette -- P1
+
+**Pattern**: Cyan-on-dark, purple-blue gradients, neon accent colors against dark backgrounds. The "AI dashboard" look.
+
+**Detection**: Check for `oklch(... 250-280)` as primary + dark background, or gradient from purple to cyan/blue. Check for saturated neon accents (`chroma > 0.25`) on `lightness < 0.15` backgrounds.
+
+**Fix**: Use brand-derived colors. Reduce chroma. Apply 60-30-10 rule. Tint neutrals toward brand hue.
+
+---
+
+## 2. Gradient Text for Impact -- P1
+
+**Pattern**: `background-clip: text` with gradient fills on headings for visual flair.
+
+**Detection**: Search for `background-clip: text` or `-webkit-background-clip: text` in stylesheets.
+
+**Fix**: Use solid color with proper contrast. If emphasis needed, use weight or size, not gradient text.
+
+---
+
+## 3. Default Dark Mode with Glowing Accents -- P2
+
+**Pattern**: Dark background as default with glowing/neon UI elements. No light mode alternative.
+
+**Detection**: Check if dark theme is the only theme defined. Look for `box-shadow` with saturated colors (`0 0 Npx oklch(... 0.2+ ...)`).
+
+**Fix**: Design light mode first. Dark mode as opt-in. Use subtle elevation shadows, not glows.
+
+---
+
+## 4. Glassmorphism Everywhere -- P1
+
+**Pattern**: `backdrop-filter: blur()` on more than 2 components. Frosted glass effect as default surface treatment.
+
+**Detection**: Count `backdrop-filter: blur` occurrences. Flag if > 2 distinct components use it.
+
+**Fix**: Reserve glass effect for 1-2 overlay/modal surfaces max. Use solid or semi-transparent backgrounds elsewhere.
+
+---
+
+## 5. Hero Metric Layout -- P2
+
+**Pattern**: Big number + small label arranged in rows/grids. The "SaaS dashboard hero" pattern with 3-4 metric cards.
+
+**Detection**: Look for repeated pattern of large font-size number + small label in card grids at page top.
+
+**Fix**: Show metrics in context of their meaning. Use sparklines with real data, comparisons, or trends instead of isolated numbers.
+
+---
+
+## 6. Identical Card Grids -- P2
+
+**Pattern**: 3+ cards with identical dimensions, same padding, same shadow, same structure. No visual hierarchy.
+
+**Detection**: Count card components with identical styling. Flag if 3+ share exact same dimensions and no hierarchy differentiation.
+
+**Fix**: Vary card sizes by importance. Use a featured/primary card. Apply visual hierarchy through size or position.
+
+---
+
+## 7. Nested Cards -- P2
+
+**Pattern**: Card inside card -- border/shadow inside border/shadow. Creates visual clutter.
+
+**Detection**: Check for components with `border`/`box-shadow` containing child components that also have `border`/`box-shadow`.
+
+**Fix**: Flatten hierarchy. Use spacing and subtle dividers instead of nested containers.
+
+---
+
+## 8. Generic Fonts -- P2
+
+**Pattern**: Inter, Roboto, Open Sans, Lato, Montserrat, or Arial as the primary font. Zero typographic identity.
+
+**Detection**: Check `font-family` declarations for the generic font list.
+
+**Fix**: Choose from recommended fonts: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces.
+
+---
+
+## 9. Rounded Rectangles + Generic Drop Shadows -- P3
+
+**Pattern**: More than 5 elements with identical `border-radius` and generic `box-shadow` (e.g., `0 1px 3px rgba(0,0,0,0.1)`).
+
+**Detection**: Count elements sharing identical `border-radius` + `box-shadow` values. Flag if > 5.
+
+**Fix**: Vary border-radius by component type (buttons vs cards vs modals). Use layered shadows with tinted colors.
+
+---
+
+## 10. Large Icons Above Every Heading -- P2
+
+**Pattern**: Decorative icon placed above every section heading. Adds visual noise without meaning.
+
+**Detection**: Check for repeated icon + heading pattern across 3+ sections.
+
+**Fix**: Use icons sparingly and only where they add meaning. Prefer inline icons at heading size, not oversized decorative ones.
+
+---
+
+## 11. One-Side Border Accent -- P3
+
+**Pattern**: `border-left: 3px solid var(--accent)` on cards or sections as the sole visual treatment.
+
+**Detection**: Search for one-sided border declarations on 3+ components.
+
+**Fix**: Use spacing, background tinting, or typography to create differentiation instead.
+
+---
+
+## 12. Decorative Sparklines -- P2
+
+**Pattern**: Tiny charts with no axis labels, no data context, no interactivity. Pure decoration.
+
+**Detection**: Check for chart/sparkline components without accessible labels, axis values, or data source.
+
+**Fix**: Either make charts meaningful (labels, context, interaction) or remove them. No decorative data visualization.
+
+---
+
+## 13. Bounce/Elastic Easing -- P2
+
+**Pattern**: Bounce or elastic easing on UI transitions. Feels toylike and unprofessional.
+
+**Detection**: Search for `bounce`, `elastic`, `cubic-bezier` with values > 1.0 in the second or fourth parameter.
+
+**Fix**: Use ease-out-quart `cubic-bezier(0.25, 1, 0.5, 1)` as default. See design-standards.md Motion section.
+
+---
+
+## 14. Redundant Copy -- P3
+
+**Pattern**: Heading restated in the body text immediately below. "Our Features" followed by "Here are our features."
+
+**Detection**: Compare heading text to first sentence of body. Flag if > 60% word overlap.
+
+**Fix**: Body text should expand on the heading, not repeat it. Each element earns its space.
+
+---
+
+## 15. All Buttons Primary -- P1
+
+**Pattern**: Every button is the same filled/primary style. No visual hierarchy between actions.
+
+**Detection**: Count button variants. Flag if > 80% of buttons share the same style (all filled, all same color).
+
+**Fix**: 1 primary CTA per viewport. Secondary = outline. Tertiary = text link. See design-standards.md Visual Hierarchy.
+
+---
+
+## 16. Everything Centered -- P2
+
+**Pattern**: Body text, lists, and form labels all center-aligned. Looks "designed" but kills readability.
+
+**Detection**: Check for `text-align: center` on body text, lists, or form elements (not just headings).
+
+**Fix**: Left-align body text. Center only headings, hero text, and short labels. Reading follows left edge.
+
+---
+
+## 17. Same Spacing Everywhere -- P2
+
+**Pattern**: More than 70% of spacing values are identical. No rhythm variation.
+
+**Detection**: Audit spacing tokens usage. Flag if > 70% of `gap`, `padding`, `margin` values use the same token.
+
+**Fix**: Apply rhythm: tight (4-8px) within groups, comfortable (16-24px) between items, generous (48-96px) between sections.
+
+---
+
+## 18. Monospace as Tech Aesthetic -- P3
+
+**Pattern**: Monospace font used on non-code content (headings, labels, body text) for "techy" feel.
+
+**Detection**: Check for monospace `font-family` on elements that are not `code`, `pre`, `kbd`, or `samp`.
+
+**Fix**: Reserve monospace for code. Use Space Grotesk or similar geometric sans if tech aesthetic is desired.
+
+---
+
+## 19. Modal Overuse -- P3
+
+**Pattern**: More than 3 modals in a flow for non-critical actions. Interrupts flow unnecessarily.
+
+**Detection**: Count modal/dialog components. Flag if > 3 modals exist for non-destructive actions.
+
+**Fix**: Use inline expansion, drawers, or page navigation. Reserve modals for confirmations and critical decisions.
+
+---
+
+## 20. Pure Black or Pure White -- P1
+
+**Pattern**: Using `#000000` or `#ffffff` (or `rgb(0,0,0)` / `rgb(255,255,255)`). Harsh contrast, unnatural.
+
+**Detection**: Search for `#000`, `#fff`, `#000000`, `#ffffff`, `rgb(0,0,0)`, `rgb(255,255,255)` in stylesheets and tokens.
+
+**Fix**: Use tinted neutrals. Darkest: `oklch(0.08 0.010 <hue>)`. Lightest: `oklch(0.98 0.005 <hue>)`.