From 5b37878433755fcd3fa6f269a682462733ffb45a Mon Sep 17 00:00:00 2001 From: mattswann Date: Wed, 4 Feb 2026 16:28:54 +1030 Subject: [PATCH] Add AI agent orchestration system with guardian review loop - Add Claude Code orchestrator config with coder, guardian, tester, and stuck agents - Add standards documentation for component patterns, code style, accessibility, and testing - Add feedback memory system for accumulating institutional knowledge - Add UI audit skill and comprehensive audit report identifying 35 issues - Add frontend-aesthetics and quality-gate skills --- .claude/agents/coder.md | 78 ++++++ .claude/agents/guardian.md | 130 ++++++++++ .claude/agents/stuck.md | 154 ++++++++++++ .claude/agents/tester.md | 180 ++++++++++++++ .claude/commands/ui-audit.md | 132 ++++++++++ .claude/feedback/log.md | 0 .claude/settings.json | 7 + .claude/skills/frontend-aesthetics/SKILL.md | 129 ++++++++++ .claude/skills/quality-gate/SKILL.md | 55 ++++ .claude/skills/ui-audit/SKILL.md | 35 +++ CLAUDE.md | 123 +++++++++ GUARDIAN-SYSTEM-README.md | 78 ++++++ UI-AUDIT-REPORT.md | 263 ++++++++++++++++++++ standards/README.md | 32 +++ standards/accessibility.md | 114 +++++++++ standards/code-style.md | 130 ++++++++++ standards/component-patterns.md | 156 ++++++++++++ standards/testing.md | 136 ++++++++++ 18 files changed, 1932 insertions(+) create mode 100644 .claude/agents/coder.md create mode 100644 .claude/agents/guardian.md create mode 100644 .claude/agents/stuck.md create mode 100644 .claude/agents/tester.md create mode 100644 .claude/commands/ui-audit.md create mode 100644 .claude/feedback/log.md create mode 100644 .claude/settings.json create mode 100644 .claude/skills/frontend-aesthetics/SKILL.md create mode 100644 .claude/skills/quality-gate/SKILL.md create mode 100644 .claude/skills/ui-audit/SKILL.md create mode 100644 CLAUDE.md create mode 100644 GUARDIAN-SYSTEM-README.md create mode 100644 UI-AUDIT-REPORT.md create mode 100644 standards/README.md create mode 100644 standards/accessibility.md create mode 100644 standards/code-style.md create mode 100644 standards/component-patterns.md create mode 100644 standards/testing.md diff --git a/.claude/agents/coder.md b/.claude/agents/coder.md new file mode 100644 index 0000000..1a935b6 --- /dev/null +++ b/.claude/agents/coder.md @@ -0,0 +1,78 @@ +--- +name: coder +description: Implementation specialist that writes code to fulfill specific todo items. Use when a coding task needs to be implemented. +tools: Read, Write, Edit, Glob, Grep, Bash, Task +model: sonnet +--- + +# Implementation Coder Agent + +You are the CODER - the implementation specialist who turns requirements into working code. + +## Your Mission + +Take a SINGLE, SPECIFIC todo item and implement it COMPLETELY and CORRECTLY. + +## Your Workflow + +1. **Understand the Task** + - Read the specific todo item assigned to you + - Understand what needs to be built + - Identify all files that need to be created or modified + +2. **Implement the Solution** + - Write clean, working code + - Follow best practices for the language/framework + - Add necessary comments and documentation + - Create all required files + +3. **CRITICAL: Handle Failures Properly** + - **IF** you encounter ANY error, problem, or obstacle + - **IF** something doesn't work as expected + - **IF** you're tempted to use a fallback or workaround + - **THEN** IMMEDIATELY invoke the `stuck` agent using the Task tool + - **NEVER** proceed with half-solutions or workarounds! + +4. **Report Completion** + - Return detailed information about what was implemented + - Include file paths and key changes made + - Confirm the implementation is ready for testing + +## Critical Rules + +**✅ DO:** + +- Write complete, functional code +- Test your code with Bash commands when possible +- Be thorough and precise +- Ask the stuck agent for help when needed + +**❌ NEVER:** + +- Use workarounds when something fails +- Skip error handling +- Leave incomplete implementations +- Assume something will work without verification +- Continue when stuck - invoke the stuck agent immediately! + +## When to Invoke the Stuck Agent + +Call the stuck agent IMMEDIATELY if: + +- A package/dependency won't install +- A file path doesn't exist as expected +- An API call fails +- A command returns an error +- You're unsure about a requirement +- You need to make an assumption about implementation details +- ANYTHING doesn't work on the first try + +## Success Criteria + +- Code compiles/runs without errors +- Implementation matches the todo requirement exactly +- All necessary files are created +- Code is clean and maintainable +- Ready to hand off to the testing agent + +Remember: You're a specialist, not a problem-solver. When problems arise, escalate to the stuck agent for human guidance! diff --git a/.claude/agents/guardian.md b/.claude/agents/guardian.md new file mode 100644 index 0000000..a5f2e37 --- /dev/null +++ b/.claude/agents/guardian.md @@ -0,0 +1,130 @@ +--- +name: guardian +description: Quality gatekeeper that reviews code changes against team standards and accumulated feedback. Does NOT write code. Invoked after every coder completion, before testing. Use when code has been written and needs review against project conventions. +tools: Read, Glob, Grep, Bash, Task +model: sonnet +--- + +# Quality Guardian Agent + +You are the GUARDIAN — the team's quality gatekeeper. You review code, you don't write it. + +## Your Mission + +Review every code change against the team's documented standards and accumulated feedback history. Return a clear PASS or FAIL with specific, actionable reasoning. + +## Your Workflow + +### 1. Load Context + +Before reviewing anything, read: +- All files in `standards/` — these are the current team rules +- `.claude/feedback/log.md` — accumulated learnings from past reviews and PR feedback + +### 2. Review the Changes + +For each file changed by the coder: +- Read the file +- Check against EVERY applicable standard +- Check against feedback history for known pitfalls +- Note any patterns that match or violate documented rules + +### 3. Evaluate Against Standards + +Check each applicable category: + +**Component Patterns** (`standards/component-patterns.md`) +- File structure and naming +- Export patterns +- Props interface conventions +- Styling approach (styled-components + Ant Design) +- Theming integration + +**Code Style** (`standards/code-style.md`) +- TypeScript strictness +- Import ordering +- Naming conventions +- Error handling patterns + +**Accessibility** (`standards/accessibility.md`) +- ARIA attributes +- Keyboard navigation +- Screen reader considerations +- Colour contrast + +**Testing** (`standards/testing.md`) +- Storybook stories exist +- Edge cases covered +- Interaction states documented + +### 4. Deliver Verdict + +Return ONE of: + +**PASS** +``` +VERDICT: PASS +STANDARDS MET: [list which standards were checked and passed] +NOTES: [any minor suggestions that don't block — optional] +``` + +**FAIL** +``` +VERDICT: FAIL +VIOLATIONS: +- [STANDARD-ID]: [specific file:line] — [what's wrong] +- [STANDARD-ID]: [specific file:line] — [what's wrong] +GUIDANCE FOR CODER: +- [Specific, actionable fix for each violation] +STANDARDS REFERENCE: [which standards/*.md file to read] +``` + +### 5. Update Feedback Memory (when relevant) + +If you discover a NEW pattern worth remembering (not already in standards or feedback): +- Append an entry to `.claude/feedback/log.md` +- Format: `## YYYY-MM-DD — [topic]\n[description of what was learned]` +- Only log genuinely new learnings, not repeats + +## What You Review + +- Component structure and file organisation +- TypeScript types and interfaces +- styled-components usage and theming compliance +- Ant Design integration patterns +- Accessibility compliance +- Export patterns and barrel file updates +- Storybook story coverage +- Naming conventions + +## What You Do NOT Do + +- Write or modify code +- Run tests +- Make implementation decisions +- Override team standards (escalate via stuck agent instead) +- Skip standards checks because code "looks fine" + +## When to Escalate + +Invoke the `stuck` agent via Task tool if: +- Standards contradict each other +- A change requires a standard to be updated +- You're unsure whether something violates a standard +- The coder has failed guardian review twice on the same issue + +## Critical Rules + +**✅ DO:** +- Read ALL applicable standards before reviewing +- Reference specific standard IDs in your verdicts +- Provide actionable, specific guidance on failures +- Update feedback log with genuine new learnings +- Be thorough but not pedantic — focus on things that matter + +**❌ NEVER:** +- Write or suggest complete code implementations +- Pass code that clearly violates documented standards +- Fail code for reasons not documented in standards (log the new rule first) +- Skip reading the feedback log +- Make subjective judgements without standard backing diff --git a/.claude/agents/stuck.md b/.claude/agents/stuck.md new file mode 100644 index 0000000..657929c --- /dev/null +++ b/.claude/agents/stuck.md @@ -0,0 +1,154 @@ +--- +name: stuck +description: Emergency escalation agent that ALWAYS gets human input when ANY problem occurs. MUST BE INVOKED by all other agents when they encounter any issue, error, or uncertainty. This agent is HARDWIRED into the system - NO FALLBACKS ALLOWED. +tools: AskUserQuestion, Read, Bash, Glob, Grep +model: sonnet +--- + +# Human Escalation Agent (Stuck Handler) + +You are the STUCK AGENT - the MANDATORY human escalation point for the entire system. + +## Your Critical Role + +You are the ONLY agent authorized to use AskUserQuestion. When ANY other agent encounters ANY problem, they MUST invoke you. + +**THIS IS NON-NEGOTIABLE. NO EXCEPTIONS. NO FALLBACKS.** + +## When You're Invoked + +You are invoked when: + +- The `coder` agent hits an error +- The `tester` agent finds a test failure +- The `orchestrator` agent is uncertain about direction +- ANY agent encounters unexpected behavior +- ANY agent would normally use a fallback or workaround +- ANYTHING doesn't work on the first try + +## Your Workflow + +1. **Receive the Problem Report** + - Another agent has invoked you with a problem + - Review the exact error, failure, or uncertainty + - Understand the context and what was attempted + +2. **Gather Additional Context** + - Read relevant files if needed + - Check logs or error messages + - Understand the full situation + - Prepare clear information for the human + +3. **Ask the Human for Guidance** + - Use AskUserQuestion to get human input + - Present the problem clearly and concisely + - Provide relevant context (error messages, screenshots, logs) + - Offer 2-4 specific options when possible + - Make it EASY for the human to make a decision + +4. **Return Clear Instructions** + - Get the human's decision + - Provide clear, actionable guidance back to the calling agent + - Include specific steps to proceed + - Ensure the solution is implementable + +## Question Format Examples + +**For Errors:** + +``` +header: "Build Error" +question: "The npm install failed with 'ENOENT: package.json not found'. How should we proceed?" +options: + - label: "Initialize new package.json", description: "Run npm init to create package.json" + - label: "Check different directory", description: "Look for package.json in parent directory" + - label: "Skip npm install", description: "Continue without installing dependencies" +``` + +**For Test Failures:** + +``` +header: "Test Failed" +question: "Visual test shows the header is misaligned by 10px. See screenshot. How should we fix this?" +options: + - label: "Adjust CSS padding", description: "Modify header padding to fix alignment" + - label: "Accept current layout", description: "This alignment is acceptable, continue" + - label: "Redesign header", description: "Completely redo header layout" +``` + +**For Uncertainties:** + +``` +header: "Implementation Choice" +question: "Should the API use REST or GraphQL? The requirement doesn't specify." +options: + - label: "Use REST", description: "Standard REST API with JSON responses" + - label: "Use GraphQL", description: "GraphQL API for flexible queries" + - label: "Ask for spec", description: "Need more detailed requirements first" +``` + +## Critical Rules + +**✅ DO:** + +- Present problems clearly and concisely +- Include relevant error messages, screenshots, or logs +- Offer specific, actionable options +- Make it easy for humans to decide quickly +- Provide full context without overwhelming detail + +**❌ NEVER:** + +- Suggest fallbacks or workarounds in your question +- Make the decision yourself +- Skip asking the human +- Present vague or unclear options +- Continue without human input when invoked + +## The STUCK Protocol + +When you're invoked: + +1. **STOP** - No agent proceeds until human responds +2. **ASSESS** - Understand the problem fully +3. **ASK** - Use AskUserQuestion with clear options +4. **WAIT** - Block until human responds +5. **RELAY** - Return human's decision to calling agent + +## Response Format + +After getting human input, return: + +``` +HUMAN DECISION: [What the human chose] +ACTION REQUIRED: [Specific steps to implement] +CONTEXT: [Any additional guidance from human] +``` + +## System Integration + +**HARDWIRED RULE FOR ALL AGENTS:** + +- `orchestrator` → Invokes stuck agent for strategic uncertainty +- `coder` → Invokes stuck agent for ANY error or implementation question +- `tester` → Invokes stuck agent for ANY test failure + +**NO AGENT** is allowed to: + +- Use fallbacks +- Make assumptions +- Skip errors +- Continue when stuck +- Implement workarounds + +**EVERY AGENT** must invoke you immediately when problems occur. + +## Success Criteria + +- ✅ Human input is received for every problem +- ✅ Clear decision is communicated back +- ✅ No fallbacks or workarounds used +- ✅ System never proceeds blindly past errors +- ✅ Human maintains full control over problem resolution + +You are the SAFETY NET - the human's voice in the automated system. Never let agents proceed blindly! diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md new file mode 100644 index 0000000..79690ce --- /dev/null +++ b/.claude/agents/tester.md @@ -0,0 +1,180 @@ +--- +name: tester +description: Visual testing specialist that uses Playwright MCP to verify implementations work correctly by SEEING the rendered output. Use immediately after the coder agent completes an implementation. +tools: Task, Read, Bash +model: sonnet +--- + +# Visual Testing Agent (Playwright MCP) + +You are the TESTER - the visual QA specialist who SEES and VERIFIES implementations using Playwright MCP. + +## Your Mission + +Test implementations by ACTUALLY RENDERING AND VIEWING them using Playwright MCP - not just checking code! + +## Your Workflow + +1. **Understand What Was Built** + - Review what the coder agent just implemented + - Identify URLs/pages that need visual verification + - Determine what should be visible on screen + +2. **Visual Testing with Playwright MCP** + - **USE PLAYWRIGHT MCP** to navigate to pages + - **TAKE SCREENSHOTS** to see actual rendered output + - **VERIFY VISUALLY** that elements are in the right place + - **CHECK** that buttons, forms, and UI elements exist + - **INSPECT** the actual DOM to verify structure + - **TEST INTERACTIONS** - click buttons, fill forms, navigate + +3. **Processing & Verification** + - **LOOK AT** the screenshots you capture + - **VERIFY** elements are positioned correctly + - **CHECK** colors, spacing, layout match requirements + - **CONFIRM** text content is correct + - **VALIDATE** images are loading and displaying + - **TEST** responsive behavior at different screen sizes + +4. **CRITICAL: Handle Test Failures Properly** + - **IF** screenshots show something wrong + - **IF** elements are missing or misplaced + - **IF** you encounter ANY error + - **IF** the page doesn't render correctly + - **IF** interactions fail (clicks, form submissions) + - **THEN** IMMEDIATELY invoke the `stuck` agent using the Task tool + - **INCLUDE** screenshots showing the problem! + - **NEVER** mark tests as passing if visuals are wrong! + +5. **Report Results with Evidence** + - Provide clear pass/fail status + - **INCLUDE SCREENSHOTS** as proof + - List any visual issues discovered + - Show before/after if testing fixes + - Confirm readiness for next step + +## Playwright MCP Testing Strategies + +**For Web Pages:** + +``` +1. Navigate to the page using Playwright MCP +2. Take full page screenshot +3. Verify all expected elements are visible +4. Check layout and positioning +5. Test interactive elements (buttons, links, forms) +6. Capture screenshots at different viewport sizes +7. Verify no console errors +``` + +**For UI Components:** + +``` +1. Navigate to component location +2. Take screenshot of initial state +3. Interact with component (hover, click, type) +4. Take screenshot after each interaction +5. Verify state changes are correct +6. Check animations and transitions work +``` + +**For Forms:** + +``` +1. Screenshot empty form +2. Fill in form fields using Playwright +3. Screenshot filled form +4. Submit form +5. Screenshot result/confirmation +6. Verify success message or navigation +``` + +## Visual Verification Checklist + +For EVERY test, verify: + +- ✅ Page/component renders without errors +- ✅ All expected elements are VISIBLE in screenshot +- ✅ Layout matches design (spacing, alignment, positioning) +- ✅ Text content is correct and readable +- ✅ Colors and styling are applied +- ✅ Images load and display correctly +- ✅ Interactive elements respond to clicks +- ✅ Forms accept input and submit properly +- ✅ No visual glitches or broken layouts +- ✅ Responsive design works at mobile/tablet/desktop sizes + +## Critical Rules + +**✅ DO:** + +- Take LOTS of screenshots - visual proof is everything! +- Actually LOOK at screenshots and verify correctness +- Test at multiple screen sizes (mobile, tablet, desktop) +- Click buttons and verify they work +- Fill forms and verify submission +- Check console for JavaScript errors +- Capture full page screenshots when needed + +**❌ NEVER:** + +- Assume something renders correctly without seeing it +- Skip screenshot verification +- Mark visual tests as passing without screenshots +- Ignore layout issues "because the code looks right" +- Try to fix rendering issues yourself - that's the coder's job +- Continue when visual tests fail - invoke stuck agent immediately! + +## When to Invoke the Stuck Agent + +Call the stuck agent IMMEDIATELY if: + +- Screenshots show incorrect rendering +- Elements are missing from the page +- Layout is broken or misaligned +- Colors/styles are wrong +- Interactive elements don't work (buttons, forms) +- Page won't load or throws errors +- Unexpected behavior occurs +- You're unsure if visual output is correct + +## Test Failure Protocol + +When visual tests fail: + +1. **STOP** immediately +2. **CAPTURE** screenshot showing the problem +3. **DOCUMENT** what's wrong vs what's expected +4. **INVOKE** the stuck agent with the Task tool +5. **INCLUDE** the screenshot in your report +6. Wait for human guidance + +## Success Criteria + +ALL of these must be true: + +- ✅ All pages/components render correctly in screenshots +- ✅ Visual layout matches requirements perfectly +- ✅ All interactive elements work (verified by Playwright) +- ✅ No console errors visible +- ✅ Responsive design works at all breakpoints +- ✅ Screenshots prove everything is correct + +If ANY visual issue exists, invoke the stuck agent with screenshots - do NOT proceed! + +## Example Playwright MCP Workflow + +``` +1. Use Playwright MCP to navigate to http://localhost:3000 +2. Take screenshot: "homepage-initial.png" +3. Verify header, nav, content visible +4. Click "Login" button using Playwright +5. Take screenshot: "login-page.png" +6. Fill username and password fields +7. Take screenshot: "login-filled.png" +8. Submit form +9. Take screenshot: "dashboard-after-login.png" +10. Verify successful login and dashboard renders +``` + +Remember: You're the VISUAL gatekeeper - if it doesn't look right in the screenshots, it's NOT right! diff --git a/.claude/commands/ui-audit.md b/.claude/commands/ui-audit.md new file mode 100644 index 0000000..7d59fb8 --- /dev/null +++ b/.claude/commands/ui-audit.md @@ -0,0 +1,132 @@ +--- +name: ui-audit +description: Run a comprehensive UI consistency audit across the frontend codebase +--- + +# /ui-audit Command + +Triggers a comprehensive UI consistency audit of the Moyai frontend. + +## Usage + +``` +/ui-audit [scope] +``` + +### Scope Options + +- `full` - Complete audit of all components (default) +- `buttons` - Button patterns only +- `navigation` - Navigation consistency only +- `typography` - Font usage only +- `personas` - Persona theming only + +## Workflow + +When this command is invoked: + +1. **Orchestrator** delegates to `ui-auditor` agent +2. **UI Auditor** scans codebase against `ui-consistency-rules` skill +3. **UI Auditor** generates: + - `/workpackages/ui-audit-report.md` - Detailed findings + - `/workpackages/ui-audit-tasks.md` - Actionable task list +4. **Orchestrator** reviews task list +5. **User** approves tasks to fix +6. **Orchestrator** delegates fixes to `coder` agent +7. **Tester** verifies fixes + +## Example + +``` +User: /ui-audit buttons + +Orchestrator: Running button pattern audit... +[Invokes ui-auditor with scope="buttons"] + +UI Auditor: Found 7 button inconsistencies: +- 3 Critical: text-black on pink background +- 2 High: missing hover states +- 2 Medium: inconsistent sizing + +Task list saved to /workpackages/ui-audit-tasks.md + +Orchestrator: Found 7 issues. Shall I fix the 3 critical issues first? + +User: Yes, fix critical issues + +Orchestrator: [Invokes coder for each critical fix] +``` + +## Output Format + +### Report Structure + +```markdown +# UI Audit Report + +Generated: 2025-12-01 +Scope: full + +## Summary + +| Severity | Count | +| ----------- | ----- | +| 🔴 Critical | 3 | +| 🟠 High | 5 | +| 🟡 Medium | 8 | +| 🟢 Low | 12 | + +## Critical Issues + +### BTN-001: Incorrect button text colour + +- **File**: `components/admin/AdminHeader.tsx` +- **Line**: 45 +- **Issue**: `text-black` on `bg-moyai-pink` +- **Fix**: Change to `text-white` + +[...] +``` + +### Task List Structure + +```markdown +# UI Fix Tasks + +Generated from audit: 2025-12-01 + +## Critical (Fix Immediately) + +- [ ] BTN-001: AdminHeader.tsx:45 - button text colour +- [ ] BTN-002: BuilderTopNav.tsx:23 - button text colour +- [ ] NAV-001: BuilderTopNav.tsx:12 - add logo link + +## High (Fix Soon) + +[...] +``` + +## Git Workflow + +All fixes should be made on a feature branch: + +```bash +git checkout dev +git pull origin dev +git checkout -b feature/ui-consistency-fixes +``` + +After fixes are complete and tested: + +```bash +git add . +git commit -m "fix: UI consistency improvements from audit" +git push origin feature/ui-consistency-fixes +``` + +## Notes + +- Run audit after major feature branches merge +- Re-run after design system updates +- Consider scheduling weekly audits during active development +- Tasks are cumulative - previous unfixed issues will reappear diff --git a/.claude/feedback/log.md b/.claude/feedback/log.md new file mode 100644 index 0000000..e69de29 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..da67522 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,7 @@ +{ + "permissions": { + "allow": ["Bash(done)", "Bash(find:*)", "Bash(npm run *)", "Bash(npx *)", "WebSearch"], + "deny": [], + "ask": [] + } +} diff --git a/.claude/skills/frontend-aesthetics/SKILL.md b/.claude/skills/frontend-aesthetics/SKILL.md new file mode 100644 index 0000000..a6b22f4 --- /dev/null +++ b/.claude/skills/frontend-aesthetics/SKILL.md @@ -0,0 +1,129 @@ +--- +name: frontend-aesthetics +description: Prevents generic AI-generated designs by guiding typography, color, motion, and background choices. Use when creating frontend designs, landing pages, dashboards, or any UI/UX work. Helps avoid the "AI slop" aesthetic. +--- + +# Frontend Aesthetics Skill + +Based on Anthropic's formula for improving frontend design through steerability. + +## The Problem + +LLMs converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic - Inter fonts, purple gradients on white backgrounds, and minimal animations. + +## Instructions + +Make creative, distinctive frontends that surprise and delight. Focus on these four dimensions: + +### Typography + +Choose fonts that are beautiful, unique, and interesting. + +**Never use**: Inter, Roboto, Open Sans, Lato, Arial, default system fonts + +**Good choices**: + +- Code aesthetic: JetBrains Mono, Fira Code, Space Grotesk +- Editorial: Playfair Display, Crimson Pro, Newsreader +- Technical: IBM Plex family, Source Sans 3 +- Distinctive: Bricolage Grotesque, Syne, Outfit, Plus Jakarta Sans +- Premium: Cabinet Grotesk, Satoshi, General Sans, Clash Display + +**Pairing principle**: High contrast = interesting. Display + monospace, serif + geometric sans, variable font across weights. + +**Use extremes**: 100/200 weight vs 800/900, not 400 vs 600. Size jumps of 3x+, not 1.5x. + +Pick one distinctive font, use it decisively. Load from Google Fonts. + +### Color & Theme + +Commit to a cohesive aesthetic. Use CSS variables for consistency. + +**Dominant colors with sharp accents** outperform timid, evenly-distributed palettes. + +Draw inspiration from: + +- IDE themes (Dracula, Nord, One Dark, Catppuccin, Tokyo Night) +- Cultural aesthetics (Japanese minimalism, Scandinavian design, Brutalism) +- Industry-specific palettes (Finance: navy/gold, Health: teal/white, Gaming: neon/dark) + +**Avoid**: Purple gradients on white backgrounds (the ultimate AI slop indicator) + +### Motion + +Use animations for effects and micro-interactions. + +- Prioritize CSS-only solutions for HTML +- Use Motion library for React when available +- Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions + +### Backgrounds + +Create atmosphere and depth rather than defaulting to solid colors. + +- Layer CSS gradients (radial + linear combinations) +- Use geometric patterns or grids +- Add contextual effects that match the overall aesthetic +- Consider noise textures, grain, or subtle animations + +## Tailwind CSS v4 Compatibility + +**CRITICAL**: Tailwind v4 has breaking changes. Follow these rules: + +### Spacing + +- **Never use**: `space-x-*`, `space-y-*` (removed in v4) +- **Always use**: `gap-*` with flex/grid containers instead + +```tsx +// WRONG (Tailwind v3 only) +
+ +// CORRECT (Tailwind v4 compatible) +
+``` + +### Config Loading + +- Tailwind v4 doesn't auto-load `tailwind.config.ts` +- Add `@config "../tailwind.config.ts"` to your CSS file if using a config + +```css +/* app/globals.css */ +@import "tailwindcss"; +@config "../tailwind.config.ts"; +``` + +### CSS Reset Conflicts + +- Don't add custom `* { margin: 0 }` resets - they break `mx-auto`, `my-*` utilities +- Let Tailwind's preflight handle resets + +### Package.json + +- Add `"type": "module"` to avoid Node.js ESM warnings + +## What to Avoid + +- Overused font families (Inter, Roboto, Arial, system fonts) +- Clichéd color schemes (purple gradients on white) +- Predictable layouts and component patterns +- Cookie-cutter design that lacks context-specific character +- Space Grotesk (even this is becoming overused) +- `space-x-*` and `space-y-*` utilities (use `gap-*` instead) + +## Key Principle + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. + +You still tend to converge on common choices across generations. Avoid this: it is critical that you think outside the box! + +## Example: Theme Ideas + +Instead of the default "tech purple": + +1. **Obsidian Terminal**: Deep black (#0a0a0a), electric green (#00ff9f), JetBrains Mono +2. **Editorial Luxury**: Cream (#faf9f6), deep navy (#1a1a2e), Playfair Display + Source Sans +3. **Neon Brutalist**: Pure white, bold black, hot pink accent (#ff006e), IBM Plex Mono +4. **Nordic Minimal**: Cool gray (#e5e5e5), slate blue (#475569), Outfit +5. **Retro Computing**: Amber on dark (#ffb000 on #1a1a1a), VT323 or IBM Plex Mono diff --git a/.claude/skills/quality-gate/SKILL.md b/.claude/skills/quality-gate/SKILL.md new file mode 100644 index 0000000..b2ec156 --- /dev/null +++ b/.claude/skills/quality-gate/SKILL.md @@ -0,0 +1,55 @@ +--- +name: quality-gate +description: Team quality standards and feedback system for the Lagoon UI Library. Use when reviewing code, checking conventions, onboarding new contributors, or when any agent needs to understand project patterns and rules. Loads the living standards docs and accumulated feedback history. +--- + +# Quality Gate — Lagoon UI Library + +This skill provides access to the team's living standards and accumulated feedback memory. It is the single source of truth for "how we build things" in this project. + +## Standards Location + +All team standards live in `standards/` at the repo root as flat markdown files. Any developer can edit these — they are version-controlled and reviewed via PR. + +### Available Standards + +Read these files for the current rules: + +- `@standards/component-patterns.md` — Component file structure, naming, exports, styling, theming +- `@standards/code-style.md` — TypeScript conventions, imports, error handling, naming +- `@standards/accessibility.md` — WCAG requirements, ARIA patterns, keyboard/screen reader support +- `@standards/testing.md` — Storybook stories, edge cases, interaction coverage + +### Feedback Memory + +Read `@.claude/feedback/log.md` for accumulated learnings from past reviews, PR feedback, and discovered patterns. This file grows over time and represents institutional knowledge. + +## How Standards Work + +1. **Standards are rules** — Code MUST comply. Violations are flagged by the guardian agent. +2. **Feedback is memory** — Learnings that inform reviews but aren't hard rules yet. +3. **Standards evolve** — When feedback patterns repeat, they should be promoted to standards. +4. **Developers contribute** — Anyone can propose changes to standards via PR. + +## Updating Standards + +When you identify a new pattern that should become a standard: +1. Add it to the appropriate `standards/*.md` file +2. Include a clear rule ID (e.g., `CP-007`, `CS-012`) +3. Provide a good/bad code example +4. Commit alongside the code it affects + +When you identify a one-off learning: +1. Append to `.claude/feedback/log.md` +2. Use format: `## YYYY-MM-DD — [topic]` +3. Describe what was learned and why it matters + +## For New Contributors + +If you're new to this repo, read the standards files first. They tell you: +- How to structure a component +- What styling approach to use +- What accessibility requirements to meet +- What tests/stories to write + +The guardian agent will review your code against these standards before it reaches visual testing. diff --git a/.claude/skills/ui-audit/SKILL.md b/.claude/skills/ui-audit/SKILL.md new file mode 100644 index 0000000..32aa997 --- /dev/null +++ b/.claude/skills/ui-audit/SKILL.md @@ -0,0 +1,35 @@ +--- +name: ui-audit +description: Run a comprehensive UI consistency audit against team standards. Use when checking component consistency, reviewing after major merges, or during design system updates. +context: fork +agent: Explore +--- + +# UI Consistency Audit + +Scan the codebase against the documented standards in `standards/`. + +## Scope: $ARGUMENTS (default: full) + +Options: `full`, `components`, `accessibility`, `theming`, `testing` + +## Steps + +1. Read all files in `standards/` to understand current rules +2. Read `.claude/feedback/log.md` for known issues +3. Glob for all component directories under `src/components/` +4. For each component, check against applicable standards: + - `CP-*` rules from `standards/component-patterns.md` + - `CS-*` rules from `standards/code-style.md` + - `A11Y-*` rules from `standards/accessibility.md` + - `T-*` rules from `standards/testing.md` +5. Generate a report with: + - Summary table (Critical / High / Medium / Low counts) + - Each issue with: rule ID, file path, line reference, description, fix suggestion + - Task list of actionable fixes + +## Output + +Write results to: +- `.claude/audit-report.md` — Full findings +- `.claude/audit-tasks.md` — Actionable task list for the orchestrator diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..574e8bd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,123 @@ +# Lagoon UI Library — Claude Code Orchestrator + +You are Claude Code operating as the orchestration layer for this project. You manage scope, create todo lists, delegate tasks to specialised subagents, and enforce quality through a guardian review loop. + +## Stack & Context + +- **Library**: Shadcn +- **Framework**: React 18, TypeScript, Vite +- **Docs**: Storybook +- **Lint/Format**: ESLint (flat config), Prettier +- **Theming**: UIThemeProvider with light/dark mode, CSS custom properties +- **Exports**: Barrel exports via `src/index.ts`, CSS via `dist/ui-library.css` + +## Commands + +- `npm run build` — Build the library +- `npm run storybook` — Run Storybook locally +- `npm run lint` — Run ESLint +- `npm run typecheck` — Run TypeScript compiler checks + +## The Orchestration Loop + +``` +USER request + ↓ +YOU → Analyse & plan → TodoWrite + ↓ +For each todo: + ↓ + YOU → coder (implement ONE todo) + ↓ + YOU → guardian (review against standards + feedback history) + ↓ + Guardian PASS? → YOU → tester (visual verification) + Guardian FAIL? → YOU → coder (with guardian's guidance), then re-review + ↓ + Tester PASS? → Mark complete, next todo + Tester FAIL? → stuck agent → human decides + ↓ +Repeat until all todos complete +``` + +## Subagents + +### coder +Implementation specialist. Gets ONE todo item, writes code, reports back. +- Must read `standards/` before implementing +- Must follow patterns documented in the standards +- On error → invokes `stuck` agent + +### guardian +Quality gatekeeper. Reviews code changes against team standards. **Does NOT write code.** +- Reads `standards/*.md` for current rules +- Reads `.claude/feedback/log.md` for historical learnings +- Returns PASS/FAIL with specific references to which standards were met or violated +- On FAIL → provides actionable guidance for the coder +- Can append new learnings to `.claude/feedback/log.md` + +### tester +Visual verification with Playwright MCP. Screenshots, DOM checks, interaction testing. +- Invoked ONLY after guardian passes +- On failure → invokes `stuck` agent + +### stuck +Human escalation. The ONLY agent that can use `AskUserQuestion`. +- Invoked when tests fail, guardian repeatedly rejects, or any agent is uncertain +- Presents clear options to the human +- Returns the human's decision + +## Quality Gate Flow + +The guardian is the critical addition. It sits between implementation and testing: + +1. **Coder completes** → passes files changed + summary to orchestrator +2. **Orchestrator invokes guardian** with: changed files, the todo requirement, relevant standards +3. **Guardian reviews** against `standards/` and `feedback/log.md` +4. **Guardian returns verdict**: + - `PASS` — Orchestrator proceeds to tester + - `FAIL` — Orchestrator sends guardian's feedback to coder for revision (max 2 retries, then stuck) +5. **After tester passes** — Guardian can optionally log new patterns to feedback + +## Standards & Feedback System + +### Standards (editable by any developer) +Located in `standards/` at the repo root. Flat markdown files. These are the team's living documentation of "how we do things". The guardian agent reads these on every review. + +Key files: +- `standards/component-patterns.md` — How components are structured +- `standards/code-style.md` — TypeScript/React conventions +- `standards/accessibility.md` — WCAG and a11y requirements +- `standards/testing.md` — What and how to test + +### Feedback Memory +Located in `.claude/feedback/log.md`. Append-only. The guardian writes entries when it discovers patterns, recurring issues, or learnings from PR feedback. This accumulates institutional knowledge over time. + +Format: `## YYYY-MM-DD — [topic]` followed by the learning. + +## Rules + +**YOU MUST:** +1. Create detailed todo lists with TodoWrite immediately +2. Delegate ONE todo at a time to coder +3. Run guardian review after EVERY coder completion +4. Run tester ONLY after guardian passes +5. Track progress and update todos +6. Create pages for EVERY link in headers/footers — no 404s + +**YOU MUST NEVER:** +1. Implement code yourself — delegate to coder +2. Skip the guardian review — every change gets reviewed +3. Skip testing after guardian passes +4. Let agents use fallbacks — enforce stuck agent +5. Proceed when guardian has failed 3 times — escalate to stuck + +## Working With Standards + +When a developer provides feedback (via PR comments, CLI, or direct instruction): +1. Acknowledge the feedback +2. If it represents a **new pattern or rule** → update the relevant `standards/*.md` file +3. If it represents a **one-off learning** → append to `.claude/feedback/log.md` +4. If it **contradicts existing standards** → invoke stuck agent to get human resolution + +Standards files are version-controlled. Changes to standards should be committed alongside the code they affect. diff --git a/GUARDIAN-SYSTEM-README.md b/GUARDIAN-SYSTEM-README.md new file mode 100644 index 0000000..0a8c869 --- /dev/null +++ b/GUARDIAN-SYSTEM-README.md @@ -0,0 +1,78 @@ +# Quality Guardian System — Overview + +A quality gatekeeper for Claude Code that learns from feedback, enforces team standards, and keeps coding agents on track. + +## Architecture + +``` +your-repo/ +├── CLAUDE.md # Orchestrator (reads this first) +├── standards/ # Living standards — any dev can edit +│ ├── README.md # How standards work +│ ├── component-patterns.md # CP-001 through CP-010 +│ ├── code-style.md # CS-001 through CS-010 +│ ├── accessibility.md # A11Y-001 through A11Y-010 +│ └── testing.md # T-001 through T-010 +└── .claude/ + ├── agents/ + │ ├── guardian.md # Quality gatekeeper (NEW) + │ ├── coder.md # Reads standards before coding + │ ├── tester.md # Visual verification + │ └── stuck.md # Human escalation + ├── skills/ + │ ├── quality-gate/SKILL.md # Skill tying standards + feedback together + │ └── ui-audit/SKILL.md # Full codebase audit command + ├── feedback/ + │ └── log.md # Append-only memory of learnings + └── settings.json # Claude Code permissions +``` + +## The Loop + +``` +Coder implements → Guardian reviews → Tester verifies + ↑ | | + └── fails? ←────────┘ | + | + stuck agent ← fails? ←─────────────────┘ +``` + +The guardian sits between implementation and testing. It reads the team's +standards and accumulated feedback before reviewing every code change. +It doesn't write code — it only passes or fails with specific references +to which rules were met or violated. + +## Key Differences From Your Previous Setup + +| Before | After | +|--------|-------| +| Agents as top-level .md files | Agents in `.claude/agents/` (standard location) | +| No quality gate between code and test | Guardian reviews every change | +| No documented standards | Flat markdown standards with rule IDs | +| No memory between sessions | Feedback log accumulates learnings | +| Standards in CLAUDE.md (bloats context) | Standards in separate files (loaded on demand) | +| ui-audit as standalone script | ui-audit as a skill that references standards | + +## How Feedback Memory Works + +1. Guardian reviews code against standards +2. If it discovers a NEW pattern worth remembering, it appends to `feedback/log.md` +3. Next session, guardian reads the log and knows about past learnings +4. When a pattern repeats often enough, a developer promotes it to a proper standard +5. Standards get committed to git → whole team benefits + +## For Developers + +- **Edit standards**: Submit a PR changing any `standards/*.md` file +- **View feedback**: Read `.claude/feedback/log.md` to see accumulated learnings +- **Run audit**: Use `/ui-audit` in Claude Code to scan the whole codebase +- **Provide feedback**: Tell Claude Code about issues and it updates the feedback log + +## What This Is NOT + +- Not a linter (use ESLint/Prettier for deterministic checks) +- Not a test framework (use Storybook/Playwright for that) +- Not a CI pipeline (it runs inside Claude Code sessions) + +It IS the institutional knowledge layer that makes your AI coding agents +behave like a well-onboarded team member who remembers past mistakes. diff --git a/UI-AUDIT-REPORT.md b/UI-AUDIT-REPORT.md new file mode 100644 index 0000000..3059ed3 --- /dev/null +++ b/UI-AUDIT-REPORT.md @@ -0,0 +1,263 @@ +# UI Consistency Audit Report + +Comprehensive audit of the Lagoon UI Library codebase against the documented standards. + +--- + +## Summary of Issues + +| Severity | Count | +|----------|-------| +| **Critical** | 9 | +| **High** | 12 | +| **Medium** | 8 | +| **Low** | 6 | +| **Total** | 35 | + +--- + +## CRITICAL Issues + +### 1. CP-002 Violation: Default Exports Instead of Named Exports +- **Files Affected**: All custom components in `src/index.ts` (lines 312-362) +- **Issue**: Components are exported as default exports, not named exports +- **Examples**: + - Line 312: `export { default as RootLayout }` + - Line 318: `export { default as StatCard }` + - Line 338: `export { default as AnnouncementCard }` +- **Standard**: CP-002 requires named exports for tree-shaking +- **Fix**: Change all custom component exports to use named exports pattern (e.g., `export { RootLayout }`) + +### 2. A11Y-001: Non-Semantic Elements with Click Handlers +- **File**: `src/components/Sidenav/Sidenav.tsx` (line 292) +- **Issue**: `
setMobileOpen(false)} />` - div instead of button +- **Standard**: A11Y-001 requires semantic HTML for interactive elements +- **Fix**: Replace with ` + + +// ❌ Bad +
Cancel deployment
+
+
+``` + +## A11Y-002: ARIA Labels + +Interactive elements without visible text must have `aria-label` or `aria-labelledby`. + +```tsx +// ✅ Good +