jfl 0.0.0

package/template/templates/brand/BRAND_DECISIONS.md

@@ -0,0 +1,168 @@
+# Brand Decisions
+
+> This file gets filled in as you make selections during the brand architect workflow.
+>
+> Last updated: {date}
+
+---
+
+## Quick Reference
+
+| Decision | Value |
+|----------|-------|
+| **Primary Mark** | {not selected} |
+| **Default Theme** | {dark / light} |
+| **Primary Accent** | {color} |
+| **Typography** | {font stack} |
+| **Tagline** | "{tagline}" |
+
+---
+
+## THE MARK
+
+### Selected Mark
+- **File:** `{filename}`
+- **Description:** {what it represents}
+- **Why chosen:** {rationale}
+
+### Mark Variants
+
+| Context | Mark | File | Notes |
+|---------|------|------|-------|
+| Favicon (16-48px) | | | |
+| Icon (80-160px) | | | |
+| PFP (400px) | | | |
+| Banner | | | |
+| Hero | | | |
+
+### Mark Files
+
+**SVG:**
+| File | Use |
+|------|-----|
+| `mark-{version}-transparent.svg` | Base mark |
+| `mark-{version}-{size}-dark.svg` | Dark mode |
+| `mark-{version}-{size}-light.svg` | Light mode |
+
+### Usage Rules
+- {Any rules about when to use what}
+- {Spacing requirements}
+- {What not to do}
+
+---
+
+## COLORS
+
+### Dark Mode (Default)
+```css
+--brand-bg: #000000;
+--brand-fg: #FFFFFF;
+--brand-accent: {accent};
+```
+
+### Light Mode
+```css
+--brand-bg: #FFFFFF;
+--brand-fg: #000000;
+--brand-accent: {accent-light};
+```
+
+### Full Palette
+| Token | Dark | Light | Use |
+|-------|------|-------|-----|
+| Background | | | Main bg |
+| Foreground | | | Text |
+| Accent | | | CTAs, highlights |
+| Success | | | Positive states |
+| Error | | | Errors |
+| Warning | | | Warnings |
+| Muted | | | Secondary text |
+
+---
+
+## TYPOGRAPHY
+
+### Font Stack
+```css
+font-family: {stack};
+```
+
+### Weights
+- **Body:** {weight}
+- **Headings:** {weight}
+- **Emphasis:** {weight}
+
+### Sizes
+| Use | Size |
+|-----|------|
+| Body | |
+| H1 | |
+| H2 | |
+| Small | |
+
+### Style Notes
+- {Preferences: lowercase, uppercase, sentence case}
+- {Letter spacing}
+- {Line height}
+
+---
+
+## SOCIAL ASSETS
+
+### Twitter Banner
+| Size | Dark | Light |
+|------|------|-------|
+| Small | `banner-sm-1500x500-dark.svg` | |
+| Medium | `banner-md-1500x500-dark.svg` | |
+| Large | `banner-lg-1500x500-dark.svg` | |
+| X-Large | `banner-xl-1500x500-dark.svg` | |
+
+### OG Images
+| Variant | File | Use |
+|---------|------|-----|
+| Default | `og-default-1200x630-dark.svg` | Homepage |
+| Tagline | `og-tagline-1200x630-dark.svg` | Marketing |
+
+### PFP
+| Platform | File |
+|----------|------|
+| Twitter | `pfp-400-dark.svg` |
+
+---
+
+## FAVICONS
+
+| Size | File | Use |
+|------|------|-----|
+| 16px | `favicon-16.png` | Browser tab |
+| 32px | `favicon-32.png` | Browser tab @2x |
+| 48px | `favicon-48.png` | Windows |
+| 96px | `favicon-96.png` | Android Chrome |
+| 180px | `favicon-180.png` | Apple Touch |
+| 192px | `favicon-192.png` | Android Chrome |
+| 512px | `favicon-512.png` | PWA |
+
+---
+
+## DO NOT USE
+
+- {Deprecated marks}
+- {Retired colors}
+- {Old assets}
+
+---
+
+## FOR IMPLEMENTERS
+
+When implementing this brand:
+
+1. Use marks from `outputs/svg/mark/`
+2. Use social assets from `outputs/svg/social/`
+3. Reference this file for all decisions
+4. Check `outputs/css/global.css` for CSS tokens
+
+---
+
+```
+{mark preview here}
+```

package/template/templates/brand/BRAND_GUIDELINES.md

