qualia-framework-v2 2.4.0 → 2.5.0

package/CLAUDE.md

@@ -51,9 +51,10 @@ No accumulated garbage. No context rot.
 ## Quality Gates (always active)
 - **Frontend guard:** Read .planning/DESIGN.md before any frontend changes
 - **Deploy guard:** tsc + lint + build + tests must pass before deploy
-- **Branch guard:** Employees cannot push to main
-- **Env guard:** Never edit .env files
-- **Intent verification:** Confirm before modifying 3+ files
+- **Branch guard:** Employees cannot push to main (OWNER can)
+- **Env guard:** Employees cannot edit .env files (OWNER can — add keys, configure secrets directly)
+- **Sudo guard:** Employees cannot run sudo (OWNER can)
+- **Intent verification:** Confirm before modifying 3+ files (OWNER: just do it)
 
 ## Tracking
 `.planning/tracking.json` is updated on every push. The ERP reads it via git.

package/agents/builder.md

@@ -83,10 +83,28 @@ Rule of thumb: If you can explain the change in one sentence in a commit message
    - Always check auth server-side
    - Enable RLS on every table
    - Validate input with Zod at system boundaries
-5. **Frontend standards:**
-   - Distinctive fonts (not Inter/Arial)
-   - Cohesive color palette with sharp accents
-   - CSS transitions, subtle animations
-   - Full-width layouts, no hardcoded max-width
+5. **Frontend standards (mandatory for any .tsx/.jsx/.css file):**
+   - Before writing any frontend code: read `.planning/DESIGN.md` if it exists — it's the design source of truth
+   - If no DESIGN.md, apply rules from `rules/frontend.md` (Qualia defaults)
+   - Distinctive fonts (never Inter, Roboto, Arial, system-ui, Space Grotesk)
+   - Cohesive color palette via CSS variables — sharp accent for CTAs
+   - All text: WCAG AA contrast (4.5:1 normal, 3:1 large text)
+   - Full-width fluid layouts — no hardcoded max-width caps
+   - Every interactive element needs ALL states: hover, focus (visible ring), active, disabled, loading, error, empty
+   - Semantic HTML (`nav`, `main`, `section`, `article`) — not div soup
+   - Keyboard accessible: Tab, Enter, Escape, Arrow keys work
+   - Touch targets: 44px minimum
+   - Form inputs: visible labels (not placeholder-only), error messages with `aria-describedby`
+   - Motion: 150–200ms hover, 250ms expand, stagger children on load, respect `prefers-reduced-motion`
+   - Mobile-first responsive: stack on mobile, expand on desktop, fluid typography
+   - Skip link on every page, heading hierarchy (one h1, sequential order)
+   - No emoji as icons — use SVGs
+   - `cursor: pointer` on all clickable elements
 6. **No empty catch blocks.** At minimum, log the error.
 7. **No dangerouslySetInnerHTML.** No eval().
+8. **React/Next.js performance:**
+   - Server Components by default — only `'use client'` for state/effects/browser APIs
+   - Fetch data in parallel (`Promise.all`), not sequential waterfalls
+   - Import specific functions, not entire libraries — avoid barrel file re-exports
+   - Use `next/image` with explicit width/height
+   - Use `next/dynamic` for heavy below-fold components

package/agents/planner.md

@@ -85,6 +85,20 @@ If a task involves a library or API you're unsure about, use WebFetch to check t
 
 **Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
 
