brandspec 0.1.0

package/workshop/phases/02-concept.md

@@ -0,0 +1,234 @@
+# Phase 2: Concept
+
+## Goal
+
+Define the brand's personality, voice, and verbal identity.
+
+**Spec reference:** Read `../../schema/spec/core.md` for core field definitions, voice structure, and what belongs in `core` vs `guidelines` vs `extensions`.
+
+## Steps
+
+### 2.1 Personality
+
+**Questions to answer:**
+
+- If the brand were a person, how would you describe them?
+- What 3-5 adjectives capture the brand?
+- What should users feel when interacting with the brand?
+
+**Facilitation approach:**
+
+Present contrasting pairs and ask user to choose:
+
+```
+Where does your brand fall?
+
+Formal ←───────→ Casual
+Traditional ←───────→ Innovative  
+Serious ←───────→ Playful
+Reserved ←───────→ Bold
+Expert ←───────→ Friendly
+```
+
+**Output: Personality Traits**
+
+```yaml
+# Example
+personality:
+  - innovative
+  - approachable
+  - confident
+  - playful
+```
+
+---
+
+### 2.2 Voice
+
+**Questions to answer:**
+
+- How does the brand speak?
+- What's the tone in different contexts?
+- What words/phrases to use or avoid?
+
+**Facilitation prompts:**
+
+```
+How would the brand greet a new user?
+How would it apologize for an error?
+What words are "on brand" vs "off brand"?
+```
+
+**Output: Voice Guidelines**
+
+The schema `core.voice` contains only `tone` and `principles`. Do/Don't examples belong in `guidelines` as enforceable rules (see `../../schema/spec/core.md` §Voice: What Goes Where).
+
+```yaml
+# core.voice — tone and principles only
+voice:
+  tone:
+    - friendly
+    - clear
+    - encouraging
+  principles:
+    - "Use active voice"
+    - "Keep sentences short"
+    - "Celebrate user wins"
+```
+
+Voice do/don't examples should be recorded in `guidelines.voice-examples`:
+
+```yaml
+# guidelines.voice-examples — enforceable voice rules
+guidelines:
+  voice-examples:
+    content: |
+      ## Voice Examples
+      - Greeting: "Hey there!" (not "Dear user")
+      - Error: "Oops, something went wrong" (not "Error 500")
+    rules:
+      - id: "voice-no-jargon"
+        description: "No corporate jargon in user-facing messages"
+        severity: warning
+        applies_to: voice
+```
+
+---
+
+### 2.3 Naming (if needed)
+
+Skip if name is already decided.
+
+**Approaches:**
+
+1. **Descriptive** - Says what it does (Dropbox, YouTube)
+2. **Abstract** - Evocative, no literal meaning (Apple, Nike)
+3. **Founder/Origin** - Personal name (Tesla, Disney)
+4. **Compound** - Combined words (Facebook, Snapchat)
+5. **Invented** - Made up (Kodak, Xerox)
+
+**Facilitation approach:**
+
+Generate candidates in each category, then filter:
+
+```
+# Candidate generation
+a) Descriptive: BrandSync, AssetHub
+b) Abstract: Beacon, Prism
+c) Compound: BrandBox, AssetFlow
+
+# Filtering criteria
+- Domain available?
+- Easy to spell/pronounce?
+- Unique enough to trademark?
+- Fits the personality?
+```
+
+**Output: Confirmed Name**
+
+The confirmed name goes into `meta.name`. The rationale is recorded in `_workshop/decisions.yml` (not in `core` or `meta`). If you want to preserve it in the final brand.yaml, use `extensions.naming.rationale`.
+
+```yaml
+# meta.name — the only required field in brandspec
+meta:
+  name: "Prism"
+
+# rationale recorded in decisions.yml, or optionally:
+extensions:
+  naming:
+    rationale: "Evokes clarity, multiple facets of brand, light/modern feel"
+```
+
+---
+
+### 2.4 Tagline
+
+**Questions to answer:**
+
+- What's the one-liner that captures the brand promise?
+- Is it memorable? Does it differentiate?
+
+**Approaches:**
+
+1. **Benefit-focused** - "Think different"
+2. **Emotional** - "Just do it"
+3. **Descriptive** - "The ultimate driving machine"
+4. **Provocative** - "Have it your way"
+
+**Facilitation approach:**
+
+Generate 5-10 candidates, narrow to 3, user picks:
+
+```
+Candidates:
+a) "Brand clarity, delivered"
+b) "Your brand, everywhere"
+c) "One source of truth"
+
+Which resonates most?
+```
+
+**Output: Tagline**
+
+```yaml
+# Example
+tagline: "Brand clarity, delivered"
+```
+
+---
+
+## Phase Complete Checklist
+
+- [ ] 3-5 personality traits selected
+- [ ] Voice tone and principles defined
+- [ ] Name confirmed (or skipped if pre-existing)
+- [ ] Tagline selected
+- [ ] All recorded in `decisions.yml`
+
+## Transition to Phase 3
+
+When all items are checked:
+
+```yaml
+# Update position.yml
+phase: 3
+step: "mood"
+mode: "facilitation"
+```
+
+## Example Session
+
+```
+AI: Now let's define personality. I'll show you some spectrums.
+    Where does your brand fall?
+    
+    Formal ←───●───→ Casual
+    
+    (1=very formal, 5=very casual)
+
+User: 4 - pretty casual but not sloppy
+
+AI: Got it. How about:
+    
+    Serious ←───●───→ Playful
+
+User: 3 - balanced, we want to be taken seriously but not boring
+
+AI: Based on this, here are personality trait candidates:
+    
+    a) Professional, reliable, calm
+    b) Approachable, confident, modern  
+    c) Bold, innovative, energetic
+    
+    Which set feels closest?
+
+User: b, but add a touch of playful from c
+
+AI: How about:
+    - Approachable
+    - Confident
+    - Modern
+    - Playful (subtle)
+    
+    [Records to decisions.yml]
+```