@@ -0,0 +1,251 @@
+# Brand Guidelines
+
+> Usage rules and application guidance for the brand.
+> Complements BRAND_DECISIONS.md (what we chose) with HOW to use it.
+
+---
+
+## Logo Usage
+
+### Clear Space
+
+Minimum clear space around the logo equals the height of the mark's "x-height" (or specify in pixels/rem).
+
+```
+    ┌─────────────────────┐
+    │                     │
+    │   ┌─────────────┐   │
+    │   │    LOGO     │   │  ← Clear space = X on all sides
+    │   └─────────────┘   │
+    │                     │
+    └─────────────────────┘
+```
+
+### Minimum Size
+
+| Context | Minimum Width |
+|---------|--------------|
+| Digital | 32px |
+| Print | 0.5in / 12mm |
+| Favicon | 16px (simplified mark) |
+
+### Logo Don'ts
+
+- [ ] Don't stretch or distort
+- [ ] Don't rotate
+- [ ] Don't add effects (shadows, glows, gradients)
+- [ ] Don't place on busy backgrounds without container
+- [ ] Don't change the colors outside approved palette
+- [ ] Don't outline or stroke the logo
+- [ ] Don't recreate in different fonts
+
+---
+
+## Color Usage
+
+### Primary Color
+
+**Use for:**
+- Primary CTAs and buttons
+- Key interactive elements
+- Links
+- Selected states
+- Brand moments
+
+**Don't use for:**
+- Large background areas (too intense)
+- Body text
+- Disabled states
+
+### Secondary Color
+
+**Use for:**
+- Secondary buttons
+- Accents and highlights
+- Hover states
+- Supporting graphics
+
+### Neutral Colors
+
+**Use for:**
+- Body text
+- Backgrounds
+- Borders
+- Disabled states
+- Secondary text
+
+### Color Accessibility
+
+| Combination | Contrast Ratio | WCAG Level |
+|-------------|----------------|------------|
+| Primary on White | {ratio} | {AA/AAA} |
+| Primary on Dark | {ratio} | {AA/AAA} |
+| Body text on Background | {ratio} | {AA/AAA} |
+
+**Minimum requirements:**
+- Normal text: 4.5:1 (AA)
+- Large text (18px+): 3:1 (AA)
+- UI components: 3:1 (AA)
+
+---
+
+## Typography
+
+### Hierarchy
+
+| Level | Size | Weight | Line Height | Use For |
+|-------|------|--------|-------------|---------|
+| Display | 48-72px | Bold | 1.1 | Hero headlines |
+| H1 | 36-48px | Bold | 1.2 | Page titles |
+| H2 | 28-36px | Semibold | 1.25 | Section headers |
+| H3 | 20-24px | Semibold | 1.3 | Subsections |
+| Body | 16-18px | Regular | 1.5-1.6 | Paragraphs |
+| Small | 14px | Regular | 1.4 | Captions, meta |
+| Micro | 12px | Medium | 1.3 | Labels, tags |
+
+### Font Weights
+
+| Weight | Value | Use For |
+|--------|-------|---------|
+| Regular | 400 | Body text |
+| Medium | 500 | Emphasis, labels |
+| Semibold | 600 | Subheadings |
+| Bold | 700 | Headlines, CTAs |
+
+### Typography Don'ts
+
+- [ ] Don't use more than 2 font families
+- [ ] Don't use light weights under 16px
+- [ ] Don't center-align long paragraphs
+- [ ] Don't use all-caps for body text
+- [ ] Don't exceed 75 characters per line
+
+---
+
+## Spacing
+
+### Base Unit
+
+All spacing derives from a base unit: **4px** (0.25rem)
+
+### Scale
+
+| Token | Value | Use For |
+|-------|-------|---------|
+| xs | 4px | Tight gaps, icon padding |
+| sm | 8px | Inline elements, small gaps |
+| md | 16px | Default spacing |
+| lg | 24px | Section padding |
+| xl | 32px | Large gaps |
+| 2xl | 48px | Section margins |
+| 3xl | 64px | Major sections |
+
+### Component Spacing
+
+| Component | Internal Padding | External Margin |
+|-----------|-----------------|-----------------|
+| Button | 8px 16px | - |
+| Card | 16px-24px | 16px |
+| Input | 12px 16px | 8px (between inputs) |
+| Section | 48px-64px | 0 |
+
+---
+
+## Voice & Tone
+
+### Brand Voice
+
+**We are:**
+- {adjective 1} - {what this means}
+- {adjective 2} - {what this means}
+- {adjective 3} - {what this means}
+
+**We are NOT:**
+- {anti-adjective 1} - {what to avoid}
+- {anti-adjective 2} - {what to avoid}
+
+### Tone by Context
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Errors | Helpful, not blaming | "Couldn't save. Check your connection." |
+| Success | Brief, celebratory | "Done!" or "Saved" |
+| Empty states | Encouraging | "No items yet. Create your first one." |
+| Loading | Honest | "Loading..." (not "Just a moment...") |
+| CTAs | Direct, active | "Start building" not "Click here to begin" |
+
+### Writing Style
+
+- Use sentence case for headings
+- Use active voice
+- Keep sentences short (under 20 words)
+- Avoid jargon unless audience expects it
+- Use "you" not "the user"
+
+---
+
+## Imagery
+
+### Photography Style
+
+- {describe style: candid vs posed, saturated vs muted, etc.}
+- {describe subjects: people, objects, abstract}
+- {describe mood: professional, playful, serious}
+
+### Illustration Style
+
+- {describe style: line art, filled, 3D, flat}
+- {describe colors: brand colors only? accent allowed?}
+- {describe complexity: minimal, detailed}
+
+### Icon Style
+
+- {describe: outlined, filled, rounded, sharp}
+- {describe: stroke width}
+- {describe: size increments}
+
+---
+
+## Motion
+
+### Principles
+
+1. **Purposeful** - Animation serves function, not decoration
+2. **Quick** - Fast enough to not delay user
+3. **Natural** - Physics-based easing, not linear
+
+### Timing
+
+| Type | Duration | Easing |
+|------|----------|--------|
+| Micro (hover, press) | 100-150ms | ease-out |
+| Small (tooltips, dropdowns) | 150-200ms | ease-out |
+| Medium (modals, panels) | 200-300ms | ease-in-out |
+| Large (page transitions) | 300-400ms | ease-in-out |
+
+### Don'ts
+
+- [ ] Don't animate for more than 400ms
+- [ ] Don't use bounce/elastic for functional UI
+- [ ] Don't animate multiple things simultaneously
+- [ ] Don't block interaction during animation
+
+---
+
+## Accessibility
+
+### Requirements
+
+- WCAG 2.1 AA compliance minimum
+- Keyboard navigation for all interactive elements
+- Screen reader support
+- Reduced motion support
+
+### Checklist
+
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Focus states are visible
+- [ ] Color is not the only indicator
+- [ ] Touch targets are 44x44px minimum
+- [ ] Content is readable at 200% zoom

