How horosheff/aura-designer works
Purpose and Entry Points
Aura Designer is an installable AI sub-agent plus Python CLI for turning a URL, screenshot, image, or idea into a design contract and responsive HTML page. IDE-native entry points are the agent definitions for Cursor, Claude Code, and Codex: .cursor/agents/aura-designer.md, .claude/agents/aura-designer.md, .codex/agents/aura-designer.md. CLI entry point: auradesign-agent/aura.py.
Design Contract as System Boundary
AURADESIGN.md is the central handoff artifact: YAML tokens plus Markdown design rules governing palette, typography, layout, components, motion, accessibility, assets, and prohibitions. Its required format is specified by auradesign-agent/AURADESIGN_SPEC.md; a root example exists at AURADESIGN.md. Downstream generation and validation consume this contract rather than implicit style presets.
Source Intake and Analysis
The scanner ingests source URLs or images and extracts a design contract: auradesign-agent/aura_scanner.py. For source-driven work, analysis creates structured evidence and replication constraints through auradesign-agent/aura_source_analyzer.py, producing maps such as AURA_SOURCE_MAP.json, AURA_COMPOSITION_LOCK.json, and AURA_COMPONENT_MAP.json. This establishes the “copy-in-copy” boundary: preserve source composition, palette, imagery intent, and hero structure before proposing improvements.
Asset Gate and Brand Material
Asset handling is isolated in auradesign-agent/aura_asset_manager.py. It requires MCP-backed image generation via user-mcp-kv/gpt-image-2 and background removal via user-mcp-kv/recraft_remove_background, explicitly avoiding fallback placeholder imagery. Supporting deliverables—including brand-kit image prompts and color rationale—are emitted by auradesign-agent/aura_deliverables.py into artifacts such as AURA_ASSET_REGISTRY.json and AURA_BRAND_KIT_IMAGE_PROMPT.md.
Two Page Production Paths
Standard contract-led HTML/CSS generation is implemented in auradesign-agent/aura_generator.py. Exact source replication follows the source-map-aware path in auradesign-agent/aura_replicator.py, consuming both the analysis artifacts and design contract to write the final index.html (for example, auradesign-agent/index.html). The CLI coordinates scan, generate, analyze, replicate, deliverables, qa, and end-to-end pipeline commands.
Quality Gates and Review Loop
Contract completeness is checked by auradesign-agent/aura_linter.py. Replicated HTML is assessed against source-map constraints by auradesign-agent/aura_visual_qa.py, producing visual-diff and QA artifacts such as AURA_VISUAL_DIFF.md and AURA_VISUAL_QA.md. A separate readonly reviewer agent, .cursor/agents/aura-design-reviewer.md, provides an additional visual review pass; equivalent definitions exist under .claude/agents/ and .codex/agents/.
Runtime, Distribution, and Specialized Skills
The executable core is dependency-free Python 3. Installation copies sub-agent definitions into target IDE project scopes through install.py, install.sh, or install.ps1. Cursor-specific reusable skills constrain Cyrillic font selection and shape fidelity: .cursor/skills/aura-cyrillic-google-fonts/SKILL.md and .cursor/skills/aura-shape-replication/SKILL.md. Documentation of installation, agent topology, and MCP dependencies is under docs/install.md, docs/agent-map.md, and docs/mcp-tools.md.
Main entry points: aura.py Aura CLI · AURADESIGN.md Design contract · aura_replicator.py Source replicator · index.html Final page
Components 19
Entry & Distribution
- IDE designer agents · Cursor, Claude Code, and Codex invoke the design sub-agent.
.cursor/agents/aura-designer.md - Aura CLI · Coordinates scan, generate, analyze, replicate, deliverables, QA, and pipeline commands.
auradesign-agent/aura.py - Installer · Copies agent definitions into target IDE project scopes.
install.py - Cursor fidelity skills · Constrains Cyrillic font choice and shape fidelity.
.cursor/skills/aura-cyrillic-google-fonts/SKILL.md
Intake & Contract
- Source scanner · Ingests URLs and images to extract a design contract.
auradesign-agent/aura_scanner.py - Source analyzer · Builds structured source evidence and replication constraints.
auradesign-agent/aura_source_analyzer.py - Source maps · Composition locks and component maps preserve source intent.
AURA_SOURCE_MAP.json - Contract specification · Defines the required YAML-plus-Markdown contract format.
auradesign-agent/AURADESIGN_SPEC.md - Design contract · Tokens and rules for palette, type, layout, components, motion, accessibility, assets, and prohibitions.
AURADESIGN.md
Page Production
- Asset gate · Requires MCP image generation and background removal without placeholders.
auradesign-agent/aura_asset_manager.py - MCP image tools · Provides gpt-image-2 and recraft_remove_background.
- Brand deliverables · Emits asset registry, image prompts, and color rationale.
auradesign-agent/aura_deliverables.py - Contract HTML generator · Builds standard responsive HTML and CSS from the contract.
auradesign-agent/aura_generator.py - Source replicator · Uses contract and source maps for exact source-aware reproduction.
auradesign-agent/aura_replicator.py - Final page
auradesign-agent/index.html
Quality & Review
- Contract linter · Checks contract completeness.
auradesign-agent/aura_linter.py - Visual QA · Assesses replicated HTML against source-map constraints.
auradesign-agent/aura_visual_qa.py - Visual QA reports · Visual-diff and visual-QA findings.
AURA_VISUAL_DIFF.md - Readonly design reviewer · Provides an additional visual review pass.
.cursor/agents/aura-design-reviewer.md
Connections 23
- Installer → IDE designer agents: installs
- IDE designer agents → Aura CLI: invokes
- Aura CLI → Source scanner: scan
- Source scanner → Design contract: extracts
- Contract specification → Design contract: defines format
- Aura CLI → Source analyzer: analyze
- Source analyzer → Source maps: produces
- Aura CLI → Asset gate: pipeline
- Asset gate → MCP image tools: uses
- Asset gate → Brand deliverables: supplies assets
- Aura CLI → Contract HTML generator: generate
- Design contract → Contract HTML generator: governs
- Contract HTML generator → Final page: writes
- Aura CLI → Source replicator: replicate
- Design contract → Source replicator: governs
- Source maps → Source replicator: constrains
- Source replicator → Final page: writes
- Design contract → Contract linter: validated by
- Final page → Visual QA: assessed by
- Source maps → Visual QA: QA constraints
- Visual QA → Visual QA reports: produces
- Readonly design reviewer → Final page: reviews
- Cursor fidelity skills → IDE designer agents: guides Cursor