+## Design-Aware Planning
+
+When a phase involves frontend work (pages, components, layouts, UI):
+
+1. **Check for `.planning/DESIGN.md`** — if it exists, reference it in task Context fields: `@.planning/DESIGN.md`
+2. **If no DESIGN.md and this is Phase 1** — add a Task 1 (Wave 1) to create it:
+   - Generate `.planning/DESIGN.md` from the design direction in PROJECT.md
+   - Use the template at `templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
+   - Done when: DESIGN.md exists with concrete CSS variable values (not placeholders)
+3. **Include design criteria in "Done when"** for frontend tasks:
+   - Not just "page renders" but "page renders with design system typography, proper color palette, all interactive states (hover/focus/loading/error/empty), semantic HTML, keyboard accessible"
+   - Include responsive: "works on 375px mobile and 1440px desktop"
+4. **Reference `@.planning/DESIGN.md`** in the Context field of every frontend task so builders read it before coding
+
 ## Rules
 
 1. **Plans complete within ~50% context.** More plans with smaller scope = consistent quality. 2-3 tasks per plan is ideal.

package/agents/verifier.md

@@ -148,6 +148,68 @@ Phase verdict:
 
 Never round up. A PARTIAL is not a PASS. The goal of verification is to catch the work that LOOKS done but ISN'T.
 
+## Design Verification (for phases with frontend work)
+
+If the phase involved UI/frontend tasks, add a **Design Quality** section to the report:
+
+### Check 1: Design System Compliance
+```bash
+# Generic fonts (should NOT appear)
+grep -rn "font-family.*Inter\|font-family.*Roboto\|font-family.*Arial\|fontFamily.*Inter\|fontFamily.*Roboto" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null
+grep -rn "font-sans\|font-inter" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null
+
+# Hardcoded max-width containers (should NOT appear)
+grep -rn "max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-width.*1280\|max-w-7xl" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null
+
+# Hardcoded colors instead of CSS variables (check density)
+grep -rn "color:.*#\|background:.*#\|bg-\[#" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | wc -l
+```
+
+### Check 2: Accessibility Basics
+```bash
+# Images without alt text
+grep -rn "<img" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "alt="
+
+# Inputs without labels
+grep -rn "<input\|<textarea\|<select" --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "aria-label\|aria-labelledby\|id=" | head -10
+
+# outline:none without replacement focus style
+grep -rn "outline.*none\|outline-none" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "focus-visible\|focus:\|focus-within"
+
+# Missing lang attribute
+grep -rn "<html" --include="*.tsx" --include="*.jsx" app/ 2>/dev/null | grep -v "lang="
+
+# Heading hierarchy — check for h1 count
+grep -rn "<h1\|<H1" --include="*.tsx" --include="*.jsx" app/ 2>/dev/null | wc -l
+```
+
+### Check 3: Interactive States
+```bash
+# Buttons/links without hover/focus styles — spot check
+grep -rn "<button\|<Button\|<a " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | head -5
+# Verify these have hover/focus transitions in their styling
+
+# Loading states — check for skeleton/spinner usage in pages with data fetching
+grep -rn "fetch\|useQuery\|useSWR\|getServerSide\|async.*Component" --include="*.tsx" app/ 2>/dev/null | head -5
+grep -rn "loading\|skeleton\|spinner\|Spinner\|Loading" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
+
+# Empty states — check lists/tables have empty handling
+grep -rn "\.length.*===.*0\|\.length.*>.*0\|isEmpty\|no.*results\|no.*data" --include="*.tsx" app/ components/ 2>/dev/null | wc -l
+```
+
+### Check 4: Responsive
+```bash
+# Check for responsive utilities or media queries
+grep -rn "sm:\|md:\|lg:\|xl:\|@media" --include="*.tsx" --include="*.jsx" --include="*.css" app/ components/ src/ 2>/dev/null | wc -l
+# If 0 responsive declarations across multiple components → FAIL
+```
+
+### Scoring Design
+- 0 generic fonts + 0 hardcoded max-widths + colors via variables = **PASS**
+- Accessibility basics all present = **PASS**
+- States and responsive present = **PASS**
+- Any category failing = add to **Gaps** list with specific file:line
+
 ## Rules
 
 1. **Never trust summaries.** Always grep the code yourself.
@@ -156,3 +218,4 @@ Never round up. A PARTIAL is not a PASS. The goal of verification is to catch th
 4. **Stubs are failures.** `// TODO: implement` means the task wasn't done.
 5. **Empty catch blocks are failures.** They hide real errors.
 6. **Run tsc.** If TypeScript doesn't compile, nothing works.
+7. **Design debt is a gap.** Generic fonts, missing states, inaccessible components, and hardcoded layouts are failures — not "nice to haves."

package/bin/install.js

@@ -253,6 +253,16 @@ async function main() {
   };
   fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
 
+  // ─── ERP API key (for report uploads) ──────────────────
+  log(`${WHITE}ERP integration${RESET}`);
+  const erpKeyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+  if (!fs.existsSync(erpKeyFile)) {
+    fs.writeFileSync(erpKeyFile, "qualia-claude-2026", { mode: 0o600 });
+    ok(".erp-api-key (created)");
+  } else {
+    ok(".erp-api-key (exists)");
+  }
+
   // ─── Configure settings.json ───────────────────────────
   console.log("");
   log(`${WHITE}Configuring settings.json...${RESET}`);