package/workshop/phases/03-visual.md

@@ -0,0 +1,271 @@
+# Phase 3: Visual Identity
+
+## Goal
+
+Define the visual language: colors, typography, and logo direction.
+
+**Spec reference:** Read `../../schema/spec/tokens.md` for token format, color system, and naming conventions. Read `../../schema/spec/assets.md` for logo system patterns and asset structure.
+
+## Steps
+
+### 3.1 Mood
+
+**Questions to answer:**
+
+- What's the visual feeling we're going for?
+- What existing brands/designs inspire us?
+- What visual territory should we own?
+
+**Facilitation approach:**
+
+Describe visual directions based on personality:
+
+```
+Based on your personality (approachable, confident, modern, playful),
+here are visual directions:
+
+a) Clean & Minimal - Lots of white space, subtle colors, geometric
+b) Warm & Friendly - Rounded shapes, warm palette, illustrations
+c) Bold & Dynamic - Strong colors, sharp contrasts, movement
+
+Which direction appeals?
+```
+
+**Output: Mood Direction**
+
+```yaml
+# Example
+mood:
+  direction: "Clean & Minimal with warm touches"
+  references:
+    - "Linear (the app)"
+    - "Notion"
+    - "Stripe"
+  characteristics:
+    - "Generous white space"
+    - "Subtle, purposeful color"
+    - "Modern but not cold"
+```
+
+---
+
+### 3.2 Colors
+
+**Spec reference:** See `../../schema/spec/tokens.md` §Colors for the complete color specification including variant naming, required/recommended tokens, dark mode, and palette generation guidelines.
+
+**Subsection overview:**
+
+| Item | Classification | Notes |
+|------|---------------|-------|
+| primary + foreground, secondary + foreground | Required | Minimum brand colors |
+| background / foreground / muted | Required | UI surfaces |
+| destructive | Required | Error states |
+| success / warning / info | Recommended | AI generates defaults from primary hue, user adjusts |
+| dark mode | Optional | Ask explicitly: "Does your product need dark mode?" |
+| brand-scale 50–900 | Optional | Advanced use only |
+| $extensions.compat | Optional | Only when legacy tool support is needed |
+
+#### Progressive shortcut (recommended flow)
+
+The full color system can feel overwhelming. Use this progressive approach:
+
+1. **User decides**: primary color direction (from personality/mood)
+2. **User decides**: secondary/accent color
+3. **AI generates**: all remaining colors (surfaces, semantics, destructive) using the palette generation guidelines in spec/tokens.md
+4. **User confirms**: "Does this palette feel right?" — adjust any that don't work
+
+This keeps user decisions to 2-3 choices while producing a complete, harmonious palette.
+
+```
+Facilitation shortcut:
+
+AI: "You chose teal as your primary. Here's the complete palette
+     I've derived from it:
+
+     Brand:    primary oklch(0.65 0.15 190) / secondary oklch(0.70 0.10 100)
+     Surfaces: background, foreground, muted (neutral with teal undertone)
+     Status:   success (green), warning (amber), info (blue), destructive (red)
+
+     [Shows full palette]
+
+     This all works together. Want to adjust anything, or shall we move on?"
+```
+
+#### Full control path
+
+For users who want to define each color individually, walk through the token categories defined in spec/tokens.md (required → recommended → optional).
+
+**Color psychology reference:**
+
+| Color | Associations |
+|-------|-------------|
+| Blue | Trust, stability, technology |
+| Green | Growth, nature, health |
+| Purple | Creativity, luxury, wisdom |
+| Orange | Energy, warmth, friendliness |
+| Red | Passion, urgency, power |
+| Yellow | Optimism, clarity, warmth |
+
+**Facilitation approach:**
+
+```
+Given your personality (modern, approachable), consider:
+
+a) Blue-based: Trust + professionalism
+   Primary: oklch(0.65 0.18 250)
+
+b) Teal-based: Modern + fresh
+   Primary: oklch(0.65 0.15 190)
+
+c) Purple-based: Creative + premium
+   Primary: oklch(0.60 0.20 300)
+
+Which family feels right?
+```
+
+#### Dark mode [Optional — ask explicitly]
+
+```
+Does your product need dark mode?
+
+a) Yes — let's define dark variants for your core colors
+b) No — skip for now (can be added later)
+c) Not sure — let's skip it and revisit when needed
+```
+
+If yes, generate `$extensions.dark` values as specified in spec/tokens.md §Dark Mode.
+
+---
+
+### 3.3 Typography
+
+**Spec reference:** See `../../schema/spec/tokens.md` §Typography for token format and font pairing strategies.
+
+**Questions to answer:**
+
+- What font for headings?
+- What font for body text?
+- What about code/monospace?
+
+**Facilitation approach:**
+
+```
+Typography options:
+
+a) Modern & Clean
+   Heading: Inter (bold)
+   Body: Inter (regular)
+
+b) Distinctive Headlines
+   Heading: Space Grotesk
+   Body: Inter
+
+c) Editorial Feel
+   Heading: Fraunces (serif)
+   Body: Inter
+
+Which direction?
+```
+
+---
+
+### 3.4 Logo System
+
+**Spec reference:** See `../../schema/spec/assets.md` §Logo System Patterns for pattern definitions, required assets per pattern, and recommended variants.
+
+**Note:** This step produces a **logo system brief** — the pattern, required assets, and usage guidance. Actual logo creation may be done externally.
+
+**Facilitation approach:**
+
+Present patterns based on brand personality and practical needs:
+
+```
+Your brand identity so far:
+- Name: [from Phase 2]
+- Personality: [from Phase 2]
+- Mood: [from 3.1]
+
+Logo system patterns:
+
+a) Wordmark
+   Your name as the identity. Clean, typographic.
+   Simplest to manage.
+
+b) Symbol + Wordmark
+   A mark that can stand on its own + your name.
+   Most flexible. Best if you need an app icon.
+
+c) Combination Mark
+   An integrated logo — symbol and name as one unit.
+   Consistent, easier to manage than (b).
+
+d) Emblem
+   Name enclosed in a shape. Heritage, authority feel.
+
+Which pattern fits your brand?
+```
+
+After pattern selection, confirm the asset checklist from spec/assets.md:
+
+```
+You chose: Symbol + Wordmark
+
+Assets you'll need:
+  ✓ symbol (primary, inverse, monochrome)
+  ✓ wordmark (primary, inverse, monochrome)
+  ○ logo-horizontal (recommended, combined layout)
+  ○ logo-vertical (recommended, combined layout)
+
+Plus for digital use:
+  ✓ favicon derived from symbol
+  ○ app icon (if applicable)
+  ○ OG image for social sharing
+
+Shall I record this, or adjust anything?
+```
+
+Then explore the visual concept:
+
+**Output: Logo System Brief**
+
+```yaml
+logo:
+  pattern: "symbol_wordmark"
+  concept: "Abstract prism shape suggesting clarity and multiple perspectives"
+  required_assets:
+    - role: symbol
+      variants: [primary, inverse, monochrome]
+    - role: wordmark
+      variants: [primary, inverse, monochrome]
+  optional_assets:
+    - role: logo
+      variants: [horizontal, vertical]
+    - role: favicon
+      note: "Derived from symbol"
+  requirements:
+    - "Symbol works at 16px (favicon)"
+    - "Single color version for sponsorship contexts"
+```
+
+---
+
+## Phase Complete Checklist
+
+- [ ] Visual mood/direction defined
+- [ ] Color palette complete (all required tokens from spec/tokens.md)
+- [ ] Typography selected (heading, body, optionally mono)
+- [ ] Logo system pattern selected
+- [ ] Required and optional assets identified
+- [ ] Logo concept/brief documented
+- [ ] All recorded in `decisions.yml`
+
+## Transition to Phase 4
+
+When all items are checked:
+
+```yaml
+# Update position.yml
+phase: 4
+step: "defaults"
+mode: "facilitation"
+```

