diff --git a/AGENTS.md b/AGENTS.md index 0d6d922..d4ea48c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,7 @@ When the user mentions these keywords, load the corresponding skill: | "reverse-engineer", "understand this codebase", "PRD from code", "architecture document" | [software-architecture-analysis](software-architecture-analysis/SKILL.md) | || "data architecture", "data platform", "data strategy", "data mesh", "governance" | [data-architect](data-architect/SKILL.md) | || "statistical analysis", "experimental design", "A/B test", "hypothesis test", "power analysis", "causal inference", "regression", "Bayesian", "p-value", "effect size", "model selection", "machine learning methodology" | [data-scientist](data-scientist/SKILL.md) | +|| "brand identity", "brand guidelines", "style guide", "brand card", "brand strategy", "visual identity", "brand documentation", "color palette", "brand book" | [brand-designer](brand-designer/SKILL.md) | || "kanban", "WIP", "cycle time", "flow metrics", "Scrum to Kanban", "multi-portfolio", "throughput", "classes of service" | [kanban-guru](kanban-guru/SKILL.md) | || "skill format", "how do I make a skill", "agentskills.io" | [agent-skills](agent-skills/SKILL.md) | || "nous", "theia", "hermes brand", "brand identity", "style guide", "mascot", "anime style", "cyber-classical", "color palette reference" | [nous-branding](nous-branding/SKILL.md) | @@ -72,7 +73,7 @@ The `description` field is the trigger mechanism. If the user's request contains ### Don't Load Everything at Startup -Loading all 5 skills at session start (~2,000 lines, ~25KB) wastes context. Let the conversation trigger loading. Skills load in ~100 tokens (metadata) and only expand when needed. +Loading all 14 skills at session start (~6,000 lines, ~75KB) wastes context. Let the conversation trigger loading. Skills load in ~100 tokens (metadata) and only expand when needed. ### Follow Progressive Disclosure diff --git a/README.md b/README.md index d0650dd..93410b9 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ Reference for the Agent Skills open format itself — directory structure, front Radarr and Sonarr media library management. Two CLIs (`radarr-cli` for movies, `sonarr-cli` for TV series) with one shared skill wrapper. List movies and series, search for additions, check calendars and wanted/missing episodes. Separate API keys per app. +### [brand-designer](brand-designer/SKILL.md) + +Create comprehensive brand identity documentation for any brand. Guides you through documenting strategy, visual identity (logo, color, typography, imagery), voice and tone, application guidelines, governance, and asset inventory. Produces markdown specs, compiled brand books, and brand-compliant images via reference-image-aware generation. Ships 7 templates, a brand-book CLI for validation/compilation, and a generate script for brand card and mockup imagery. + ### [cli-builder](cli-builder/SKILL.md) Build and refactor CLI tools for AI agent consumption. 10 universal patterns (non-interactive, `--json`, `--dry-run`, idempotent, lazy auth, progressive help), an agent-compatibility test suite, a Python API client pattern, and a bash scaffold template. Principles grounded in real failures from building 15+ agent-facing CLIs. diff --git a/brand-designer/SKILL.md b/brand-designer/SKILL.md new file mode 100644 index 0000000..29c8bd2 --- /dev/null +++ b/brand-designer/SKILL.md @@ -0,0 +1,188 @@ +--- +name: brand-designer +description: >- + Create comprehensive brand identity documentation for any brand. Guides you + through documenting strategy, visual identity (logo, color, typography, imagery), + voice and tone, application guidelines, governance, and asset inventory. + Produces markdown specs, compiled brand books, and brand-compliant images via + reference-image-aware generation. Use when you need to capture a brand's identity + in structured, durable form — for vault storage, agency handoff, or press kit + distribution. +license: MIT +compatibility: >- + CLI requires Python 3.8+; generate script requires an image generation backend. + All templates are plain markdown. Works with any agent supporting Agent Skills. +metadata: + source: "https://github.com/agentskills/agent-skills" + spec-version: "1.0" + category: creative +--- + +# Brand Designer + +A systematic toolkit for documenting brand identity. Elicits brand information through structured templates, validates completeness, compiles into reference documents, and generates brand-compliant images. + +## Quick Start + +```bash +# 1. Scaffold a new brand +brand-book init ./my-brand --name "Acme Corp" + +# 2. Fill in the templates (7 markdown files) +# Start with strategy.md → visual-id.md → voice.md + +# 3. Validate your work +brand-book validate ./my-brand/strategy.md --strict + +# 4. Compile output +brand-book compile ./my-brand --artifact brand-card # One-page summary +brand-book compile ./my-brand --artifact full # Full brand book + +# 5. Generate brand image (optional) +generate brand-card --brand-dir ./my-brand --layout landscape +``` + +## When to Use This Skill + +| Trigger | Artifact | Audience | +|---------|----------|----------| +| "I need a brand card for press/stakeholders" | Brand card (image + one-pager) | Executives, press, partners | +| "I need to document my brand strategy" | Strategy memo | Leadership, marketing | +| "I need visual identity documentation" | Visual identity spec | Designers, developers | +| "I need brand voice guidelines" | Voice & messaging spec | Writers, content team | +| "I need a full brand book for agency handoff" | Compiled brand book | Agencies, partners | +| "I need to inventory all my brand assets" | Asset inventory | Everyone | + +## Workflow + +### 1. Choose artifact type + +The decision tree in `references/canonical-components.md` maps brand maturity to artifact scope: + +- **Startup** (<10 people) → Brand card + Strategy memo (condensed) +- **Growing** (10-50) → Full visual identity + voice specs +- **Scaling** (50-200) → All specs + governance framework +- **Enterprise** (200+) → Full system + asset inventory + compiled brand book + +### 2. Fill templates + +7 templates live in `templates/`. Start with strategy (it informs everything else), then visual-id, voice, and the rest: + +| Template | What It Captures | Depends On | +|----------|-----------------|------------| +| `strategy.md` | Positioning, personality, mission, audience | — | +| `visual-id.md` | Logo system, color palette, typography, iconography, imagery | Strategy | +| `voice.md` | Voice attributes, tone matrix, vocabulary, copy examples | Strategy | +| `application.md` | Digital, print, social, co-branding rules | Visual identity | +| `governance.md` | Versioning, review cadence, exceptions | — | +| `asset-inventory.md` | Structured file index | All others | +| `brand-card.md` | Condensed visual summary (sources from others) | Strategy, visual-id, voice | + +**Filling technique:** Replace `{{placeholders}}` in each template with your brand's information. Required fields are marked in frontmatter. Optional fields can be removed. + +### 3. Validate + +```bash +brand-book validate ./my-brand/visual-id.md # Basic checks +brand-book validate ./my-brand/brand-card.md --strict # Cross-reference checks +brand-book validate ./my-brand/*.md # Batch check all +``` + +Validation catches: +- Missing required fields +- Incomplete color values (missing RGB, CMYK, or Pantone) +- Cross-reference breaks (brand-card sourcing from nonexistent specs) + +### 4. Compile + +```bash +brand-book compile ./my-brand --artifact brand-card # One-pager +brand-book compile ./my-brand --artifact full # Full book +brand-book compile ./my-brand --artifact full --format html --output book.html # HTML +``` + +The `--artifact` selector maps to individual templates or the compiled whole. See `references/artifact-hierarchy.md` for the complete taxonomy. + +### 5. Generate images (optional) + +```bash +generate brand-card --brand-dir ./my-brand --layout landscape # Press kit card +generate mockup --brand-dir ./my-brand --type social # Social media mockup +generate swatch --brand-dir ./my-brand # Color palette card +generate moodboard --brand-dir ./my-brand --theme "innovation" # Mood board +generate logo-bg primary --brand-dir ./my-brand --background dark # Logo on dark +``` + +The `generate` script is prompt-engineering-first: it reads your brand data and constructs optimized prompts for image generation backends. For best results with accurate logo rendering, provide reference images alongside the prompt. + +## Scripts Reference + +### `scripts/brand-book` +The main CLI. Subcommands: + +| Command | Action | +|---------|--------| +| `init [--name]` | Scaffold brand directory with 7 templates | +| `compile [--artifact] [--format] [--output]` | Assemble brand artifact | +| `validate [--strict] [--json]` | Check frontmatter completeness | +| `preview [--json]` | Terminal preview of a brand component | + +All subcommands support `--json` for machine output and `--dry-run` for preview. + +### `scripts/generate` +Image prompt construction for brand-compliant generation. Subcommands: + +| Command | Action | +|---------|--------| +| `brand-card [--layout portrait|landscape]` | Brand card image prompt | +| `mockup --type stationery|social|signage|digital` | Application mockup prompt | +| `swatch` | Palette visualization prompt | +| `moodboard [--theme]` | Mood board prompt | +| `logo-bg [--background]` | Logo presentation prompt | + +## Reference Files + +| File | What It Contains | +|------|-----------------| +| `references/canonical-components.md` | Definitive component hierarchy + maturity decision tree | +| `references/artifact-hierarchy.md` | Every artifact: who consumes it, format, depth, relationships | +| `references/gold-standard-analysis.md` | Structural analysis of Cash App, IBM, Netflix, Bang & Olufsen, Klarna | +| `references/brand-card-formats.md` | Format comparison: PDF vs online vs CLI vs Figma vs image | +| `references/template-schemas.md` | Complete YAML frontmatter schemas for all 7 templates | +| `references/image-generation.md` | Brand-compliant image prompt patterns and reference-image usage | + +## Artifact Tiers Summary + +``` +Tier 0: Brand Card → image + one-pager → stakeholders, press +Tier 1: Strategy Memo → narrative document → leadership, marketing +Tier 2: Visual Identity → structured spec → designers, developers +Tier 3: Voice & Messaging → guidelines with examples → writers, content +Tier 4: Application → channel-by-channel rules → producers, agencies +Tier 5: Governance → framework document → brand owners, legal +Tier 6: Asset Inventory → indexed table → everyone + └── Compiled Brand Book (Tiers 0-6 combined) → agencies, partners +``` + +## Gotchas + +### Templates are elicitation tools, not final designs +The templates produce markdown documentation, not designed PDFs. The content is structured and correct; visual polish is a post-processing step. If you need a beautifully designed PDF, export the markdown and lay it out in InDesign/Figma. + +### Color accuracy in generated images +Generated images will *approximate* brand colors, not match them precisely. The `generate swatch` command provides hex values in the prompt, but image models interpret color imprecisely. For Pantone-accurate color reference, use the documented values in the spec, not generated images. + +### Reference-image-aware generation is setup-dependent +The `generate` script constructs prompts regardless of backend. To use reference images (logos, existing materials) for better results, you need a generation setup that supports image inputs — e.g., ComfyUI, local Stable Diffusion with img2img, or an API that accepts image references. The prompts work without this; they just improve with it. + +### Brand card sources from other templates +The brand-card template uses `source:` frontmatter links to strategy, visual-id, and voice templates. This means: compile may show placeholder text if those source templates aren't filled yet. Fill strategy + visual-id before expecting a complete brand card. + +### The skill produces documents, not art +The image generation capability exists, but the primary output is **structured documentation** — markdown that can live in a vault, be versioned in git, and be compiled into various formats. The images are the garnish, not the meal. + +## See Also + +- `nous-branding` — Reference-image generation for Nous Research brand +- `cli-builder` — Patterns used by the brand-book CLI +- `references/image-generation.md` — Detailed prompt craft guide diff --git a/brand-designer/references/artifact-hierarchy.md b/brand-designer/references/artifact-hierarchy.md new file mode 100644 index 0000000..c0bfd27 --- /dev/null +++ b/brand-designer/references/artifact-hierarchy.md @@ -0,0 +1,147 @@ +# Artifact Hierarchy + +Every artifact the `brand-designer` skill produces, organized by audience, format, depth, and relationship. + +## Quick Reference + +``` +Tier 0: Brand Card → Stakeholders, Press, Partners (image + one-pager) +Tier 1: Strategy Memo → Leadership, Marketing (narrative) +Tier 2: Visual Identity → Designers, Developers (structured spec) +Tier 3: Voice & Messaging → Writers, Content, Support (guidelines) +Tier 4: Application → Producers, Agencies (rules + examples) +Tier 5: Governance → Brand Owners, Legal (framework) +Tier 6: Asset Inventory → Everyone (index) + └── Compiled Brand Book (Tiers 1-6 combined) (comprehensive reference) +``` + +## Artifact Descriptions + +### Brand Card (Tier 0) + +| Field | Value | +|-------|-------| +| **What it is** | A single-page visual and textual summary of the brand's identity. The "elevator pitch." | +| **Audience** | Stakeholders, executives, press, partners, new hires | +| **Format** | (a) Markdown one-pager via `templates/brand-card.md`, (b) Generated image via `scripts/generate brand-card` | +| **Depth** | Condensed — selects key elements from other tiers, does not exhaust | +| **Dependency** | Sources from Strategy, Visual Identity, and Voice. Requires those to exist first (or be filled alongside). | +| **When to produce** | Always — even pre-revenue startups benefit from a brand card | +| **Image variant** | `generate brand-card --layout portrait|landscape` — renders logo + palette swatches + type specimen + tagline | + +### Strategy Memo (Tier 1) + +| Field | Value | +|-------|-------| +| **What it is** | The "why" behind the brand. Positioning, personality, audience, competitive landscape. | +| **Audience** | Leadership, marketing team, agency briefs | +| **Format** | Markdown template via `templates/strategy.md` | +| **Depth** | Narrative — 3-5 pages of structured prose | +| **Dependency** | None (foundational) | +| **When to produce** | Growing brands (10+ people) or any brand working with agencies | + +### Visual Identity Spec (Tier 2) + +| Field | Value | +|-------|-------| +| **What it is** | The "how it looks." Complete documentation of logo system, color, typography, iconography, imagery. | +| **Audience** | Designers, developers, content creators, agencies | +| **Format** | Markdown template via `templates/visual-id.md` | +| **Depth** | Exhaustive — tables, values in multiple color spaces, type scale, do/don't examples | +| **Dependency** | Informed by Strategy Memo (positioning drives visual decisions) | +| **When to produce** | Growing brands producing external materials | +| **Image variants** | `generate swatch` (palette visualization), `generate logo-bg` (logo on different backgrounds), `generate mockup` (application examples) | + +### Voice & Messaging Spec (Tier 3) + +| Field | Value | +|-------|-------| +| **What it is** | The "how it sounds." Voice attributes, tone matrix, vocabulary, copy examples. | +| **Audience** | Writers, content marketers, customer support, product designers | +| **Format** | Markdown template via `templates/voice.md` | +| **Depth** | Moderate — enough rules to be practical, with plenty of examples | +| **Dependency** | Informed by Strategy Memo (personality drives voice) | +| **When to produce** | Growing brands with >1 person writing for the brand | +| **Image variants** | `generate moodboard [--theme ]` — visual mood board aligned to voice | + +### Application Guidelines (Tier 4) + +| Field | Value | +|-------|-------| +| **What it is** | The "where it goes." Rules for digital, print, social, signage, co-branding. | +| **Audience** | Producers, agencies, marketing operations | +| **Format** | Markdown template via `templates/application.md` | +| **Depth** | Moderate — channel-by-channel with file format matrix | +| **Dependency** | Depends on Visual Identity Spec (colors, type, logo are referenced) | +| **When to produce** | Brands appearing on 3+ channels | +| **Image variants** | `generate mockup --type stationery|social|signage|digital` | + +### Governance Framework (Tier 5) + +| Field | Value | +|-------|-------| +| **What it is** | The "how we keep it consistent." Versioning, ownership, review cadence, exception process. | +| **Audience** | Brand owners, stewards, legal, marketing ops | +| **Format** | Markdown template via `templates/governance.md` | +| **Depth** | Moderate — framework documents, content light | +| **Dependency** | None (parallel to other tiers) | +| **When to produce** | Scaling brands (50+ people) or any brand with multiple contributors | + +### Asset Inventory (Tier 6) + +| Field | Value | +|-------|-------| +| **What it is** | A structured index of every brand asset with format metadata, path, usage context. | +| **Audience** | Everyone who needs to find a brand file | +| **Format** | Markdown template via `templates/asset-inventory.md` | +| **Depth** | Tabular — rows of files with columns for format, path, usage, owner | +| **Dependency** | Depends on all other tiers being defined (assets are created from specs) | +| **When to produce** | Brands with >50 asset files | + +### Compiled Brand Book (All Tiers) + +| Field | Value | +|-------|-------| +| **What it is** | All spec documents assembled into a single unified reference, in canonical order. | +| **Audience** | Agencies, new hires, external partners — anyone who needs the complete picture | +| **Format** | (a) Compiled markdown via `brand-book compile --artifact full`, (b) HTML with optional CSS | +| **Depth** | Comprehensive — all sections, all detail | +| **Dependency** | Requires all other tiers to exist | +| **When to produce** | Agency handoff, enterprise distribution, press kit | + +## Production Flow + +``` +User fills templates (Phase 2) + │ + ▼ +brand-book validate (Step 3.3) + checks: required fields, color spaces, cross-references + │ + ▼ +brand-book compile --artifact brand-card + │ │ + ▼ ▼ + Markdown one-pager generate brand-card + │ + ▼ + Brand card image + +brand-book compile --artifact full + │ + ▼ + Compiled brand book (markdown or HTML) +``` + +## Who Needs What + +| Role | Artifacts They Use | +|------|-------------------| +| **CEO / Founder** | Brand card, strategy memo | +| **Designer** | Visual identity spec, asset inventory, brand card | +| **Developer** | Visual identity spec (colors, type), asset inventory | +| **Writer / Marketer** | Voice spec, brand card, application guidelines | +| **Agency Partner** | Compiled brand book, asset inventory | +| **Press / Media** | Brand card image, compiled brand book | +| **New Hire** | Brand card (first), compiled brand book (week one) | +| **Legal / Ops** | Governance framework, co-branding rules | diff --git a/brand-designer/references/brand-card-formats.md b/brand-designer/references/brand-card-formats.md new file mode 100644 index 0000000..377a7ec --- /dev/null +++ b/brand-designer/references/brand-card-formats.md @@ -0,0 +1,142 @@ +# Brand Documentation Formats: Comparison & Selection Guide + +Brand identity documentation comes in multiple formats. The right choice depends on team size, update frequency, technical sophistication, and audience. + +## Format Options + +### 1. Online Brand Guidelines (Web/Frontify/Zeroheight) + +**Best for:** Growing to enterprise teams that update frequently (>2x/year) + +| Factor | Assessment | +|--------|-----------| +| Update speed | Instant — single source of truth updates for everyone | +| Asset delivery | Embedded downloads — no separate file hosting needed | +| Searchability | Full-text search + deep-linkable sections | +| Interactivity | Video, interactive examples, click-to-copy color codes | +| Governance | Roles, permissions, analytics, version history | +| Cost | Platform subscription ($500-$5K/yr) or custom development | +| Technical skill | Medium — content management, no coding required | +| Offline access | No | + +**Examples:** Bang & Olufsen (Frontify), Trustpilot (Frontify), Sinch (Frontify), IBM, Cash App + +### 2. PDF Brand Book + +**Best for:** Small teams, agency deliverables, static identities that rarely change + +| Factor | Assessment | +|--------|-----------| +| Update speed | Slow — re-export from InDesign/Figma, re-upload, renotify | +| Asset delivery | Static — files must be downloaded separately | +| Searchability | Limited — reader search only, no cross-linking | +| Interactivity | None — static pages | +| Governance | Manual version control (filename conventions) | +| Cost | Design tool subscription only | +| Technical skill | Medium — InDesign/Figma/Illustrator | +| Offline access | Yes — downloadable, printable | + +**Examples:** Most agency client deliverables, some small-company brand books + +### 3. Notion / Google Docs / Wiki + +**Best for:** Early-stage startups, internal-only documentation + +| Factor | Assessment | +|--------|-----------| +| Update speed | Fast — anyone can edit | +| Asset delivery | Embedded previews + download links | +| Searchability | Native platform search | +| Interactivity | Comments, embeds, checklists | +| Governance | Page-level permissions | +| Cost | Free to low (<$50/user/mo) | +| Technical skill | Low | +| Offline access | Limited | + +**Examples:** Early-stage startups before they invest in a formal brand portal + +### 4. Figma / Design Tool Libraries + +**Best for:** Design-team-internal documentation tightly coupled to design tools + +| Factor | Assessment | +|--------|-----------| +| Update speed | Fast — design tokens in component libraries | +| Asset delivery | Direct — designers consume in tool | +| Searchability | Figma search | +| Interactivity | Interactive components, prototyping | +| Governance | Figma permissions, library publishing | +| Cost | Figma subscription | +| Technical skill | High — requires design tool proficiency | +| Offline access | Limited | + +**Examples:** Design system teams that keep brand documentation inside their tooling + +### 5. CLI-Generated / Markdown + Compiler + +**Best for:** Developer-friendly teams, vault-based knowledge management, open-source projects + +| Factor | Assessment | +|--------|-----------| +| Update speed | Fast — edit markdown, recompile | +| Asset delivery | Referenced by path, compiled in | +| Searchability | grep/full-text search on markdown | +| Interactivity | None in markdown; HTML output can include CSS | +| Governance | Git-based — PRs, version tags, changelogs | +| Cost | Free | +| Technical skill | Medium — markdown + CLI | +| Offline access | Yes — plain text files | + +**Examples:** This skill's output format, designlang's generated brand books + +### 6. Brand Card Image (Single Visual) + +**Best for:** Press kits, social media, stakeholder presentations, quick reference + +| Factor | Assessment | +|--------|-----------| +| Update speed | Slow — regenerate when identity changes | +| Asset delivery | Single image file | +| Searchability | None — it's an image | +| Interactivity | None | +| Governance | Manual | +| Cost | Free | +| Technical skill | Low — use the `generate` script | +| Offline access | Yes | + +**Examples:** Nous-branding card, groktopus-branding card, most press kit brand sheets + +## Decision Matrix + +| Your situation | Recommended format | Why | +|----------------|-------------------|-----| +| Solo founder, pre-revenue | Brand card image + Notion | Fast, free, covers 80% of needs | +| Small team (<10), one brand | Brand card + PDF | Simple to produce, easy to share | +| Growing team (10-50), multiple channels | Online guidelines + spec docs | Single source of truth, instant updates | +| Agency delivering to client | PDF brand book + design source files | Client expects a deliverable, source files enable future edits | +| Developer-facing product brand | CLI-generated markdown + design tokens | Devs prefer markdown; tokens integrate with code | +| Enterprise, global, many partners | Online guidelines (Frontify/Zeroheight) + compiled brand book PDF | Access control, analytics, partner self-service | +| Open source project | Markdown + generated brand card | Git-based, low barrier, low cost | + +## Hybrid Approach + +Most mature brands use **multiple formats** for different audiences: + +| Audience | Format | Depth | +|----------|--------|-------| +| Executive / board | Brand card image + strategy memo | One-pager | +| Design team | Figma library + online guidelines | Full spec | +| Engineering team | Design tokens + markdown spec | Structured data | +| Marketing / content | Online guidelines + voice spec | Practical rules | +| External agencies | Compiled brand book PDF | All-in-one reference | +| Press / partners | Brand card image + press kit | Visual summary | + +## Format Transition Path + +``` +Startup Growing Scaling Enterprise +────── ─────── ─────── ───────── +Brand card → Brand card → Online guidelines → Online guidelines +Notion/Google Docs + spec docs (markdown) + compiled PDF + design system tokens + + Figma (design team) + asset inventory + global localization +``` diff --git a/brand-designer/references/canonical-components.md b/brand-designer/references/canonical-components.md new file mode 100644 index 0000000..692d67a --- /dev/null +++ b/brand-designer/references/canonical-components.md @@ -0,0 +1,193 @@ +# Canonical Brand Identity Components + +A definitive hierarchy of every component a brand identity can document, organized by maturity tier. Each component notes whether it's **required** (must document), **recommended** (should document), or **advanced** (document when scaling). + +## Decision Tree + +Which components to document depends on brand maturity: + +```mermaid +flowchart TD + A[What stage is the brand?] --> B{Startup
pre-revenue, team < 10} + A --> C{Growing
revenue, team 10-50} + A --> D{Scaling
team 50-200} + A --> E{Enterprise
team 200+} + + B --> B1[Brand Card + Strategy Memo] + B1 --> B2[Visual Identity Spec
condensed] + B2 --> B3[Done — revisit at next stage] + + C --> C1[Strategy Memo] + C1 --> C2[Visual Identity Spec
full] + C2 --> C3[Voice & Messaging] + C3 --> C4[Application Guidelines
digital-first] + + D --> D1[All spec documents] + D1 --> D2[Governance framework] + D2 --> D3[Asset inventory] + D3 --> D4[Co-branding guidelines] + + E --> E1[Compiled Brand Book] + E1 --> E2[Design system integration] + E2 --> E3[Global localization] + E3 --> E4[Training materials] +``` + +## Component Hierarchy + +### Tier 0 — Brand Card (visual summary) +*Required at any stage. The "elevator pitch" of the brand.* + +| Component | What It Documents | Depth | +|-----------|------------------|-------| +| Brand name & tagline | Full name, shorthand, tagline/mission statement | One line each | +| Logo presentation | Primary logo on light + dark backgrounds | Image + brief specs | +| Color swatches | Core palette as visual swatches with names | 4-8 colors | +| Type specimen | Primary typeface shown in headline + body | One type family | +| Brand personality | 3-5 keywords describing the brand character | Keywords + one-liner | +| Reference image | A hero image that embodies the brand feel | Single image | + +### Tier 1 — Strategy & Positioning +*Required for growing brands. Provides the "why" behind visual decisions.* + +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Brand positioning statement | Audience, differentiator, market category | `positioning.audience`, `positioning.differentiator`, `positioning.market` | +| Brand personality (5-axis) | Traits along sincere/exciting/competent/sophisticated/rugged | `personality[5].axis` + `personality[5].value` | +| Mission & vision | Core mission statement and long-term vision | `mission`, `vision` | +| Core values | 3-5 values with descriptions | `values[].name`, `values[].description` | +| Competitive landscape | Key competitors and brand differentiation | `competitors[].name`, `competitors[].differentiator` | +| Target audience | Primary and secondary audience personas | `audiences.primary`, `audiences.secondary` | + +### Tier 2 — Visual Identity (full spec) +*Required for any brand producing external materials. The "how it looks."* + +#### Logo System +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Primary logo | Full-color horizontal logo | `file.svg`, `file.png`, `min-width` | +| Secondary logo | Stacked or condensed variant | `file.svg`, usage context | +| Icon / symbol | Standalone mark without wordmark | `file.svg`, min size | +| Monochrome variants | Black, white, grayscale versions | `file.svg` per variant | +| Clear space | Minimum empty area around logo | `value` in units of logo height | +| Minimum size | Smallest reproducible size per medium | `print`, `screen`, `social` | +| Background rules | Approved and prohibited backgrounds | `allowed[]`, `prohibited[]` | +| Incorrect usage | Visual "do not" examples | `misuses[].image`, `misuses[].note` | +| Favicon / app icon | Simplified mark for small contexts | `favicon.ico`, `apple-touch-icon` | + +#### Color Palette +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Primary palette | Core brand colors | Per color: `hex`, `rgb`, `cmyk`, `pantone` | +| Secondary palette | Supporting accent colors | Per color: `hex`, `rgb`, `cmyk` | +| Functional palette | UI states (success, error, warning, info) | Per color: `hex`, `role` | +| Neutral palette | Grays, blacks, whites | Per shade: `hex`, `usage` | +| Dark mode adaptation | Adjusted palette for dark backgrounds | Per color: `hex` (dark) | +| WCAG contrast pairs | Color combinations that meet AA/AAA | `foreground`, `background`, `ratio`, `level` | +| Usage rules | Which colors for which contexts | Per color: `role`, `max-area` | + +#### Typography +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Primary typeface | Main brand font | `family`, `weights[]`, `license` | +| Secondary typeface | Supporting font for body/code | `family`, `weights[]`, `fallback` | +| Type scale | Size/line-height/tracking per level | `levels[].name`, `font-size`, `line-height`, `tracking` | +| Hierarchy roles | Which type level for heading/body/caption | `role`, `type-level`, `usage-context` | +| Web fallbacks | System font stack | `font-stack` | +| Licensing | Font source and license type | `foundry`, `license-type` | + +#### Iconography (recommended) +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Icon style | Stroke weight, corner radius, filled/outlined | `stroke-width`, `corner-radius`, `style` | +| Grid system | Base grid size, padding | `grid-size`, `padding` | +| Metaphor rules | How abstract concepts map to icons | `rules[]` | +| Accessibility | Minimum touch target, contrast | `min-touch`, `min-contrast` | + +#### Photography & Imagery (recommended) +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Visual narrative | Subject matter, mood, lighting | `subject-matter`, `mood`, `lighting` | +| Color grading | Filter, temperature, saturation | `lookup-table` or `description` | +| Framing rules | Composition guidelines | `rules[]` | +| Diversity standards | Representation requirements | `guidelines` | +| Anti-patterns | What to avoid in imagery | `prohibited[]` | + +#### Illustration Style (advanced) +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Art style | Medium, linework, coloring | `description` | +| Palette constraints | Colors allowed/forbidden | `allowed-colors[]`, `forbidden-colors[]` | +| Detail level | Minimal vs. detailed | `scale 1-5` | +| Tone | Whimsical, serious, technical, etc. | `descriptors[]` | + +### Tier 3 — Voice, Tone & Messaging +*Required when multiple people write for the brand.* + +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Voice attributes | 3-5 defining voice traits | `attributes[].name`, `attributes[].description` | +| Tone matrix | How tone shifts by context and audience | `matrix[].context`, `matrix[].audience`, `matrix[].tone` | +| Messaging pillars | Core message categories | `pillars[].name`, `pillars[].description` | +| Vocabulary | Approved terms, forbidden terms | `approved[]`, `forbidden[]` | +| Good/bad copy examples | Before/after for common scenarios | `examples[].scenario`, `examples[].bad`, `examples[].good` | +| Localization notes | Cross-market adaptation rules | `rules[]` | + +### Tier 4 — Application Guidelines +*Required for any brand that appears across multiple channels.* + +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Digital applications | Social media, email, website | Per channel: `templates[]`, `specs` | +| Print applications | Business cards, letterhead, signage | Per medium: `templates[]`, `specs` | +| Co-branding rules | Partner logo usage | `rules[]`, `examples[]` | +| File format matrix | Which format for which use | `deliverables[].format`, `deliverables[].usage` | +| Motion principles | Animation duration, easing | `principles[]` | + +### Tier 5 — Governance & Maintenance +*Required for scaling/enterprise brands. The "how we keep it consistent."* + +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Version numbering | MAJOR.MINOR.PATCH convention | `scheme` | +| Brand steward | Who owns the brand | `name`, `contact` | +| Review cadence | Scheduled review frequency | `frequency`, `trigger-events[]` | +| Exception process | How to request deviations | `process-steps[]`, `approval-chain` | +| Changelog | History of updates | `entries[].date`, `entries[].change` | +| Archive policy | How to retire old assets | `retention`, `disposal` | + +### Tier 6 — Asset Inventory +*Required for any brand with >50 files.* + +| Component | What It Documents | Required Fields | +|-----------|------------------|-----------------| +| Logo files | All variants with formats and paths | Per asset: `name`, `format[]`, `path`, `usage` | +| Color reference files | Swatch books, palette files | Per asset: `name`, `format`, `path` | +| Font files | Typeface files and licenses | Per asset: `family`, `format[]`, `path` | +| Icon sets | Icon libraries with format | Per asset: `name`, `count`, `format`, `path` | +| Illustration assets | Illustration libraries | Per asset: `name`, `style`, `path` | +| Photography | Photo libraries, stock sources | Per asset: `source`, `license`, `path` | +| Templates | Slide decks, email, social templates | Per asset: `name`, `tool`, `path` | +| Video assets | Brand videos, motion files | Per asset: `name`, `duration`, `path` | + +## Component Relationships + +Components are not independent — they reference each other: + +``` +Brand Card (Tier 0) ──sources from──▶ Strategy + Visual-ID + Voice +Strategy (Tier 1) ──informs──▶ Visual-ID (Tier 2) + Voice (Tier 3) +Visual-ID (Tier 2) ──feeds──▶ Application (Tier 4) + Image Generation +Voice (Tier 3) ──feeds──▶ Application (Tier 4) +Application (Tier 4) ──uses──▶ Asset Inventory (Tier 6) +All tiers ──governed by──▶ Governance (Tier 5) +``` + +## Component Maturity Model + +| Brand Stage | Tiers to Document | Format | +|-------------|-------------------|--------| +| **Startup** (<10 people, pre-revenue) | Tier 0 + Tier 1 (condensed) | Brand card image + strategy memo | +| **Growing** (10-50 people, revenue) | Tier 0-3 | Full spec documents + brand card | +| **Scaling** (50-200 people, multi-channel) | Tier 0-5 | All specs + governance + compiled brand book | +| **Enterprise** (200+, global) | Tier 0-6 | Full system + asset inventory + localization | diff --git a/brand-designer/references/gold-standard-analysis.md b/brand-designer/references/gold-standard-analysis.md new file mode 100644 index 0000000..2458b84 --- /dev/null +++ b/brand-designer/references/gold-standard-analysis.md @@ -0,0 +1,216 @@ +# Gold-Standard Brand Documentation: Structural Analysis + +An analysis of how leading brands document their identity, extracted from public brand portals and design publications. Each entry covers: section ordering, depth per section, how they handle do/don't, asset delivery, and governance. + +--- + +## 1. Cash App — `design.cash.app` + +**Style:** Minimal, focused, digital-first. Masterclass in disciplined scope. + +### Section Ordering +1. Logo — primary, secondary, icon-only variants +2. Color — the signature green (#00D54B), supporting palette, gradient rules +3. Typography — custom typeface (Cash Sans), weights, fallbacks +4. Voice — direct, confident, avoids financial jargon +5. Brand assets — the `$cashtag` as a core asset (dedicated section) + +### What Makes It Stand Out +- **Strict palette discipline:** Core palette is intentionally tiny. No secondary palette bloat. +- **`$cashtag` as brand asset:** An entire section dedicated to proper use of the `$cashtag` in marketing, partnerships, and social — treating it not as a feature but as a core brand element. +- **Voice for a digital age:** Provides practical examples of on-brand copy from in-app notifications to social media captions. Shows rewritten examples, not just principles. +- **Extensive do/don't:** Every section has clear examples of correct and incorrect usage. + +### Governance Approach +- **Public portal with gated depth:** Anyone can view, no login needed +- **Asset delivery:** Direct download of brand assets from the portal + +### Depth Assessment +| Section | Depth | Notable | +|---------|-------|---------| +| Logo | Detailed | Multiple variants, clear space, minimum sizes | +| Color | Moderate | HEX+R+G values, gradient rules, backgrounds | +| Typography | Moderate | Weights, sizes, fallbacks, licensing | +| Voice | Detailed | Situational examples, before/after rewrites | +| Application | Light | Focused on partner-facing use, not exhaustive | + +--- + +## 2. IBM Design Language — `ibm.com/design/language` + +**Style:** Comprehensive, living system. The "enterprise standard." + +### Section Ordering +1. Principles — Pause, Studio, Thumb, Loop, Frame +2. Color — IBM Carbon palette, data visualization palette +3. Typography — IBM Plex family, type scale +4. Spacing — 8px grid, spacing scale +5. Motion — duration, easing, choreography +6. Data visualization — chart types, color usage, accessibility +7. Resources — Sketch/Adobe libraries, design kits + +### What Makes It Stand Out +- **Data visualization guidelines:** A rare and valuable section documenting chart types, color assignments, and annotation rules. Most brand guidelines skip this entirely. +- **Design system integration:** Brand guidelines flow directly into the Carbon Design System — the same tokens power both brand and product. +- **"What's new" section:** A dedicated changelog so users immediately see what's updated. +- **Downloadable design kits:** Libraries for Sketch and Adobe with core components, not just static assets. +- **Restrained scope:** Doesn't try to document every possible application — focuses on the system, not the artifacts. + +### Governance Approach +- **Living website** with version tracking +- **Tool integrations:** Design kits for Sketch/Adobe +- **Resource library:** Links to design tools and repositories + +### Depth Assessment +| Section | Depth | Notable | +|---------|-------|---------| +| Principles | Detailed | 5 principles with full explanation | +| Color | Comprehensive | Full palette + data viz palette + accessibility | +| Typography | Comprehensive | IBM Plex full family + type scale | +| Data viz | Detailed | Rare — chart types, color mapping, annotations | +| Resources | Detailed | Downloadable design kits, tool integrations | +| Motion | Moderate | Duration, easing, choreography principles | + +--- + +## 3. Netflix — `brand.netflix.com` + +**Style:** Clean, iconic, straight-to-the-point. Built for speed and clarity. + +### Section Ordering +1. Logo usage — primary and secondary variants +2. Color — red, black, white +3. Typography — Netflix Sans +4. Co-branding — partner logo rules +5. In-use examples — brand in application +6. Things to avoid — incorrect usage + +### What Makes It Stand Out +- **Co-branding as a priority:** Comprehensive guidelines for how partners should use the Netflix logo — crucial for a brand that appears on thousands of partner devices. +- **In-use examples over abstract rules:** Shows real applications across digital and offline mediums rather than just describing rules. +- **Gated governance:** Public access to core guidelines, but deeper materials require requesting access — a deliberate governance constraint. +- **"Things to avoid" section:** Dedicated page of incorrect usage examples, which is more effective than scattered do/don't notes. + +### Governance Approach +- **Two-tier access:** Public brand site for core rules; request-based access for deeper materials +- **Partner focus:** Guidelines optimized for external creators, not just internal teams + +### Depth Assessment +| Section | Depth | Notable | +|---------|-------|---------| +| Logo | Detailed | Multiple variants, do/don't, co-branding | +| Color | Minimal | Three colors only | +| Typography | Moderate | Primary typeface, weights | +| Co-branding | Comprehensive | Partner-focused, rules + examples | +| In-use examples | Moderate | Real campaign applications | + +--- + +## 4. Bang & Olufsen — `brand.bang-olufsen.com` (Frontify) + +**Style:** Design-first, premium. The brand hub IS a brand experience. + +### Section Ordering +1. Welcome/introduction +2. Logo — variants, clear space, minimum sizes +3. Color — palette with usage +4. Typography — font specifications +5. Imagery — photography style, editing +6. Assets — searchable, filterable library +7. Templates — downloadable production files + +### What Makes It Stand Out +- **Brand hub as product:** The brand portal itself reflects B&O's design sensibility — visually elegant interface that mirrors the premium nature of the brand. +- **Search + filter over thousands of assets:** Meticulously organized, tagged, and categorized. Users can find specific product photos or campaign materials instantly. +- **Creative empowerment:** The guidelines give teams confidence to create on-brand work without friction. +- **Asset management is first-class:** Not just rules — thousands of downloadable assets with powerful metadata. + +### Governance Approach +- **Frontify-hosted:** Centralized platform with permissions +- **Asset-first:** The hub prioritizes asset delivery over rules +- **Visual design of the hub is on-brand:** The container IS the brand + +### Depth Assessment +| Section | Depth | Notable | +|---------|-------|---------| +| Logo | Detailed | Full variant set, clear space, backgrounds | +| Color | Moderate | Primary palette with context | +| Typography | Moderate | Typeface specs, usage | +| Imagery | Detailed | Photography style, editing recommendations | +| Asset library | Comprehensive | Thousands of tagged, searchable assets | +| Templates | Moderate | Downloadable production files | + +--- + +## 5. Klarna — `brand.klarna.com` + +**Style:** Engaging, visual, partner-friendly. Designed for thousands of external users. + +### Section Ordering +1. Cover page — highly visual, scrollable mission + campaign examples +2. Logo — primary, secondary, icon +3. Color — palette with codes +4. Typography — typeface, weights +5. Tone of voice — concise with rewritten examples +6. Assets — downloadable + +### What Makes It Stand Out +- **Cover page as brand immersion:** The first interaction is a scrollable cover with brand mission and past campaigns — you experience the brand before reading rules. +- **Tone of voice with rewrites:** Shows actual copy rewrites with annotations explaining *why* the revision is better. +- **Simple navigation:** Users can jump to core elements from a persistent navigation menu. +- **Partner-scale governance:** Designed for thousands of external partners, not just an internal design team. + +### Governance Approach +- **Public portal:** Anyone can access brand assets +- **Simple navigation:** Prioritizes speed of access over comprehensiveness +- **Asset delivery:** Direct downloads + +### Depth Assessment +| Section | Depth | Notable | +|---------|-------|---------| +| Cover/mission | High | Campaign examples, brand immersion | +| Logo | Detailed | Full set with usage rules | +| Color | Moderate | Codes + usage examples | +| Typography | Moderate | Primary typeface + weights | +| Tone of voice | Detailed | Before/after rewrites with annotations | + +--- + +## Common Patterns Across Gold Standards + +### What All 5 Do Well +1. **Logo comes first** — Every single one leads with logo variants before anything else +2. **Visual examples over text** — Rules are shown, not just told +3. **Do/don't examples** — Every one includes incorrect usage examples +4. **Direct asset delivery** — Downloadable files from the portal itself +5. **Clear color codes** — HEX values at minimum; IBM adds accessible contrast pairs + +### What Differentiates the Best +1. **In-use examples** (Netflix, Starbucks) — Show real applications, not abstract rules +2. **Voice with rewrites** (Cash App, Klarna, Sinch) — Before/after copy pairs with annotations +3. **Data viz guidelines** (IBM) — A rare but critical section for analytical brands +4. **Governance gating** (Netflix) — Two-tier access for public vs. deeper materials +5. **Asset management at scale** (Bang & Olufsen) — Thousands of tagged, searchable assets + +### What Most Are Missing (Opportunity) +- **Accessibility standards** — Only IBM explicitly documents WCAG compliance +- **Dark mode palettes** — Rarely addressed in public brand guidelines +- **Motion principles** — Beyond basic logo animation rules +- **Governance/versioning** — Most don't show changelogs or review cadence +- **Asset inventory** — No structured index of every file with format metadata + +## Recommended "Brand Book Section Template" + +Synthesized from these analyses, the canonical section order for a compiled brand book: + +1. **Brand Strategy** — positioning, personality, mission, audience +2. **Logo System** — all variants, clear space, minimum size, backgrounds, misuse +3. **Color Palette** — primary, secondary, functional, dark mode, WCAG pairs +4. **Typography** — typefaces, scale, hierarchy, fallbacks, licensing +5. **Iconography** — style, grid, metaphor rules (if applicable) +6. **Imagery** — photography, illustration, motion (if applicable) +7. **Voice & Tone** — attributes, tone matrix, vocabulary, copy examples +8. **Application Guidelines** — digital, print, social, co-branding +9. **Governance** — versioning, ownership, review cadence, exceptions +10. **Asset Inventory** — structured file index +11. **Resources** — downloads, templates, design kits diff --git a/brand-designer/references/image-generation.md b/brand-designer/references/image-generation.md new file mode 100644 index 0000000..60dcc3a --- /dev/null +++ b/brand-designer/references/image-generation.md @@ -0,0 +1,126 @@ +# Brand-Compliant Image Generation + +How to generate on-brand images using the `generate` script and reference-image-aware prompts. Follows patterns proven in nous-branding and groktopus-branding. + +## Core Principle + +The built-in `image_generate` tool cannot use uploaded reference images. The `generate` script fills this gap by constructing brand-aware prompts and (optionally) routing through a reference-image-capable backend. + +## Prompt Architecture + +A brand-compliant prompt has four layers: + +``` +[SCENE] — What's being shown (brand card, mockup, swatch, moodboard) ++ [COLORS] — Exact palette constraints from brand data ++ [STYLE] — Visual style (minimalist, photorealistic, illustrative, design-system) ++ [CONSTRAINTS]— What NOT to include (do/don't rules, banned elements) +``` + +### Good prompt structure + +``` +Professional brand card for "BrandName", horizontal 16:9 format. +Clean, minimalist design with: +- Large prominent brand name "BrandName" with tagline +- Color palette swatches: Brand Blue #0055FF, Accent Green #00CC66, Off Black #1A1A1A +- Clean sans-serif typography (Inter, SF Pro) +- Brand personality: competent, sincere +- Clean white background with subtle brand accent +- Elegant layout suitable for press kit +No photorealistic people. Design-system mockup style. +``` + +### Bad prompt structure + +``` +A cool-looking brand thing with some colors and maybe a logo. Make it look professional. +``` + +## Color in Prompts + +**Always include HEX values** in prompts — models interpret `#0055FF` more precisely than "brand blue." + +**Include color names** alongside hex values for models that don't parse hex well: +``` +- Brand palette: Deep Navy #0A1628, Warm Gold #D4A843, Cream #F5F0E8 +``` + +**Specify contrast relationships** for legibility: +``` +- Dark text (#1A1A1A) on light background (#F8F8F8) +- White text (#FFFFFF) on brand-colored surfaces (#0055FF) +``` + +## Reference Image Patterns + +When a reference-image-capable backend is available: + +| Image Type | Best Reference Images | Effect | +|------------|----------------------|--------| +| Brand card | Logo + existing brand materials + palette card | Accurate logo rendering in context | +| Mockup | Logo + product photos | Realistic application examples | +| Swatch card | Palette reference image | Precise color matching | +| Logo bg | Logo file (transparent PNG) | Clean logo on various backgrounds | + +## Subcommand Prompt Guide + +### `generate brand-card` + +Best output when the prompt includes: +- Brand name typographically (models render text inconsistently — accept this) +- HEX values for ALL primary and secondary colors +- The primary typeface name +- Layout: "flat lay" or "mockup on wall" for landscape; "social media card" for portrait + +### `generate mockup --type signage` + +For signage and environmental graphics, add context: +``` +"architectural context, modern building exterior, subtle brand integration" +``` +Avoid: +``` +"huge logo on a building" — reads as billboard, not brand architecture +``` + +### `generate swatch` + +Models tend to invent colors if not given exact values. Mitigations: +1. Provide hex values in the prompt +2. Reference an uploaded color palette card image +3. Expect some drift — swatch generation is a guide, not a Pantone proof + +### `generate moodboard` + +Moodboards benefit most from brand personality data. Include: +``` +"Collage-style layout with textures, color fields, typography samples, +and atmospheric imagery capturing [brand personality keywords] essence" +``` + +## Brand Card Layout Guide + +| Layout | Dimensions | Use Case | Prompt Hint | +|--------|-----------|----------|-------------| +| Landscape | 16:9 (1920×1080) | Press kit, website hero, slide deck | "horizontal brand card, wide layout" | +| Portrait | 4:5 (1080×1350) | Social media, Instagram | "vertical brand card, social media format" | + +## Do/Don't + +| Do | Don't | +|----|-------| +| Include HEX values in prompts | Rely on color names alone ("brand blue" is ambiguous) | +| Specify what to exclude | Leave composition entirely to the model | +| Use reference images for logos | Expect text in generated images to be accurate | +| Match background to brand usage rules | Place colored logos on clashing backgrounds | +| Test prompts iteratively | Expect first-generation perfection | + +## LLM Enhancement + +When `BRAND_DESIGNER_LLM_URL` and `BRAND_DESIGNER_LLM_KEY` are set, the `generate` script can optionally: +- Refine prompts before sending to the imaging backend +- Suggest prompt improvements based on brand voice +- Classify whether a generated output is on-brand + +This is optional — the script works without it; the LLM just improves quality. diff --git a/brand-designer/references/template-schemas.md b/brand-designer/references/template-schemas.md new file mode 100644 index 0000000..18ae1be --- /dev/null +++ b/brand-designer/references/template-schemas.md @@ -0,0 +1,416 @@ +# Template Schema Definitions + +This document defines the YAML frontmatter schema for each of the 7 templates. Templates are authored as markdown files with YAML frontmatter. All templates follow these conventions: + +- `type:` field identifies the template variant +- `brand:` field links across all templates for the same brand +- Array fields use block-list format (one `- ` per line) +- Booleans are bare (`true`/`false`, not quoted) +- Dates are `YYYY-MM-DD` +- Wikilinks are quoted `"[[Link]]"` + +--- + +## brand-card.md + +```yaml +--- +type: brand-card +brand: Brand Name +tagline: "Short brand mission or positioning statement" +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +source: + strategy: "[[Brand Name Strategy]]" + visual-id: "[[Brand Name Visual Identity]]" + voice: "[[Brand Name Voice]]" +layout: portrait|landscape +--- +``` + +**Body sections:** Brand name + tagline → Logo (referenced) → Color swatches (condensed, 4-8 colors with names + HEX) → Type specimen (primary typeface name + weights) → Brand personality keywords → Tagline/positioning + +--- + +## strategy.md + +```yaml +--- +type: brand-strategy +brand: Brand Name +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +positioning: + audience: "Primary target audience description" + differentiator: "What makes this brand unique" + market: "Market category" +personality: + - axis: sincere|exciting|competent|sophisticated|rugged + value: 1-5 + - axis: sincere|exciting|competent|sophisticated|rugged + value: 1-5 + - axis: sincere|exciting|competent|sophisticated|rugged + value: 1-5 + - axis: sincere|exciting|competent|sophisticated|rugged + value: 1-5 + - axis: sincere|exciting|competent|sophisticated|rugged + value: 1-5 +mission: "Core mission statement" +vision: "Long-term vision statement" +values: + - name: Value Name + description: "What this value means in practice" + - name: Value Name + description: "What this value means in practice" +competitors: + - name: Competitor Name + differentiator: "How we differ" +audiences: + primary: + name: "Persona name" + description: "Description of primary audience" + secondary: + name: "Persona name" + description: "Description of secondary audience" +--- +``` + +**Body sections:** Positioning statement → Personality profile (with axis descriptions) → Mission & vision → Core values → Competitive landscape → Audience personas + +--- + +## visual-id.md + +```yaml +--- +type: brand-visual-identity +brand: Brand Name +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +logo: + primary: + description: "Full-color horizontal logo" + file_svg: "path/logo.svg" + file_png: "path/logo.png" + min_width_px: 100 + secondary: + description: "Stacked vertical variant" + file_svg: "path/logo-stacked.svg" + icon: + description: "Standalone symbol" + file_svg: "path/icon.svg" + min_width_px: 24 + monochrome: + - variant: black|white|grayscale + file_svg: "path/logo-black.svg" + clear_space: 0.25 + min_sizes: + print_mm: 15 + screen_px: 32 + social_px: 48 + backgrounds: + allowed: + - light solid + - dark solid + prohibited: + - busy imagery + - similar color to mark + incorrect_usage: + - description: "Don't stretch the logo" + - description: "Don't add drop shadows" + - description: "Don't recolor" +colors: + primary: + - name: "Brand Blue" + hex: "#0055FF" + rgb: "0 85 255" + cmyk: "100 67 0 0" + pantone: "2736 C" + usage: "Primary brand elements" + secondary: + - name: "Accent Green" + hex: "#00CC66" + rgb: "0 204 102" + cmyk: "75 0 85 0" + usage: "Call-to-action elements" + functional: + - name: "Success" + hex: "#00AA55" + role: success + - name: "Error" + hex: "#DD3333" + role: error + neutral: + - name: "Off Black" + hex: "#1A1A1A" + usage: "Body text" + dark_mode: + enabled: true + adaptation: invert + wcag_pairs: + - foreground: "#0055FF" + background: "#FFFFFF" + ratio: 8.6 + level: AAA +typography: + primary: + family: "Brand Sans" + weights: + - 300 + - 400 + - 600 + - 700 + license: "Google Fonts / OFL" + secondary: + family: "Brand Serif" + weights: + - 400 + - 700 + fallback: "Georgia, serif" + scale: + - level: h1 + font_size: 48 + line_height: 1.2 + tracking: -0.02 + - level: h2 + font_size: 36 + line_height: 1.3 + tracking: -0.01 + - level: h3 + font_size: 24 + line_height: 1.4 + tracking: 0 + - level: body + font_size: 16 + line_height: 1.6 + tracking: 0 + - level: caption + font_size: 12 + line_height: 1.4 + tracking: 0.01 + web_fallbacks: "'Brand Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif" +iconography: + style: outlined + stroke_weight: 1.5 + corner_radius: 2 + grid_size: 24 + padding: 2 + accessibility: + min_touch_target: 44 + min_contrast: 3.0 +photography: + narrative: "Description of visual style, subject matter, and mood" + color_grading: "Description of filter or color treatment" + framing_rules: + - "Rule description" + diversity_guidelines: "Representation standards" + prohibited: + - "Generic stock photography" + - "Overly posed corporate shots" +illustration: + style: "Description of illustration style" + allowed_colors: ["List of palette colors"] + detail_level: 3 + tone: ["descriptive adjectives"] +--- +``` + +**Body sections:** Logo system (variants table, clear space diagram, minimum sizes, backgrounds, misuse examples) → Color palette (primary, secondary, functional, neutral, dark mode, WCAG pairs) → Typography (typefaces table, scale, hierarchy, fallbacks, licensing) → Iconography (style, grid, accessibility) → Photography (narrative, framing, diversity, anti-patterns) → Illustration (style, palette constraints, detail level) + +--- + +## voice.md + +```yaml +--- +type: brand-voice +brand: Brand Name +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +attributes: + - name: "Confident" + description: "Speaks with authority, not arrogance" + - name: "Clear" + description: "Prefer the direct word over the impressive one" + - name: "Human" + description: "Warm, conversational, never corporate" +tone_matrix: + - context: "Product copy" + audience: "New users" + tone: "Helpful, encouraging" + - context: "Error message" + audience: "All users" + tone: "Apologetic, solution-oriented" + - context: "Social media" + audience: "Followers" + tone: "Playful, brief" +pillars: + - name: "Innovation" + description: "We push boundaries" +vocabulary: + approved: + - "we" + - "you" + - "let's" + forbidden: + - "leverage" + - "synergize" + - "utilize" +examples: + - scenario: "404 error page" + bad: "The requested resource was not found" + good: "Hmm, that page wandered off. Let's get you back." +localization: + notes: + - "Maintain direct address in all markets" +--- +``` + +**Body sections:** Voice attributes (3-5 with descriptions) → Tone matrix (context × audience → tone) → Messaging pillars → Vocabulary (approved words, words to avoid) → Copy examples (before/after pairs for common scenarios) → Localization notes + +--- + +## application.md + +```yaml +--- +type: brand-application +brand: Brand Name +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +digital: + channels: + - name: "Social media" + templates: + - "path/template-instagram.png" + - "path/template-linkedin.png" + specs: "1080x1080 square, 1200x628 landscape" + - name: "Email" + templates: + - "path/email-template.html" + specs: "600px max width, inline CSS" +print: + items: + - name: "Business card" + templates: + - "path/business-card.ai" + specs: "3.5x2in, 4/4 CMYK + spot gloss" + - name: "Letterhead" + templates: + - "path/letterhead.ai" + specs: "8.5x11in, 1-color logo" +cobranding: + rules: + - "Partner logo must be same size or smaller" + - "Minimum clear space: 1x partner logo height" + examples: + - "path/cobrand-example.png" +file_formats: + - format: SVG + usage: "Web, digital, scalable" + - format: EPS + usage: "Print production" + - format: PNG + usage: "Office documents, social" + - format: PDF + usage: "Print-ready, client delivery" +motion: + principles: + - "Duration: 200-400ms for micro-interactions" + - "Easing: ease-in-out for UI elements" +--- +``` + +**Body sections:** Digital applications (per-channel templates and specs) → Print applications (per-medium templates and specs) → Co-branding rules → File format delivery matrix → Motion principles + +--- + +## governance.md + +```yaml +--- +type: brand-governance +brand: Brand Name +created: YYYY-MM-DD +updated: YYYY-MM-DD +version: 0.1.0 +status: draft|active|archived +versioning: + scheme: "MAJOR.MINOR.PATCH" + current_version: "1.0.0" + notes: "MAJOR = redesign, MINOR = palette/type change, PATCH = documentation fix" +steward: + name: "Brand Owner Name" + role: "Title" + contact: "email@example.com" +review: + cadence: "Quarterly" + last_review: YYYY-MM-DD + next_review: YYYY-MM-DD + trigger_events: + - "Logo refresh" + - "Merger or acquisition" + - "New product launch with distinct identity" +exceptions: + process: + - "Submit exception request to brand steward" + - "Steward reviews within 5 business days" + - "Approved exceptions logged with expiration date" + approval_chain: "Brand Steward → VP Marketing (if high-visibility)" +changelog: + - date: YYYY-MM-DD + change: "Initial brand identity documentation" + author: "Author Name" +archive: + retention: "Current + 2 previous versions" + disposal: "Deprecated assets moved to /archive/ directory" +--- +``` + +**Body sections:** Version numbering convention → Brand steward contact → Review cadence + trigger events → Exception request process → Changelog → Archive policy + +--- + +## asset-inventory.md + +```yaml +--- +type: brand-asset-inventory +brand: Brand Name +updated: YYYY-MM-DD +owner: "Brand Steward Name" +--- +``` + +**Body sections:** Table of all brand assets. The body is primarily a markdown table with these columns: + +| Asset Name | Formats | Path | Usage Context | Updated | Owner | +|---|---|---|---|---|---| +| Primary Logo Color | SVG, PNG, EPS | `/assets/logos/primary/` | Web, print, social | 2026-01-15 | Design Team | +| Primary Logo B/W | SVG, EPS | `/assets/logos/primary/bw/` | Print, monotone | 2026-01-15 | Design Team | +| Brand Colors (ASE) | ASE, PDF | `/assets/color/` | Design tools reference | 2026-01-15 | Design Team | +| Brand Sans Regular | WOFF2, TTF | `/assets/fonts/` | Web, desktop | 2026-01-15 | Design Team | +| Icon Set | SVG | `/assets/icons/` | Web, app UI | 2026-01-15 | Design Team | +| Social Templates | PSD, AI, FIG | `/assets/templates/social/` | Social media production | 2026-01-15 | Design Team | +| Brand Guidelines | Markdown | `/docs/brand/` | Internal reference | 2026-01-15 | Brand Steward | + +### Asset categories (in canonical order) +- **Logo files:** All variants, all formats +- **Color reference files:** ASE swatches, palette reference cards +- **Font files:** All licensed typefaces with format variants +- **Icon sets:** Style-specific icon libraries +- **Illustration assets:** Style-specific illustration libraries +- **Photography:** Stock libraries, commissioned shoots, usage rights +- **Templates:** Social, email, slide deck, document templates +- **Video/Motion:** Brand videos, logo animations, lower thirds +- **Documentation:** Brand guidelines, spec documents, usage guides diff --git a/brand-designer/scripts/brand-book b/brand-designer/scripts/brand-book new file mode 100755 index 0000000..602a0a1 --- /dev/null +++ b/brand-designer/scripts/brand-book @@ -0,0 +1,549 @@ +#!/usr/bin/env python3 +""" +brand-book — CLI for brand identity artifact assembly, validation, and scaffolding. + +Part of the brand-designer AgentSkill. Follows cli-builder conventions: +non-interactive, flag-driven, idempotent, --json and --dry-run support. + +Subcommands: + init — Scaffold a new brand directory with all 7 templates + compile — Read frontmatter from markdown files, assemble into artifact + validate — Check required fields, color space completeness, cross-references + preview — Render a terminal preview of a brand component +""" + +import argparse +import json +import os +import re +import shutil +import sys +import textwrap +from datetime import date +from pathlib import Path + +# --- Configuration --- + +TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "templates" + +ARTIFACT_TYPES = [ + "brand-card", "strategy", "visual-id", "voice", + "application", "governance", "asset-inventory", "full" +] + +TEMPLATE_MAP = { + "brand-card": "templates/brand-card.md", + "strategy": "templates/strategy.md", + "visual-id": "templates/visual-id.md", + "voice": "templates/voice.md", + "application": "templates/application.md", + "governance": "templates/governance.md", + "asset-inventory": "templates/asset-inventory.md", +} + +CANONICAL_ORDER = [ + "strategy", "visual-id", "voice", "application", + "governance", "asset-inventory" +] + +# --- Frontmatter Parsing --- + +def parse_frontmatter(text): + """Extract YAML frontmatter from markdown. Returns (frontmatter_dict, body_text). + + Uses PyYAML if available (preferred), falls back to a simple line parser. + """ + match = re.match(r'^---\n(.*?)\n---\n(.*)', text, re.DOTALL) + if not match: + return {}, text.strip() + + raw_yaml = match.group(1) + body = match.group(2).strip() + + # Try PyYAML first + try: + import yaml + result = yaml.safe_load(raw_yaml) + if isinstance(result, dict): + return result, body + except ImportError: + pass + except yaml.YAMLError: + pass + + # Fallback: simple line parser for basic key:value and list frontmatter + lines = raw_yaml.split('\n') + result = {} + current_list_key = None + current_list = [] + + for line in lines: + stripped = line.strip() + if not stripped or stripped.startswith('#'): + continue + + # List item + if stripped.startswith('- '): + item_text = stripped[2:].strip() + # Check if this is a k:v pair within the list item + if ': ' in item_text and not item_text.startswith('"') and not item_text.startswith("'"): + parts = item_text.split(': ', 1) + current_list.append({parts[0].strip(): parts[1].strip().strip('"').strip("'")}) + else: + current_list.append(item_text.strip('"').strip("'")) + continue + + # Flush pending list + if current_list_key is not None and current_list: + result[current_list_key] = current_list + current_list_key = None + current_list = [] + + # Key: value pair + if ': ' in stripped: + key, value = stripped.split(': ', 1) + key = key.strip() + value = value.strip().strip('"').strip("'") + + if value == '' or value == '|' or value == '>': + # Value follows on next lines — could be nested or multiline + current_list_key = key + current_list = [] + continue + + # Type coercion + if value == 'true': value = True + elif value == 'false': value = False + elif value == 'null' or value == '~': value = None + + result[key] = value + + # Flush trailing list + if current_list_key is not None and current_list: + result[current_list_key] = current_list + + return result, body + + +def read_frontmatter(path): + """Read and parse frontmatter from a markdown file.""" + with open(path) as f: + text = f.read() + fm, body = parse_frontmatter(text) + fm['_path'] = str(path) + fm['_body'] = body + return fm + + +# --- Validation --- + +def validate_frontmatter(fm, strict=False): + """Validate a frontmatter dict. Returns list of (field, severity, message) tuples.""" + issues = [] + artifact_type = fm.get('type', 'unknown') + + # Required fields for all types + for field in ['type', 'brand']: + if field not in fm or not fm[field]: + issues.append((field, 'error', f"Missing required field: {field}")) + + if artifact_type not in ARTIFACT_TYPES and artifact_type not in [ + 'brand-card-template', 'brand-strategy-template', 'brand-visual-identity-template', + 'brand-voice-template', 'brand-application-template', 'brand-governance-template', + 'brand-asset-inventory-template' + ]: + issues.append(('type', 'warning', f"Unknown artifact type: {artifact_type}")) + + # Type-specific validation + type_checks = { + 'brand-visual-identity': validate_visual_id, + 'brand-strategy': validate_strategy, + 'brand-voice': validate_voice, + } + + check_fn = type_checks.get(artifact_type) + if check_fn: + issues.extend(check_fn(fm)) + + # Cross-reference validation (strict mode) + if strict: + # brand-card must have source links + if artifact_type == 'brand-card': + sources = fm.get('source', {}) + if not sources: + issues.append(('source', 'error', "Brand card must reference source templates via `source:`")) + + # visual-id must have logo variant coverage + if artifact_type in ('brand-visual-identity', 'brand-visual-identity-template'): + logo = fm.get('logo', {}) + if not logo.get('primary'): + issues.append(('logo.primary', 'warning', "Missing primary logo definition")) + + return issues + + +def validate_visual_id(fm): + """Validate visual identity spec.""" + issues = [] + colors = fm.get('colors', {}) + primary = colors.get('primary', []) + if not primary: + issues.append(('colors.primary', 'error', "At least one primary color required")) + else: + for i, color in enumerate(primary): + for space in ['hex', 'rgb', 'cmyk']: + if space not in color: + issues.append((f'colors.primary[{i}].{space}', 'warning', + f"Color '{color.get('name', 'unnamed')}' missing {space.upper()} value")) + + typography = fm.get('typography', {}) + if not typography.get('primary'): + issues.append(('typography.primary', 'error', "Primary typeface required")) + + return issues + + +def validate_strategy(fm): + """Validate strategy memo.""" + issues = [] + for field in ['positioning', 'mission']: + if field not in fm: + issues.append((field, 'warning', f"Consider adding {field}")) + + positioning = fm.get('positioning', {}) + if isinstance(positioning, dict): + for sub in ['audience', 'differentiator']: + if sub not in positioning: + issues.append((f'positioning.{sub}', 'warning', f"Consider adding positioning.{sub}")) + + return issues + + +def validate_voice(fm): + """Validate voice guidelines.""" + issues = [] + attributes = fm.get('attributes', []) + if not attributes: + issues.append(('attributes', 'warning', "No voice attributes defined")) + return issues + + +# --- Compilation --- + +def compile_brand_card(templates_dir, brand_name=None): + """Compile a brand card one-pager from source templates.""" + sections = [] + sections.append("# Brand Card\n") + + # Try to find strategy for tagline and personality + for tmpl_name in ['strategy', 'visual-id']: + tmpl_path = templates_dir / f"{tmpl_name}.md" + if tmpl_path.exists(): + fm, body = parse_frontmatter(tmpl_path.read_text()) + if tmpl_name == 'strategy': + brand = fm.get('brand', brand_name or 'Your Brand') + positioning = fm.get('positioning', {}) + if isinstance(positioning, dict) and positioning.get('differentiator'): + sections.append(f"> **{positioning.get('differentiator')}**\n") + elif tmpl_name == 'visual-id': + collect_color_swatches(fm, sections) + collect_typeface_info(fm, sections) + + if not sections or len(sections) < 2: + sections.append("*Fill in your brand templates to see compiled content here.*") + + return '\n'.join(sections) + + +def collect_color_swatches(fm, sections): + """Extract and format color swatch info for brand card.""" + colors = fm.get('colors', {}) + primary = colors.get('primary', []) + if primary: + sections.append("## Color Palette\n") + sections.append("| Name | HEX |") + sections.append("|------|-----|") + for c in primary[:6]: + name = c.get('name', 'Unnamed') + hex_val = c.get('hex', '—') + sections.append(f"| {name} | `#{hex_val}` |") + sections.append("") + + +def collect_typeface_info(fm, sections): + """Extract and format typeface info for brand card.""" + typography = fm.get('typography', {}) + primary = typography.get('primary', {}) + if isinstance(primary, dict) and primary.get('family'): + sections.append("## Typography\n") + family = primary['family'] + weights = primary.get('weights', []) + weight_str = ', '.join(str(w) for w in weights) if weights else '—' + sections.append(f"- **Primary:** {family} ({weight_str})\n") + secondary = typography.get('secondary', {}) + if isinstance(secondary, dict) and secondary.get('family'): + sections.append(f"- **Secondary:** {secondary.get('family')}\n") + sections.append("") + + +def compile_full(templates_dir): + """Compile all spec documents into a single brand book.""" + sections = [] + + # Read all spec templates in canonical order + for tmpl_name in CANONICAL_ORDER: + tmpl_path = templates_dir / f"{tmpl_name}.md" + if tmpl_path.exists(): + fm, body = parse_frontmatter(tmpl_path.read_text()) + brand = fm.get('brand', 'Your Brand') + # Use the body directly + sections.append(f"\n\n\n\n{body}") + + if not sections: + return "*No spec documents found to compile.*" + + return '\n'.join(sections) + + +# --- Preview --- + +def preview_artifact(fm): + """Render a terminal-friendly preview of a brand component.""" + lines = [] + artifact_type = fm.get('type', 'unknown').replace('-template', '') + brand = fm.get('brand', 'Unnamed Brand') + + lines.append(f"╔══ {brand} — {artifact_type.upper()} ══" + "╗") + lines.append("") + + if artifact_type == 'brand-card' or artifact_type == 'brand-card-template': + tagline = fm.get('tagline', '') + if tagline: + lines.append(f" {tagline}") + lines.append("") + + if 'positioning' in fm: + pos = fm['positioning'] + if isinstance(pos, dict): + diff = pos.get('differentiator', '') + if diff: + lines.append(f" Key differentiator: {diff}") + lines.append("") + + if 'colors' in fm: + colors = fm['colors'] + primary = colors.get('primary', []) + if primary: + lines.append(" Colors:") + for c in primary[:4]: + name = c.get('name', '?') + hex_val = c.get('hex', '?') + lines.append(f" {name:20s} #{hex_val}") + lines.append("") + + if 'typography' in fm: + type_spec = fm['typography'] + primary = type_spec.get('primary', {}) + if isinstance(primary, dict) and primary.get('family'): + lines.append(f" Typeface: {primary['family']}") + lines.append("") + + if 'attributes' in fm: + attrs = fm['attributes'] + if attrs: + lines.append(" Voice:") + for attr in attrs[:3]: + if isinstance(attr, dict): + lines.append(f" {attr.get('name', '?'):15s} — {attr.get('description', '')}") + lines.append("") + + # Footer + issues = validate_frontmatter(fm) + errors = [i for i in issues if i[1] == 'error'] + warnings = [i for i in issues if i[1] == 'warning'] + if errors: + lines.append(f" ⚠ {len(errors)} error(s) — run `validate`") + if warnings: + lines.append(f" ⚡ {len(warnings)} warning(s) — run `validate --strict`") + + return '\n'.join(lines) + + +# --- Scaffolding --- + +def scaffold_brand(target_dir, brand_name=None): + """Create a new brand directory with all 7 templates.""" + target = Path(target_dir) + + if target.exists() and list(target.iterdir()): + print(f"Error: {target} already exists and is not empty.") + sys.exit(1) + + target.mkdir(parents=True, exist_ok=True) + templates_dir = TEMPLATES_DIR + + if not templates_dir.exists(): + print(f"Error: Templates directory not found at {templates_dir}") + sys.exit(1) + + # Copy all templates + copied = [] + for tmpl_path in sorted(templates_dir.glob("*.md")): + dest = target / tmpl_path.name + content = tmpl_path.read_text() + + # Replace {{brand}} placeholder if brand name provided + if brand_name: + content = content.replace("{{brand}}", brand_name) + content = content.replace("{{Brand Name}}", brand_name) + + dest.write_text(content) + copied.append(dest.name) + + return copied + + +# --- CLI --- + +def main(): + # Use parent parser for shared flags + parent_parser = argparse.ArgumentParser(add_help=False) + parent_parser.add_argument('--json', action='store_true', help='Output as JSON') + parent_parser.add_argument('--dry-run', action='store_true', help='Preview what would happen') + + parser = argparse.ArgumentParser( + description="Brand identity artifact CLI — scaffold, compile, validate, preview", + parents=[parent_parser], + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=textwrap.dedent("""\ + Examples: + brand-book init ./my-brand --name "Acme Corp" + brand-book compile ./my-brand --artifact brand-card + brand-book compile ./my-brand --artifact full --format html + brand-book validate ./my-brand/visual-id.md --strict + brand-book preview ./my-brand/strategy.md + """) + ) + + subparsers = parser.add_subparsers(dest='command', help='Subcommand') + + # init + init_parser = subparsers.add_parser('init', parents=[parent_parser], add_help=False, + help='Scaffold a new brand directory') + init_parser.add_argument('directory', help='Target directory for the new brand') + init_parser.add_argument('--name', '-n', help='Brand name (replaces {{brand}} placeholders)') + + # compile + compile_parser = subparsers.add_parser('compile', parents=[parent_parser], add_help=False, + help='Assemble brand artifacts from templates') + compile_parser.add_argument('directory', help='Directory containing brand templates') + compile_parser.add_argument('--artifact', choices=ARTIFACT_TYPES, default='full', + help='Artifact type to compile (default: full)') + compile_parser.add_argument('--format', choices=['markdown', 'html'], default='markdown', + help='Output format') + compile_parser.add_argument('--output', '-o', help='Output file path') + + # validate + validate_parser = subparsers.add_parser('validate', parents=[parent_parser], add_help=False, + help='Validate brand documentation') + validate_parser.add_argument('files', nargs='+', help='Files to validate') + validate_parser.add_argument('--strict', action='store_true', help='Check cross-references') + + # preview + preview_parser = subparsers.add_parser('preview', parents=[parent_parser], add_help=False, + help='Preview a brand component') + preview_parser.add_argument('file', help='File to preview') + + args = parser.parse_args() + + if args.json: + # JSON output mode — defer to command handlers + pass + + if args.dry_run: + print("[DRY RUN] No changes made.") + return + + if args.command == 'init': + result = scaffold_brand(args.directory, args.name) + if args.json: + print(json.dumps({"status": "ok", "copied": result})) + else: + print(f"Scaffolded brand directory at {args.directory}/") + for f in result: + print(f" + {f}") + + elif args.command == 'compile': + target = Path(args.directory) + if not target.exists(): + print(f"Error: Directory not found: {args.directory}") + sys.exit(1) + + if args.artifact == 'brand-card': + output = compile_brand_card(target) + elif args.artifact == 'full': + output = compile_full(target) + else: + # Single template compilation + tmpl_name = args.artifact + tmpl_path = target / f"{tmpl_name}.md" + if not tmpl_path.exists(): + print(f"Error: Template not found: {tmpl_path}") + sys.exit(1) + fm, body = parse_frontmatter(tmpl_path.read_text()) + output = body + + if args.json: + print(json.dumps({"status": "ok", "content": output, "length": len(output)})) + else: + if args.output: + Path(args.output).write_text(output) + print(f"Written to {args.output}") + else: + print(output) + + elif args.command == 'validate': + all_issues = [] + for filepath in args.files: + path = Path(filepath) + if not path.exists(): + all_issues.append((filepath, 'error', f"File not found: {filepath}")) + continue + fm = read_frontmatter(path) + issues = validate_frontmatter(fm, strict=args.strict) + all_issues.extend((filepath,) + i for i in issues) + + if args.json: + issues_json = [ + {"file": f, "field": field, "severity": sev, "message": msg} + for f, field, sev, msg in all_issues + ] + print(json.dumps({"issues": issues_json, "count": len(all_issues)})) + else: + if not all_issues: + print("✓ No issues found.") + return + + for fpath, field, sev, msg in all_issues: + icon = "✗" if sev == 'error' else "⚠" if sev == 'warning' else "→" + print(f" {icon} [{sev.upper()}] {fpath} — {field}: {msg}") + print(f"\n{len(all_issues)} issue(s) found.") + + elif args.command == 'preview': + path = Path(args.file) + if not path.exists(): + print(f"Error: File not found: {args.file}") + sys.exit(1) + fm = read_frontmatter(path) + preview = preview_artifact(fm) + if args.json: + print(json.dumps({"preview": preview})) + else: + print(preview) + + else: + parser.print_help() + + +if __name__ == '__main__': + main() diff --git a/brand-designer/scripts/brand-book_test.sh b/brand-designer/scripts/brand-book_test.sh new file mode 100644 index 0000000..867bd4d --- /dev/null +++ b/brand-designer/scripts/brand-book_test.sh @@ -0,0 +1,119 @@ +#!/usr/bin/env bash +# brand-book test suite +# Run: bash scripts/brand-book_test.sh + +set -uo pipefail +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +BRAND_BOOK="$SCRIPT_DIR/brand-book" +TEMPLATES_DIR="$SCRIPT_DIR/../templates" +TEST_DIR="/tmp/brand-test-$$" +PASS=0 +FAIL=0 + +cleanup() { rm -rf "$TEST_DIR"; } +trap cleanup EXIT + +green() { printf " \033[32m✓\033[0m %s\n" "$1"; ((PASS++)); } +red() { printf " \033[31m✗\033[0m %s\n" "$1"; ((FAIL++)); } + +echo "=== brand-book Test Suite ===" +echo "" + +# 1. Smoke: CLI runs +if "$BRAND_BOOK" --help > /dev/null 2>&1; then + green "CLI runs with --help" +else + red "CLI --help failed" +fi + +# 2. Init: scaffold a brand +mkdir -p "$TEST_DIR" +if "$BRAND_BOOK" init "$TEST_DIR/mybrand" --name "Acme Corp" > /dev/null 2>&1; then + green "init scaffolds brand directory" +else + red "init failed" +fi + +# 3. Init creates 7 template files +COUNT=$(ls "$TEST_DIR/mybrand/"*.md 2>/dev/null | wc -l | tr -d ' ') +if [ "$COUNT" -eq 7 ]; then + green "init creates 7 template files (got: $COUNT)" +else + red "init created $COUNT files, expected 7" +fi + +# 4. Validate a template +if "$BRAND_BOOK" validate "$TEST_DIR/mybrand/strategy.md" > /dev/null 2>&1; then + green "validate runs on strategy template" +else + red "validate failed on strategy template" +fi + +# 5. Validate with --strict +if "$BRAND_BOOK" validate --strict "$TEST_DIR/mybrand/brand-card.md" > /dev/null 2>&1; then + green "validate --strict runs on brand-card" +else + red "validate --strict failed" +fi + +# 6. Compile brand card +OUTPUT=$("$BRAND_BOOK" compile "$TEST_DIR/mybrand" --artifact brand-card 2>/dev/null) +if [ -n "$OUTPUT" ]; then + green "compile --artifact brand-card produces output (${#OUTPUT} chars)" +else + red "compile brand-card produced empty output" +fi + +# 7. Compile full brand book +OUTPUT=$("$BRAND_BOOK" compile "$TEST_DIR/mybrand" --artifact full 2>/dev/null) +if [ -n "$OUTPUT" ]; then + green "compile --artifact full produces output (${#OUTPUT} chars)" +else + red "compile full produced empty output" +fi + +# 8. Compile with --output +OUTFILE="$TEST_DIR/compiled.md" +"$BRAND_BOOK" compile "$TEST_DIR/mybrand" --artifact full --output "$OUTFILE" > /dev/null 2>&1 +if [ -f "$OUTFILE" ]; then + green "compile --output writes to file" +else + red "compile --output did not create file" +fi + +# 9. Preview +OUTPUT=$("$BRAND_BOOK" preview "$TEST_DIR/mybrand/strategy.md" 2>/dev/null) +if [ -n "$OUTPUT" ]; then + green "preview produces output" +else + red "preview produced empty output" +fi + +# 10. Preview with --json +OUTPUT=$("$BRAND_BOOK" preview --json "$TEST_DIR/mybrand/strategy.md" 2>/dev/null) +if echo "$OUTPUT" | python3 -m json.tool > /dev/null 2>&1; then + green "preview --json produces valid JSON" +else + red "preview --json is not valid JSON" +fi + +# 11. Validate with --json +OUTPUT=$("$BRAND_BOOK" validate --json "$TEST_DIR/mybrand/visual-id.md" 2>/dev/null) +if echo "$OUTPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); assert 'issues' in d; assert 'count' in d" > /dev/null 2>&1; then + green "validate --json produces valid JSON with issues and count" +else + red "validate --json format incorrect" +fi + +# 12. Re-init on existing dir fails +mkdir -p "$TEST_DIR/nonempty" +touch "$TEST_DIR/nonempty/existing.txt" +if "$BRAND_BOOK" init "$TEST_DIR/nonempty" --name "Test" > /dev/null 2>&1; then + red "init on non-empty directory should have failed" +else + green "init rejects non-empty directory" +fi + +echo "" +echo "=== Results: $PASS passed, $FAIL failed ===" +[ "$FAIL" -eq 0 ] || exit 1 diff --git a/brand-designer/scripts/generate b/brand-designer/scripts/generate new file mode 100644 index 0000000..cfb15fe --- /dev/null +++ b/brand-designer/scripts/generate @@ -0,0 +1,309 @@ +#!/usr/bin/env python3 +""" +generate — Brand-compliant image generation script. + +Produces brand card images, palette swatch cards, application mockups, +and mood boards. Reads brand data from compiled brand directories +or individual templates. Designed to be reference-image-aware, following +the pattern from nous-branding/groktopus-branding. + +Environment variables (optional — if set, LLM-enhanced features activate): + BRAND_DESIGNER_LLM_URL — OpenAI-compatible API endpoint + BRAND_DESIGNER_LLM_KEY — API key for the above + +Subcommands: + brand-card — Generate the primary brand card image + mockup — Generate application mockups + swatch — Generate color palette visualization + moodboard — Generate mood/theme board + logo-bg — Generate logo on different backgrounds +""" + +import argparse +import json +import os +import sys +import textwrap +from pathlib import Path + + +def load_brand_data(brand_dir): + """Load frontmatter from a compiled brand directory.""" + data = {} + brand_dir = Path(brand_dir) + if not brand_dir.exists(): + return data + + # Try to load from individual template files + for tmpl_name in ['strategy', 'visual-id', 'voice']: + tmpl_path = brand_dir / f"{tmpl_name}.md" + if tmpl_path.exists(): + # Parse frontmatter + text = tmpl_path.read_text() + import re + match = re.match(r'^---\n(.*?)\n---\n(.*)', text, re.DOTALL) + if match: + try: + import yaml + fm = yaml.safe_load(match.group(1)) + if isinstance(fm, dict): + data[tmpl_name] = fm + except ImportError: + pass + + return data + + +def colors_to_prompt(data): + """Build a color description from brand data for use in image prompts.""" + visual = data.get('visual-id', {}) + colors = visual.get('colors', {}) + + color_parts = [] + for palette_name in ['primary', 'secondary']: + palette = colors.get(palette_name, []) + for c in palette: + name = c.get('name', '') + hex_val = c.get('hex', '') + if name and hex_val: + color_parts.append(f"{name} #{hex_val}") + + return "; ".join(color_parts) if color_parts else "" + + +def personality_to_prompt(data): + """Build a brand personality description for image prompts.""" + strategy = data.get('strategy', {}) + personality = strategy.get('personality', []) + + traits = [] + for p in personality if isinstance(personality, list) else []: + if isinstance(p, dict) and p.get('axis') and p.get('value', 0) >= 3: + traits.append(p['axis']) + + return ", ".join(traits) if traits else "" + + +def prompt_brand_card(data, layout="landscape"): + """Construct a prompt for the brand card image.""" + strategy = data.get('strategy', {}) + visual = data.get('visual-id', {}) + voice_data = data.get('voice', {}) + + brand_name = strategy.get('brand', visual.get('brand', 'Your Brand')) + tagline = strategy.get('tagline', '') + color_desc = colors_to_prompt(data) + personality_desc = personality_to_prompt(data) + + # Get typography name + typography = visual.get('typography', {}) + primary_type = '' + if isinstance(typography, dict): + primary = typography.get('primary', {}) + if isinstance(primary, dict): + primary_type = primary.get('family', '') + + # Build the prompt + orientation = "horizontal 16:9" if layout == "landscape" else "vertical 4:5" + + prompt = textwrap.dedent(f"""\ + Professional brand card for "{brand_name}", {orientation} format. + Clean, minimalist design with: + - Large prominent brand name "{brand_name}" {'with tagline: "' + tagline + '"' if tagline else ''} + - Color palette swatches: {color_desc or "professional corporate palette"} + - Brand typeface specimen showing "{primary_type or "clean sans-serif"}" typography + {'- Brand personality: ' + personality_desc if personality_desc else ''} + - Clean white or light background with subtle brand accent + - Elegant layout suitable for press kit or brand portal + No photorealistic people. Design-system mockup style, not a photograph. + """) + + return prompt.strip() + + +def prompt_mockup(data, mockup_type="stationery"): + """Construct a prompt for a brand application mockup.""" + color_desc = colors_to_prompt(data) + strategy = data.get('strategy', {}) + + scene_descriptions = { + "stationery": "business cards, letterhead, and envelope set on a wooden desk, top-down flat lay", + "social": "social media post mockup on a smartphone screen with brand-colored UI elements", + "signage": "storefront sign or exterior building signage with brand logo, photorealistic architectural context", + "digital": "laptop and tablet displaying brand website or app interface, mockup style", + } + + scene = scene_descriptions.get(mockup_type, scene_descriptions["stationery"]) + + prompt = textwrap.dedent(f"""\ + Brand application mockup for {strategy.get('brand', 'a brand')}. + {scene}. + Brand colors: {color_desc or "professional corporate colors"}. + Clean, professional product photography style. + Subtle branding, not overwhelming. Show the brand in context. + """).strip() + + return prompt + + +# --- Subcommand handlers --- + +def cmd_brand_card(args): + data = load_brand_data(args.brand_dir) + prompt = prompt_brand_card(data, layout=args.layout) + if args.json: + print(json.dumps({"prompt": prompt, "model": "image-gen", "layout": args.layout})) + else: + print(f"=== Brand Card Prompt ({args.layout}) ===") + print(prompt) + print() + print("To generate: pipe this prompt to your preferred image generation tool.") + print("For reference-image-aware generation, include brand logo and palette card") + print("as reference images alongside this prompt.") + + +def cmd_mockup(args): + data = load_brand_data(args.brand_dir) + prompt = prompt_mockup(data, mockup_type=args.type) + if args.json: + print(json.dumps({"prompt": prompt, "model": "image-gen", "type": args.type})) + else: + print(f"=== Mockup Prompt ({args.type}) ===") + print(prompt) + print() + print("To generate: pipe to image generation tool.") + print("Best results with reference image of brand logo and/or color palette.") + + +def cmd_swatch(args): + data = load_brand_data(args.brand_dir) + visual = data.get('visual-id', {}) + colors = visual.get('colors', {}) + + prompt = "Color palette visualization card. Professional swatch layout showing:\n\n" + for palette_name in ['primary', 'secondary', 'neutral']: + palette = colors.get(palette_name, []) + if not palette: + continue + prompt += f"{palette_name.title()} palette:\n" + for c in palette: + name = c.get('name', '') + hex_val = c.get('hex', '') + if name and hex_val: + prompt += f" - {name}: #{hex_val}\n" + prompt += "\n" + + if not colors: + prompt += "(No brand colors loaded — add a visual-id.md template with palette data)\n" + + if args.json: + print(json.dumps({"prompt": prompt, "model": "image-gen"})) + else: + print("=== Swatch Card Prompt ===") + print(prompt) + print("To generate: pipe prompt to image generation tool.") + print("Include brand color reference card as reference image for accurate matching.") + + +def cmd_moodboard(args): + data = load_brand_data(args.brand_dir) + prompt = persona = personality_to_prompt(data) + strategy = data.get('strategy', {}) + theme = args.theme or "brand identity" + + full_prompt = textwrap.dedent(f"""\ + Mood board for {theme} theme. + Brand personality: {persona or "professional, modern"}. + Brand: {strategy.get('brand', 'a brand')}. + {strategy.get('positioning', {}).get('differentiator', '')} + + Collage-style layout with textures, color fields, typography samples, + and atmospheric imagery that captures the brand's essence. + Artistic, inspirational. Not a product mockup. + """).strip() + + if args.json: + print(json.dumps({"prompt": full_prompt})) + else: + print(f"=== Moodboard Prompt ({theme}) ===") + print(full_prompt) + print() + print("Best with reference images of brand logo, palette, and existing brand materials.") + + +def cmd_logo_bg(args): + data = load_brand_data(args.brand_dir) + color_desc = colors_to_prompt(data) + bg_type = args.background or "light" + + prompt = textwrap.dedent(f"""\ + Brand logo presentation on {bg_type} background. + Clean, professional showcase of a logo mark. + Background: {bg_type} solid or subtle gradient. + Logo colors: {color_desc or "brand signature color"}. + Minimal, elegant. Product photography style. + No text except the logo itself. Centered composition. + """).strip() + + if args.json: + print(json.dumps({"prompt": prompt})) + else: + print(f"=== Logo Presentation Prompt ({bg_type} background) ===") + print(prompt) + print() + print("Best with the actual brand logo as a reference image.") + + +# --- Main CLI --- + +def main(): + parser = argparse.ArgumentParser( + description="Brand-compliant image generation", + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument('--brand-dir', '-d', default='.', + help='Brand directory with template files') + parser.add_argument('--json', action='store_true', + help='Output as JSON (machine-readable prompt)') + + subparsers = parser.add_subparsers(dest='command') + + # brand-card + bc = subparsers.add_parser('brand-card', help='Generate brand card image') + bc.add_argument('--layout', choices=['portrait', 'landscape'], default='landscape') + + # mockup + mk = subparsers.add_parser('mockup', help='Generate application mockup') + mk.add_argument('--type', choices=['stationery', 'social', 'signage', 'digital'], + default='stationery') + + # swatch + subparsers.add_parser('swatch', help='Generate palette visualization') + + # moodboard + mb = subparsers.add_parser('moodboard', help='Generate mood/theme board') + mb.add_argument('--theme', help='Theme or subject for the mood board') + + # logo-bg + lb = subparsers.add_parser('logo-bg', help='Generate logo presentation') + lb.add_argument('variant', help='Logo variant name') + lb.add_argument('--background', choices=['light', 'dark', 'gradient'], default='light') + + args = parser.parse_args() + + if args.command == 'brand-card': + cmd_brand_card(args) + elif args.command == 'mockup': + cmd_mockup(args) + elif args.command == 'swatch': + cmd_swatch(args) + elif args.command == 'moodboard': + cmd_moodboard(args) + elif args.command == 'logo-bg': + cmd_logo_bg(args) + else: + parser.print_help() + + +if __name__ == '__main__': + main() diff --git a/brand-designer/templates/application.md b/brand-designer/templates/application.md new file mode 100644 index 0000000..f89e262 --- /dev/null +++ b/brand-designer/templates/application.md @@ -0,0 +1,90 @@ +--- +type: brand-application-template +name: Application Guidelines Template +description: >- + Document how the brand is applied across channels and media. Covers digital, + print, social, co-branding, and file format delivery. For brands appearing + on 3+ channels. +--- + +# Application Guidelines: {{brand}} + +> **Visual reference:** See [[{{Brand Name}} Visual Identity]] for the colors, typography, and logo assets used in these applications. + +## Digital Applications + +### Social Media + +| Platform | Dimensions | Format | Template | +|----------|------------|--------|----------| +| Instagram (post) | 1080×1080 px | PNG/JPG | `{{path/template-insta.png}}` | +| Instagram (story) | 1080×1920 px | PNG/JPG | `{{path/template-story.png}}` | +| LinkedIn (post) | 1200×628 px | PNG/JPG | `{{path/template-linkedin.png}}` | +| Twitter/X | 1200×675 px | PNG/JPG | `{{path/template-x.png}}` | +| Facebook | 1200×630 px | PNG/JPG | `{{path/template-fb.png}}` | + +### Email + +| Element | Spec | +|---------|------| +| Max width | `{{600}}`px | +| Styling | {{Inline CSS}} | +| Header | {{path/email-header.png}} | +| Footer | {{path/email-footer.png}} | + +### Website Elements + +| Element | Specification | +|---------|---------------| +| Navigation bar | Primary color background, white text | +| Buttons (primary) | Accent color, 8px radius, 48px min height | +| Buttons (secondary) | Outlined, 2px stroke, transparent fill | +| Links | Primary color, underline on hover | +| Forms | Light gray border, 4px radius, 12px padding | + +## Print Applications + +| Item | Dimensions | Colors | Bleed | Template | +|------|------------|--------|-------|----------| +| Business card | 3.5×2 in / 85×55 mm | 4/4 CMYK | 3mm | `{{path/business-card.ai}}` | +| Letterhead | 8.5×11 in / A4 | 1-color logo | None | `{{path/letterhead.ai}}` | +| Presentation deck | 16:9 (1920×1080) | RGB | None | `{{path/deck.pptx}}` | + +## Co-branding + +### Rules + +- Partner logo must be **equal or smaller** in visual weight +- Minimum clear space: **1×** the partner's logo height on all sides +- Partner logo should be in black, white, or their primary brand color +- Do not lock up partner logo with the {{brand}} logo in a fixed relationship unless approved + +### Acceptable Examples + +{{Include visual examples of correct co-branding}} + +### Unacceptable Examples + +{{Include visual examples of incorrect co-branding}} + +## File Format Delivery + +| Format | When to Use | +|--------|-------------| +| **SVG** | Web, digital interfaces, scalable vector graphics | +| **EPS** | Print production, professional design software | +| **PNG** | Office documents, social media, web (when SVG not supported) | +| **PDF** | Print-ready files, client delivery, documentation | +| **JPG** | Photography, social media, web imagery | +| **FIG** | Figma-based design and prototyping | +| **AI** | Adobe Illustrator source editing | +| **PSD** | Adobe Photoshop layered compositions | +| **TTF/WOFF2** | Font distribution for desktop/web | + +## Motion Principles (optional) + +| Element | Duration | Easing | Notes | +|---------|----------|--------|-------| +| Micro-interactions | `{{200-400ms}}` | `{{ease-in-out}}` | UI feedback | +| Logo animation | `{{1-2s}}` | `{{ease-out}}` | Video intros | +| Page transitions | `{{300ms}}` | `{{ease}}` | Web/app navigation | diff --git a/brand-designer/templates/asset-inventory.md b/brand-designer/templates/asset-inventory.md new file mode 100644 index 0000000..99005c6 --- /dev/null +++ b/brand-designer/templates/asset-inventory.md @@ -0,0 +1,82 @@ +--- +type: brand-asset-inventory-template +name: Brand Asset Inventory Template +description: >- + Structured index of every brand asset. Fill in rows as you create assets. + Each row documents the file's name, formats, location, usage context, + last update date, and owner. +--- + +# Asset Inventory: {{brand}} + +> Maintained by: {{Brand Steward Name}} +> Last updated: {{YYYY-MM-DD}} + +## Logo Files + +| Asset | Formats | Path | Usage | Updated | Owner | +|-------|---------|------|-------|---------|-------| +| Primary Logo (color) | SVG, PNG, EPS | `/assets/logos/primary/` | Web, print, social | | Design | +| Primary Logo (reversed) | SVG, PNG, EPS | `/assets/logos/primary/reversed/` | Dark backgrounds | | Design | +| Primary Logo (black) | SVG, EPS | `/assets/logos/primary/monochrome/` | 1-color print | | Design | +| Secondary Logo (stacked) | SVG, PNG | `/assets/logos/secondary/` | Square spaces | | Design | +| Icon / Symbol | SVG, PNG | `/assets/logos/icon/` | Favicon, avatars | | Design | +| Favicon | ICO, PNG | `/assets/logos/favicon/` | Browser tab | | Design | +| App icon | PNG | `/assets/logos/app-icon/` | Mobile apps | | Design | + +## Color & Typography + +| Asset | Formats | Path | Usage | Updated | Owner | +|-------|---------|------|-------|---------|-------| +| Color palette (ASE) | ASE, PDF | `/assets/color/` | Design tools | | Design | +| Color reference card | PDF, PNG | `/assets/color/` | Quick reference | | Design | +| Typeface files (Brand Sans) | WOFF2, TTF | `/assets/fonts/` | Web, desktop | | Design | +| Typeface files (Brand Serif) | WOFF2, TTF | `/assets/fonts/` | Web, desktop | | Design | + +## Icon & Illustration Libraries + +| Asset | Formats | Count | Path | Updated | Owner | +|-------|---------|-------|------|---------|-------| +| Core icon set | SVG | {{24}} | `/assets/icons/` | | Design | +| Illustration library | SVG, PNG | {{}} | `/assets/illustrations/` | | Design | + +## Photography + +| Asset | Source | License | Path | Updated | Owner | +|-------|--------|---------|------|---------|-------| +| Headshot library | Commissioned | Full rights | `/assets/photography/headshots/` | | Design | +| Product photography | In-house | Full rights | `/assets/photography/product/` | | Design | +| Stock photo library | {{Source}} | {{License}} | `/assets/photography/stock/` | | Marketing | + +## Templates + +| Asset | Tool | Path | Updated | Owner | +|-------|------|------|---------|-------| +| Social media templates | Figma | `/assets/templates/social/` | | Design | +| Email templates | HTML | `/assets/templates/email/` | | Marketing | +| Slide deck | Keynote | `/assets/templates/deck/` | | Design | +| Business card | AI | `/assets/templates/print/` | | Design | +| Letterhead | AI | `/assets/templates/print/` | | Design | + +## Video & Motion + +| Asset | Duration | Format | Path | Updated | Owner | +|-------|----------|--------|------|---------|-------| +| Logo animation | {{5s}} | MP4, MOV | `/assets/video/logo-anim/` | | Design | +| Brand video | {{30s}} | MP4 | `/assets/video/brand/` | | Marketing | + +## Documentation + +| Asset | Format | Path | Updated | Owner | +|-------|--------|------|---------|-------| +| Brand Card | MD, PNG | `/docs/brand/card/` | | Brand Steward | +| Strategy Memo | MD | `/docs/brand/strategy/` | | Brand Steward | +| Visual Identity Spec | MD | `/docs/brand/visual-id/` | | Design | +| Voice Guidelines | MD | `/docs/brand/voice/` | | Brand Steward | +| Application Guidelines | MD | `/docs/brand/application/` | | Design | +| Governance Framework | MD | `/docs/brand/governance/` | | Brand Steward | +| Compiled Brand Book | MD, HTML | `/docs/brand/book/` | | Brand Steward | + +--- + +*All brand documentation is versioned. See [[{{Brand Name}} Governance]] for the versioning scheme.* diff --git a/brand-designer/templates/brand-card.md b/brand-designer/templates/brand-card.md new file mode 100644 index 0000000..a526e78 --- /dev/null +++ b/brand-designer/templates/brand-card.md @@ -0,0 +1,62 @@ +--- +type: brand-card-template +name: Brand Card Template +description: >- + Single-page brand card template. Fill this to produce a condensed visual and + textual summary of your brand. Sources from your other brand templates via + the `source` frontmatter field. When complete, run `generate brand-card` + to produce the image version. +--- + +# Brand Card: {{brand}} + +Replace the sections below with your brand's information. + +## Brand Name & Tagline + +**Brand Name:** `{{your brand name}}` +**Tagline:** `{{your tagline}}` + +## Logo + +*Reference your primary logo file. See [[{{Brand Name}} Visual Identity]] for all variants.* + +| Variant | File | Usage | +|---------|------|-------| +| Primary (color) | {{path/logo.svg}} | Light backgrounds | +| Primary (reversed) | {{path/logo-white.svg}} | Dark backgrounds | +| Icon | {{path/icon.svg}} | Social avatars, favicon | + +## Color Palette + +| Swatch | Name | HEX | +|--------|------|-----| +| {{color box placeholder}} | {{Primary Color Name}} | `#{{hex}}` | +| {{color box placeholder}} | {{Secondary Color Name}} | `#{{hex}}` | +| {{color box placeholder}} | {{Accent Color Name}} | `#{{hex}}` | +| {{color box placeholder}} | {{Neutral Color Name}} | `#{{hex}}` | + +*Full palette with RGB, CMYK, Pantone values in [[{{Brand Name}} Visual Identity]].* + +## Typography + +| Role | Typeface | Weights | Fallback | +|------|----------|---------|----------| +| Display / Headlines | {{Primary Typeface}} | {{weights}} | {{fallback}} | +| Body | {{Secondary Typeface}} | {{weights}} | {{fallback}} | + +## Brand Personality + +{{keyword}}, {{keyword}}, {{keyword}}, {{keyword}} + +*Full personality profile in [[{{Brand Name}} Strategy]].* + +## Voice + +{{Short description of brand voice — e.g., "Confident, clear, and human."}} + +*Full voice guidelines in [[{{Brand Name}} Voice]].* + +--- + +*Generated from [[{{Brand Name}} Strategy]], [[{{Brand Name}} Visual Identity]], [[{{Brand Name}} Voice]].* diff --git a/brand-designer/templates/governance.md b/brand-designer/templates/governance.md new file mode 100644 index 0000000..9e22b79 --- /dev/null +++ b/brand-designer/templates/governance.md @@ -0,0 +1,79 @@ +--- +type: brand-governance-template +name: Brand Governance Framework Template +description: >- + Define how the brand is maintained, versioned, and evolved. Covers version + numbering, stewardship, review cadence, exception process, changelog, and + archive policy. Essential for scaling brands with multiple contributors. +--- + +# Brand Governance: {{brand}} + +## Version Numbering + +**Scheme:** `MAJOR.MINOR.PATCH` + +| Bump | When | Example | +|------|------|---------| +| **MAJOR** | Complete brand redesign (logo change, new palette, new type) | `1.0.0` → `2.0.0` | +| **MINOR** | Palette expansion, typeface addition, new logo variant | `1.0.0` → `1.1.0` | +| **PATCH** | Documentation fix, example update, typo correction | `1.0.0` → `1.0.1` | + +**Current version:** `{{1.0.0}}` + +## Brand Steward + +| Field | Value | +|-------|-------| +| **Owner** | {{Name}} | +| **Role** | {{Title}} | +| **Contact** | {{email@example.com}} | + +The brand steward is the single point of accountability for brand consistency. +All exception requests route through this person. + +## Review Cadence + +| Cadence | Activity | +|---------|----------| +| **{{Quarterly}}** | {{Scheduled comprehensive review}} | +| **{{Annually}}** | {{Full brand audit across all channels}} | + +### Trigger Events (off-cycle review) + +- Logo refresh or evolution +- Merger, acquisition, or rebranding +- New product launch with distinct sub-brand +- Market expansion into new region/culture +- Consistent brand drift detected in audit + +## Exception Process + +When a team needs to deviate from brand guidelines: + +1. **Submit** — Fill out the exception request form detailing the deviation, rationale, and duration +2. **Review** — Brand steward evaluates within {{5}} business days +3. **Approve/Deny** — Approved exceptions are logged with expiration date; denied requests get alternative guidance +4. **Log** — All exceptions recorded in changelog for quarterly review + +**Approval chain:** +- Standard exceptions → Brand steward +- High-visibility exceptions (homepage, major campaign) → Brand steward + VP Marketing + +## Changelog + +| Date | Version | Change | Author | +|------|---------|--------|--------| +| {{YYYY-MM-DD}} | {{0.1.0}} | {{Initial brand identity documentation}} | {{Name}} | +| {{YYYY-MM-DD}} | {{1.0.0}} | {{First published version}} | {{Name}} | +| | | | | + +## Archive Policy + +- **Retention:** Current version + {{2}} previous major versions +- **Disposal:** Archived assets moved to `/archive/` directory +- **Access:** Archived versions still accessible via changelog but clearly marked as superseded + +--- + +*This governance framework documents how [[{{Brand Name}}]] is maintained. See [[{{Brand Name}} Asset Inventory]] for the file index.* diff --git a/brand-designer/templates/strategy.md b/brand-designer/templates/strategy.md new file mode 100644 index 0000000..1cec222 --- /dev/null +++ b/brand-designer/templates/strategy.md @@ -0,0 +1,69 @@ +--- +type: brand-strategy-template +name: Brand Strategy Memo Template +description: >- + Document the "why" behind your brand. Fill in positioning, personality, + mission, values, audience, and competitive landscape. This template + informs your visual identity and voice decisions. +--- + +# Brand Strategy: {{brand}} + +## Positioning Statement + +**Target Audience:** +{{Who you serve — be specific}} + +**Key Differentiator:** +{{What makes you unique in the market}} + +**Market Category:** +{{The category you compete in}} + +**Positioning Statement (one sentence):** +> For {{target audience}}, {{brand}} is the {{market category}} that {{differentiator}}. + +## Brand Personality + +Rate your brand on each axis (1-5): + +| Axis | Score (1-5) | Description | +|------|-------------|-------------| +| **Sincere** (honest, genuine, cheerful) | | | +| **Exciting** (daring, spirited, imaginative) | | | +| **Competent** (reliable, intelligent, successful) | | | +| **Sophisticated** (glamorous, charming, smooth) | | | +| **Rugged** (tough, strong, outdoorsy) | | | + +*Note: A brand is typically strong on 2-3 axes, not all 5.* + +## Mission & Vision + +**Mission** (what you do every day): +{{Core mission statement — 1-2 sentences}} + +**Vision** (the future you're building toward): +{{Long-term vision — 1-2 sentences}} + +## Core Values + +| Value | What It Means in Practice | +|-------|--------------------------| +| {{Value 1}} | {{Description}} | +| {{Value 2}} | {{Description}} | +| {{Value 3}} | {{Description}} | + +## Competitive Landscape + +| Competitor | Their Position | Our Differentiator | +|------------|---------------|-------------------| +| {{Competitor 1}} | {{Position}} | {{How we differ}} | +| {{Competitor 2}} | {{Position}} | {{How we differ}} | + +## Target Audience + +**Primary Audience:** {{Persona name}} +{{Demographic and psychographic description}} + +**Secondary Audience:** {{Persona name}} +{{Demographic and psychographic description}} diff --git a/brand-designer/templates/visual-id.md b/brand-designer/templates/visual-id.md new file mode 100644 index 0000000..d2614dc --- /dev/null +++ b/brand-designer/templates/visual-id.md @@ -0,0 +1,171 @@ +--- +type: brand-visual-identity-template +name: Visual Identity Spec Template +description: >- + Complete documentation of your brand's visual system. Fill in logo variants, + color values in all spaces, typography scale, iconography, photography, + and illustration style. This is the primary reference for designers and + developers. +--- + +# Visual Identity: {{brand}} + +> **Strategy reference:** See [[{{Brand Name}} Strategy]] for the positioning and personality that drive these visual decisions. + +## Logo System + +### Logo Variants + +| Variant | Preview | File (SVG) | File (PNG) | Min Width | Usage | +|---------|---------|------------|------------|-----------|-------| +| Primary (color) | | `logo.svg` | `logo.png` | `{{100px}}` | Light backgrounds | +| Secondary (stacked) | | `logo-stacked.svg` | `logo-stacked.png` | `{{80px}}` | Square spaces | +| Icon only | | `icon.svg` | `icon.png` | `{{24px}}` | Favicon, avatars | + +### Monochrome Variants + +- **Black:** `logo-black.svg` — for 1-color print, dark-on-light +- **White:** `logo-white.svg` — for dark backgrounds +- **Grayscale:** `logo-gray.svg` — for limited-color applications + +### Clear Space + +Minimum empty area around logo: **{{0.25}}×** the height of the logo on all sides. + +*Any text or graphic within this zone weakens the logo's visual impact.* + +### Minimum Reproduction Size + +| Medium | Size | +|--------|------| +| Print | `{{15}}` mm | +| Screen | `{{32}}` px | +| Social avatar | `{{48}}` px | + +### Approved Backgrounds + +| Background Type | Logo Variant to Use | +|----------------|-------------------| +| Light solid (#FFFFFF - #CCCCCC) | Primary color | +| Dark solid (#333333 - #000000) | White reversed | +| Photography (even toned) | White reversed | +| Photography (busy) | Avoid — use solid | + +### Incorrect Usage + +> Do **not** stretch, recolor, add effects, rotate, or change the logo in any way. Use only provided files. + +| Incorrect | Why | +|-----------|-----| +| {{Screenshot placeholder}} | Do not stretch the logo | +| {{Screenshot placeholder}} | Do not change logo colors | +| {{Screenshot placeholder}} | Do not add drop shadows or outlines | +| {{Screenshot placeholder}} | Do not place on busy backgrounds | + +## Color Palette + +### Primary Colors + +| Name | Swatch | HEX | RGB | CMYK | Pantone | Usage | +|------|--------|-----|-----|------|---------|-------| +| {{Brand Blue}} | | `#{{hex}}` | `{{r g b}}` | `{{c m y k}}` | `{{code}}` | Primary brand elements | +| {{Brand Red}} | | `#{{hex}}` | `{{r g b}}` | `{{c m y k}}` | `{{code}}` | Accent highlights | + +### Secondary Colors + +| Name | Swatch | HEX | RGB | CMYK | Usage | +|------|--------|-----|-----|------|-------|-------| +| {{Accent Green}} | | `#{{hex}}` | `{{r g b}}` | `{{c m y k}}` | CTA buttons | +| {{Accent Yellow}} | | `#{{hex}}` | `{{r g b}}` | `{{c m y k}}` | Notifications | + +### Functional Colors (UI) + +| Role | Name | Swatch | HEX | Contrast on White | +|------|------|--------|-----|-------------------| +| Success | {{Green}} | | `#{{hex}}` | {{ratio}}:1 | +| Error | {{Red}} | | `#{{hex}}` | {{ratio}}:1 | +| Warning | {{Yellow}} | | `#{{hex}}` | {{ratio}}:1 | +| Info | {{Blue}} | | `#{{hex}}` | {{ratio}}:1 | + +### Neutral Palette + +| Name | Swatch | HEX | Usage | +|------|--------|-----|-------| +| Off Black | | `#{{hex}}` | Body text | +| Dark Gray | | `#{{hex}}` | Secondary text | +| Medium Gray | | `#{{hex}}` | Borders, dividers | +| Light Gray | | `#{{hex}}` | Backgrounds | +| Off White | | `#{{hex}}` | Page backgrounds | + +### Dark Mode (optional) + +| Token | Light Value | Dark Value | +|-------|-------------|------------| +| Background | `#FFFFFF` | `#{{hex}}` | +| Text Primary | `#{{hex}}` | `#FFFFFF` | +| {{Token}} | `#{{hex}}` | `#{{hex}}` | + +## Typography + +### Typefaces + +| Role | Typeface | Weights | Fallback | License | +|------|----------|---------|----------|---------| +| Display/Headlines | {{Primary Typeface}} | {{300, 400, 600, 700}} | {{system stack}} | {{license}} | +| Body | {{Secondary Typeface}} | {{400, 600}} | {{system stack}} | {{license}} | +| Code (if applicable) | {{Mono Typeface}} | {{400}} | {{mono stack}} | {{license}} | + +### Type Scale + +| Level | Size | Line Height | Tracking | Usage | +|-------|------|-------------|----------|-------| +| **H1** | `{{48}}px` | `{{1.2}}` | `{{-0.02em}}` | Page titles | +| **H2** | `{{36}}px` | `{{1.3}}` | `{{-0.01em}}` | Section headers | +| **H3** | `{{24}}px` | `{{1.4}}` | `{{0}}` | Subsection headers | +| **Body** | `{{16}}px` | `{{1.6}}` | `{{0}}` | Paragraphs | +| **Caption** | `{{12}}px` | `{{1.4}}` | `{{0.01em}}` | Image captions, footnotes | + +### Web Font Stack + +``` +{{Primary Typeface}}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif +``` + +## Iconography (optional) + +| Property | Value | +|----------|-------| +| Style | {{outlined / filled}} | +| Stroke weight | `{{1.5}}`px | +| Corner radius | `{{2}}`px | +| Grid size | `{{24}}`×`{{24}}` | +| Min touch target | `{{44}}`px | + +## Photography & Imagery (optional) + +### Visual Narrative + +{{Describe the photographic style: subject matter, mood, lighting, color treatment}} + +### Framing Rules + +- {{Rule 1: e.g., "Subjects should be in natural settings, not studios"}} +- {{Rule 2: e.g., "Use negative space for copy overlay"}} + +### Diversity Standards + +{{Representation guidelines for photography}} + +### Avoid + +- {{Anti-pattern 1: "Generic stock photography of people in business suits shaking hands"}} +- {{Anti-pattern 2: "Overly filtered or faux-vintage looks"}} + +## Illustration Style (optional) + +| Property | Value | +|----------|-------| +| Style | {{Description, e.g., "Flat vector, geometric, 2-color"}} | +| Detail level | {{1-5 scale}} | +| Tone | {{Whimsical, technical, serious, etc.}} | +| Allowed palette | {{Referenced from color palette above}} | diff --git a/brand-designer/templates/voice.md b/brand-designer/templates/voice.md new file mode 100644 index 0000000..62c9bb5 --- /dev/null +++ b/brand-designer/templates/voice.md @@ -0,0 +1,99 @@ +--- +type: brand-voice-template +name: Voice & Messaging Guidelines Template +description: >- + Document how your brand sounds. Define voice attributes, map tone by + context, set vocabulary rules, and provide before/after copy examples. + Essential for anyone writing for your brand. +--- + +# Voice & Messaging: {{brand}} + +> **Strategy reference:** See [[{{Brand Name}} Strategy]] for the personality traits that inform this voice. + +## Voice Attributes + +Define 3-5 voice attributes. Each should be a single word followed by a short description of what it means in practice. + +| Attribute | What It Means | +|-----------|---------------| +| **{{Confident}}** | {{Speaks with authority, not arrogance. Uses declarative statements.}} | +| **{{Clear}}** | {{Prefer the direct word over the impressive one. One idea per sentence.}} | +| **{{Human}}** | {{Warm, conversational. Writes like a person, not a corporation.}} | +| **{{}}** | {{}} | +| **{{}}** | {{}} | + +## Tone Matrix + +Tone shifts based on context and audience. Fill in how your brand adapts: + +| Context | Audience | Tone | Example | +|---------|----------|------|---------| +| Landing page | New visitors | {{Welcoming, benefit-focused}} | {{}} | +| Product copy | Active users | {{Helpful, precise}} | {{}} | +| Error message | Frustrated user | {{Apologetic, solution-first}} | {{}} | +| Social media | Followers | {{Playful, brief}} | {{}} | +| Customer support | Existing customer | {{Empathetic, direct}} | {{}} | +| Internal comms | Employees | {{Transparent, casual}} | {{}} | +| Press release | Media | {{Factual, restrained}} | {{}} | + +## Messaging Pillars + +The core message categories your brand consistently communicates. + +| Pillar | Description | Example Headline | +|--------|-------------|-----------------| +| {{Innovation}} | {{We push boundaries}} | {{"The future of X is here"}} | +| {{Trust}} | {{We're reliable}} | {{"Built to last"}} | +| {{}} | {{}} | {{}} | + +## Vocabulary + +### Approved Words & Phrases + +Use these consistently: + +- {{we / our}} — first-person inclusive +- {{you / your}} — direct address the customer +- {{}} +- {{}} + +### Words to Avoid + +Do not use these: + +| Word | Instead Use | +|------|-------------| +| leverage | use | +| synergize | work together | +| utilize | use | +| empower | help / enable | +| {{}} | {{}} | + +## Copy Examples + +Before/after pairs show the voice in action. + +### Headlines + +| Before (off voice) | After (on voice) | +|-------------------|-----------------| +| {{"Leverage our platform to optimize workflows"}} | {{"Get more done, faster"}} | +| {{}} | {{}} | + +### Error Messages + +| Before | After | +|--------|-------| +| {{"The requested resource was not found (404)"}} | {{"Hmm, that page wandered off. Let's get you back."}} | +| {{"An unexpected error occurred"}} | {{"Something went wrong — we're on it. Try again in a moment."}} | + +### Social Media + +| Before | After | +|--------|-------| +| {{}} | {{}} | + +## Localization Notes + +{{Cross-market adaptation rules, if applicable.}}