package/template/templates/brand/VOICE_AND_TONE.md

@@ -0,0 +1,146 @@
+# Voice and Tone Guide
+
+> How your brand speaks. Copy to `knowledge/VOICE_AND_TONE.md` and customize.
+
+---
+
+## Voice (Consistent)
+
+Your voice is WHO you are. It stays consistent across all contexts.
+
+### Voice Attributes
+
+**We are:**
+- {attribute 1} - {what this means in practice}
+- {attribute 2} - {what this means in practice}
+- {attribute 3} - {what this means in practice}
+
+**We are NOT:**
+- {anti-attribute 1}
+- {anti-attribute 2}
+- {anti-attribute 3}
+
+### Voice Examples
+
+| Instead of | We say |
+|------------|--------|
+| "Leverage synergies" | {plain language version} |
+| "Click here" | {more engaging version} |
+| "Dear valued customer" | {your version} |
+
+---
+
+## Tone (Flexible)
+
+Tone is HOW you express your voice in different contexts. It shifts based on situation.
+
+### Tone Spectrum
+
+```
+Serious ←────────────────────────────→ Playful
+       Where do you sit by default?
+
+Formal ←────────────────────────────→ Casual
+       Where do you sit by default?
+
+Reserved ←────────────────────────────→ Enthusiastic
+       Where do you sit by default?
+```
+
+### Tone by Context
+
+| Context | Tone Adjustment |
+|---------|-----------------|
+| Error messages | More empathetic, helpful |
+| Success messages | More celebratory |
+| Documentation | More neutral, clear |
+| Marketing | More energetic |
+| Support | More patient, detailed |
+
+---
+
+## Copy Patterns
+
+### Headlines
+- {Pattern: question / statement / command}
+- {Case: lowercase / Title Case / UPPERCASE}
+- {Length: short punchy / descriptive}
+
+**Examples:**
+- Good: "{example}"
+- Avoid: "{anti-example}"
+
+### Body Copy
+- {Sentence length preference}
+- {Paragraph length}
+- {Use of contractions: yes/no}
+
+### CTAs (Calls to Action)
+- {Action verbs you prefer}
+- {Length: short / descriptive}
+
+**Examples:**
+- Good: "{example}"
+- Avoid: "{anti-example}"
+
+---
+
+## Formatting Conventions
+
+### Punctuation
+- **Periods in headlines:** {yes/no}
+- **Oxford comma:** {yes/no}
+- **Exclamation points:** {rarely/sometimes/often}
+
+### Capitalization
+- **Headings:** {lowercase / Title Case / Sentence case}
+- **Buttons:** {lowercase / Title Case / UPPERCASE}
+- **Product names:** {how to capitalize your product name}
+
+### Special Characters
+- **Emoji:** {never / sparingly / freely}
+- **Terminal characters:** {>, //, $, etc.}
+
+---
+
+## Word List
+
+### Words We Use
+| Word | Instead of | Why |
+|------|------------|-----|
+| {your word} | {common alternative} | {reason} |
+
+### Words We Avoid
+| Avoid | Because |
+|-------|---------|
+| {word} | {reason} |
+
+---
+
+## Sample Copy
+
+### Tagline
+> "{your tagline}"
+
+### Elevator Pitch (1 sentence)
+> "{one sentence description}"
+
+### Boilerplate (1 paragraph)
+> "{standard description paragraph}"
+
+### Error Message Example
+> "{example error in your voice}"
+
+### Success Message Example
+> "{example success in your voice}"
+
+---
+
+## Voice Checklist
+
+Before publishing, ask:
+- [ ] Does this sound like us?
+- [ ] Would we say this out loud?
+- [ ] Is it clear to our audience?
+- [ ] Does it match the context's tone?
+- [ ] Are we avoiding our "don't" words?