picasso-skill 1.1.0 → 1.3.0

package/bin/install.mjs

@@ -1,43 +1,56 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, cpSync, readdirSync } from "fs";
+import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync } from "fs";
 import { resolve, join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const skillSource = join(packageRoot, "skills", "picasso");
+const agentSource = join(packageRoot, "agents", "picasso.md");
 
 const args = process.argv.slice(2);
 const command = args[0] || "install";
 
 if (command === "help" || command === "--help" || command === "-h") {
   console.log(`
-  picasso-skill - The ultimate AI design skill
+  picasso-skill - The ultimate AI design skill + agent
 
   Usage:
-    npx picasso-skill              Install to current project (.claude/skills/)
-    npx picasso-skill --global     Install globally (~/.claude/skills/)
-    npx picasso-skill --cursor     Install for Cursor (.cursor/skills/)
-    npx picasso-skill --codex      Install for Codex (~/.codex/skills/)
+    npx picasso-skill              Install skill + agent to current project
+    npx picasso-skill --global     Install globally (~/.claude/)
+    npx picasso-skill --skill-only Install skill only (no agent)
+    npx picasso-skill --cursor     Install skill for Cursor
+    npx picasso-skill --codex      Install skill for Codex
     npx picasso-skill --agents     Install to .agents/skills/
     npx picasso-skill --path DIR   Install to a custom directory
+
+  What gets installed:
+    .claude/skills/picasso/        Skill (knowledge base: 13 reference files)
+    .claude/agents/picasso.md      Agent (autonomous design auditor)
   `);
   process.exit(0);
 }
 
-let targetDir;
+const isGlobal = args.includes("--global") || args.includes("-g");
+const skillOnly = args.includes("--skill-only");
+const home = process.env.HOME || process.env.USERPROFILE;
+
+let skillDir;
+let agentDir;
 
-if (args.includes("--global") || args.includes("-g")) {
-  const home = process.env.HOME || process.env.USERPROFILE;
-  targetDir = join(home, ".claude", "skills", "picasso");
+if (isGlobal) {
+  skillDir = join(home, ".claude", "skills", "picasso");
+  agentDir = join(home, ".claude", "agents");
 } else if (args.includes("--cursor")) {
-  targetDir = join(process.cwd(), ".cursor", "skills", "picasso");
+  skillDir = join(process.cwd(), ".cursor", "skills", "picasso");
+  agentDir = null; // Cursor doesn't support agents
 } else if (args.includes("--codex")) {
-  const home = process.env.HOME || process.env.USERPROFILE;
-  targetDir = join(home, ".codex", "skills", "picasso");
+  skillDir = join(home, ".codex", "skills", "picasso");
+  agentDir = null;
 } else if (args.includes("--agents")) {
-  targetDir = join(process.cwd(), ".agents", "skills", "picasso");
+  skillDir = join(process.cwd(), ".agents", "skills", "picasso");
+  agentDir = null;
 } else if (args.includes("--path")) {
   const pathIdx = args.indexOf("--path");
   const customPath = args[pathIdx + 1];
@@ -45,36 +58,53 @@ if (args.includes("--global") || args.includes("-g")) {
     console.error("Error: --path requires a directory argument");
     process.exit(1);
   }
-  targetDir = resolve(customPath, "picasso");
+  skillDir = resolve(customPath, "picasso");
+  agentDir = null;
 } else {
   // Default: project-level Claude Code
-  targetDir = join(process.cwd(), ".claude", "skills", "picasso");
+  skillDir = join(process.cwd(), ".claude", "skills", "picasso");
+  agentDir = join(process.cwd(), ".claude", "agents");
 }
 
-console.log(`\n  Installing Picasso skill to: ${targetDir}\n`);
+if (skillOnly) agentDir = null;
+
+console.log(`\n  Installing Picasso to: ${skillDir}\n`);
 
 try {
-  mkdirSync(targetDir, { recursive: true });
-  mkdirSync(join(targetDir, "references"), { recursive: true });
+  // Install skill
+  mkdirSync(skillDir, { recursive: true });
+  mkdirSync(join(skillDir, "references"), { recursive: true });
 
-  // Copy SKILL.md
-  cpSync(join(skillSource, "SKILL.md"), join(targetDir, "SKILL.md"));
+  cpSync(join(skillSource, "SKILL.md"), join(skillDir, "SKILL.md"));
 
-  // Copy all reference files
   const refs = readdirSync(join(skillSource, "references"));
   for (const ref of refs) {
     cpSync(
       join(skillSource, "references", ref),
-      join(targetDir, "references", ref)
+      join(skillDir, "references", ref)
     );
   }
 
-  console.log(`  Done! Installed ${1 + refs.length} files:`);
+  console.log(`  Skill installed (${1 + refs.length} files):`);
   console.log(`    SKILL.md`);
   for (const ref of refs) {
     console.log(`    references/${ref}`);
   }
+
+  // Install agent
+  if (agentDir && existsSync(agentSource)) {
+    mkdirSync(agentDir, { recursive: true });
+    cpSync(agentSource, join(agentDir, "picasso.md"));
+    console.log(`\n  Agent installed:`);
+    console.log(`    ${join(agentDir, "picasso.md")}`);
+  }
+
   console.log(`\n  Picasso is ready. Start designing.\n`);
+
+  if (agentDir) {
+    console.log(`  The Picasso agent will automatically audit your frontend code.`);
+    console.log(`  You can also invoke it manually with /audit, /critique, or /polish.\n`);
+  }
 } catch (err) {
   console.error(`  Error installing: ${err.message}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"
@@ -32,6 +32,7 @@
   "files": [
     "bin/",
     "skills/",
+    "agents/",
     "LICENSE"
   ]
 }

package/skills/picasso/references/accessibility-wcag.md

@@ -0,0 +1,245 @@
+# Accessibility & WCAG 2.2 Reference
+
+## 1. ARIA Patterns Catalog
+
+### Dialog / Modal
+- `role="dialog"`, `aria-modal="true"`, `aria-labelledby` (title)
+- Tab/Shift+Tab cycle within dialog (focus trap), Escape closes
+- On open: focus first focusable element. On close: return focus to trigger.
+
+```html
+<div role="dialog" aria-modal="true" aria-labelledby="dlg-title">
+  <h2 id="dlg-title">Confirm Delete</h2>
+  <p>This action cannot be undone.</p>
+  <button>Cancel</button>
+  <button>Delete</button>
+</div>
+```
+
+### Tabs
+- `tablist` > `tab` + `tabpanel`
+- `aria-selected="true|false"` on each tab, `aria-controls` linking tab to panel
+- Left/Right arrows between tabs, Home/End to first/last
+
+### Accordion
+- Heading elements containing `<button>` triggers
+- `aria-expanded="true|false"` on button, `aria-controls` pointing to content
+- Enter/Space toggles section
+
+### Combobox / Autocomplete
+- `role="combobox"` on input, popup uses `listbox`
+- `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-autocomplete`
+- Down Arrow opens/navigates popup, Escape closes, Enter selects
+
+### Menu / Menubar
+- `menu`/`menubar` > `menuitem`, `menuitemcheckbox`, `menuitemradio`
+- `aria-haspopup`, `aria-expanded` on submenu triggers
+- Arrow keys navigate, Enter/Space activates, Escape closes submenu
+
+### Listbox
+- `listbox` > `option`
+- `aria-selected`, `aria-multiselectable` for multi-select
+- Up/Down arrows, Home/End, type-ahead character navigation
+
+### Tree View
+- `tree` > `treeitem` (nested groups use `group` role)
+- `aria-expanded` on parent nodes, `aria-level`, `aria-setsize`, `aria-posinset`
+- Right expands/enters child, Left collapses/moves to parent
+
+### Toolbar
+- `toolbar` on container, `aria-orientation`
+- Arrow keys between controls (roving tabindex), Tab moves out entirely
+
+### Feed
+- `feed` > `article` on each entry
+- `aria-busy` while loading, `aria-setsize`/`aria-posinset` on articles
+- Page Down/Up between articles
+
+### Alert / Alert Dialog
+- `role="alert"` (non-modal): implicitly `aria-live="assertive"`. No focus change.
+- `role="alertdialog"` (modal): follows dialog focus trap pattern.
+
+### Breadcrumb
+- `<nav aria-label="Breadcrumb">` with ordered list
+- `aria-current="page"` on current page link
+
+### Disclosure
+- `<button aria-expanded="false" aria-controls="content-id">` toggles content
+- Enter/Space toggles expansion
+
+---
+
+## 2. Focus Management for SPAs
+
+### Route Change Announcements
+```html
+<div aria-live="polite" class="sr-only" id="route-announcer"></div>
+```
+Update textContent on route change: "Products page loaded".
+
+### Focus Restoration
+Move focus to `<h1>` of new view (add `tabindex="-1"`) or main content landmark. On modal close, restore focus to trigger element.
+
+### Skip Links
+```html
+<a href="#main" class="skip-link">Skip to main content</a>
+<main id="main" tabindex="-1">...</main>
+```
+
+### Focus Trapping
+Contain Tab/Shift+Tab within overlays. Use `inert` attribute on background content (modern browsers) or manage via JS. On last focusable element, Tab wraps to first.
+
+### Roving Tabindex
+Only one child has `tabindex="0"` at a time; all others `tabindex="-1"`. On arrow key, swap values and `.focus()`. Alternative: `aria-activedescendant` on container.
+
+---
+
+## 3. Accessible Forms
+
+### Error Handling
+```html
+<input id="email" aria-invalid="true" aria-describedby="email-err" aria-required="true">
+<span id="email-err" role="alert">Please enter a valid email address.</span>
+```
+
+- `aria-invalid="true"` on fields with errors.
+- `aria-describedby` linking to error message.
+- `role="alert"` for immediate screen reader announcement.
+- On submit, move focus to first invalid field.
+
+### Required Fields
+Use both `required` (native) and `aria-required="true"`. Pair with visible asterisk + legend.
+
+### Field Descriptions
+```html
+<label for="pw">Password</label>
+<input id="pw" type="password" aria-describedby="pw-hint">
+<p id="pw-hint">Must be at least 8 characters with one number.</p>
+```
+
+### Autocomplete Attributes
+Use `autocomplete` values: `name`, `email`, `tel`, `street-address`, `postal-code`, `cc-number`, etc.
+
+### Group Labeling
+```html
+<fieldset>
+  <legend>Payment Method</legend>
+  <label><input type="radio" name="pay" value="card"> Credit Card</label>
+  <label><input type="radio" name="pay" value="paypal"> PayPal</label>
+</fieldset>
+```
+
+### Accessible Date Pickers
+Prefer native `<input type="date">`. For custom: `role="grid"` calendar, arrow key navigation, Enter to select, Escape to close, label each cell with full date.
+
+---
+
+## 4. WCAG 2.2 New Criteria
+
+### Target Size Minimum (2.5.8 -- Level AA)
+All interactive targets must be at least **24x24 CSS pixels**.
+
+```css
+button, a, input, select, [role="button"] {
+  min-width: 24px;
+  min-height: 24px;
+}
+```
+
+### Dragging Alternatives (2.5.7 -- Level AA)
+Every drag-and-drop operation must have a single-pointer alternative (click/tap). Sortable lists must also support "Move Up"/"Move Down" buttons.
+
+### Focus Appearance (2.4.11 -- Level AA)
+Focus indicators: minimum **2px perimeter outline** with **3:1 contrast ratio** between focused and unfocused states.
+
+```css
+:focus-visible {
+  outline: 2px solid #005fcc;
+  outline-offset: 2px;
+}
+```
+
+### Consistent Help (3.2.6 -- Level A)
+Help mechanisms must appear in the **same relative order** across all pages.
+
+---
+
+## 5. Screen Reader Dynamic Content
+
+### aria-live Regions
+```html
+<div aria-live="polite" aria-atomic="true">3 results found</div>
+<div aria-live="assertive">Session expiring in 30 seconds</div>
+```
+- `polite`: announced after current speech.
+- `assertive`: interrupts (use sparingly).
+- `aria-atomic="true"`: reads entire region, not just changed text.
+
+### Status Messages (WCAG 4.1.3)
+```html
+<div role="status">File uploaded successfully.</div>
+```
+
+### Loading States
+```html
+<div role="status" aria-live="polite">Loading results...</div>
+<table aria-busy="true">...</table>
+```
+Set `aria-busy="true"` during update, `false` when complete.
+
+### Progress Updates
+```html
+<div role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100"
+     aria-label="Upload progress">65%</div>
+```
+
+---
+
+## 6. Accessible Data Tables
+
+### Complex Headers
+```html
+<th id="q1" scope="col">Q1</th>
+<th id="revenue" scope="row">Revenue</th>
+<td headers="q1 revenue">$1.2M</td>
+```
+
+### Sortable Columns
+```html
+<th aria-sort="ascending" scope="col">
+  <button>Name <span aria-hidden="true">&uarr;</span></button>
+</th>
+```
+Values: `ascending`, `descending`, `none`. Only one column sorted at a time.
+
+### Expandable Rows
+Parent row: `aria-expanded="true|false"`. Use `aria-level`, `aria-setsize`, `aria-posinset` for treegrid.
+
+### Responsive Tables
+- **Reflow:** Transform cells into stacked blocks with `data-label` + CSS `::before` for headers.
+- **Scroll:** `tabindex="0"`, `role="region"`, `aria-label="Scrollable table"`.
+
+---
+
+## 7. Accessible Drag and Drop
+
+### Keyboard Alternatives (WCAG 2.5.7)
+```html
+<li aria-roledescription="sortable item">
+  Item A
+  <button aria-label="Move Item A up">Up</button>
+  <button aria-label="Move Item A down">Down</button>
+</li>
+```
+
+### Live Region Announcements
+```html
+<div aria-live="assertive" class="sr-only" id="dnd-status"></div>
+```
+- On grab: "Grabbed Item A. Current position 2 of 5."
+- On move: "Item A moved to position 3 of 5."
+- On drop: "Item A dropped at position 3 of 5."
+- On cancel: "Reorder cancelled. Item A returned to position 2."
+
+### Modern Pattern
+`aria-grabbed`/`aria-dropeffect` are deprecated. Use `aria-roledescription="draggable"`, `aria-pressed`/`aria-selected` for state, and live regions for announcements. Space/Enter to grab/drop, arrow keys to reposition, Escape to cancel.

package/skills/picasso/references/anti-patterns.md

@@ -4,92 +4,181 @@ This is the most important reference file. These are the patterns that make AI-g
 
 ---
 
+## The AI Slop Fingerprint
+
+Any 3 or more of these together = AI slop. Stop and redesign.
+
+- Inter/Roboto + purple-to-blue gradient + centered hero + 3 equal feature cards + "Build the future of work" headline
+- `bg-indigo-500` as default accent (the Tailwind feedback loop)
+- Uniform 8px or 16px border-radius on everything
+- Generic `box-shadow: 0 4px 6px rgba(0,0,0,0.1)` on every card
+- Same page structure: hero > 3 cards > testimonials > pricing > CTA
+- Gradient text (`background-clip: text`) that fails accessibility
+- Abstract 3D blobs or stock photos of people smiling at laptops
+- Everything perfectly centered on a vertical axis
+- Uniform spacing with no density variation between sections
+- Fade-in-on-scroll applied identically to every element
+- Feature icons from Lucide/Heroicons in tinted circles
+- "Trusted by 10,000+ teams" with grayed-out logos nobody recognizes
+
+**The test:** Show someone a screenshot without context. If they say "AI-generated" in 3 seconds, it fails. The fingerprint is not any single choice -- it is the combination of defaults that signals zero human judgment.
+
+---
+
 ## Typography Anti-Patterns
 
-- **Inter everywhere.** The default safe choice. It signals "I did not think about fonts."
-- **Roboto, Arial, Helvetica, system-ui as primary.** Same problem.
-- **Space Grotesk on repeat.** Overused in AI/crypto contexts. Pick something else.
-- **Light (300) weight for body text.** Hard to read on most screens.
-- **Centered paragraphs.** Center alignment works for 1-2 lines (headings, quotes). Never for body text.
-- **No max-width on text.** Lines spanning 1400px are unreadable. Cap at 600-750px for body text.
-- **All caps without letter-spacing.** All-caps text needs 0.08-0.15em spacing to be legible.
+- **Inter everywhere.** Signals "I did not think about fonts."
+- **Roboto, Arial, Helvetica, system-ui as primary.** System defaults, not design decisions.
+- **Space Grotesk on repeat.** Overused in AI/crypto contexts.
+- **Light (300) weight for body text.** Hard to read. 400 minimum for body, 500+ for small text.
+- **Centered paragraphs.** Center alignment works for 1-2 lines only. Never for body text.
+- **No max-width on text.** Cap at 600-750px for body (45-75 characters per line).
+- **All caps without letter-spacing.** Needs 0.08-0.15em spacing to be legible.
 - **More than 3 font families.** Two is ideal. Three is the maximum.
-- **Font size under 14px for body text.** Especially on mobile.
+- **Font size under 14px for body text.** 16px is a safe default.
+- **Same font weight for everything.** Use at least 3 distinct weights for hierarchy.
+- **Line-height of 1.5 for all text.** Headings: 1.1-1.2. Body: 1.5-1.7. Small text: 1.6-1.8.
+- **No optical size adjustment.** Display text: lighter weight, tighter tracking. Small UI text: heavier, looser tracking.
 
 ---
 
 ## Color Anti-Patterns
 
-- **Purple gradient on white background.** The signature AI slop aesthetic.
-- **Pure black text (#000000).** Always use tinted near-black (e.g., oklch(0.15 0.02 260)).
-- **Pure gray (#808080, #cccccc).** Always tint neutrals toward the palette hue.
-- **Gray text on colored backgrounds.** Creates low contrast and looks washed out.
-- **Full-saturation brand colors for large surfaces.** Reserve maximum chroma for small accents. Large areas need reduced saturation.
-- **Too many accent colors.** One primary, one secondary maximum. More creates visual chaos.
-- **Using opacity instead of actual color values.** opacity:0.5 on colored elements creates inconsistent results depending on background.
-- **No dark mode consideration.** Even if not implementing dark mode, design with the possibility in mind.
+- **Purple gradient on white background.** The signature AI slop aesthetic. If your first instinct is purple-to-blue, stop.
+- **`bg-indigo-500`, `bg-violet-500`, `bg-purple-500` as primary.** The Tailwind default palette trap.
+- **Pure black text (#000000).** Use tinted near-black (e.g., `oklch(0.15 0.02 260)`).
+- **Pure gray (#808080, #cccccc).** Tint neutrals toward the palette hue.
+- **Gray text on colored backgrounds.** Low contrast, washed out. Use white or a very light tint.
+- **Full-saturation brand colors for large surfaces.** Reserve max chroma for small accents. Large areas need reduced saturation.
+- **Too many accent colors.** One primary, one secondary maximum.
+- **Using opacity instead of actual color values.** `opacity:0.5` creates inconsistent results. Define explicit tokens.
+- **No dark mode consideration.** Use CSS custom properties from the start.
+- **Gradient text without a solid fallback.** Breaks in selection, high contrast mode, some browsers.
+- **Rainbow or multi-stop gradients.** Two stops maximum. Four or more is a circus.
 
 ---
 
 ## Layout Anti-Patterns
 
-- **Everything centered vertically and horizontally.** Creates a lifeless vertical highway. Use left-aligned content with intentional centering for specific elements.
-- **Cards nested inside cards.** One level of card is usually enough. Nesting creates visual confusion about hierarchy.
-- **Wrapping everything in cards.** Not every piece of content needs a container with rounded corners and a shadow. Sometimes flat sections, dividers, or whitespace work better.
-- **Uniform rounded corners on everything.** Vary border-radius by context: pills for tags (999px), subtle rounding for cards (8-12px), sharper for data elements (4px).
-- **Equal spacing everywhere.** Groups need tighter internal spacing and wider external spacing. Without this, there is no visual structure.
-- **Three or four equal columns at every breakpoint.** Asymmetric grids (2:1, 3:2) are more interesting and create clearer hierarchy.
+- **Everything centered vertically and horizontally.** Creates a lifeless vertical highway. Use left-aligned content with intentional centering.
+- **Three-column equal-width feature grid as default.** The most common AI layout. Make one card dominant (2:1 split) or use a different structure.
+- **Same page structure every time.** Hero > cards > testimonials > pricing > CTA. Break the pattern: split-screen, bento grid, horizontal scroll, text-as-hero.
+- **No spatial surprises.** Every section on the same grid. Professional sites break the grid -- full-bleed images, asymmetric splits, oversized pull quotes.
+- **No density variation.** Some sections should feel spacious (hero, CTA), others dense (feature lists, data tables, pricing).
+- **No overlapping elements or grid breaks.** Elements that bleed outside containers add depth and interest.
+- **Uniform card sizing in grids.** Primary item should be visually dominant. Featured card taller/wider.
+- **Cards nested inside cards.** One level is usually enough.
+- **Wrapping everything in cards.** Sometimes flat sections, dividers, or whitespace work better.
+- **Equal spacing everywhere.** Groups need tighter internal spacing and wider external spacing.
 - **Content that could belong to any product.** If the layout has no personality, the design is not done.
+- **Sticky header over 80px.** Keep slim (48-56px) or hide on scroll-down.
+
+---
+
+## Shadow Anti-Patterns
+
+- **Same shadow on every elevated element.** `shadow-md` on cards, modals, dropdowns, and buttons is not a system.
+- **No shadow hierarchy.** Define 3-4 levels: subtle (tooltips), moderate (cards, dropdowns), dramatic (modals, drawers).
+- **Shadows invisible in dark mode.** `rgba(0,0,0,0.1)` disappears on dark backgrounds. Use inner glows, border effects, or background lightness differentiation.
+- **Shadows instead of background-color for elevation.** Elevation is often better communicated through surface tint, not shadows.
+- **Hard-edged shadows.** Small blur + high opacity = 2005. Modern shadows: large blur (20-40px), low opacity (0.03-0.08).
+- **Colored shadows that do not match the element.** A blue button with gray shadow looks disconnected. Use the element's hue at low opacity.
+
+---
+
+## Border Radius Anti-Patterns
+
+- **Uniform 8px or 16px on everything.** Border radius is a system, not one value.
+- **No hierarchy.** Pills for tags (999px), generous for modals (16-24px), subtle for cards (8-12px), sharp for data (2-4px), sharp for marketing (0-2px).
+- **Nested radius not accounting for padding.** Inner radius = outer radius minus padding. Card with `16px` radius and `8px` padding = inner element at `8px` radius.
+- **Rounded corners on elements flush with container edges.** Touching corners should be 0 radius.
+- **Mixing rounded and sharp in the same component.** Button at `8px` next to input at `0px` = two design systems colliding.
 
 ---
 
 ## Motion Anti-Patterns
 
-- **Bounce/elastic easing.** Feels dated and gimmicky. Use ease-out curves.
-- **Animating everything on the page.** Creates visual noise. Animate the important moments.
-- **transition: all 0.3s.** Animates properties you did not intend. Be specific: `transition: opacity 0.2s, transform 0.3s`.
-- **No loading feedback.** User clicks a button and nothing happens for 2 seconds. Always show progress.
-- **Spinner for content areas.** Use skeleton screens instead. Spinners should be reserved for small inline actions.
-- **Animation without prefers-reduced-motion handling.** Always provide a reduced-motion path.
+- **Bounce/elastic easing.** Dated. Use ease-out for entrances, ease-in for exits.
+- **Animating everything.** Animate important moments only: state changes, entrances, user-initiated actions.
+- **transition: all 0.3s.** Be specific: `transition: opacity 0.2s ease-out, transform 0.3s ease-out`.
+- **Uniform fade-in-on-scroll.** Stagger timing. Vary animation type. Let some elements just be there.
+- **No loading feedback.** Always show progress on async actions.
+- **Spinner for content areas.** Use skeleton screens. Spinners for small inline actions only.
+- **No prefers-reduced-motion handling.** Wrap motion in `@media (prefers-reduced-motion: no-preference)`.
+- **Duration over 500ms for UI transitions.** 150-300ms for most interactions. 300-500ms for large layout changes.
+- **Animating layout properties (width, height, top, left).** Triggers reflows. Animate `transform` and `opacity` only.
 
 ---
 
 ## Interaction Anti-Patterns
 
 - **Placeholder text as the only label.** Disappears on focus. Inaccessible.
-- **outline: none without replacement.** Keyboard users lose all orientation.
+- **outline: none without replacement.** Replace with a custom focus ring, never remove it.
 - **Hover-only interactions.** Must have keyboard and touch equivalents.
-- **Custom scrollbars that break native behavior.** Users expect scrolling to work natively.
-- **Toast notifications for errors.** They disappear. Use inline error messages instead.
-- **Alert/confirm dialogs for minor actions.** Blocking the entire page for "Are you sure?" on non-destructive actions.
-- **No focus trapping in modals.** Tab key escapes the modal and the user gets lost.
-- **Links that look like buttons and buttons that look like links.** Use the correct element for the correct purpose.
+- **Custom scrollbars that break native behavior.** Custom thin scrollbars fine. Custom scroll physics not.
+- **Toast notifications for errors.** They disappear. Use inline errors. Toasts for confirmations only.
+- **Alert/confirm dialogs for minor actions.** Do not block the page for non-destructive actions.
+- **No focus trapping in modals.** Tab key must stay within the modal.
+- **Links that look like buttons, buttons that look like links.** `<a>` navigates. `<button>` acts.
+- **Disabled buttons with no explanation.** Show inline validation or tooltip for why the action is unavailable.
+- **Click targets smaller than 44x44px on mobile.** 44px minimum per Apple and Google guidelines.
 
 ---
 
-## Code Anti-Patterns
+## Content / Copy Anti-Patterns
 
-- **div soup.** Use semantic HTML: nav, main, section, article, aside, header, footer.
-- **Inline styles for everything.** Use CSS variables, modules, or Tailwind. Inline styles cannot be overridden or themed.
-- **!important everywhere.** If specificity requires !important, the CSS architecture is broken.
-- **z-index: 9999.** Use a z-index scale (1, 10, 20, 30...) with named CSS variables.
-- **Fixed pixel values for everything.** Use rem for typography and spacing, em for component-internal sizing, px only for borders and shadows.
-- **console.log left in production.** Clean it up.
+- **"Lorem ipsum" in final deliverables.** Design without content is decoration.
+- **Stock photo people smiling at laptops.** Use contextual illustrations, product screenshots, or abstract art.
+- **"Click here" link text.** Describe the destination: "View documentation."
+- **"Submit" button text.** Use the specific action: "Create account", "Send message", "Save changes."
+- **Walls of text without hierarchy.** Break with headings, spacing, and visual rhythm.
+- **Generic headlines.** "Build the future of work." "Your all-in-one platform." "Scale without limits." These say nothing. Use a specific value proposition.
+- **AI-telltale words.** "Delve", "pivotal", "seamless", "leverage", "cutting-edge", "elevate", "harness", "robust", "streamline", "utilize." If you would not say it in conversation, do not write it.
+- **Hedge language.** "May help you", "might improve." Commit to the claim or do not make it.
+- **Unrealistic demo data.** Not $1M revenue and 99.99% uptime. Use $47,230 and 99.93%. Not "John Doe" -- use "Sarah Chen" or "Marcus Rivera."
+- **Broken Unsplash placeholder links.** `unsplash.com/random` links rot. Use solid color blocks or local assets.
+- **Exclamation marks in UI copy.** "Welcome!" "Success!" Save enthusiasm for genuinely exciting moments.
 
 ---
 
-## Content Anti-Patterns
+## Code Anti-Patterns
 
-- **"Lorem ipsum" in final deliverables.** Use real or realistic content. Design without content is decoration.
-- **Stock photo people smiling at laptops.** If using imagery, make it contextual.
-- **"Click here" link text.** Links should describe their destination: "View documentation" not "Click here".
-- **"Submit" button text.** Use the specific action: "Create account", "Send message", "Save changes".
-- **Walls of text without hierarchy.** Break content with headings, spacing, and visual rhythm.
+- **div soup.** Use semantic HTML: `nav`, `main`, `section`, `article`, `aside`, `header`, `footer`.
+- **Inline styles for everything.** Use CSS variables, modules, or Tailwind.
+- **!important everywhere.** If needed, the CSS architecture is broken.
+- **z-index: 9999.** Use a scale with named variables: `--z-dropdown: 10`, `--z-modal: 20`, `--z-toast: 30`.
+- **Fixed pixel values for everything.** `rem` for typography/spacing, `em` for component internals, `px` for borders/shadows.
+- **console.log left in production.**
+- **Tailwind class strings over 200 characters.** Extract to a component or use `@apply`.
+- **Hardcoded color values instead of CSS custom properties.** `bg-[#6366f1]` in 40 files means 40 edits for a brand change.
+- **No responsive behavior.** Test at 320px, 768px, and 1440px minimum.
 
 ---
 
 ## The Overall Pattern to Avoid
 
-The "AI slop" aesthetic is recognizable by its combination of: Inter/Roboto font, purple/blue gradient accents, evenly spaced centered layouts, uniform card grids with identical rounded corners, and generic stock imagery. Any single element might be fine in isolation. Together, they signal "an AI made this with zero human judgment."
+The AI slop aesthetic: Inter/Roboto + purple/blue gradient + centered layouts + uniform card grids + identical rounded corners + generic shadows + stock imagery. Any single element is fine in isolation. Together they signal zero human judgment.
+
+The antidote is intentionality. Every choice -- font, color, spacing, layout, animation, shadow, radius, copy -- should be a conscious decision tied to the specific context. If you cannot explain why you chose it, you defaulted.
+
+---
 
-The antidote is intentionality. Every choice (font, color, spacing, layout, animation) should be a conscious decision tied to the specific context of what you are building.
+## Professional Alternatives (Quick Reference)
+
+| AI Default | Professional Alternative |
+|---|---|
+| Inter / Roboto | Satoshi, Cabinet Grotesk, Plus Jakarta Sans, Outfit, General Sans, Switzer |
+| Purple-to-blue gradient | Single brand hue + tinted neutrals (monochromatic palette) |
+| 3-column equal cards | Asymmetric grid with primary card dominant (2:1 or 3:2 split) |
+| Centered everything | Left-aligned content with intentional centering for heroes/CTAs only |
+| Uniform 8px radius | Context-appropriate: 0-2px marketing, 8-12px cards, 16-24px modals, 999px tags |
+| `0 4px 6px rgba(0,0,0,0.1)` | Elevation-based shadow scale with 3-4 distinct levels |
+| Hero > Cards > Testimonials > CTA | Split-screen, bento grid, horizontal scroll, text-as-hero, editorial layout |
+| Fade-in everything identically | Staggered entrance with varied timing, direction, and type per element |
+| "Scale without limits" | Specific claim with real metric: "Process 10k invoices in 3 minutes" |
+| `bg-indigo-500` accent | A hue reflecting the brand, not Tailwind's default palette |
+| Generic box icons in circles | Custom illustrations, product screenshots, or no icons at all |
+| "Trusted by 10,000+ teams" | Real customer logos with permission, or skip entirely |
+| Uniform section spacing | Varied density: spacious heroes, dense feature grids, breathing room at CTAs |
+| Same shadow on everything | Shadow hierarchy: none flat, subtle cards, medium dropdowns, heavy modals |
+| Stock laptop photos | Product screenshots, hand-drawn illustrations, or abstract geometric art |