@@ -322,6 +332,11 @@ async function main() {
       {
         matcher: "Bash",
         hooks: [
+          {
+            type: "command",
+            command: `${hd}/auto-update.sh`,
+            timeout: 5,
+          },
           {
             type: "command",
             if: "Bash(git push*)",
@@ -414,7 +429,7 @@ async function main() {
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
@@ -425,11 +440,11 @@ async function main() {
   console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
   console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
   console.log(`  Agents:       ${WHITE}3${RESET} ${DIM}(planner, builder, verifier)${RESET}`);
-  console.log(`  Hooks:        ${WHITE}6${RESET} ${DIM}(branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
-  console.log(`  Rules:        ${WHITE}3${RESET} ${DIM}(security, frontend, deployment)${RESET}`);
+  console.log(`  Hooks:        ${WHITE}7${RESET} ${DIM}(auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
+  console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
   console.log(`  Scripts:      ${WHITE}1${RESET} ${DIM}(state.js — state machine)${RESET}`);
   console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
-  console.log(`  Templates:    ${WHITE}4${RESET}`);
+  console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);
   console.log(`  CLAUDE.md:    ${GREEN}✓${RESET} ${DIM}(${member.role})${RESET}`);
 

package/hooks/auto-update.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Qualia auto-update — checks once per day, updates silently in background
+# Runs as PreToolUse hook. Cached so it's a no-op most of the time.
+
+CLAUDE_DIR="$HOME/.claude"
+CACHE_FILE="$CLAUDE_DIR/.qualia-last-update-check"
+CONFIG_FILE="$CLAUDE_DIR/.qualia-config.json"
+LOCK_FILE="$CLAUDE_DIR/.qualia-updating"
+MAX_AGE=86400  # 24 hours in seconds
+
+# Exit fast if recently checked (most common path — single stat call)
+if [ -f "$CACHE_FILE" ]; then
+  LAST_CHECK=$(cat "$CACHE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  AGE=$((NOW - LAST_CHECK))
+  if [ "$AGE" -lt "$MAX_AGE" ]; then
+    exit 0
+  fi
+fi
+
+# Exit if already updating
+[ -f "$LOCK_FILE" ] && exit 0
+
+# Update cache timestamp immediately (prevents concurrent checks)
+date +%s > "$CACHE_FILE"
+
+# Run the actual check + update in background so we don't block the user
+(
+  trap 'rm -f "$LOCK_FILE"' EXIT
+  touch "$LOCK_FILE"
+
+  # Get installed version
+  INSTALLED=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$CONFIG_FILE','utf8')).version)}catch{console.log('0.0.0')}" 2>/dev/null)
+  [ -z "$INSTALLED" ] && INSTALLED="0.0.0"
+
+  # Get latest from npm (5s timeout)
+  LATEST=$(npm view qualia-framework-v2 version 2>/dev/null)
+  [ -z "$LATEST" ] && exit 0
+
+  # Compare versions
+  NEEDS_UPDATE=$(node -e "
+    const a='$LATEST'.split('.').map(Number), b='$INSTALLED'.split('.').map(Number);
+    for(let i=0;i<3;i++){if(a[i]>b[i]){console.log('yes');process.exit()}if(a[i]<b[i]){process.exit()}}
+  " 2>/dev/null)
+
+  if [ "$NEEDS_UPDATE" = "yes" ]; then
+    # Get saved install code
+    CODE=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('$CONFIG_FILE','utf8')).code)}catch{}" 2>/dev/null)
+    [ -z "$CODE" ] && exit 0
+
+    # Run silent update
+    npx qualia-framework-v2@latest install <<< "$CODE" > /dev/null 2>&1
+  fi
+) &
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"

package/rules/design-reference.md

@@ -0,0 +1,179 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss"]
+---
+
+# Design Reference — Deep Specs
+
+Detailed values for motion, accessibility, and responsive design. Loaded alongside `frontend.md` for frontend work.
+
+## Motion Specification
+
+### Duration Table
+
+| Action | Duration | Easing | Example |
+|--------|----------|--------|---------|
+| Micro-feedback | 100ms | ease-out | Button press, checkbox toggle |
+| Hover/focus | 150ms | ease-out | Color change, underline appear |
+| Small reveal | 200ms | ease-out | Tooltip show, dropdown open |
+| Expand/collapse | 250ms | ease-in-out | Accordion, panel slide |
+| Page element enter | 300ms | cubic-bezier(0, 0, 0.2, 1) | Card fade-in, section reveal |
+| Page transition | 400ms | cubic-bezier(0.4, 0, 0.2, 1) | Route change, modal open |
+| Complex orchestration | 500–800ms | staggered | Page load sequence |
+
+### Easing Curves (CSS)
+
+```css
+--ease-standard: cubic-bezier(0.4, 0, 0.2, 1);   /* General movement */
+--ease-decelerate: cubic-bezier(0, 0, 0.2, 1);     /* Enter screen */
+--ease-accelerate: cubic-bezier(0.4, 0, 1, 1);     /* Exit screen */
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);  /* Playful bounce */
+--ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1);   /* Subtle shift */
+```
+
+### Stagger Pattern
+
+```css
+/* Stagger children on page load */
+@keyframes fadeUp {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.stagger > * {
+  animation: fadeUp 300ms var(--ease-decelerate) both;
+}
+.stagger > *:nth-child(1) { animation-delay: 0ms; }
+.stagger > *:nth-child(2) { animation-delay: 60ms; }
+.stagger > *:nth-child(3) { animation-delay: 120ms; }
+.stagger > *:nth-child(4) { animation-delay: 180ms; }
+.stagger > *:nth-child(5) { animation-delay: 240ms; }
+```
+
+### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+## WCAG AA Checklist
+
+### Perceivable
+- [ ] All images have descriptive alt text (decorative: `alt=""` + `aria-hidden="true"`)
+- [ ] Color contrast: 4.5:1 normal text, 3:1 large text (18px+ bold / 24px+)
+- [ ] Color contrast: 3:1 for UI components and graphical objects
+- [ ] Information not conveyed by color alone — icons, text, patterns as supplements
+- [ ] Video/audio: captions or transcripts where applicable
+- [ ] Text resizable to 200% without loss of content
+- [ ] Content reflows at 320px viewport width (no horizontal scroll)
+
+### Operable
+- [ ] All functionality available via keyboard (Tab, Enter, Space, Escape, Arrows)
+- [ ] No keyboard traps (except intentional focus traps in modals)
+- [ ] Visible focus indicator: 2px+ ring, contrasting color, no `outline: none` without replacement
+- [ ] Skip navigation link as first focusable element
+- [ ] Touch targets: 44x44px minimum (48x48px recommended)
+- [ ] No content that flashes more than 3 times per second
+- [ ] Page titles are descriptive and unique
+
+### Understandable
+- [ ] Form inputs have visible labels (not placeholder-only)
+- [ ] Error messages identify the field and describe the error
+- [ ] Error suggestions explain how to fix the problem
+- [ ] Required fields marked with `aria-required="true"` and visual indicator
+- [ ] Language set: `<html lang="en">`
+- [ ] Consistent navigation across pages
+- [ ] No unexpected context changes on input
+
+### Robust
+- [ ] Valid HTML (no duplicate IDs, proper nesting)
+- [ ] ARIA used correctly: `role`, `aria-label`, `aria-describedby`, `aria-expanded`, `aria-hidden`
+- [ ] Dynamic content: `aria-live="polite"` for updates, `aria-live="assertive"` for errors
+- [ ] Custom components have proper roles and keyboard interaction patterns
+
+## Responsive Breakpoints
+
+### Strategy: Mobile-First with Fluid Scaling
+
+```css
+/* Base: mobile (320px–639px) */
+/* sm: 640px+ — large phone / small tablet */
+/* md: 768px+ — tablet */
+/* lg: 1024px+ — laptop */
+/* xl: 1280px+ — desktop */
+/* 2xl: 1536px+ — large desktop */
+```
+
+### Common Patterns
+
+| Pattern | Mobile | Tablet | Desktop |
+|---------|--------|--------|---------|
+| Navigation | Hamburger + drawer | Hamburger or condensed | Full horizontal |
+| Grid | 1 column | 2 columns | 3–4 columns |
+| Sidebar | Hidden, overlay | Collapsible | Always visible |
+| Hero | Stacked, full-width | Stacked, padded | Side-by-side |
+| Table | Card view or scroll | Scroll with sticky col | Full table |
+| Modal | Full screen | Centered, 80% width | Centered, max-width |
+| Form | Single column | Single column | Two column for long forms |
+
+### Fluid Typography
+
+```css
+/* Body */
+font-size: clamp(1rem, 0.5rem + 1.5vw, 1.125rem);
+
+/* H1 */
+font-size: clamp(2rem, 1rem + 3vw, 3.75rem);
+
+/* H2 */
+font-size: clamp(1.5rem, 0.75rem + 2.25vw, 2.5rem);
+
+/* H3 */
+font-size: clamp(1.25rem, 0.75rem + 1.5vw, 1.875rem);
+```
+
+### Fluid Spacing
+
+```css
+/* Section padding */
+padding-inline: clamp(1rem, 5vw, 4rem);
+padding-block: clamp(2rem, 8vw, 6rem);
+
+/* Component gap */
+gap: clamp(1rem, 3vw, 2rem);
+```
+
+## React/Next.js Performance (Critical)
+
+### Priority 1: Eliminate Waterfalls
+- Fetch data in parallel (`Promise.all`), not sequentially
+- Use Suspense boundaries to stream content progressively
+- Prefetch data on hover/focus for anticipated navigation
+- Colocate data fetching with the component that needs it
+
+### Priority 2: Bundle Size
+- Import specific functions, not entire libraries (`import { format } from 'date-fns'`)
+- Avoid barrel files (index.ts re-exports) — import directly from source
+- Use `next/dynamic` for heavy components not needed on initial load
+- Lazy-load below-fold content and non-critical features
+
+### Priority 3: Rendering
+- Server Components by default — only add `'use client'` when needed (state, effects, browser APIs)
+- Avoid unnecessary `useEffect` — derive values during render when possible
+- Use CSS `content-visibility: auto` for long scrollable lists
+- Images: `next/image` with proper `width`/`height` to prevent layout shift
+
+## Compound Component Patterns
+
+When building reusable components:
+- **No boolean prop proliferation** (`isCompact`, `showHeader`, `isRounded`) — use composition instead
+- Compound components: `<Select>`, `<Select.Trigger>`, `<Select.Content>` with shared context
+- Explicit variants: `<Alert.Destructive>` instead of `<Alert isDestructive>`
+- Children over render props: `children` for composition, not `renderHeader`/`renderFooter`
+- React 19: use `use()` instead of `useContext()`, skip `forwardRef` (ref is a regular prop)

package/rules/frontend.md

@@ -2,31 +2,124 @@
 globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "tailwind.config.*"]
 ---
 
-# Frontend Aesthetics
+# Frontend Design Standards
 
-- Distinctive fonts (not Inter/Arial)
-- Cohesive color palette with sharp accents
-- CSS transitions, staggered animations
-- Layered backgrounds, subtle gradients
-- Avoid: card grids, generic heroes, blue-purple gradients
-- Full-width layouts — no hardcoded 1200px/1280px caps. Use fluid widths that fill the viewport with sensible padding.
+These are Qualia brand standards — mandatory for every frontend component. Not suggestions.
 
-Note: Qualia agents MUST follow these rules when building any frontend component. These are Fawzi's brand standards, not suggestions.
+## Typography
+
+**Never use:** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk (overused by AI).
+
+- Pair a distinctive display font with a refined body font
+- Type scale: 12 / 14 / 16 / 18 / 20 / 24 / 30 / 36 / 48 / 60 / 72
+- Body: 16px min, line-height 1.5–1.7
+- Headings: line-height 1.1–1.3, letter-spacing -0.02em for large sizes
+- Weight hierarchy: Regular (400) body, Medium (500) labels, Semibold (600) headings, Bold (700) display
+- Prose max-width: 65ch. Everything else: fluid full-width
+
+## Color
+
+- Commit to a cohesive palette — define in CSS variables
+- One dominant brand color with sharp accent for CTAs
+- Never: blue-purple gradients, rainbow palettes, gray-on-gray
+- Dark mode: not just inverted — rethink surfaces, reduce contrast slightly
+- Semantic colors: success (green), warning (amber), error (red), info (blue) — always with non-color indicator too
+- All text must meet **WCAG AA** contrast: 4.5:1 normal text, 3:1 large text (18px+ bold or 24px+)
+
+## Layout
+
+- Full-width layouts — no hardcoded `max-width: 1200px` or `1280px` caps
+- Fluid padding: `clamp(1rem, 5vw, 4rem)` for horizontal, generous vertical
+- 8px spacing grid: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96
+- Tight spacing within groups, generous between sections
+- Asymmetry > symmetry. Overlap, diagonal flow, grid-breaking elements when appropriate
+- No card grids — use varied layouts with visual hierarchy
+- No generic hero sections — make them distinctive and purposeful
+
+## Motion & Animation
+
+- Hover/focus transitions: 150–200ms ease-out
+- Expand/collapse: 200–300ms ease-in-out
+- Page transitions: 300–500ms ease-out
+- Staggered entrance animations: 50–80ms delay between items
+- **Always** respect `prefers-reduced-motion: reduce` — disable non-essential animation
+- Easing: `cubic-bezier(0.4, 0, 0.2, 1)` (standard), `cubic-bezier(0, 0, 0.2, 1)` (decelerate), `cubic-bezier(0.4, 0, 1, 1)` (accelerate)
+- One well-orchestrated page load > scattered micro-interactions
+- CSS-only for HTML projects, Motion library (`motion/react`) for React
+
+## States (Every Interactive Element)
+
+- **Loading:** Skeleton or spinner on async operations — never a blank void
+- **Empty:** Helpful message + action when lists/data are empty — never "No results"
+- **Error:** User-friendly message + recovery action — never raw error text
+- **Hover:** Visual feedback within 100ms
+- **Focus:** Visible focus ring (2px+ offset, high contrast) — never `outline: none` without replacement
+- **Active/Pressed:** Scale down slightly or color shift
+- **Disabled:** Reduced opacity (0.5) + `cursor: not-allowed` + `aria-disabled`
+
+## Accessibility (WCAG AA Minimum)
+
+- Semantic HTML: `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>` — not divs for everything
+- Heading hierarchy: One `<h1>` per page, sequential order (no skipping h2→h4)
+- All images: descriptive `alt` text (or `alt=""` + `aria-hidden` if decorative)
+- All form inputs: visible `<label>` linked via `htmlFor` — not placeholder-only
+- All interactive elements: keyboard accessible (Tab, Enter, Escape, Arrow keys)
+- Touch targets: 44x44px minimum
+- ARIA: use native HTML elements first. Only add ARIA when HTML semantics aren't enough
+- Never rely solely on color to convey information — add icons, text, or patterns
+- Skip link: `<a href="#main" class="sr-only focus:not-sr-only">` on every page
+- Live regions: `aria-live="polite"` for dynamic content updates (toasts, form validation)
+
+## Responsive Design
+
+- Mobile-first: base styles for mobile, `@media (min-width)` for larger screens
+- Breakpoints: `sm: 640px`, `md: 768px`, `lg: 1024px`, `xl: 1280px`, `2xl: 1536px`
+- Fluid typography: `clamp(1rem, 0.5rem + 1.5vw, 1.25rem)` for body, scale up for headings
+- Stack on mobile, expand on desktop — never force horizontal scroll
+- Test: 320px (small phone), 375px (iPhone), 768px (tablet), 1024px (laptop), 1440px (desktop)
+- Images: `max-width: 100%`, `height: auto`, use `srcset` for responsive images
+- Navigation: hamburger menu on mobile, expanded on desktop
+
+## Component Quality
+
+- `cursor: pointer` on ALL clickable elements
+- Smooth transitions (150–300ms) on all state changes
+- No emoji as icons — use SVGs or icon libraries
+- Buttons: clear visual hierarchy (primary, secondary, ghost, destructive)
+- Inputs: visible borders, focus rings, error states with `aria-describedby`
+- Links: distinguishable from text (underline or color + another indicator)
+- Modals: trap focus, close on Escape, `aria-modal="true"`, restore focus on close
+- Toast/notifications: `aria-live`, auto-dismiss with adequate time (5s+), dismissible
+
+## Anti-Patterns (Kill on Sight)
+
+- Card grids where every card looks identical → varied layouts
+- Generic hero with stock photo → distinctive, purposeful hero
+- Blue-purple gradients → brand colors
+- Static pages with no motion → purposeful animation
+- Fixed widths → fluid responsive
+- Gray text on white (#999 on #fff fails WCAG) → proper contrast
+- Placeholder text shipped to production → real content or proper empty states
+- `outline: none` without focus replacement → visible focus indicators
+- `div` soup → semantic HTML
+- Hardcoded colors scattered in JSX → CSS variables or Tailwind config
+
+## Design System Integration
+
+If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
+Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
 
 ## Impeccable Design Skills (global)
-Use these `/commands` for design refinement on any frontend work:
-- `/polish` — Final detail pass before shipping (spacing, alignment, consistency)
-- `/bolder` — Amplify safe/boring designs to be more striking
+- `/polish` — Final detail pass before shipping
+- `/bolder` — Amplify safe/boring designs
 - `/design-quieter` — Tone down overly aggressive designs
-- `/animate` — Add purposeful micro-interactions and motion
+- `/animate` — Add purposeful micro-interactions
 - `/colorize` — Inject strategic color into monochrome UIs
 - `/clarify` — Fix unclear UX copy, labels, error messages
-- `/critique` — Design director-level review (run before shipping)
+- `/critique` — Design director-level review
 - `/distill` — Strip unnecessary complexity
 - `/delight` — Add memorable touches and personality
 - `/harden` — Edge cases, overflow, i18n robustness
-- `/onboard` — First-time user experience flows
-- `/normalize` — Align with project design system
 - `/responsive` — Cross-device responsive adaptation
 
 ### Recommended workflow

package/skills/qualia-new/SKILL.md

@@ -223,6 +223,44 @@ Create Supabase project (via MCP or manual).
 **`.planning/PROJECT.md`** — use template, fill from answers:
 - Client, description, requirements (from features), out of scope, stack, design direction, decisions
 
+### Step 8a. Create Design System
+
+Generate **`.planning/DESIGN.md`** using `templates/DESIGN.md` as the template.
+
+Fill in based on the design direction chosen in Step 3:
+
+**Dark & Bold:**
+- Palette: dark backgrounds (#0a0a0a, #141414), vibrant accent (teal #00d4aa, amber #f59e0b, etc.)
+- Typography: bold display font + clean body font (e.g., "Plus Jakarta Sans" + "DM Sans")
+- Effects: glass morphism, noise textures, glow effects
+- Motion: expressive — staggered fades, parallax hints
+
+**Clean & Minimal:**
+- Palette: light backgrounds (#fafafa, #ffffff), single muted accent
+- Typography: refined serif or geometric sans (e.g., "Outfit" + "Source Serif 4")
+- Effects: subtle shadows, thin borders
+- Motion: minimal — fades only, no stagger
+
+**Colorful & Playful:**
+- Palette: vibrant multi-color, warm backgrounds
+- Typography: rounded friendly fonts (e.g., "Nunito" + "Quicksand")
+- Effects: gradients, rounded shapes, illustrations
+- Motion: expressive — bouncy spring easing, scale on hover
+
+**Corporate / Professional:**
+- Palette: navy/charcoal base, conservative accent (blue, green)
+- Typography: trustworthy geometric (e.g., "Manrope" + "IBM Plex Sans")
+- Effects: clean borders, subtle shadows, structured grids
+- Motion: subtle — smooth fades, no bounce
+
+**Always include in DESIGN.md:**
+- Concrete CSS variable values (not placeholders)
+- Google Fonts import URL
+- Spacing scale (8px grid)
+- Component patterns (buttons, inputs, cards)
+- Responsive approach
+- Anti-patterns to avoid
+
 ### Step 8b. Initialize State
 
 ```bash

package/skills/qualia-polish/SKILL.md

@@ -14,39 +14,125 @@ Run after all feature phases are verified. Makes it look production-ready.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 1. Critique
-Review the entire UI. Check:
-- Visual hierarchy and information architecture
-- Color consistency, contrast, readability
-- Spacing and alignment
-- Component consistency across pages
-
-### 2. Polish
-Fix what critique found:
-- Alignment and spacing issues
-- Font consistency
-- Color palette adherence (Qualia teal brand)
-- Transition and hover state consistency
+### 0. Load Design Context
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+If DESIGN.md exists → use it as the standard. If not → use Qualia defaults from `rules/frontend.md`.
+
+Read EVERY frontend file before modifying. No blind edits.
+
+### 1. Critique (Structured Audit)
+
+Review the entire UI against this checklist. Check each item, note violations with file:line.
+
+**Typography:**
+- [ ] No generic fonts (Inter, Roboto, Arial, system-ui, Space Grotesk)
+- [ ] Proper type scale with clear hierarchy (display → heading → body → caption)
+- [ ] Body text: 16px+, line-height 1.5–1.7
+- [ ] Headings: tighter line-height (1.1–1.3), negative letter-spacing for large sizes
+- [ ] Prose max-width: 65ch
+- [ ] Font weights used for hierarchy (Regular, Medium, Semibold, Bold)
+
+**Color & Contrast:**
+- [ ] Cohesive palette via CSS variables (not scattered hex values)
+- [ ] All text passes WCAG AA contrast (4.5:1 normal, 3:1 large)
+- [ ] CTA buttons use accent color — stand out from the page
+- [ ] No blue-purple gradients, no rainbow palettes
+- [ ] Dark mode: rethought surfaces (not just inverted)
+- [ ] Semantic colors used consistently (success=green, error=red, warning=amber)
+
+**Layout & Spacing:**
+- [ ] Full-width fluid layouts — no hardcoded max-width caps
+- [ ] 8px spacing grid followed consistently
+- [ ] Tight spacing within groups, generous between sections
+- [ ] Fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
+- [ ] No identical card grids — varied visual hierarchy
+- [ ] No generic heroes — purposeful, distinctive
+
+**Interactive States:**
+- [ ] Every button/link: hover (color shift, 150ms), focus (visible ring), active (press feedback), disabled
+- [ ] Loading: skeleton or spinner on all async operations
+- [ ] Empty: helpful message + action on empty lists/data
+- [ ] Error: user-friendly message + recovery action on failed fetches
+- [ ] Form validation: inline errors with `aria-describedby`
+
+**Motion:**
+- [ ] Hover/focus: 150–200ms transitions
+- [ ] Page load: staggered entrance animations (50–80ms delay)
+- [ ] Expand/collapse: 250ms ease-in-out
+- [ ] `prefers-reduced-motion` respected (no animation for users who opt out)
+- [ ] No jank: transforms and opacity only for animated properties
+
+**Accessibility:**
+- [ ] Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer`
+- [ ] One `h1` per page, sequential heading hierarchy
+- [ ] All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
+- [ ] All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
+- [ ] All interactive elements: keyboard accessible (Tab/Enter/Escape)
+- [ ] Touch targets: 44px minimum
+- [ ] Skip link: `<a href="#main">` as first focusable element
+- [ ] No `outline: none` without focus replacement
+- [ ] `<html lang="en">` set
+- [ ] Color not sole information carrier — icons/text as supplements
+
+**Responsive:**
+- [ ] Mobile-first approach (base styles for mobile, min-width breakpoints for larger)
+- [ ] No horizontal scroll at 320px
+- [ ] Navigation: hamburger on mobile, expanded on desktop
+- [ ] Touch targets adequate on mobile (44px min)
+- [ ] Fluid typography with `clamp()`
+- [ ] Images: `max-width: 100%`, responsive srcset where needed
+- [ ] Tables: card view or horizontal scroll on mobile
+
+**Performance:**
+- [ ] Server Components by default — `'use client'` only when needed
+- [ ] Images via `next/image` with width/height
+- [ ] No barrel file imports — direct imports from source
+- [ ] Heavy components lazy-loaded with `next/dynamic`
+- [ ] Data fetched in parallel, not sequentially
+
+### 2. Fix Everything
+
+Work through violations from the critique. Fix each category:
+
+1. Typography first (sets the visual foundation)
+2. Color & contrast (palette coherence)
+3. Layout & spacing (structural fixes)
+4. Interactive states (loading, empty, error, hover, focus)
+5. Motion (transitions, entrance animations, reduced-motion)
+6. Accessibility (semantic HTML, ARIA, keyboard, labels)
+7. Responsive (mobile breakpoints, fluid sizing)
+8. Performance (quick wins — image optimization, dynamic imports)
 
 ### 3. Harden
-Edge cases and robustness:
-- Empty states (no data, loading, error)
-- Text overflow, long content
-- Mobile responsive (check all breakpoints)
-- Error messages (user-friendly, not technical)
 
-### 4. Qualia Frontend Rules
-- Distinctive fonts (not Inter/Arial)
-- Cohesive color palette with sharp accents
-- CSS transitions, staggered animations
-- Full-width layouts, no hardcoded max-width caps
-- No card grids, no generic heroes, no blue-purple gradients
+After polish, stress-test edge cases:
+- Long text content (overflow, truncation, word-break)
+- Extremely long usernames or email addresses
+- Empty data everywhere simultaneously
+- Error state on every fetch simultaneously
+- 320px viewport width
+- Keyboard-only navigation through entire flow
+- Screen reader landmarks check (semantic HTML)
+- Right-to-left text (if i18n is planned)
+- Slow network (loading states visible, no flash of empty content)
 
-### 5. Commit & Update
+### 4. Verify
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors before committing.
+
+### 5. Commit & Transition
 
 ```bash
 git add {changed files}
-git commit -m "polish: design and UX pass"
+git commit -m "polish: design and UX pass — typography, accessibility, responsive, states"
 ```
 
 ```bash
@@ -54,6 +140,22 @@ node ~/.claude/bin/state.js transition --to polished
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
+### 6. Report
+
 ```
+◆ QUALIA ► POLISHED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Files modified: {N}
+
+  Typography    ✓ {brief}
+  Color         ✓ {brief}
+  Layout        ✓ {brief}
+  States        ✓ {brief}
+  Motion        ✓ {brief}
+  Accessibility ✓ {brief}
+  Responsive    ✓ {brief}
+  Performance   ✓ {brief}
+  Hardening     ✓ {brief}
+
   → Run: /qualia-ship
 ```

package/skills/qualia-report/SKILL.md

@@ -5,7 +5,7 @@ description: "Generate session report and commit to repo. Mandatory before clock
 
 # /qualia-report — Session Report
 
-Generate a concise report of what was done. Committed to git for the ERP to read.
+Generate a concise report of what was done. Committed to git and uploaded to the ERP for clock-out.
 
 ## Process
 
@@ -69,7 +69,28 @@ git commit -m "report: session {YYYY-MM-DD}"
 git push
 ```
 
-### 5. Update State
+### 5. Upload to ERP
+
+**This step is MANDATORY** — the clock-out modal requires the report to be uploaded.
+
+```bash
+ERP_URL="https://portal.qualiasolutions.net"
+API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
+REPORT_FILE=".planning/reports/report-{date}.md"
+EMAIL=$(git config user.email)
+PROJECT=$(basename $(pwd))
+
+curl -s -X POST "$ERP_URL/api/claude/report-upload" \
+  -H "X-API-Key: $API_KEY" \
+  -F "file=@$REPORT_FILE" \
+  -F "employee_email=$EMAIL" \
+  -F "project_name=$PROJECT"
+```
+
+If the upload succeeds, print: "Report uploaded to ERP. You can now clock out."
+If it fails (no API key, network error), print the error and tell the employee to ask Fawzi.
+
+### 6. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"

package/templates/DESIGN.md

@@ -0,0 +1,137 @@
+# Design System — {Project Name}
+
+> Generated during project setup. This is the source of truth for all frontend work.
+> Builder agents read this before writing any component. Update it as design evolves.
+
+## Brand
+
+- **Tone:** {dark-bold | clean-minimal | colorful-playful | corporate-professional}
+- **Personality:** {1-2 sentences describing the feel — e.g., "Confident and technical, like a Bloomberg terminal meets a luxury brand"}
+- **Industry:** {e.g., fintech, healthcare, SaaS, e-commerce}
+
+## Color System
+
+```css
+:root {
+  /* Primary — brand identity */
+  --color-primary: {value};
+  --color-primary-hover: {value};
+  --color-primary-subtle: {value};  /* backgrounds, badges */
+
+  /* Accent — CTAs, highlights */
+  --color-accent: {value};
+  --color-accent-hover: {value};
+
+  /* Neutral — text, borders, backgrounds */
+  --color-bg: {value};
+  --color-bg-subtle: {value};       /* cards, raised surfaces */
+  --color-bg-muted: {value};        /* disabled, secondary surfaces */
+  --color-text: {value};
+  --color-text-muted: {value};      /* secondary text */
+  --color-text-subtle: {value};     /* placeholders, hints */
+  --color-border: {value};
+  --color-border-subtle: {value};
+
+  /* Semantic */
+  --color-success: {value};
+  --color-warning: {value};
+  --color-error: {value};
+  --color-info: {value};
+}
+
+/* Dark mode overrides */
+[data-theme="dark"] {
+  --color-bg: {value};
+  --color-bg-subtle: {value};
+  --color-text: {value};
+  /* ... override all tokens ... */
+}
+```
+
+## Typography
+
+```css
+:root {
+  /* Font families */
+  --font-display: '{Display Font}', {fallback};    /* Hero text, page titles */
+  --font-heading: '{Heading Font}', {fallback};     /* Section headings */
+  --font-body: '{Body Font}', {fallback};           /* Paragraphs, UI text */
+  --font-mono: '{Mono Font}', monospace;            /* Code, data */
+
+  /* Scale */
+  --text-xs: clamp(0.75rem, 0.7rem + 0.25vw, 0.8rem);
+  --text-sm: clamp(0.875rem, 0.8rem + 0.4vw, 0.9rem);
+  --text-base: clamp(1rem, 0.5rem + 1.5vw, 1.125rem);
+  --text-lg: clamp(1.125rem, 0.75rem + 1.2vw, 1.25rem);
+  --text-xl: clamp(1.25rem, 0.75rem + 1.5vw, 1.5rem);
+  --text-2xl: clamp(1.5rem, 0.75rem + 2.25vw, 2rem);
+  --text-3xl: clamp(1.875rem, 1rem + 2.5vw, 2.5rem);
+  --text-4xl: clamp(2.25rem, 1rem + 3vw, 3rem);
+  --text-5xl: clamp(3rem, 1rem + 4vw, 4rem);
+}
+```
+
+**Google Fonts import:** `{URL}`
+
+## Spacing Scale
+
+Based on 8px grid: `4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128`
+
+- **Within components:** 8–16px
+- **Between related elements:** 16–24px
+- **Between sections:** 48–96px
+- **Page padding:** `clamp(1rem, 5vw, 4rem)` horizontal
+
+## Motion
+
+- **Approach:** {minimal | subtle | expressive}
+- **Page load:** staggered fade-up, 60ms delay between elements
+- **Hover/focus:** 150ms ease-out
+- **Expand/collapse:** 250ms ease-in-out
+- **Page transitions:** 400ms ease-out
+- **Reduced motion:** all non-essential animations disabled
+
+## Component Patterns
+
+### Buttons
+- **Primary:** solid {accent} background, white text, rounded-{radius}
+- **Secondary:** bordered, transparent background
+- **Ghost:** text-only, hover background
+- **Destructive:** red variant for dangerous actions
+- **Sizes:** sm (32px), md (40px), lg (48px)
+
+### Inputs
+- Border: 1px solid var(--color-border)
+- Focus: 2px ring var(--color-primary)
+- Error: red border + error text below with `aria-describedby`
+- Height: 40px (md), 48px (lg)
+
+### Cards/Surfaces
+- Background: var(--color-bg-subtle)
+- Border: 1px solid var(--color-border-subtle) or shadow
+- Border-radius: {value}
+- No identical card grids — vary layout and emphasis
+
+## Responsive Approach
+
+- **Strategy:** mobile-first
+- **Primary breakpoints:** 768px (tablet), 1024px (desktop)
+- **Navigation:** hamburger on mobile, expanded on desktop
+- **Layout:** single column mobile → multi-column desktop
+- **Touch targets:** 44px minimum on mobile
+
+## Visual Effects
+
+- {e.g., "Noise texture overlay at 3% opacity on hero sections"}
+- {e.g., "Glass-morphism on floating elements: backdrop-blur-xl bg-white/80"}
+- {e.g., "Gradient mesh on hero: radial-gradient from primary to transparent"}
+- {e.g., "Decorative geometric shapes as background accents"}
+
+## Anti-Patterns (Don't Do This)
+
+- No Inter, Roboto, Arial, system-ui fonts
+- No blue-purple gradients
+- No identical card grids
+- No generic stock-photo heroes
+- No hardcoded max-width containers (use fluid layouts)
+- No gray-on-gray low-contrast text