Design Evolution v2

Genetic algorithm over DNA codes + persistent design memory. Simple loop: detect brand → generate population → user selects winners/losers → mutate winners, kill losers, add immigrants → repeat until lock-in. Learning persists across sessions and repositories.

Engine

All state via engine.py. Per-project state in .design-evolution/evolution.yaml. Global memory in ~/.claude/design-memory.db (SQLite, auto-created).

ENGINE="$HOME/.claude/skills/evolve/engine.py"
python3 "$ENGINE" --repo "$REPO" <command> [args]

First Invocation

1. Brand Auto-Detection

Run brand detection first:

python3 "$ENGINE" --repo "$REPO" detect

This scans for: brand.yaml, tailwind config, @theme CSS blocks, Google Fonts, component libraries (shadcn, Radix, etc.), dark mode support. Reports completeness score (0-100%) and remediation suggestions.

If gaps found, offer to run remediation:

• Missing brand.yaml → “Run /brand-init first?”
• Missing tokens → “Run /brand-compile first?”

2. Ask Constraint Level

AskUserQuestion:
"How much creative freedom?"
- "Strict" → Lock color+typography. Evolve layout/motion/density/background only.
- "Extend" → Respect existing tokens but allow new ones.
- "Reimagine" → Brand as inspiration only. Everything open.
- "Greenfield" → Ignore existing design system. Start fresh.

3. Ask Scope + Context

AskUserQuestion:
"What's the scope?"
- "Full design system" → scope=full
- "Specific component" → scope=component (ask which)

"What context?" (multiselect)
- SaaS / Landing / Dashboard / Portfolio / E-commerce

Context tags affect which taste data is loaded from memory. A “saas” project inherits preferences from past “saas” work but not “landing” preferences.

3b. Parse Taste Dials

Parse --variance, --motion, --density args. Defaults from taste-skill: 8/6/4.

DESIGN_VARIANCE = args.variance ?? 8   # Layout axis: 1-3=centered, 4-7=offset, 8-10=asymmetric
MOTION_INTENSITY = args.motion ?? 6    # Motion axis: 1-3=none/subtle, 4-7=orchestrated, 8-10=aggressive
VISUAL_DENSITY = args.density ?? 4     # Density axis: 1-3=spacious, 4-7=mixed, 8-10=compact

These values are injected into EVERY proposal generation prompt. They override the DNA axes for Layout, Motion, and Density (additive precision — not a replacement for DNA codes).

4. Initialize

python3 "$ENGINE" --repo "$REPO" init \
  --project "$PROJECT" \
  --scope "$SCOPE" \
  --contexts "saas,dashboard" \
  --brand "$BRAND_FILE" \
  --lock "$LOCKED_AXES" \
  --population 8

This auto-detects brand state, registers the project in memory, and imports any existing evolution data.

5. Generate Population

python3 "$ENGINE" --repo "$REPO" suggest --count 8

For first pass exploration, prefer hardened seed mode:

python3 "$ENGINE" --repo "$REPO" seed --count 8

seed guarantees:

• high-variance DNA spread (diversity floor 4+)
• materialized HTML previews for every proposal
• fallback logo assets per proposal

Population is biased by:

• Local taste from this project’s prior selections (2x weight)
• Global taste from all past projects
• Contextual taste from projects with matching context tags (1.5x weight)
• Hard preferences: vetoed values excluded, mandated values boosted
• DNA bank: 1-2 slots seeded from banked interesting designs

5b. Explicit Anchor Mode (Mandatory)

If user explicitly names a prior proposal as target direction (example: gen-5/5a):

• Freeze that proposal as the baseline archetype for next generation.
• Build survivors/mutations from that anchor first, not from latest generation winners.
• Keep at least one near-faithful baseline variant to prevent drift.
• Treat “go back to X” as a hard constraint, not soft preference.

5c. Hard Preference Enforcement (MANDATORY — Run Before EVERY Generation)

Before generating ANY proposals, query ALL hard preferences from the design memory DB:

python3 "$ENGINE" memory rules

Extract every VETO and MANDATE. Build a BANNED/REQUIRED block that gets injected verbatim into EVERY agent prompt (survivors, mutations, immigrants — all of them).

Format for agent prompts:

=== HARD VETOES (ABSOLUTE — violating ANY of these = instant rejection) ===
- NEVER use [font]: [reason]
- NEVER use [CSS pattern]: [reason]
- NEVER use [color/background]: [reason]
...

=== HARD MANDATES (REQUIRED — omitting ANY of these = instant rejection) ===
- ALWAYS use [pattern]: [reason]
...

