qualia-framework 2.6.0 → 3.2.0

package/hooks/pre-deploy-gate.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-deploy-gate.js — quality gates before production deploy.
+// PreToolUse hook on `vercel --prod*` commands. Runs tsc, lint, tests, build,
+// then scans for service_role leaks in client code.
+// Exits 1 to BLOCK deploy. Exits 0 to allow.
+// Cross-platform (Windows/macOS/Linux). No `grep` or `find` — pure Node.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function runGate(label, cmd, args, { required = true } = {}) {
+  const r = spawnSync(cmd, args, {
+    stdio: "ignore",
+    timeout: 180000,
+    shell: process.platform === "win32",
+  });
+  if (r.status === 0) {
+    console.log(`  ✓ ${label}`);
+    return true;
+  }
+  if (required) {
+    console.log(`BLOCKED: ${label} errors. Fix before deploying.`);
+    process.exit(1);
+  }
+  return false;
+}
+
+function hasScript(name) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    return pkg.scripts && typeof pkg.scripts[name] === "string";
+  } catch {
+    return false;
+  }
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      walk(full, out);
+    } else if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function scanServiceRoleLeaks() {
+  const roots = ["app", "components", "src", "pages", "lib"];
+  const leaks = [];
+  for (const root of roots) {
+    for (const file of walk(root)) {
+      // Skip server-only files (convention: *.server.ts, server/ dirs)
+      if (/\.server\.|[\\/]server[\\/]/.test(file)) continue;
+      try {
+        const content = fs.readFileSync(file, "utf8");
+        if (/service_role/.test(content)) {
+          leaks.push(file);
+        }
+      } catch {}
+    }
+  }
+  return leaks;
+}
+
+console.log("⬢ Pre-deploy gate...");
+
+// TypeScript
+if (fs.existsSync("tsconfig.json")) {
+  runGate("TypeScript", "npx", ["tsc", "--noEmit"]);
+}
+
+// Lint
+if (hasScript("lint")) {
+  runGate("Lint", "npm", ["run", "lint"]);
+}
+
+// Tests
+if (hasScript("test")) {
+  runGate("Tests", "npm", ["test"]);
+}
+
+// Build
+if (hasScript("build")) {
+  runGate("Build", "npm", ["run", "build"]);
+}
+
+// Security: no service_role in client code
+const leaks = scanServiceRoleLeaks();
+if (leaks.length > 0) {
+  console.log("BLOCKED: service_role found in client code. Remove before deploying.");
+  for (const f of leaks.slice(0, 10)) {
+    console.log(`  ✗ ${f}`);
+  }
+  process.exit(1);
+}
+console.log("  ✓ Security");
+console.log("⬢ All gates passed.");
+
+process.exit(0);