package/workshop/phases/04-documentation.md

@@ -0,0 +1,99 @@
+# Phase 4: Documentation
+
+## Goal
+
+Generate `brand.yaml` and finalize the brandspec directory.
+
+**Spec reference:** See `../../schema/spec/tokens.md` §Spacing, §Radius. See `../../schema/spec/assets.md` for asset registration. See `../../schema/spec/core.md` for core field structure.
+
+## Steps
+
+### 4.1 Defaults Confirmation
+
+Confirm standard spacing and radius tokens before generating `brand.yaml`.
+
+```
+Almost done. Standard spacing and radius will be included
+(compatible with shadcn/ui + Tailwind v4):
+
+  Spacing: xs 0.25rem / sm 0.5rem / md 1rem / lg 1.5rem / xl 2rem
+  Radius:  sm 0.25rem / md 0.5rem / lg 1rem
+
+OK with these defaults?
+```
+
+If the user wants to customize, adjust. Otherwise record as confirmed and move on.
+
+---
+
+### 4.2 brand.yaml Generation
+
+Generate `brand.yaml` from all decisions (using latest non-superseded decisions).
+
+**Process:**
+
+1. Gather all decisions from `decisions.yml` (latest non-superseded for each key)
+2. Structure into brandspec format following the spec files (core.md, tokens.md, assets.md, guidelines.md)
+3. Write to `brand.yaml`
+4. If assets exist from Phase 3 logo work or user-provided files, register them in the `assets` section using the structure defined in spec/assets.md. If none exist, leave `assets: []`
+5. If dark mode was defined, add `$extensions.dark` to surface and brand color tokens
+6. Validate against schema:
+
+```bash
+npx brandspec validate brand.yaml
+```
+
+If validation fails, fix and re-validate.
+
+**Output:** `brand.yaml` (brandspec directory root)
+
+---
+
+### 4.3 Final Review
+
+Present the completed brandspec directory to the user for approval.
+
+```
+Here's your brandspec:
+
+  brandspec/
+  ├── brand.yaml          — source of truth
+  ├── assets/             — brand assets (if any)
+  └── _workshop/          — process records
+      └── decisions.yml
+
+Review:
+1. Does the essence capture your brand?
+2. Are the colors right?
+3. Anything to adjust?
+```
+
+If the user requests changes, go back and fix. Otherwise, mark complete.
+
+---
+
+## Phase Complete Checklist
+
+- [ ] Spacing/radius confirmed
+- [ ] `brand.yaml` generated and valid
+- [ ] Assets registered (or noted as next action)
+- [ ] User has reviewed and approved
+
+## Workshop Complete
+
+When approved:
+
+```yaml
+# Update position.yml
+phase: 4
+step: "complete"
+mode: "execution"
+completed_at: "2026-02-23"
+```
+
+**Next steps to suggest:**
+
+1. Create logo based on the brief (Phase 3) and register in `assets/`
+2. Generate token files: `npx brandspec generate --format all`
+3. Use `npx brandspec consult` for brand-aligned AI consultation
+4. Host on brandspec.tools for team distribution