Why this exists: Vetoes stored in the DB were not reaching agent prompts, causing the same rejected patterns (border-top on rounded cards, banned fonts) to reappear generation after generation. This step is non-negotiable.

CSS-level vetoes (card border treatments, dark-in-light theming) are stored alongside DNA-axis vetoes. Both MUST be included in prompts.

5d. Survivor Fidelity (MANDATORY)

Survivors and mutations MUST be given the actual parent HTML file to READ and MODIFY. Giving agents only a DNA code and description causes them to generate from scratch, losing all the qualities that made the parent a winner.

For each survivor/mutation agent prompt:

1. Include the full path to the parent HTML file
2. Instruct the agent to READ the parent file FIRST
3. Instruct the agent to MODIFY the parent, not generate from scratch
4. Specify ONLY the targeted changes (e.g., “change background from gradient to patterned”)
5. Verify output file size is within 20% of parent (drift guard)

Template:

Read the parent proposal at: [path to parent index.html]
This file is the STARTING POINT. You MUST modify this file, NOT generate from scratch.
The user selected this proposal as a winner because [reasons].
Your job: make ONLY these targeted changes: [specific axis changes].
Preserve everything else — layout, typography, component structure, color relationships.

6. Generate Proposals — MULTI-PROVIDER DELEGATION

Distribute proposals across varied AI providers for aesthetic diversity. Each provider brings different creative biases — mixing them prevents convergence.

Provider roster (use 2+ per generation):

Provider diversity (user preference): Aim for genuine diversity — don’t lock any provider to a fixed percentage. Track which providers produce liked proposals and bias toward them in subsequent generations. Codex is weakest for frontend design work. Don’t use the same provider for both survivors.

Performance tracking (update after each generation’s feedback):

• Gemini: 2/4 liked in gen 2 (2E winner, 2F decent; 2C broken, 2D disliked)
• Kimi: mixed (2A decent/2B AI slop in gen 2; 1A ok/1B wrong direction in gen 1)
• Claude: mixed (2G promising/2H disliked in gen 2)
• Codex: 0/2 liked in gen 1 (both killed)

Example distribution for 8 proposals: Gemini(3-4), Kimi(2), Claude(2-3). Adjust per generation. Vary per generation. Don’t use same provider for both survivors.

Each proposal MUST include:

