A Claude Code-integrated multi-framework app development framework with TypeScript, Tailwind CSS, and automated design-to-code pipelines.
- 56 Custom Agents -- Specialized AI agents for engineering, design, testing, marketing, operations, and more
- 23 Development Skills -- Automated workflows for Figma/Canva/screenshot/conversation conversion, TDD, E2E testing, visual QA, state management, forms, auth, animation, SEO, and more
- 10-Phase Design-to-React Pipeline -- Convert Figma or Canva designs into fully working, tested React apps with a single command -- or just describe the app and let
/build-from-conversationgenerate the Figma design first - App-Type Awareness -- Tailored build and test strategies for web apps, Chrome extensions, and PWAs
- Testing Stack -- Vitest, React Testing Library, Playwright (cross-browser), Storybook, and pixel-diff visual QA
- Code Quality Scripts -- Linting, formatting, type checking, bundle analysis, accessibility scanning, and design token verification
# Clone the repository
git clone <repository-url>
cd aurelius
# Initialize a new project (Next.js, Vite, Astro, SvelteKit, or Expo)
./scripts/setup-project.sh my-app --vite # or --next, --astro, --svelte, --expo
# Install dependencies
cd app && pnpm install
# Start development
pnpm dev/build-from-figma https://figma.com/file/abc123/My-Design
This runs a 10-phase autonomous pipeline:
[0] Token Sync → Drift check (conditional, if lockfile exists)
[1] Intake → Figma discovery + build-spec.json
[2] Token Lock → Design tokens lockfile + Tailwind config
[3] TDD (Gate) → Failing tests written first (mandatory)
[4] Build → React components that pass the tests
[5] Visual Diff → Pixel-level comparison loop (max 5 iterations, 2% threshold)
[6] E2E Tests → Playwright tests (app-type-aware)
[7] Cross-Browser→ Firefox/WebKit screenshots (non-blocking)
[8] Quality Gate → Coverage + TypeScript + build + tokens + Lighthouse + mutation score (opt-in)
[8.5] Responsive → Screenshots at 5 breakpoints (non-blocking)
[9] Report → Build report with diff images + component docs
project-root/
├── app/ # Your application (generated by pipeline or setup script)
├── scripts/ # Automation scripts
│ ├── setup-project.sh # Initialize new project
│ ├── lint-and-format.sh # ESLint + Prettier
│ ├── run-tests.sh # Vitest with coverage
│ ├── check-types.sh # TypeScript type checking
│ ├── check-bundle-size.sh # Bundle size analysis
│ ├── check-accessibility.sh # a11y scanning
│ ├── verify-tokens.sh # Design token enforcement
│ ├── verify-test-coverage.sh # Component test verification
│ ├── visual-diff.js # Pixel-level screenshot comparison
│ ├── cross-browser-test.sh # Playwright multi-browser
│ ├── setup-playwright.sh # One-time browser setup
│ ├── check-dead-code.sh # Dead code detection (knip)
│ ├── check-security.sh # Dependency audit + anti-patterns
│ ├── generate-api-client.sh # OpenAPI → typed client
│ ├── check-responsive.sh # Responsive screenshots
│ ├── check-dark-mode.sh # Dark mode verification
│ ├── sync-tokens.sh # Token drift detection
│ ├── generate-stories.sh # Storybook story generation
│ └── generate-component-docs.sh # Component documentation
├── templates/ # Starter configs
│ ├── shared/ # ESLint, Prettier, Tailwind, TS, Vitest
│ ├── nextjs/ # Next.js config
│ ├── vite/ # Vite config
│ ├── astro/ # Astro hybrid-islands starter (React + Tailwind)
│ └── chrome-extension/ # Playwright E2E fixtures for extensions
├── docs/ # Documentation
│ ├── figma-to-react/ # Figma pipeline guide
│ ├── canva-to-react/ # Canva pipeline guide
│ └── react-development/ # Development standards
├── .claude/ # Claude Code configuration
│ ├── agents/ # 56 custom agents
│ ├── skills/ # 23 development skills
│ ├── commands/ # Slash commands (/build-from-figma, /lint, /test)
│ ├── pipeline.config.json # Pipeline thresholds and app-type definitions
│ ├── CUSTOM-AGENTS-GUIDE.md # Agent catalog
│ └── PLUGINS-REFERENCE.md # Plugin reference
├── CLAUDE.md # Claude Code project instructions
└── README.md # This file
/build-from-canva https://www.canva.com/design/DAGxyz.../My-Design
Same 12-phase pipeline as Figma, with AI-powered token inference:
- Phase 1: Vision-based design discovery (screenshots + Claude analysis)
- Phase 2: AI token extraction with confidence scoring (requires user confirmation)
- Phases 3-9: Shared pipeline (TDD, build, visual diff, E2E, quality gate)
/build-from-conversation a minimal analytics dashboard with auth and dark mode
No design file needed -- describe the app and the pipeline designs it first:
- Phase C0: Structured interview (max 7 questions) →
build-spec.json+design-brief.json - Phase C1: The conversation-designer agent renders the brief as HTML mockups, which are captured into a real Figma file via the Figma MCP (
generate_figma_design) - Handoff: The generated Figma URL feeds
/build-from-figma, which runs unchanged (figma-intake fast-paths the interview)
aurelius pipeline indesign brochure.pdf --target react --styling tailwind --output ./src/indesign
For print-first sources, InDesign joins Figma and Canva as a first-class input. An
exported IDML package or PDF (the normal designer handoff) is parsed into the
shared IR, mapped to design tokens, and turned into typed React components plus
Storybook stories — driven by the indesign-to-react agent or the
indesign-conversion skill. See docs/pipelines/indesign.md.
The /build-from-figma command takes a Figma URL and autonomously builds a working React application through 10 phases. Key enforcement rules:
- TDD is mandatory -- Tests are written before components (Phase 3 gates Phase 4)
- Visual QA uses pixel diff --
pixelmatch-based comparison, not manual eyeballing - E2E tests are generated -- Tailored to app type (web app, Chrome extension, PWA)
- Design tokens are locked -- A lockfile prevents hardcoded values from entering components
| App Type | Detection | E2E Strategy | Special Handling |
|---|---|---|---|
| Web App | Default | Page navigation, forms, responsive | Standard Playwright |
| Chrome Extension | manifest.json with manifest_version |
Extension load, popup, storage, content scripts | Persistent browser context with --load-extension |
| PWA | manifest.json with start_url |
Install prompt, offline fallback | Service worker and offline tests |
All thresholds and behavior are configurable in .claude/pipeline.config.json:
- Visual diff pass threshold (default: 2%)
- Max visual iterations (default: 5)
- TDD enforcement (default: on, non-negotiable)
- Coverage threshold (default: 80%)
- Lighthouse minimums (performance: 80, accessibility: 90)
- App-type-specific E2E strategies
Agents are auto-selected by Claude Code based on your task:
| Category | Count | Key Agents |
|---|---|---|
| Engineering | 12 | frontend-developer, backend-architect, rapid-prototyper, test-writer-fixer, error-boundary-architect, migration-specialist, i18n-engineer, animation-optimizer, bundle-analyzer |
| Design | 5 | ui-designer, ux-researcher, brand-guardian |
| Design-to-Code | 8 | figma-react-converter, canva-react-converter, astro-converter, vue-converter, svelte-converter, react-native-converter, conversation-designer, asset-cataloger |
| Testing & QA | 7 | visual-qa-agent, accessibility-auditor, api-tester, performance-benchmarker |
| Product | 3 | sprint-prioritizer, feedback-synthesizer, trend-researcher |
| Marketing | 7 | content-creator, growth-hacker, app-store-optimizer |
| Project Mgmt | 3 | studio-producer, project-shipper, experiment-tracker |
| Operations | 5 | analytics-reporter, infrastructure-maintainer, legal-compliance-checker |
| Other | 5 | docusaurus-expert, agent-expert, command-expert, joker, studio-coach |
Full catalog: .claude/CUSTOM-AGENTS-GUIDE.md
| # | Skill | Purpose |
|---|---|---|
| 1 | figma-intake | Figma discovery + build-spec.json generation |
| 2 | design-token-lock | Extract and lock design tokens from Figma |
| 3 | tdd-from-figma | Write failing tests before components (app-type-aware) |
| 4 | figma-to-react-workflow | Generate components that pass the tests |
| 5 | visual-qa-verification | Pixel-diff comparison loop with region analysis |
| 6 | e2e-test-generator | Generate Playwright E2E tests (app-type-aware) |
| 7 | parallel-orchestration | Concurrent phase execution with dependency graph |
| # | Skill | Purpose |
|---|---|---|
| 8 | canva-intake | Canva design discovery + build-spec.json generation |
| 9 | canva-token-inference | AI-powered token extraction from Canva/screenshot sources |
| 10 | screenshot-intake | URL/screenshot capture + vision-based discovery |
| 11 | conversation-intake | Conversational interview → build-spec.json + design-brief.json |
| 12 | design-brief-to-figma | Generate a real Figma file from the design brief (HTML-mockup capture) |
| # | Skill | Purpose |
|---|---|---|
| 13 | react-component-development | Component patterns, hooks, composition |
| 14 | react-testing-workflows | Vitest, RTL, Playwright, Storybook |
| 15 | react-performance-optimization | Profiling, bundle analysis, Web Vitals |
| 16 | react-accessibility | WCAG 2.1 AA patterns for React |
| 17 | state-management | Zustand, TanStack Query, URL state architecture |
| 18 | form-handling | React Hook Form + Zod: typed forms, wizards |
| 19 | auth-flows | Auth.js, Clerk, Supabase Auth, RBAC |
| 20 | animation-motion | Framer Motion, CSS transitions, reduced-motion a11y |
| 21 | seo-metadata | Next.js Metadata API, JSON-LD, OG images, sitemaps |
| # | Skill | Purpose |
|---|---|---|
| 22 | export-design-system | Export components + tokens as a publishable pnpm workspace |
Full catalog: .claude/skills/README.md
./scripts/lint-and-format.sh # ESLint + Prettier
./scripts/check-types.sh # TypeScript type checking
./scripts/check-bundle-size.sh # Bundle size analysis
./scripts/check-accessibility.sh # Automated a11y scanning./scripts/run-tests.sh # Vitest unit/component tests
./scripts/cross-browser-test.sh # Playwright multi-browser screenshots
./scripts/setup-playwright.sh # One-time browser engine setupMutation testing measures how well the test suite actually catches bugs. The
framework's own TypeScript code (packages/pipeline) is mutation-tested via
Stryker; stryker.conf.json lives at the repo
root but runs from packages/pipeline so the pnpm-linked dependencies resolve
inside Stryker's sandbox.
# Full run (slow — re-runs the suite per mutant)
cd packages/pipeline && npx stryker run ../../stryker.conf.json
# Scope to one area while iterating
cd packages/pipeline && npx stryker run ../../stryker.conf.json --mutate "src/tokens/**/*.ts"The HTML report is written to packages/pipeline/reports/mutation/index.html.
- Threshold (opt-in). The target mutation score lives in
.claude/pipeline.config.json→qualityGate.mutationScore({ "enabled": false, "threshold": 80, "blocking": false }). It is off by default; setenabled: trueto treat it as a quality gate. - CI.
.github/workflows/mutation.ymlruns Stryker nightly and on demand (workflow_dispatch) — never on PRs, to avoid latency. It is informational: the score is posted to the run summary and the HTML report is uploaded as an artifact.
./scripts/verify-tokens.sh # Catch hardcoded design values
./scripts/verify-test-coverage.sh # Ensure every component has tests
node scripts/visual-diff.js --batch actual/ expected/ --json # Pixel diffFull reference: scripts/README.md
Starter configuration files for new projects:
| Directory | Contents |
|---|---|
templates/shared/ |
ESLint, Prettier, Tailwind, TypeScript, Vitest configs |
templates/nextjs/ |
Next.js config |
templates/vite/ |
Vite config |
templates/astro/ |
Astro hybrid-islands starter (React islands + Tailwind, file-based routing) |
templates/chrome-extension/ |
Playwright E2E fixtures for Chrome extensions |
Full reference: templates/README.md
The framework uses four MCP (Model Context Protocol) servers for Figma access, browser automation, and testing:
| Server | Purpose | Required For |
|---|---|---|
| Figma Desktop MCP | Read designs, extract tokens, capture screenshots from Figma | Phases 1-2, 5 |
| Figma Remote MCP | Fallback remote Figma access | Phases 1-2, 5 |
| Chrome DevTools MCP | Screenshots, Lighthouse audits, DOM inspection | Phases 5, 7-8 |
| Canva AI Connector | Search, export, interact with Canva designs | Phases 1-2 (Canva) |
| Playwright MCP | Cross-browser testing (Chromium, Firefox, WebKit) | Phases 6-7 |
MCP servers are configured in .claude/settings.json. Figma Desktop MCP requires the Figma desktop app running locally.
episodic-memory # Persistent memory across sessions
commit-commands # Git workflow automation (/commit, /commit-push-pr)
superpowers # Advanced development workflows (TDD, planning, debugging)
ai-taskmaster # Task management (local)
GitHub integration via gh CLI (not a plugin).
Details: .claude/PLUGINS-REFERENCE.md
| Document | Location | Description |
|---|---|---|
| Developer onboarding | docs/onboarding/README.md |
Start here -- quickstart, architecture, configuration, troubleshooting |
| Quickstart guide | docs/onboarding/quickstart.md |
Clone to running project in 10 minutes |
| Architecture overview | docs/onboarding/architecture.md |
All 56 agents, 23 skills, 4 pipelines, and how they connect |
| Pipeline configuration | docs/onboarding/pipeline-configuration.md |
Every setting in pipeline.config.json explained |
| Troubleshooting FAQ | docs/onboarding/troubleshooting.md |
Common issues and solutions |
| Project instructions | CLAUDE.md |
Full project config for Claude Code |
| Figma pipeline guide | docs/figma-to-react/README.md |
Pipeline overview and troubleshooting |
| React standards | docs/react-development/README.md |
TypeScript, Tailwind, testing conventions |
| Canva pipeline guide | docs/canva-to-react/README.md |
Canva pipeline overview and troubleshooting |
| Conversation pipeline guide | docs/conversation-to-app/README.md |
Conversational app creation via generated Figma designs |
| InDesign pipeline guide | docs/pipelines/indesign.md |
Convert exported IDML/PDF into React components, tokens, and Storybook stories |
| Agent catalog | .claude/CUSTOM-AGENTS-GUIDE.md |
All 56 agents with use cases |
| Skills catalog | .claude/skills/README.md |
All 23 skills with triggers |
| Plugin reference | .claude/PLUGINS-REFERENCE.md |
Plugin configuration and commands |
| Scripts reference | scripts/README.md |
All scripts with usage examples |
| Templates reference | templates/README.md |
Starter configs and how to use them |
| Pipeline config | .claude/pipeline.config.json |
Thresholds, app types, quality gates |
| Agent naming guide | .claude/AGENT-NAMING-GUIDE.md |
Conventions for creating new agents |
| Project | Description |
|---|---|
| AI SEO Copilot (Chrome) | Free, open-source Chrome extension for AI-powered SEO analysis. Built with React 19, TypeScript, and Vite. The Chrome extension pipeline in Aurelius was battle-tested against this project. Install from Chrome Web Store |
| AI SEO Copilot (Webflow) | The original Webflow app with ~20,000 installs |
| Flavian | Claude Code-integrated WordPress development framework with FSE block theme tools and Figma-to-WordPress pipelines |
| Nerva | Claude Code-integrated API and backend development framework with Hono, Cloudflare Workers, and Drizzle ORM |
| Claudius | Embeddable AI chat widget powered by Claude. React + TypeScript + Cloudflare Workers |
MIT
