picasso-skill 1.2.0 → 1.3.0

package/README.md

@@ -56,7 +56,7 @@ Upload `skills/picasso/SKILL.md` as a Custom Skill in Claude.ai settings. Upload
 
 | | Skill | Agent |
 |---|---|---|
-| **What it is** | Static knowledge base (13 reference files) | Autonomous design engineer |
+| **What it is** | Static knowledge base (20 reference files) | Autonomous design engineer |
 | **How it works** | Loaded into context when designing | Runs as a sub-process with its own tools |
 | **When it runs** | When you ask for design help | Proactively after any frontend code change |
 | **Can audit code** | Only when you ask | Automatically |
@@ -71,22 +71,32 @@ Upload `skills/picasso/SKILL.md` as a Custom Skill in Claude.ai settings. Upload
 skills/picasso/
   SKILL.md                          # Main skill file (knowledge base)
   references/
-    typography.md                   # Type systems, font pairing, scales, OpenType
-    color-and-contrast.md           # OKLCH, tinted neutrals, dark mode, a11y
+    anti-patterns.md                # AI slop fingerprint + what NOT to do
+    typography.md                   # Font pairing, type scales, variable fonts, 12 curated pairings
+    color-and-contrast.md           # OKLCH, 10 curated palettes, P3 wide gamut, dark mode
     spatial-design.md               # Spacing scales, grids, visual hierarchy
     motion-and-animation.md         # Easing, staggering, text morphing, reduced motion
     interaction-design.md           # Forms, focus, loading, empty states, errors
-    responsive-design.md            # Mobile-first, fluid, container queries, dvh/svh
+    responsive-design.md            # Mobile-first, dvh/svh, container queries, print
     sensory-design.md               # UI sounds, haptic feedback, multi-sensory
     react-patterns.md               # React 19, Tailwind v4, Server Actions, dark mode
-    anti-patterns.md                # What NOT to do (the most important file)
+    accessibility-wcag.md           # Full ARIA patterns, WCAG 2.2, SPA focus management
+    modern-css-performance.md       # :has(), scroll animations, view transitions, @layer
+    performance-optimization.md     # Core Web Vitals, 45 React/Next.js perf patterns
+    ux-writing.md                   # Button labels, error templates, microcopy, banned words
+    ux-psychology.md                # Gestalt, cognitive laws, scanning patterns
+    conversion-design.md            # Landing pages, CTAs, pricing, onboarding
+    data-visualization.md           # Charts, dashboards, data palettes, Tufte principles
+    style-presets.md                # 22 curated visual presets with colors + fonts
     design-system.md                # DESIGN.md generation, theming, tokens (OKLCH)
     generative-art.md               # p5.js, SVG, Canvas 2D, noise, seeded randomness
     component-patterns.md           # Standard naming, taxonomy, state matrix
-    accessibility.md                # ARIA, keyboard nav, screen readers, WCAG 2.2
 
 agents/
   picasso.md                        # Autonomous design auditor agent
