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):

font-family: 'Inter', system-ui, -apple-system, sans-serif;
font-weight: 700; /* Bold */
letter-spacing: -0.02em; /* Tight tracking */

Body Text:

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

Monospace (Code, Technical):

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):

background: #8B5CF6;
color: #FFFFFF;
border-radius: 8px;
padding: 12px 24px;
font-weight: 600;

Secondary (Outline):

background: transparent;
border: 1px solid #2A2A2A;
color: #1A1A1A;
border-radius: 8px;
padding: 12px 24px;

Ghost (Text only):

background: transparent;
color: #666666;
hover: color: #1A1A1A;

Cards

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

--duration-fast: 150ms;
--duration-normal: 250ms;
--duration-slow: 350ms;

Easing Functions

--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:

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

// 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