• Color palette (hex + OKLCH, semantic names)
• Typography scale (families, sizes, weights, line heights)
• Spacing system (base unit, scale)
• Component examples (button, card, input, nav item)
• Animation specifications (if motion axis != “none”)
• Externalized logo/mark slot (gen-N/assets/logos/*) instead of only inline placeholder
• Light AND dark theme support (default to system prefers-color-scheme)
• Full rendered HTML preview

Quality gate: Each proposal should target 90+/100 from the /ui-skills expert panel (Ogilvy, Rams, Scher, Wiebe, Laja, Walter, Cialdini, Ive, Wroblewski, Millman). Apply /frontend-design aesthetic guidelines: bold direction, no generic AI slop, distinctive font choices, intentional composition.

taste-frontend injection (MANDATORY): Every proposal prompt MUST include:

Load ~/.claude/skills/aesthetic-system/references/taste-frontend.md and follow strictly.
Active dials: DESIGN_VARIANCE={DESIGN_VARIANCE}, MOTION_INTENSITY={MOTION_INTENSITY}, VISUAL_DENSITY={VISUAL_DENSITY}.
Apply pre-flight checklist (Section 10 of taste-frontend.md) before finalizing.

Resolved dial values override DNA axes for Layout, Motion, and Density.

Layout rule: Items in the same state (pending, alive, winner, killed) MUST occupy equal space. No arbitrary bento sizing for same-status proposals.

// Claude batch (via Task tool — parallel in single message)
Task({ subagent_type: "general-purpose", prompt: claudePrompt(dna_a) })
Task({ subagent_type: "general-purpose", prompt: claudePrompt(dna_b) })
Task({ subagent_type: "general-purpose", prompt: claudePrompt(dna_c) })
Task({ subagent_type: "general-purpose", prompt: claudePrompt(dna_d) })

// Codex batch (via CLI — run sequentially or background)
codex exec --full-auto "${codexPrompt(dna_e)}" --output-last-message /tmp/evolve-e.md
codex exec --full-auto "${codexPrompt(dna_f)}" --output-last-message /tmp/evolve-f.md

// Gemini batch (via CLI)
gemini "${geminiPrompt(dna_g)}" > /tmp/evolve-g.md
gemini "${geminiPrompt(dna_h)}" > /tmp/evolve-h.md

### 6b. Asset Batch (Mandatory)

After DNA proposal generation, run `/asset-generation` and mount assets into each proposal.

Rules:
1. Use **Recraft + OpenAI + Nano Banana Pro** in exploratory rounds.
2. Generate assets **per proposal** (`7a`, `7b`, ...) using that proposal's palette and style.
3. Match exploration width to design uncertainty:
   - Early rounds: broad style/color/logo families
   - Late rounds: narrow around surviving direction
4. Never ship noisy illustration-style logos as the primary mark.
5. Logo marks must be favicon/app-icon safe (legible at 16/24px, flat, low detail).
6. If generated logos fail QA, synthesize deterministic geometric SVG fallback marks.
7. Ensure proposal variants are meaningfully distinct; near-clone rounds are invalid.
8. User-provided logo references are **principle references only**:
   - extract qualities (simplicity, geometry, proportion, negative space)
   - never replicate exact silhouettes/compositions
   - reject outputs resembling known or provided logos

Required structure:
- `.design-evolution/gen-N/assets/logos/7a/{recraft,openai,gemini}-*.{svg,png}`
- `.design-evolution/gen-N/assets/logos/7a/final.{svg,png}`
- `.design-evolution/gen-N/assets/textures/7a/*.png` (optional)

In each proposal HTML:
- reference external assets via relative paths
- do not hardcode a one-size-fits-all logo across all variants
- keep background motifs subtle; no text artifacts/gibberish textures
- enforce CTA button label optical centering and stable line-height

### 7. Register, Catalog, Serve

```bash
python3 "$ENGINE" --repo "$REPO" add "dna1" "dna2" ... --origins "random,random,..."
python3 "$ENGINE" --repo "$REPO" catalog
python3 "$ENGINE" --repo "$REPO" serve &

Catalog quality is part of the feature. The catalog should not be a bare file list. It must help the user build design taste and vocabulary.

Each proposal card should include:

• DNA code + axis pills
• Design vocabulary readout per axis (term + concise meaning)
• Critique prompts (“what to inspect”) for structure, typography, motion, spacing
• Proposal notes + origin provenance

If catalog clarity is weak, improve engine rendering before generating more proposals.

NEVER hardcode port 8888. Engine hashes project name → port 8800-9799.

MANDATORY VERIFICATION: After catalog generation, verify EVERY proposal link works:

for id in a b c d e f g h; do
  ls "$REPO/.design-evolution/gen-${GEN}/${GEN}${id}/index.html" || echo "MISSING: ${GEN}${id}"
done
grep -c "Open Preview" "$REPO/.design-evolution/catalog.html"

8. Selection

User provides feedback → translate to engine commands:

python3 "$ENGINE" --repo "$REPO" select --winners "1a,1e" --kill "1b,1c,1f"
python3 "$ENGINE" --repo "$REPO" note --proposal 1a --text "love the asymmetry"
python3 "$ENGINE" --repo "$REPO" note --text "want more editorial feel overall"

Selection writes to both local taste AND global memory. Winners accumulate positive scores globally; killed proposals accumulate negative. This learning carries over to the next project.

9. Evolution

python3 "$ENGINE" --repo "$REPO" advance

Then generate new proposals (same delegation as step 6) and repeat.

For the winner/loser loop, prefer hardened breed mode:

python3 "$ENGINE" --repo "$REPO" breed

breed guarantees:

• winners persist as survivors
• mutations are parented from winners
• at least two immigrants (new species) are injected
• parent lineage is recorded in evolution state
• next generation previews are materialized immediately

10. Lock-in

python3 "$ENGINE" --repo "$REPO" lock 3b
python3 "$ENGINE" --repo "$REPO" export

Locked DNA is auto-banked in global memory for future seeding.

Handoff routing:

• Full system → /design-theme with locked DNA
• Component → /ui-skills or direct implementation
• Brand update → /brand-compile if tokens changed

10b. Enhanced Handoff — Component Seeding (Full System Only)

When scope=full and user confirms lock-in, the handoff generates a complete design system:

1. Design tokens → /design-theme generates globals.css with @theme block.

2. Component seeds → Generate initial components/ui/ using the locked token system. Minimum set (delegate to Codex or Kimi with taste-frontend.md loaded):

• Button (variants: default, ghost, destructive, outline)
• Card, CardHeader, CardContent, CardFooter
• Input, Textarea, Select
• Badge, Avatar
• Separator
• Typography (H1-H4, P, Muted)

Components must:

• Import only ~/lib/cn and consume tokens via Tailwind classes
• No inline style={{}} props
• No hardcoded hex/px values outside token names

3. Guardrail rules → Invoke /guardrail to generate guardrails/no-adhoc-styling.js (blocks arbitrary Tailwind values + inline styles). Enforced via lefthook pre-commit.

4. Design system doc → Write design-system.md at repo root documenting:

• Active DNA code and axis values
• Active dials (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY)
• Token list with semantic names
• Component inventory
• What’s enforced by linting

Memory

Global design memory persists across sessions at ~/.claude/design-memory.db.

Taste

Accumulated preference scores for each axis value. Updated on every selection. Global taste merges with contextual taste (scoped to tags like “saas”, “landing”) and hard preferences.

python3 "$ENGINE" memory taste                    # Show merged taste
python3 "$ENGINE" memory taste --context saas     # Context-filtered

Hard Preferences

Vetoes exclude values from population generation. Mandates force inclusion.

python3 "$ENGINE" memory veto typography minimal --reason "boring"
python3 "$ENGINE" memory mandate color dark --reason "brand identity"
python3 "$ENGINE" memory rules                    # List all
python3 "$ENGINE" memory rules --remove 1         # Remove by ID

DNA Bank

Save interesting designs across projects for reuse. Winners are auto-banked after 2+ selections. Locked proposals always banked.

python3 "$ENGINE" --repo "$REPO" bank 2c --note "great editorial feel" --tags "saas,dark"
python3 "$ENGINE" memory bank                     # Browse bank
python3 "$ENGINE" memory bank --search editorial  # Search

History + Import

python3 "$ENGINE" memory history                  # All feedback
python3 "$ENGINE" memory history --project scry   # Per-project
python3 "$ENGINE" memory import PATH --project scry --context saas  # Import YAML

Brand Detection

Auto-detects existing design infrastructure via detect.py:

python3 "$ENGINE" --repo "$REPO" detect           # Summary
python3 "$ENGINE" --repo "$REPO" detect --json    # Machine-readable

Image Generation (Recraft AI)

Generate vector logos, icons, and illustrations via Recraft API. Requires RECRAFT_AI_API_KEY (preferred) or RECRAFT_API_TOKEN.

python3 "$ENGINE" recraft logo "minimalist owl logo" --colors "#1a1a2e,#e94560" --n 4
python3 "$ENGINE" recraft icon "search magnifying glass" --colors "#1a1a2e" --n 4
python3 "$ENGINE" recraft illustrate "abstract data visualization" --n 4
python3 "$ENGINE" recraft vectorize IMAGE_URL
python3 "$ENGINE" recraft test    # API connectivity check

Brand colors from brand.yaml can be auto-injected into the --colors flag. Vector output (SVG) for logo and icon styles. Raster (PNG) for illustrations.

For multi-provider workflows (Recraft + Nano Banana Pro + OpenAI), use /asset-generation.

Subsequent Invocations

If .design-evolution/evolution.yaml exists:

python3 "$ENGINE" --repo "$REPO" status

Based on state:

• Has alive proposals → prompt for selection
• Has winners, no next gen → run advance + generate
• Locked → offer handoff to implementation skill

Integration

Hands off to:

• /design-theme — implement locked DNA as tokens
• /brand-compile — update brand tokens from locked DNA
• /brand-assets — generate branded visual assets
• /pencil-to-code — if Pencil backend used
• /theme-factory — apply 10 pre-built visual themes (color palettes, font pairings) to artifact outputs (slides, reports, HTML)
• /design-md — generate DESIGN.md as source-of-truth for Stitch MCP design system generation

Anti-Convergence

Enforced by min_diversity (default 3 = proposals differ on 3+ axes), immigration (fresh random genes), and DNA bank seeding (proven winners from other projects injected into population).

Maintenance & Scalability

Evolve is designed to scale across hundreds of repos and generations.

Automatic bounds

• Taste scores clamped to ±20 on every update (prevents runaway accumulation)
• Evolution YAML archived beyond 10 generations (older gens → generations-archive.jsonl)
• Connection caching — single SQLite connection per process (no open/close per call)

evolve gc [--keep-gens N]

Manual garbage collection. Safe to run anytime, idempotent.

What it does:

1. Clamp taste — caps all scores to ±20
2. Prune DNA bank — keeps 200 most recent entries (locked designs protected)
3. Prune feedback — keeps 500 per project (oldest deleted)
4. WAL checkpoint — reclaims SQLite journal space
5. HTML cleanup — removes old gen-N/ preview directories, keeping last N (default: 3)

evolve memory maintenance subcommands

evolve memory stats           # DB overview
evolve memory taste           # Current taste profile
evolve memory bank            # Browse DNA bank
evolve memory veto AXIS VAL   # Hard veto (never use this value)
evolve memory mandate AXIS VAL # Hard mandate (always use this value)
evolve memory rules           # List/remove hard preferences
evolve memory history         # Feedback log
evolve memory import --path P # Import from evolution.yaml