+
+templates/
+  picasso-config.md                 # .picasso.md project config template
 ```
 
 ## Agent Commands
@@ -107,7 +117,13 @@ The Picasso agent responds to these commands:
 | `/theme` | Generate or apply a theme |
 | `/stitch` | Generate a complete DESIGN.md from the current codebase |
 | `/harden` | Add error handling, loading states, empty states |
-| `/a11y` | Accessibility-only audit (axe-core, ARIA, contrast, keyboard) |
+| `/a11y` | Accessibility audit: axe-core + pa11y + Lighthouse |
+| `/perf` | Lighthouse performance audit with Core Web Vitals thresholds |
+| `/visual-diff` | Screenshot desktop + mobile in light/dark, analyze visually |
+| `/consistency` | Multi-page consistency check across all routes |
+| `/lint-design` | Find hardcoded colors, spacing, fonts, z-index chaos |
+| `/install-hooks` | Generate git pre-commit hook for design checks |
+| `/ci-setup` | Generate GitHub Actions workflow for PR design review |
 
 ## Agent Audit Checklist
 

package/agents/picasso.md

@@ -41,7 +41,13 @@ Before judging anything, understand what you're working with.
 1. **Identify changed files** -- run `git diff --name-only` and `git diff --staged --name-only` to find modified frontend files (.tsx, .jsx, .css, .html, .svelte, .vue, .astro)
 2. **Read the files** -- read every changed frontend file in full. Do not review code you haven't read.
 3. **Find the design system** -- search for `DESIGN.md`, `tailwind.config.*`, `theme.ts`, `tokens.css`, `globals.css`, or CSS variable definitions. If a design system exists, all findings must be measured against it.
-4. **Check for existing patterns** -- grep for common component imports (shadcn, radix, headless-ui, chakra, mantine) to understand the component library in use.
+4. **Load project design config** -- search for `.picasso.md` in the project root (or locate it with `glob **/.picasso.md`). If found, parse it and treat its values as the project's declared design preferences:
+   - **Typography overrides** -- if the config declares a font (e.g., Inter, Roboto), do NOT flag it as AI-slop. The project has intentionally chosen it.
+   - **Color overrides** -- if the config declares a primary accent or neutral tint, validate usage against those values instead of Picasso defaults.
+   - **Design settings** -- honor `DESIGN_VARIANCE`, `MOTION_INTENSITY`, and `VISUAL_DENSITY` when calibrating the severity and scope of suggestions.
+   - **Constraints** -- treat every listed constraint as a hard requirement that overrides other Picasso recommendations (e.g., if "No animations" is listed, skip all motion suggestions).
+   - If `.picasso.md` is **not found**, proceed with Picasso defaults and note in the report that no project config was detected. You can generate one with the config template at `templates/picasso-config.md`.
+5. **Check for existing patterns** -- grep for common component imports (shadcn, radix, headless-ui, chakra, mantine) to understand the component library in use.
 
 ## Phase 2: Design Audit
 
@@ -310,7 +316,304 @@ When the user invokes these commands, execute the corresponding workflow:
 | `/theme` | Generate or apply a theme via DESIGN.md |
 | `/stitch` | Generate a complete DESIGN.md from the current codebase |
 | `/harden` | Add error handling, loading states, empty states, edge case handling |
-| `/a11y` | Accessibility-only audit: run axe-core, check ARIA, validate contrast, test keyboard nav |
+| `/a11y` | Accessibility-only audit: run axe-cli, pa11y, and Lighthouse accessibility category with JSON output parsing; check ARIA, validate contrast, test keyboard nav |
+| `/perf` | Performance audit: run Lighthouse CLI, extract Core Web Vitals (LCP, CLS, INP/TBT), report with pass/fail thresholds |
+| `/visual-diff` | Visual regression: take desktop + mobile screenshots in light and dark mode, analyze for AI-slop indicators |
+| `/consistency` | Multi-page consistency check: discover routes, run checks across all pages, produce cross-page comparison table |
+| `/lint-design` | Design token linting: find hardcoded colors, inconsistent spacing, non-standard fonts, z-index chaos, transition:all |
+| `/install-hooks` | Generate a git pre-commit hook that runs fast grep-based design checks (no server needed) |
+| `/ci-setup` | Generate a GitHub Actions workflow for PR design review: a11y, perf, screenshots, PR comment |
+
+## Advanced Automation Commands
+
+### /perf -- Performance Audit
+
+Run Lighthouse CLI, extract Core Web Vitals (LCP, CLS, INP/TBT), report scores with pass/fail thresholds:
+
+```bash
+npx lighthouse http://localhost:3000 --only-categories=performance --output=json --output-path=/tmp/lh-perf.json --chrome-flags="--headless --no-sandbox" --quiet
+```
+
+Parse the JSON output to extract these metrics with thresholds:
+
+| Metric | Pass | Needs Work | Fail |
+|---|---|---|---|
+| Performance Score | >= 90 | 50-89 | < 50 |
+| FCP (First Contentful Paint) | < 1.8s | 1.8-3.0s | > 3.0s |
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5-4.0s | > 4.0s |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 |
+| TBT (Total Blocking Time) | < 200ms | 200-600ms | > 600ms |
+| SI (Speed Index) | < 3.4s | 3.4-5.8s | > 5.8s |
+
+```bash
+# Parse results from JSON
+node -e "
+const r = require('/tmp/lh-perf.json');
+const a = r.audits;
+console.log('Performance Score:', Math.round(r.categories.performance.score * 100));
+console.log('FCP:', a['first-contentful-paint'].displayValue);
+console.log('LCP:', a['largest-contentful-paint'].displayValue);
+console.log('CLS:', a['cumulative-layout-shift'].displayValue);
+console.log('TBT:', a['total-blocking-time'].displayValue);
+console.log('SI:', a['speed-index'].displayValue);
+"
+```
+
+### /visual-diff -- Visual Regression
+
+Take screenshots at desktop (1440x900) and mobile (375x812), both light and dark mode. Use Playwright screenshot commands:
+
+```bash
+# Desktop - Light mode
+npx playwright screenshot http://localhost:3000 /tmp/picasso-desktop-light.png --viewport-size=1440,900 2>/dev/null
+
+# Desktop - Dark mode (inject prefers-color-scheme)
+npx playwright screenshot http://localhost:3000 /tmp/picasso-desktop-dark.png --viewport-size=1440,900 --color-scheme=dark 2>/dev/null
+
+# Mobile - Light mode
+npx playwright screenshot http://localhost:3000 /tmp/picasso-mobile-light.png --viewport-size=375,812 2>/dev/null
+
+# Mobile - Dark mode
+npx playwright screenshot http://localhost:3000 /tmp/picasso-mobile-dark.png --viewport-size=375,812 --color-scheme=dark 2>/dev/null
+```
+
+Analyze all four screenshots visually for:
+- AI-slop indicators (generic gradients, everything centered, uniform card grids)
+- Light/dark mode consistency (same hierarchy, no lost contrast, no invisible elements)
+- Mobile responsiveness (no overflow, readable text, adequate touch targets)
+- Visual regression from previous state (if baseline screenshots exist)
+
+### /consistency -- Multi-Page Consistency Check
+
+Discover routes (from file-system routing or user input), run the same checks across all pages, produce a cross-page comparison table:
+
+```bash
+# Discover routes from Next.js app directory
+find src/app -name "page.tsx" -o -name "page.jsx" 2>/dev/null | sed 's|src/app||;s|/page\.\(tsx\|jsx\)||;s|^$|/|'
+
+# Or from pages directory
+find src/pages -name "*.tsx" -o -name "*.jsx" 2>/dev/null | sed 's|src/pages||;s|\.\(tsx\|jsx\)||;s|/index$|/|'
+```
+
+For each discovered route:
+1. Take a screenshot
+2. Extract font families used (`grep -rn 'font-family\|fontFamily'`)
+3. Extract color values used
+4. Extract spacing patterns
+5. Check for shared component usage
+
+Output a cross-page comparison table:
+
+```
+| Page     | Font Families | Primary Colors | Spacing Base | Shared Components |
+|----------|---------------|----------------|--------------|-------------------|
+| /        | Geist, mono   | oklch(...)     | 4px scale    | Header, Footer    |
+| /about   | Geist, mono   | oklch(...)     | 4px scale    | Header, Footer    |
+| /pricing | Geist, serif  | #3b82f6 (!)    | mixed (!)    | Header only (!)   |
+```
+
+Flag inconsistencies with `(!)` markers.
+
+### /lint-design -- Design Token Linting
+
+Run Stylelint + grep-based checks to find design system violations:
+
+```bash
+# 1. Find hardcoded colors that should be tokens
+grep -rn '#[0-9a-fA-F]\{3,8\}' --include="*.tsx" --include="*.jsx" --include="*.css" | grep -v 'node_modules\|\.git\|\.next' | head -30
+
+# 2. Find inconsistent spacing values (non-4px-multiple)
+grep -rn 'padding\|margin\|gap' --include="*.css" --include="*.tsx" | grep -oP '\d+px' | sort | uniq -c | sort -rn
+
+# 3. Find non-standard font stacks
+grep -rn 'font-family\|fontFamily' --include="*.css" --include="*.tsx" --include="*.jsx" | grep -v 'node_modules' | head -20
+
+# 4. Find z-index chaos (values not from a defined scale)
+grep -rn 'z-index\|zIndex' --include="*.css" --include="*.tsx" --include="*.jsx" | grep -v 'node_modules' | head -20
+
+# 5. Find transition:all (anti-pattern)
+grep -rn 'transition:\s*all\|transition-property:\s*all' --include="*.css" --include="*.tsx" --include="*.jsx" | grep -v 'node_modules'
+
+# 6. Run Stylelint if available
+npx stylelint "**/*.css" --formatter=json 2>/dev/null || true
+```
+
+Report findings grouped by category with severity and suggested token replacements.
+
+### /install-hooks -- Git Pre-commit Hook
+
+Generate a `.git/hooks/pre-commit` script that runs fast design checks (grep-based, no server needed):
+
+```bash
+cat > .git/hooks/pre-commit << 'HOOK'
+#!/usr/bin/env bash
+set -e
+
+STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx|css|html|svelte|vue)$' || true)
+[ -z "$STAGED" ] && exit 0
+
+ERRORS=0
+
+echo "Running Picasso pre-commit checks..."
+
+# 1. transition:all detection
+if echo "$STAGED" | xargs grep -l 'transition:\s*all' 2>/dev/null; then
+  echo "ERROR: transition:all found. Specify properties explicitly."
+  ERRORS=$((ERRORS + 1))
+fi
+
+# 2. Pure black (#000) detection
+if echo "$STAGED" | xargs grep -l '#000000\|#000[^0-9a-fA-F]' 2>/dev/null; then
+  echo "ERROR: Pure black (#000) found. Use tinted near-black instead."
+  ERRORS=$((ERRORS + 1))
+fi
+
+# 3. outline:none detection (without focus-visible replacement)
+if echo "$STAGED" | xargs grep -l 'outline:\s*none\|outline:\s*0[^.]' 2>/dev/null; then
+  echo "WARNING: outline:none found. Ensure :focus-visible has a replacement."
+  ERRORS=$((ERRORS + 1))
+fi
+
+# 4. Missing alt text detection
+if echo "$STAGED" | xargs grep -l '<img' 2>/dev/null | xargs grep -L 'alt=' 2>/dev/null; then
+  echo "ERROR: <img> tags without alt attribute found."
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ "$ERRORS" -gt 0 ]; then
+  echo ""
+  echo "Picasso found $ERRORS design issue(s). Fix them before committing."
+  exit 1
+fi
+
+echo "Picasso pre-commit checks passed."
+exit 0
+HOOK
+chmod +x .git/hooks/pre-commit
+echo "Pre-commit hook installed."
+```
+
+### /ci-setup -- GitHub Actions Workflow
+
+Generate a `.github/workflows/picasso-review.yml` that runs on PRs touching frontend files:
+
+```yaml
+name: Picasso Design Review
+
+on:
+  pull_request:
+    paths:
+      - '**/*.tsx'
+      - '**/*.jsx'
+      - '**/*.css'
+      - '**/*.html'
+      - '**/*.svelte'
+      - '**/*.vue'
+
+jobs:
+  picasso-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Start dev server
+        run: npm run dev &
+        env:
+          PORT: 3000
+
+      - name: Wait for server
+        run: npx wait-on http://localhost:3000 --timeout 60000
+
+      - name: Accessibility audit (axe-cli)
+        run: npx axe-cli http://localhost:3000 --exit --save /tmp/axe-results.json || true
+
+      - name: Accessibility audit (pa11y)
+        run: npx pa11y http://localhost:3000 --reporter json > /tmp/pa11y-results.json || true
+
+      - name: Lighthouse accessibility
+        run: |
+          npx lighthouse http://localhost:3000 --only-categories=accessibility --output=json --output-path=/tmp/lh-a11y.json --chrome-flags="--headless --no-sandbox" --quiet || true
+
+      - name: Lighthouse performance
+        run: |
+          npx lighthouse http://localhost:3000 --only-categories=performance --output=json --output-path=/tmp/lh-perf.json --chrome-flags="--headless --no-sandbox" --quiet || true
+
+      - name: Take screenshots
+        run: |
+          npx playwright install chromium --with-deps
+          npx playwright screenshot http://localhost:3000 /tmp/picasso-desktop.png --viewport-size=1440,900
+          npx playwright screenshot http://localhost:3000 /tmp/picasso-mobile.png --viewport-size=375,812
+
+      - name: Parse scores
+        id: scores
+        run: |
+          PERF=$(node -e "const r=require('/tmp/lh-perf.json');console.log(Math.round(r.categories.performance.score*100))" 2>/dev/null || echo "N/A")
+          A11Y=$(node -e "const r=require('/tmp/lh-a11y.json');console.log(Math.round(r.categories.accessibility.score*100))" 2>/dev/null || echo "N/A")
+          echo "perf=$PERF" >> $GITHUB_OUTPUT
+          echo "a11y=$A11Y" >> $GITHUB_OUTPUT
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: picasso-results
+          path: /tmp/picasso-*.png
+
+      - name: Post PR comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const perf = '${{ steps.scores.outputs.perf }}';
+            const a11y = '${{ steps.scores.outputs.a11y }}';
+            const body = `## Picasso Design Review\n\n| Metric | Score |\n|---|---|\n| Performance | ${perf}/100 |\n| Accessibility | ${a11y}/100 |\n\nScreenshots uploaded as workflow artifacts.`;
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body
+            });
+```
+
+### /a11y -- Accessibility Audit (Enhanced)
+
+Run all three accessibility tools with JSON output parsing:
+
+```bash
+# 1. axe-cli -- WCAG 2.1 AA violations
+npx axe-cli http://localhost:3000 --exit --save /tmp/axe-results.json 2>/dev/null
+node -e "
+const r = require('/tmp/axe-results.json');
+const v = r[0]?.violations || [];
+console.log('axe-cli: ' + v.length + ' violations');
+v.forEach(v => console.log('  [' + v.impact + '] ' + v.id + ': ' + v.description + ' (' + v.nodes.length + ' nodes)'));
+"
+
+# 2. pa11y -- HTML_CodeSniffer + WCAG 2.1 AA
+npx pa11y http://localhost:3000 --reporter json > /tmp/pa11y-results.json 2>/dev/null
+node -e "
+const r = require('/tmp/pa11y-results.json');
+console.log('pa11y: ' + r.length + ' issues');
+r.forEach(i => console.log('  [' + i.type + '] ' + i.code + ': ' + i.message));
+"
+
+# 3. Lighthouse accessibility category
+npx lighthouse http://localhost:3000 --only-categories=accessibility --output=json --output-path=/tmp/lh-a11y.json --chrome-flags="--headless --no-sandbox" --quiet
+node -e "
+const r = require('/tmp/lh-a11y.json');
+const score = Math.round(r.categories.accessibility.score * 100);
+console.log('Lighthouse a11y score: ' + score + '/100');
+const failed = Object.values(r.audits).filter(a => a.score === 0);
+failed.forEach(a => console.log('  FAIL: ' + a.id + ' - ' + a.title));
+"
+```
+
+Combine results from all three tools, deduplicate overlapping findings, and report with severity levels.
 
 ## Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"

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.