1000planets-site/spec-kit/decisions/0002-brand-guidelines.md

# ADR 0002: Brand Guidelines

**Status**: ✅ Accepted
**Date**: 2025-12-11
**Deciders**: Client requirements + Design team

---

## Brand Essence

### Name Origin
**"1000 Planets"** - Inspired by *Valerian and the City of a Thousand Planets*, representing an intergalactic marketplace of infinite possibilities.

**Core Message**: *"Find what you're looking for."*

### Mission Statement
An AI-forward marketing agency committed to putting tools in the hands of customers to grow their reach with automated solutions and robust data ownership.

**Social Impact Goal**: Enable economic empowerment - targeting $500/month baseline income for partner agents, with focus on single mothers and underserved communities.

---

## Brand Personality

1. **Bold & Disruptive**
   - Paradigm shift in giving end users control
   - Ownership and autonomy over their data and decisions
   - Not afraid to challenge traditional agency models

2. **Trustworthy & Reliable**
   - Robust support systems
   - Transparent pricing and operations
   - Proven, dependable technology

3. **Approachable & Premium**
   - Polished without pretension
   - Human-readable language (no jargon)
   - Focuses on what matters to small business owners

---

## Visual Identity

### Design Inspiration

**Primary**: Linear
- Clean, bold typography
- Generous white space
- Sharp, modern interfaces
- Subtle animations

**Secondary**: Vercel
- Performance-focused aesthetic
- Developer-quality polish
- Minimalist navigation
- Dark mode excellence

### Core Principles
- **Polished & Premium** - High-quality, professional
- **Human-Readable** - Clear, direct communication
- **Functional** - Every element serves a purpose
- **Accessible** - WCAG 2.1 AA minimum

---

## Color System

### Base Palette: Dark/Light Charcoal & White

**Light Mode**:
```
Background: #FFFFFF (pure white)
Surface: #F5F5F5 (off-white)
Border: #E5E5E5 (light gray)
Text Primary: #1A1A1A (near black)
Text Secondary: #666666 (medium gray)
Text Tertiary: #999999 (light gray)
```

**Dark Mode**:
```
Background: #0A0A0A (near black)
Surface: #1A1A1A (dark charcoal)
Border: #2A2A2A (lighter charcoal)
Text Primary: #FFFFFF (white)
Text Secondary: #CCCCCC (light gray)
Text Tertiary: #888888 (medium gray)
```

### Semantic Colors (Standard Messaging)

| Color | Hex | Usage | Meaning |
|-------|-----|-------|---------|
| 🔴 **Red** | `#EF4444` | Error, broken, critical | Stop, danger, failure |
| 🟢 **Green** | `#10B981` | Success, go, active | Ready, approved, complete |
| 🟡 **Yellow** | `#F59E0B` | Caution, warning, pending | Review, attention needed |
| 🔵 **Blue** | `#3B82F6` | Admin, information, system | Informational, neutral |
| 🟣 **Purple** | `#8B5CF6` | Agentic, AI-driven, automation | AI/automation indicators |

### Accent Color (Primary Brand)
**Purple** (`#8B5CF6`) - Represents our AI-forward, agentic nature

**Usage**:
- Primary CTAs
- Interactive elements
- Progress indicators
- AI/automation badges
- Links and highlights

---

## Typography

### Font Stack

**Headings** (Display, H1-H3):
```css
font-family: 'Inter', system-ui, -apple-system, sans-serif;
font-weight: 700; /* Bold */
letter-spacing: -0.02em; /* Tight tracking */
```

**Body Text**:
```css
font-family: 'Inter', system-ui, -apple-system, sans-serif;
font-weight: 400; /* Regular */
line-height: 1.6; /* Comfortable reading */
```

**Monospace** (Code, Technical):
```css
font-family: 'JetBrains Mono', 'Fira Code', monospace;
```

### Type Scale

| Element | Size | Weight | Line Height |
|---------|------|--------|-------------|
| **Display** | 72px | 700 | 1.1 |
| **H1** | 48px | 700 | 1.2 |
| **H2** | 36px | 700 | 1.3 |
| **H3** | 24px | 600 | 1.4 |
| **H4** | 20px | 600 | 1.5 |
| **Body Large** | 18px | 400 | 1.6 |
| **Body** | 16px | 400 | 1.6 |
| **Body Small** | 14px | 400 | 1.5 |
| **Caption** | 12px | 500 | 1.4 |

