Aurelius

A Claude Code-integrated multi-framework app development framework with TypeScript, Tailwind CSS, and automated design-to-code pipelines.

What This Framework Provides

• 48 Custom Agents -- Specialized AI agents for engineering, design, testing, marketing, operations, and more
• 17 Development Skills -- Automated workflows for Figma/Canva 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
• 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

Quick Start

# Clone the repository
git clone <repository-url>
cd aurelius

# Initialize a new project (Next.js or Vite)
./scripts/setup-project.sh my-app --vite    # or --next

# Install dependencies
cd app && pnpm install

# Start development
pnpm dev

Build from Figma (Autonomous Pipeline)

/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

Directory Structure

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
│   └── 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/                  # 48 custom agents
│   ├── skills/                  # 17 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 (Autonomous Pipeline)

/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)

The Figma-to-React Pipeline

How It Works

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

Supported App Types

Pipeline Configuration

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

48 Custom Agents

Agents are auto-selected by Claude Code based on your task:

Full catalog: .claude/CUSTOM-AGENTS-GUIDE.md

17 Development Skills

Pipeline Skills (Phases 1-6)

Canva Pipeline Skills

React Development Skills

Full catalog: .claude/skills/README.md

Scripts

Code Quality

./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

Testing

./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 setup

Pipeline Verification

./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 diff

Full reference: scripts/README.md

Templates

Starter configuration files for new projects:

Full reference: templates/README.md

MCP Server Integration

The framework uses four MCP (Model Context Protocol) servers for Figma access, browser automation, and testing:

MCP servers are configured in .claude/settings.json. Figma Desktop MCP requires the Figma desktop app running locally.

Claude Code Plugins

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

Documentation Index

License

MIT