package/hooks/pre-push.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-push.js — update tracking.json with last commit + timestamp.
+// PreToolUse hook on `git push*` commands. state.js handles phase/status sync;
+// this just stamps the file so the ERP sees fresh commit info on every push.
+// Cross-platform (Windows/macOS/Linux).
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const TRACKING = path.join(".planning", "tracking.json");
+
+try {
+  if (fs.existsSync(TRACKING)) {
+    const r = spawnSync("git", ["log", "--oneline", "-1", "--format=%h"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    const lastCommit = ((r.stdout || "").trim());
+    const now = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
+    const t = JSON.parse(fs.readFileSync(TRACKING, "utf8"));
+    if (lastCommit) t.last_commit = lastCommit;
+    t.last_updated = now;
+    fs.writeFileSync(TRACKING, JSON.stringify(t, null, 2) + "\n");
+
+    spawnSync("git", ["add", TRACKING], { timeout: 3000 });
+  }
+} catch (err) {
+  process.stderr.write(`WARNING: tracking sync failed: ${err.message}\n`);
+}
+
+process.exit(0);

package/hooks/session-start.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/session-start.js — branded context panel on session start.
+// Cross-platform (Windows/macOS/Linux). Zero shell dependencies.
+//
+// CRITICAL: this hook must NEVER exit non-zero. Claude Code treats any non-zero
+// exit from a SessionStart hook as a "hook error" and shows a red banner. The
+// banner is purely informational — we'd rather render nothing than block a
+// session. Every call is wrapped in try/catch and we always exit 0 at the end.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const HOME = os.homedir();
+const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
+const STATE_FILE = path.join(".planning", "STATE.md");
+const CONTINUE_HERE = ".continue-here.md";
+
+function runUi(...args) {
+  if (!fs.existsSync(UI)) return;
+  try {
+    spawnSync(process.execPath, [UI, ...args], {
+      stdio: "inherit",
+      timeout: 3000,
+    });
+  } catch {}
+}
+
+function getNextCommand() {
+  const stateJs = path.join(HOME, ".claude", "bin", "state.js");
+  if (!fs.existsSync(stateJs)) return "";
+  try {
+    const r = spawnSync(process.execPath, [stateJs, "check"], {
+      encoding: "utf8",
+      timeout: 3000,
+    });
+    if (!r.stdout) return "";
+    const j = JSON.parse(r.stdout);
+    return j.next_command || "";
+  } catch {
+    return "";
+  }
+}
+
+function maybeShowUpdateBanner() {
+  // Sticky framework update notification for EMPLOYEEs. Populated by
+  // auto-update.js when it detects a newer qualia-framework version on npm.
+  // OWNER auto-updates silently, so this file is never created for Fawzi.
+  try {
+    const notifFile = path.join(HOME, ".claude", ".qualia-update-available.json");
+    if (!fs.existsSync(notifFile)) return;
+
+    const cfg = readConfig();
+    // Belt-and-suspenders: even if a stale notification exists, OWNER never sees it.
+    if (cfg.role === "OWNER") {
+      try { fs.unlinkSync(notifFile); } catch {}
+      return;
+    }
+
+    const notif = JSON.parse(fs.readFileSync(notifFile, "utf8"));
+
+    // If the user has already updated (cfg.version >= notif.latest), clear the file.
+    if (cfg.version && notif.latest) {
+      const cmp = (a, b) => {
+        const pa = String(a).split(".").map(Number);
+        const pb = String(b).split(".").map(Number);
+        for (let i = 0; i < 3; i++) {
+          if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+          if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+        }
+        return 0;
+      };
+      if (cmp(cfg.version, notif.latest) >= 0) {
+        try { fs.unlinkSync(notifFile); } catch {}
+        return;
+      }
+    }
+
+    runUi("update", notif.current || cfg.version || "?", notif.latest || "?");
+  } catch {
+    // Never fail the session start.
+  }
+}
+
+function fallbackText() {
+  // If qualia-ui.js is missing, emit plain text. Keeps the session informative
+  // even on a broken install.
+  if (fs.existsSync(STATE_FILE)) {
+    try {
+      const content = fs.readFileSync(STATE_FILE, "utf8");
+      const phase = (content.match(/^Phase:\s*(.+)$/m) || [])[1] || "—";
+      const status = (content.match(/^Status:\s*(.+)$/m) || [])[1] || "—";
+      console.log(`QUALIA: Project loaded. Phase: ${phase.trim()} | Status: ${status.trim()}`);
+      console.log("QUALIA: Run /qualia for next step.");
+    } catch {
+      console.log("QUALIA: Project detected but STATE.md could not be read.");
+    }
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    console.log("QUALIA: Handoff file found. Read .continue-here.md to resume.");
+  } else {
+    console.log("QUALIA: No project detected. Run /qualia-new to start.");
+  }
+}
+
+try {
+  // Sticky update notification — shown before anything else every session
+  // until the employee runs `npx qualia-framework@latest install`.
+  maybeShowUpdateBanner();
+
+  if (!fs.existsSync(UI)) {
+    fallbackText();
+  } else if (fs.existsSync(STATE_FILE)) {
+    runUi("banner", "router");
+    const next = getNextCommand();
+    if (next) {
+      console.log("");
+      runUi("next", next);
+    }
+  } else if (fs.existsSync(CONTINUE_HERE)) {
+    runUi("banner", "resume");
+    runUi("warn", "Previous session found — type /qualia-resume to pick up where you left off");
+    console.log("");
+  } else {
+    // No project — show a welcoming first-run experience
+    const config = readConfig();
+    const name = config.installed_by || "";
+    runUi("banner", "router");
+    if (name) {
+      console.log(`  ${TEAL}Ready when you are, ${name}.${RESET}`);
+    }
+    console.log("");
+    console.log(`  ${DIM}Start here:${RESET}`);
+    console.log(`    ${TEAL}/qualia-new${RESET}    ${DIM}Set up a new project${RESET}`);
+    console.log(`    ${TEAL}/qualia${RESET}        ${DIM}What should I do next?${RESET}`);
+    console.log(`    ${TEAL}/qualia-quick${RESET}  ${DIM}Quick fix (skip planning)${RESET}`);
+    console.log("");
+  }
+} catch {
+  // Deliberately silent — hook must never fail
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function _trace(hookName, result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: hookName,
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+_trace("session-start", "allow");
+process.exit(0);

package/package.json

@@ -1,33 +1,42 @@
 {
   "name": "qualia-framework",
-  "version": "2.6.0",
-  "description": "Qualia Solutions — Claude Code Framework",
+  "version": "3.2.0",
+  "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
   },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai",
+    "framework",
+    "workflow",
+    "qualia",
+    "agents",
+    "automation"
+  ],
+  "author": "Qualia Solutions <hello@qualia.solutions>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QualiasolutionsCY/qualia-framework.git"
+  },
+  "homepage": "https://github.com/QualiasolutionsCY/qualia-framework#readme",
   "scripts": {
-    "preuninstall": "node bin/cli.js uninstall --force"
+    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh && bash tests/bin.test.sh && bash tests/statusline.test.sh"
   },
   "files": [
     "bin/",
-    "framework/",
-    "profiles/",
+    "agents/",
+    "hooks/",
+    "rules/",
+    "skills/",
     "templates/",
-    "uninstall.sh"
+    "tests/",
+    "CLAUDE.md",
+    "guide.md"
   ],
   "engines": {
-    "node": ">=18.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
-  },
-  "keywords": [
-    "claude-code",
-    "qualia",
-    "framework",
-    "ai-dev"
-  ],
-  "author": "Qualia Solutions",
-  "license": "UNLICENSED"
+    "node": ">=18"
+  }
 }

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

@@ -0,0 +1,126 @@
+---
+globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "tailwind.config.*"]
+---
+
+# Frontend Design Standards
+
+These are Qualia brand standards — mandatory for every frontend component. 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)
+- `/polish` — Final detail pass before shipping
+- `/bolder` — Amplify safe/boring designs
+- `/design-quieter` — Tone down overly aggressive designs
+- `/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
+- `/distill` — Strip unnecessary complexity
+- `/delight` — Add memorable touches and personality
+- `/harden` — Edge cases, overflow, i18n robustness
+- `/responsive` — Cross-device responsive adaptation
+
+### Recommended workflow
+1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship