Brandbook — AI-Powered Brand Identity Generator

Creates complete brand identity for mobile/web apps through structured dialogue, AI research, and optional MCP image generation.

Activation: brandbook, brandbook {app-name}

When to Use

• Launching new app, need visual identity from scratch
• Rebranding existing product
• Need store-ready assets specification

Don't use: Redesigning mature brand with existing guidelines (hire an agency)

Principles

1. Concrete over abstract — HEX codes, not "blueish"; font names, not "something modern"
2. Research-backed — every choice has psychological/market justification
3. Ready-to-use outputs — AI prompts are copy-paste ready, specs are pixel-exact
4. Accessibility-first — WCAG AA compliance is mandatory, not optional
5. Progressive enhancement — MCP image gen if available, prompts-only if not
6. Anti-convergence — LLMs drift to "average design" (Inter, purple gradients, rounded-white-cards). Phase 0 forces emotive narrative BEFORE any visual work. All colors in OKLCH for perceptual uniformity

Output

All files created in brandbook/:

Coder handoff (written outside brandbook/):

Phase Overview

SHIELD:      0. Convergence Shield (emotive narrative, banned defaults, 3 directions)
             See: foundation.md

FOUNDATION:  1. Discovery → 2. Brand DNA → 3. Voice Framework
             See: foundation.md

DESIGN:      4. Research → 5. Visual System → 6. Accessibility
             → 7. Logo & Icon → 8. Motion
             See: design.md

LAUNCH:      9. Store Assets → 10. Marketing Kit
             See: launch.md

COMPILE:     11. Compilation + Checklist + MCP Generation
             12. Design Tokens Export (brand-tokens.css)
             13. Coder Handoff (.claude/rules/brand.md)
             See: completion.md

Modules

Flow:

SKILL.md → foundation.md → design.md → launch.md → completion.md

Pre-flight

1. Check context: Look for files in biz/, ai/ — product briefs, personas, research
2. Migrate legacy path: Check if biz/brandbook/ exists (v1 output). If yes:
   • Show user: "Found previous brandbook at biz/brandbook/. Migrate to brandbook/?"
   • If approved: mv biz/brandbook/* brandbook/ && rmdir biz/brandbook
   • This preserves existing work (assets, docs) under the new path
3. Detect existing brand: Check if .claude/rules/brand.md exists (previous run). If yes:
   • Read the existing file
   • Show diff summary: "Previous brand: {font}, {primary color}, {archetype}"
   • Ask: "Update existing brand or start fresh?"
   • If update → pre-fill Phase 0 emotive narrative from existing, highlight what changed
4. Detect MCP: List available tools. Image generation tools found? → enable generation mode
5. Create output dir: mkdir -p brandbook/assets

Asset Storage Rules

- MCP auto-saves all generated files to brandbook/assets/ (SAVE_MEDIA_DIR)
- After each generation: show the saved file to user (Read tool)
- Never give CDN URLs — only local paths
- Report: "Saved: brandbook/assets/{filename}"

MCP Detection

Step 1: ToolSearch(query: "fal-ai")
Step 2: Tools found?  → IMAGE_GEN_MODE = true
Step 3: Not found?    → Ask user (AskUserQuestion), do NOT silently fall back

If not found — ask, don't assume:

• fal-ai может быть не установлен, или установлен с project scope вместо user scope
• Спроси пользователя: "fal-ai не найден. Работаем без генерации или хотите настроить?"
• Для установки: claude mcp add fal-ai -s user -- uvx --from fal-mcp-server fal-mcp

Available fal-ai tools (when MCP connected):

IMAGE: generate_image, generate_image_structured, generate_image_from_image,
       edit_image, remove_background, upscale_image, inpaint_image,
       resize_image, compose_images
VIDEO: generate_video, generate_video_from_image, generate_video_from_video
AUDIO: generate_music
UTIL:  list_models, recommend_model, get_pricing, get_usage, upload_file

Recommended Models (via FAL.AI)

Use recommend_model tool for AI-powered suggestions, or these defaults:

STRICT RULES

1. READ-ONLY for app code — never modify source files
2. Output ONLY to brandbook/ — local output directory (except .claude/rules/brand.md)
3. Every choice needs WHY — "Blue (#1E40AF) because fintech vertical = trust, contrast 7.2:1"
4. Concrete values only — no "consider using...", always exact HEX/font/size
5. Accessibility is mandatory — WCAG AA minimum for all color combinations
6. Ask before MCP generation — calls cost money, user must approve
7. Use existing context — if biz/ has product briefs, pre-fill Discovery answers
8. ALL ASSETS LOCAL — every generated file saved to brandbook/assets/. No CDN links — only local paths. After generation → show image to user
9. Anti-convergence — NEVER start with Inter, system-ui, purple/blue gradients, or rounded-white-card aesthetics. Phase 0 Convergence Shield is MANDATORY before any visual decisions
10. OKLCH-first — all color values include OKLCH notation alongside HEX. OKLCH ensures perceptual uniformity across brand palette