---

## Voice & Tone

### Writing Principles

1. **Human-Readable** - No jargon, no buzzwords
2. **Direct & Clear** - Say what you mean
3. **Empowering** - "You can do this"
4. **Results-Focused** - Show the value
5. **Conversational** - Like a trusted advisor

### Language Guidelines

**DO**:
- ✅ "Grow your business with AI automation"
- ✅ "You own your data. Always."
- ✅ "See results in days, not months"
- ✅ "Start your free 30-day trial"
- ✅ "Built for small business owners like you"

**DON'T**:
- ❌ "Leverage synergistic AI paradigms"
- ❌ "Disrupt the marketing ecosystem"
- ❌ "Best-in-class solutions"
- ❌ "Revolutionary technology"
- ❌ Technical jargon without explanation

### Tone by Context

| Context | Tone | Example |
|---------|------|---------|
| **Homepage** | Confident, welcoming | "Welcome to your AI-powered growth partner" |
| **Pricing** | Transparent, fair | "Simple pricing. No surprises." |
| **Docs** | Helpful, clear | "Here's how to get started in 3 steps" |
| **Errors** | Apologetic, helpful | "Something went wrong. Let's fix it together." |
| **Success** | Celebratory | "You're all set! Your trial starts now." |

---

## Components & UI Patterns

### Buttons

**Primary** (Purple, high contrast):
```css
background: #8B5CF6;
color: #FFFFFF;
border-radius: 8px;
padding: 12px 24px;
font-weight: 600;
```

**Secondary** (Outline):
```css
background: transparent;
border: 1px solid #2A2A2A;
color: #1A1A1A;
border-radius: 8px;
padding: 12px 24px;
```

**Ghost** (Text only):
```css
background: transparent;
color: #666666;
hover: color: #1A1A1A;
```

### Cards

```css
background: #FFFFFF / #1A1A1A (dark);
border: 1px solid #E5E5E5 / #2A2A2A;
border-radius: 12px;
padding: 24px;
box-shadow: 0 1px 3px rgba(0,0,0,0.05);
```

### Spacing Scale

```
4px  → tight
8px  → compact
12px → cozy
16px → comfortable (default)
24px → relaxed
32px → spacious
48px → loose
64px → extra loose
```

---

## Animations & Motion

### Principles
- **Purposeful** - Every animation serves a function
- **Subtle** - Not distracting
- **Fast** - <300ms for most transitions
- **Natural** - Easing curves feel organic

### Standard Durations
```css
--duration-fast: 150ms;
--duration-normal: 250ms;
--duration-slow: 350ms;
```

### Easing Functions
```css
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
```

---

## Accessibility Requirements

### WCAG 2.1 AA Compliance

**Color Contrast**:
- Text: 4.5:1 minimum (normal), 3:1 (large text)
- UI Components: 3:1 minimum

**Interactive Elements**:
- Minimum touch target: 44x44px
- Keyboard accessible (tab order, focus states)
- Screen reader friendly (ARIA labels)

**Focus States**:
```css
outline: 2px solid #8B5CF6;
outline-offset: 2px;
```

---

## Usage Examples

### Hero Section
```
Background: Gradient (dark charcoal to black)
Heading: 72px, white, bold
Subheading: 20px, gray-300
CTA: Purple button, "Start Free Trial"
```

### Feature Card
```
Background: White/dark-charcoal
Icon: Purple circle background
Title: 24px, bold
Description: 16px, gray-600
Border: Subtle, light-gray/dark-gray
```

---

## Implementation in Code

### Tailwind Config
```js
// tailwind.config.js
colors: {
  background: "hsl(var(--background))",
  foreground: "hsl(var(--foreground))",
  primary: "#8B5CF6", // Purple
  success: "#10B981", // Green
  warning: "#F59E0B", // Yellow
  error: "#EF4444", // Red
  info: "#3B82F6", // Blue
  agentic: "#8B5CF6", // Purple (AI indicator)
}
```

---

## References

- Linear Design System
- Vercel Design Guidelines
- Material Design (Color System)
- WCAG 2.1 Guidelines