package/workshop/templates/_workshop/decisions.yml

@@ -0,0 +1,15 @@
+# Workshop decisions - append-only log
+# Each decision is permanent and timestamped
+# When overriding a previous decision, use `supersedes` to reference its ID
+
+decisions: []
+
+# Decision schema:
+#   - id: "d001"            # Unique ID (auto-increment)
+#     timestamp: "ISO 8601"
+#     phase: 1
+#     step: "product"
+#     key: "product_essence"
+#     value: "..."
+#     rationale: "..."
+#     supersedes: null       # or "d00X" if overriding a previous decision

package/workshop/templates/_workshop/memo.md

@@ -0,0 +1,23 @@
+# Working Memo
+
+This file is for working notes during the workshop.
+It can be overwritten freely - nothing here is permanent.
+
+Use this for:
+- Brainstorming candidates
+- Exploring options
+- Draft content before finalizing
+
+---
+
+## Current Focus
+
+
+
+## Candidates / Options
+
+
+
+## Notes
+
+

package/workshop/templates/_workshop/position.yml

@@ -0,0 +1,9 @@
+# Workshop position - tracks current progress
+# Updated by AI after each step completion
+
+phase: 1
+step: "product"
+mode: "facilitation"
+revision: 1              # +1 when backtracking
+updated: ""
+completed_at: null        # ISO date when workshop finishes

package/workshop/templates/_workshop/session.md

@@ -0,0 +1,28 @@
+# Session Handoff
+
+This file captures context for resuming the workshop.
+Updated at the end of each session.
+
+---
+
+## Last Session
+
+Updated: <!-- ISO timestamp -->
+
+## Current State
+
+- Phase:
+- Step:
+- Mode:
+
+## Key Decisions Made
+
+
+
+## Next Actions
+
+
+
+## Open Questions
+
+