agents-config 1.0.0

package/instructions/mui.instructions.md

@@ -0,0 +1,50 @@
+# Material-UI (MUI) Coding Instructions
+
+**INSTRUCTIONS:**
+Create responsive React applications using Material-UI (MUI v7.3+) and TypeScript with strict type safety.
+
+Include the following specifications:
+
+1. **Accessibility & Performance**: Prioritize as first-class features. Follow [Web Interface Guidelines](./web-interface-guidelines.instructions.md)—semantic HTML, ARIA labels, keyboard navigation, focus states, and screen reader support.
+
+2. **Adaptive Layout & Mobile-First UX**: Use Container Queries, dynamic viewport units (`cqw`, `dvh`), and `clamp()` for responsive spacing and visual hierarchy. Test on mobile-first.
+
+3. **Grid System**: Use [MUI Grid v2 syntax](https://mui.com/material-ui/react-grid/).
+
+4. **Modern CSS & Progressive Enhancement**: Apply [CSS Wrapped 2025](https://chrome.dev/css-wrapped-2025/) principles.
+
+5. **Theming**: 
+   - Use MUI's theme provider with `cssVariables` enabled
+   - Support light/dark modes via [CSS Theme Variables](https://mui.com/material-ui/customization/css-theme-variables/usage/#light-and-dark-modes)
+   - Respect system preference (`prefers-color-scheme`) and persist user choice to `localStorage`
+   - Avoid color-mode flicker per [MUI docs](https://mui.com/material-ui/customization/dark-mode/#dark-mode-flicker)
+
+6. **Typography & Design Tokens**: Create elegant color palettes, typography scales, and spacing systems. Follow copy guidelines (curly quotes, ellipsis `…`, non-breaking spaces).
+
+7. **Icons**: Use `@mui/icons-material`—no webfont icons.
+
+8. **Dark Mode Toggle**: Implement [MUI's prescribed method](https://mui.com/material-ui/customization/dark-mode/#toggling-color-mode) with smooth transitions.
+
+9. **Component Architecture**: Extend MUI base components with TypeScript. Use PascalCase for filenames (`.tsx`). One component per file. Prefer functional components with hooks.
+
+10. **Testing & Documentation**: Create Storybook documentation and visual regression tests (Playwright/Chromatic when possible).
+
+11. **Web Standards Compliance**: Ensure forms, inputs, focus states, and interactive elements meet standards in the Web Interface Guidelines:
+    - Form inputs require labels and proper `type`/`inputmode`
+    - Icon-only buttons need `aria-label`
+    - Focus-visible states required (no `outline-none` without replacement)
+    - Semantic HTML (`<button>`, `<a>`, `<label>`) before ARIA
+    - Skip link for main content; heading hierarchy
+    - No paste-blocking; no zoom-disabling viewport settings
+    - Images need `width`/`height` to prevent CLS
+    - Virtualize large lists (>50 items)
+    - URL state for filters, tabs, pagination, expanded panels
+    - Destructive actions need confirmation
+    - Honor `prefers-reduced-motion`
+    - Animations use `transform`/`opacity` only; no `transition: all`
+    
+    **NOTE:**
+    - Use MUI's theme provider with `cssVariables` enabled
+    - Support light/dark modes via [CSS Theme Variables](https://mui.com/material-ui/customization/css-theme-variables/usage/#light-and-dark-modes)
+    - Respect system preference (`prefers-color-scheme`) and persist user choice to `localStorage`
+    - Avoid color-mode flicker per [MUI docs](https://mui.com/material-ui/customization/dark-mode/#dark-mode-flicker)

package/instructions/storybook.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: '**/*.stories.@(js|jsx|ts|tsx)'
+---
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.
+
+# /build.storybook - Scaffold Storybook Story
+
+Generate a Storybook story file following the DevLog application patterns.
+
+## Usage
+- `/build.storybook ComponentName` - Creates basic story with Primary/Secondary variants
+- `/build.storybook ComponentName --visual` - Includes visual regression testing tag
+- `/build.storybook ComponentName --variants variant1,variant2` - Custom story variants
+
+## Story Template Structure
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import Stack from '@mui/material/Stack';
+import { ComponentName } from './ComponentName';
+
+const meta: Meta = {
+  title: 'Category/Subcategory/ComponentName',
+  component: ComponentName,
+  argTypes: {
+    // Define component prop controls
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [(Story) => <Story />],
+  tags: ['!visual:check'], // Use 'visual:check' for visual regression testing
+} satisfies Meta<typeof ComponentName>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary = {
+  args: {
+    // Primary story args
+  },
+  render: (args) => {
+    return (
+      <ComponentName {...args} />
+    );
+  },
+} satisfies Story;
+```
+
+## Requirements
+Don't assume, always ask for the following inputs before generating code:
+- Use proper Storybook title categorization matching file structure
+- Add `'visual:check'` tag only when component is ready for visual regression testing
+- Define argTypes for interactive controls in Storybook
+- Use `satisfies` for type safety with Meta and Story types

package/instructions/web-interface-guidelines.instructions.md

@@ -0,0 +1,331 @@
+---
+description: Review UI code for Web Interface Guidelines compliance
+applyTo: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.
+
+## Interactions
+
+### Keyboard
+
+- MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)
+- MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`)
+- MUST: Manage focus (trap, move, return) per APG patterns
+- NEVER: `outline: none` without visible focus replacement
+
+### Targets & Input
+
+- MUST: Hit target ≥24px (mobile ≥44px); if visual <24px, expand hit area
+- MUST: Mobile `<input>` font-size ≥16px to prevent iOS zoom
+- NEVER: Disable browser zoom (`user-scalable=no`, `maximum-scale=1`)
+- MUST: `touch-action: manipulation` to prevent double-tap zoom
+- SHOULD: Set `-webkit-tap-highlight-color` to match design
+
+### Forms
+
+- MUST: Hydration-safe inputs (no lost focus/value)
+- NEVER: Block paste in `<input>`/`<textarea>`
+- MUST: Loading buttons show spinner and keep original label
+- MUST: Enter submits focused input; in `<textarea>`, ⌘/Ctrl+Enter submits
+- MUST: Keep submit enabled until request starts; then disable with spinner
+- MUST: Accept free text, validate after—don't block typing
+- MUST: Allow incomplete form submission to surface validation
+- MUST: Errors inline next to fields; on submit, focus first error
+- MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`
+- SHOULD: Disable spellcheck for emails/codes/usernames
+- SHOULD: Placeholders end with `…` and show example pattern
+- MUST: Warn on unsaved changes before navigation
+- MUST: Compatible with password managers & 2FA; allow pasting codes
+- MUST: Trim values to handle text expansion trailing spaces
+- MUST: No dead zones on checkboxes/radios; label+control share one hit target
+
+### State & Navigation
+
+- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels)
+- MUST: Back/Forward restores scroll position
+- MUST: Links use `<a>`/`<Link>` for navigation (support Cmd/Ctrl/middle-click)
+- NEVER: Use `<div onClick>` for navigation
+
+### Feedback
+
+- SHOULD: Optimistic UI; reconcile on response; on failure rollback or offer Undo
+- MUST: Confirm destructive actions or provide Undo window
+- MUST: Use polite `aria-live` for toasts/inline validation
+- SHOULD: Ellipsis (`…`) for options opening follow-ups ("Rename…") and loading states ("Loading…")
+
+### Touch & Drag
+
+- MUST: Generous targets, clear affordances; avoid finicky interactions
+- MUST: Delay first tooltip; subsequent peers instant
+- MUST: `overscroll-behavior: contain` in modals/drawers
+- MUST: During drag, disable text selection and set `inert` on dragged elements
+- MUST: If it looks clickable, it must be clickable
+
+### Autofocus
+
+- SHOULD: Autofocus on desktop with single primary input; rarely on mobile
+
+## Animation
+
+- MUST: Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- SHOULD: Prefer CSS > Web Animations API > JS libraries
+- MUST: Animate compositor-friendly props (`transform`, `opacity`) only
+- NEVER: Animate layout props (`top`, `left`, `width`, `height`)
+- NEVER: `transition: all`—list properties explicitly
+- SHOULD: Animate only to clarify cause/effect or add deliberate delight
+- SHOULD: Choose easing to match the change (size/distance/trigger)
+- MUST: Animations interruptible and input-driven (no autoplay)
+- MUST: Correct `transform-origin` (motion starts where it "physically" should)
+- MUST: SVG transforms on `<g>` wrapper with `transform-box: fill-box`
+
+## Layout
+
+- SHOULD: Optical alignment; adjust ±1px when perception beats geometry
+- MUST: Deliberate alignment to grid/baseline/edges—no accidental placement
+- SHOULD: Balance icon/text lockups (weight/size/spacing/color)
+- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
+- MUST: Respect safe areas (`env(safe-area-inset-*)`)
+- MUST: Avoid unwanted scrollbars; fix overflows
+- SHOULD: Flex/grid over JS measurement for layout
+
+## Content & Accessibility
+
+- SHOULD: Inline help first; tooltips last resort
+- MUST: Skeletons mirror final content to avoid layout shift
+- MUST: `<title>` matches current context
+- MUST: No dead ends; always offer next step/recovery
+- MUST: Design empty/sparse/dense/error states
+- SHOULD: Curly quotes (" "); avoid widows/orphans (`text-wrap: balance`)
+- MUST: `font-variant-numeric: tabular-nums` for number comparisons
+- MUST: Redundant status cues (not color-only); icons have text labels
+- MUST: Accessible names exist even when visuals omit labels
+- MUST: Use `…` character (not `...`)
+- MUST: `scroll-margin-top` on headings; "Skip to content" link; hierarchical `<h1>`–`<h6>`
+- MUST: Resilient to user-generated content (short/avg/very long)
+- MUST: Locale-aware dates/times/numbers (`Intl.DateTimeFormat`, `Intl.NumberFormat`)
+- MUST: Accurate `aria-label`; decorative elements `aria-hidden`
+- MUST: Icon-only buttons have descriptive `aria-label`
+- MUST: Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA
+- MUST: Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+
+## Content Handling
+
+- MUST: Text containers handle long content (`truncate`, `line-clamp-*`, `break-words`)
+- MUST: Flex children need `minWidth: 0` to allow truncation
+- MUST: Handle empty states—no broken UI for empty strings/arrays
+
+## Performance
+
+- SHOULD: Test iOS Low Power Mode and macOS Safari
+- MUST: Measure reliably (disable extensions that skew runtime)
+- MUST: Track and minimize re-renders (React DevTools/React Scan)
+- MUST: Profile with CPU/network throttling
+- MUST: Batch layout reads/writes; avoid reflows/repaints
+- MUST: Mutations (`POST`/`PATCH`/`DELETE`) target <500ms
+- SHOULD: Prefer uncontrolled inputs; controlled inputs cheap per keystroke
+- MUST: Virtualize large lists (>50 items)
+- MUST: Preload above-fold images; lazy-load the rest
+- MUST: Prevent CLS (explicit image dimensions)
+- SHOULD: `<link rel="preconnect">` for CDN domains
+- SHOULD: Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+## Dark Mode & Theming
+
+- MUST: `color-scheme: dark` on `<html>` for dark themes
+- SHOULD: `<meta name="theme-color">` matches page background
+- MUST: Native `<select>`: explicit `background-color` and `color` (Windows fix)
+
+## Hydration
+
+- MUST: Inputs with `value` need `onChange` (or use `defaultValue`)
+- SHOULD: Guard date/time rendering against hydration mismatch
+
+## Design
+
+- SHOULD: Layered shadows (ambient + direct)
+- SHOULD: Crisp edges via semi-transparent borders + shadows
+- SHOULD: Nested radii: child ≤ parent; concentric
+- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
+- MUST: Accessible charts (color-blind-friendly palettes)
+- MUST: Meet contrast—prefer [APCA](https://apcacontrast.com/) over WCAG 2
+- MUST: Increase contrast on `:hover`/`:active`/`:focus`
+- SHOULD: Match browser UI to bg
+- SHOULD: Avoid dark color gradient banding (use background images when needed)
+
+## Output Instructions
+
+Review these files for compliance: $ARGUMENTS
+
+Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+
+### Focus States
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders end with `…` and show example pattern
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`—list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible—respond to user input mid-animation
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `"` `"` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content Handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `minWidth: 0` to allow text truncation
+- Handle empty states—don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+### Navigation & State
+
+- URL reflects state—filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
+- Destructive actions need confirmation modal or undo window—never immediate
+
+### Touch & Interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- During drag: disable text selection, `inert` on dragged elements
+- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
+
+### Safe Areas & Layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale & i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+
+### Hydration Safety
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover & Interactive States
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Title Case for headings/buttons (MLA style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+
+## Output Format
+
+Group by file. Use `file:line` format (VS Code clickable). Terse findings.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all → list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." → "…"
+
+## src/Card.tsx
+
+✓ pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "agents-config",
+  "version": "1.0.0",
+  "description": "A comprehensive knowledge base and skill library for building production-grade React applications with AI-powered tools and best practices.",
+  "author": "Eric Thayer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ericthayer/agents-config.git"
+  },
+  "homepage": "https://github.com/ericthayer/agents-config#readme",
+  "bugs": {
+    "url": "https://github.com/ericthayer/agents-config/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "copilot",
+    "claude",
+    "gemini",
+    "cursor",
+    "react",
+    "typescript",
+    "accessibility",
+    "performance",
+    "development-tools",
+    "code-generation",
+    "agentic-workflows"
+  ],
+  "type": "module",
+  "bin": {
+    "agents-init": "./bin/agents-init.js"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "bin/",
+    "adapters/",
+    "instructions/",
+    "rules/",
+    "skills/",
+    "prompts/",
+    "schemas/"
+  ],
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js",
+    "test": "node ./bin/agents-init.js --dry-run",
+    "prepare": "echo 'Ready to publish'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/create-pr.prompt.md

@@ -0,0 +1,78 @@
+---
+agent: agent
+---
+
+# Create PR from Last Commit
+
+## Task
+Analyze the last git commit and create a comprehensive PR description.
+
+## Instructions
+
+1. **Get the latest commit details:**
+   - Use `mcp_github_get_commit` with:
+     - owner: `ericthayer`
+     - repo: `devlog`
+     - sha: Get from `git log -1 --pretty=format:"%H"`
+     - include_diff: `true`
+
+2. **Analyze the commit data:**
+   - Extract commit message (title and body)
+   - Review files changed (additions, deletions, modifications)
+   - Examine the diff to understand the scope of changes
+   - Identify the type of change (feat, fix, refactor, docs, etc.)
+
+3. **Build PR description following this structure:**
+   
+   ```markdown
+   ## Summary
+   [1-2 sentences describing the overall change]
+   
+   ## Changes
+   - **Files Modified:** [List key files with brief descriptions]
+   - **Key Changes:** [Bullet points of what was changed and why]
+   
+   ## Type of Change
+   - [ ] Bug fix (non-breaking)
+   - [ ] New feature (non-breaking)
+   - [ ] Breaking change
+   - [ ] Documentation update
+   - [ ] Refactoring
+   
+   ## Testing
+   [Describe testing approach or note if manual testing needed]
+   
+   ## Checklist
+   - [ ] Code follows project style guidelines
+   - [ ] Documentation updated
+   - [ ] No new warnings generated
+   - [ ] Tests added/updated
+   ```
+
+4. **Create the Pull Request:**
+  
+```bash
+# Get current branch
+BRANCH=$(git branch --show-current)
+
+# Create PR with template
+gh pr create \
+  --title "$(git log -1 --pretty=format:'%s')" \
+  --body "$(cat .github/pr-template-commits.md)" \
+  --base main \
+  --head $BRANCH
+```
+
+See `.github/GITHUB_AUTH_SETUP.md` for authentication setup.
+
+## Context
+- Repository: github.com/ericthayer/devlog
+- Default base branch: `main`
+- See `.github/pr-template-commits.md` for reusable PR description template
+- See `.github/GITHUB_AUTH_SETUP.md` for GitHub authentication guide
+
+## Success Criteria
+✅ PR created with descriptive title
+✅ Body contains summary, changes, and testing info
+✅ All relevant files mentioned
+✅ Clear description of what and why

package/prompts/scaffold-component.prompt.md

@@ -0,0 +1,57 @@
+---
+agent: agent
+description: Create a React component named [ComponentName] that accepts props defined in [ComponentName]Props interface.
+---
+# Create Starter Component
+**Read Instructions** from `./instructions/development-standards.instructions.md` before proceeding to see if there is anything specific to this prompt and helpful context when building React components.
+
+**Development Process**: Follow [Spec-Driven Development](../workflows/sdd-workflow.md)
+- Create component spec FIRST using the SDD template before generating code
+- Spec location: `src/components/${category}/${componentName}/${componentName}.spec.md`
+- Update spec changelog for any changes during development
+
+**Alternative**: Use the `scaffold-component` skill from `../skills/scaffold-component/SKILL.md` for full SDD workflow integration
+
+## Context Variables
+- Current file: ${file}
+- Working directory: ${fileDirname}
+- Component name hint: ${fileBasenameNoExtension}
+
+## Required Inputs
+Don't assume, always ask for the following inputs before generating code:
+1. **Component Name** (must start with "Cb", e.g., "CbButton", "CbDataGrid")
+2. **MUI Base Component** (what MUI component to extend, e.g., "Button", "Card")
+3. **Category** (one of: dataDisplay, inputs, navigation, surfaces, feedback, entitlements, templates)
+
+## Generation Rules
+- Create 4 files in `./src/components/${category}/${componentName}/`:
+  - `${componentName}.tsx` - Main component
+  - `${componentName}.stories.tsx` - Storybook stories (must include 'visual:check' tag)
+  - `${componentName}.mdx` - Documentation
+  - `index.ts` - Exports
+
+## Templates
+Reference files in `src/examples/StarterComponent/` for structure patterns:
+- Use `CbStarter.tsx` pattern for component structure
+- Use `CbStarter.stories.tsx` pattern for stories (includes visual:check tag)
+- Use `CbStarter.mdx` pattern for documentation
+
+## MDX Structure (CRITICAL)
+**MUST include these wrappers** (see `.github/instructions/mdx.instructions.md`):
+1. Import `Unstyled` from `@storybook/addon-docs/blocks`
+2. Wrap all content in `<Unstyled>` → `<CSSTransition>` → `<div className="cbds-spec">` → `<ThemeProvider>`
+
+```mdx
+<Meta of={ComponentStories} />
+
+<Unstyled>
+  <CSSTransition in={true} appear timeout={300} classNames="fade">
+    <div className="cbds-spec">
+      <ThemeProvider theme={createCoBankTheme()}>
+        <CssBaseline />
+        {/* Content here */}
+      </ThemeProvider>
+    </div>
+  </CSSTransition>
+</Unstyled>
+```

package/rules/accessibility.md

@@ -0,0 +1,36 @@
+---
+description: Accessibility standards for Three.js and React applications.
+---
+
+**OBJECTIVE:**
+Building inclusive 3D web experiences that are accessible to keyboard users, screen reader users, and those with motion sensitivities.
+
+**REASON:**
+3D environments are inherently non-semantic. Without explicit effort, they are invisible to assistive technologies and can cause physical discomfort for users with vestibular disorders.
+
+**DESCRIPTION:**
+Guidelines for semantic canvas layering, focus management, and motion preference handling.
+
+**INSTRUCTIONS:**
+
+### Instant Perceptual Feedback
+- **Critical CSS Inlining**: Inline the minimum CSS required to render a themed background and loading indicator directly in the `<head>` of `index.html`. This prevents the "blank white screen" during bundle download.
+- **Pre-Hydration Status**: Provide a `role="status"` or `aria-live="polite"` container in the initial HTML structure. Use CSS `:empty` pseudo-classes to show a loading message that automatically disappears once React hydrates the root.
+- **Theme-Aware Loading**: Ensure the initial "Critical" background color matches the user's system preference (light/dark) to avoid "flash of un-themed content" (FOUT/FOIT).
+
+### Scene Accessibility
+- **Canvas Metadata**: Always provide a descriptive `aria-label` or `title` on the `<canvas>` element. Use `role="img"` if the scene is purely visual, or `role="application"` if it is interactive.
+- **Fallback Content**: Place a text description of the scene inside the `<canvas>` tag for older browsers or screen readers that don't support canvas metadata.
+
+### Motion Control (CRITICAL)
+- **Respect `@media (prefers-reduced-motion)`**: Use the `useMediaQuery` hook or CSS to detect if the user prefers reduced motion.
+- **Auto-Pause/Slow**: If reduced motion is active, automatically pause or significantly slow down ambient animations (rotations, particle systems, floating effects).
+- **Toggle Visibility**: Avoid rapid flashing or strobing effects in 3D scenes.
+
+### Interaction & Focus
+- **Standard UI Elements**: Use standard HTML `<button>` or `<a>` tags for interactions whenever possible, layered over the canvas.
+- **Keyboard Navigation**: Ensure every interactive element in the 3D scene can be reached and activated via the `Tab` and `Enter/Space` keys.
+- **Visual Focus States**: Never remove focus outlines (`outline: none`) without providing a clear, high-contrast alternative for navigated elements.
+
+### Contrast & Legibility
+- **Text over 3D**: Ensure text labels overlaying 3D scenes have sufficient contrast (WCAG AA 4.5:1). Use text-shadows or semi-transparent backgrounds to guarantee legibility over dynamic backgrounds.