From 673007cc9f4ddf2c99249475e7795c16ae37d489 Mon Sep 17 00:00:00 2001 From: fullsizemalt <106900403+fullsizemalt@users.noreply.github.com> Date: Thu, 11 Dec 2025 12:23:51 -0800 Subject: [PATCH] Discovery complete: Creative brief and architectural decisions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Completed client discovery questionnaire - Created creative brief with mission, brand essence, and strategy - ADR 0001: Tech stack (Next.js 14, Tailwind, Sanity, self-hosted) - ADR 0002: Brand guidelines (colors, typography, voice, accessibility) Key insights: - Social impact mission: /month for single mothers and underserved communities - Visual: Linear + Vercel aesthetic with semantic color system - Target: Small business owners with high Google rankings but poor sites - Primary CTA: 30-day free trial with domain pointing Ready to build! 🤖 Generated with Claude Code Co-Authored-By: Claude --- docs/CREATIVE_BRIEF.md | 246 +++++++++++++++ spec-kit/decisions/0001-tech-stack.md | 154 +++++++++ spec-kit/decisions/0002-brand-guidelines.md | 333 ++++++++++++++++++++ 3 files changed, 733 insertions(+) create mode 100644 docs/CREATIVE_BRIEF.md create mode 100644 spec-kit/decisions/0001-tech-stack.md create mode 100644 spec-kit/decisions/0002-brand-guidelines.md diff --git a/docs/CREATIVE_BRIEF.md b/docs/CREATIVE_BRIEF.md new file mode 100644 index 0000000..d0391d4 --- /dev/null +++ b/docs/CREATIVE_BRIEF.md @@ -0,0 +1,246 @@ +# Creative Brief: 1000planets.cloud +**Project**: Forward-Facing Marketing Site +**Date**: 2025-12-11 +**Status**: ✅ Discovery Complete - Moving to Design & Build + +--- + +## Mission Statement + +**"Changing lives through accessible AI automation."** + +1000planets.cloud empowers small business owners and aspiring agency partners with AI-driven tools that deliver immediate ROI while maintaining complete data ownership and control. Our platform enables friends, family, and underserved communities (including single mothers seeking dependable income) to launch their own marketing agencies under our umbrella. + +**Success = $500/month baseline income for partners through automated, scalable systems.** + +--- + +## Brand Essence + +### One-Sentence Description +*"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."* + +### Name Origin: "1000 Planets" +Inspired by *Valerian and the City of a Thousand Planets* - an intergalactic marketplace offering wares of infinite possibilities. **The message: "Find what you're looking for."** + +### Brand Personality +1. **Bold & Disruptive** - Paradigm shift giving end users control, ownership, autonomy +2. **Trustworthy & Reliable** - Robust support, proven systems +3. **Approachable & Premium** - Polished without pretension, human-readable language + +--- + +## Visual Identity + +### Design Inspiration +- **Primary**: Linear (clean, bold, modern) +- **Secondary**: Vercel (performance-focused, developer-quality) + +### Color System +**Base Palette**: Human-readable dark/light with charcoals and functional whites + +**Semantic Colors** (standard messaging): +- 🔴 **Red** - Error, broken, critical +- 🟢 **Green** - Success, go, active +- 🟡 **Yellow** - Caution, warning, pending +- 🔵 **Blue** - Admin, information, system +- 🟣 **Purple** - Agentic, AI-driven, automation + +### Design Principles +- **Polished & Premium** - High-quality, professional aesthetic +- **Human-Readable** - No jargon, clear communication +- **Matters to SMBs** - Focus on what drives results + +--- + +## Target Audience + +### Primary: Small Business Owners +**Profile**: +- Found via Google Business scraping in geographical regions +- High search rankings but low-performing/antiquated websites +- No lead capture or customer acquisition tools +- Need qualified leads and want to leverage existing rankings + +**Psychographics**: +- AI-curious but not technical +- Wants immediate ROI +- Values data ownership +- Seeks simple, trustworthy solutions + +### Secondary: Agency Partners (Future Focus) +**Profile**: +- Friends, family, underserved communities +- Single mothers seeking dependable work +- Looking for $500/month baseline income +- Want to run their own agencies with their own branding/domains + +--- + +## Value Propositions (Priority Order) + +1. **Speed to Market** - Launch fast, see results immediately +2. **Savings Through Automation** - Lower costs, higher efficiency +3. **Privacy & Security** (Essential) - Your data, your control +4. **Human-in-the-Loop Control** - Final approval on everything +5. **Granular Flexibility** - Set-it-and-forget-it OR hands-on +6. **Scalability** - Grow at your pace +7. **Global, AI-Forward** - Cutting-edge technology, accessible to all + +--- + +## Pain Points We Solve + +**Current State** (Customer's Problem): +- ❌ High Google rankings wasted on poor websites +- ❌ Outdated visuals hurting credibility +- ❌ No lead capture systems +- ❌ Missing customer acquisition tools +- ❌ Can't afford traditional agencies + +**Future State** (Our Solution): +- ✅ Modern, high-converting microsites +- ✅ Automated lead capture +- ✅ AI-driven content updates +- ✅ Qualified leads delivered +- ✅ Affordable, transparent pricing + +--- + +## Product Strategy + +### Positioning +**Platform approach** - Solve different verticals with AI-driven, up-to-date solutions + +### Portfolio Display +- ❌ **NOT showcasing** Hotel Yield AI or Microsite Automation separately +- ✅ **Showcase** demo microsites as proof of function +- ✅ **Discovery through sales** - Hand-holding, consultative approach +- ✅ Let customers think they're driving ideas (not being sold) + +### Pricing Transparency +**Hybrid Model**: +- Display base pricing publicly +- "Contact us" for enterprise/custom solutions +- Agency partners can choose their own approach when they spin off + +--- + +## Calls to Action + +### Primary CTA: **"Start Free Trial"** +**Requirements**: +- Basic customization tool for client population +- Ability to point at their own domain +- 30-day trial period + +### Secondary CTAs: +1. Newsletter signup +2. Explore documentation +3. View case studies (when available) + +--- + +## Technical Requirements + +### Tech Stack (My Recommendation) +- **Framework**: Next.js 14 (App Router) - Performance, SEO, flexibility +- **Styling**: Tailwind CSS - Rapid development, consistent design +- **CMS**: Sanity.io - Developer-friendly, flexible content management +- **Hosting**: Self-hosted on nexus-vector +- **Analytics**: Plausible (privacy-focused) + optional GA +- **Domain**: 1000planets.cloud (registered, currently 404) + +### Must-Haves +- ✅ Spec-kit compliant architecture +- ✅ Mobile-first responsive design +- ✅ Accessibility (WCAG 2.1 AA) +- ✅ Performance (90+ Lighthouse score) +- ✅ SEO optimized +- ✅ Newsletter capture +- ✅ Documentation system + +--- + +## Content Strategy + +### Starting from Scratch +- All copy to be drafted (human-readable, no jargon) +- Focus on AI/agentic-curious small business owners +- Emphasize immediate ROI and data ownership +- No logos, photos, testimonials, case studies yet (create placeholders) + +### Tone of Voice +- **Professional but approachable** - Like a trusted advisor +- **Clear and direct** - No fluff, no jargon +- **Empowering** - You're in control +- **Results-focused** - Show the value + +### Key Messaging Pillars +1. **Accessibility** - AI automation for everyone +2. **Autonomy** - You own your data and decisions +3. **Impact** - Real income, real results +4. **Trust** - Transparent, reliable, proven + +--- + +## Success Metrics + +### Primary Goal +**Economic empowerment through accessible automation** +- $500/month baseline for partner agents +- Support single mothers and underserved communities +- Enable agency spin-offs with own branding/domains + +### Conversion Metrics +- Free trial signups +- Newsletter subscriptions +- Demo requests +- Documentation engagement + +### Post-Launch +- May update content frequently at first +- Analytics tracking (Plausible) +- No A/B testing initially + +--- + +## Timeline & Approach + +**Target**: ASAP +**Scope**: Full site (not MVP) +**Strategy**: Build fast, iterate based on real user feedback + +### Launch Plan +1. **Week 1**: Architecture, design system, core pages +2. **Week 2**: Content creation, CMS setup, trial flow +3. **Week 3**: Testing, refinement, deployment prep +4. **Week 4**: Launch on nexus-vector, monitor, iterate + +--- + +## Key Differentiators + +What makes 1000planets.cloud unique: + +1. **Social Impact Mission** - Not just profit, changing lives +2. **Data Ownership** - Your data stays yours +3. **Agency Enablement** - Help others build their own agencies +4. **AI-Forward, Human-Controlled** - Best of both worlds +5. **Transparent Pricing** - No hidden costs +6. **Rapid Deployment** - See results in days, not months + +--- + +## Next Steps + +1. ✅ Create tech stack ADR +2. ✅ Create brand guidelines document +3. ✅ Design component system +4. ✅ Draft all page copy +5. ✅ Build Next.js site +6. ✅ Deploy to nexus-vector + +--- + +**This brief is our north star. Every design and development decision flows from here.** diff --git a/spec-kit/decisions/0001-tech-stack.md b/spec-kit/decisions/0001-tech-stack.md new file mode 100644 index 0000000..92ae6fa --- /dev/null +++ b/spec-kit/decisions/0001-tech-stack.md @@ -0,0 +1,154 @@ +# ADR 0001: Technology Stack + +**Status**: ✅ Accepted +**Date**: 2025-12-11 +**Deciders**: Development team + Client requirements + +--- + +## Context + +We need to build a hypermodern, performant marketing site for 1000planets.cloud that: +- Loads fast and ranks well (SEO critical) +- Supports future CMS integration for blog/case studies +- Can be self-hosted on nexus-vector +- Enables rapid iteration and content updates +- Maintains spec-kit compliance +- Scales to support agency partner spin-offs + +--- + +## Decision + +### Core Framework: **Next.js 14 (App Router)** + +**Rationale**: +- **Performance**: Built-in optimization (image, font, code splitting) +- **SEO**: Server-side rendering, meta tag management +- **Flexibility**: Can serve static pages OR dynamic content +- **Developer Experience**: TypeScript support, hot reload, great docs +- **Ecosystem**: Massive community, proven at scale +- **Self-hosting**: Can deploy anywhere (Docker, VPS, etc.) + +**Alternatives Considered**: +- **Astro**: Great for content-heavy sites, but less flexible for future interactive features +- **Vanilla React**: More control but need to build everything from scratch +- **Remix**: Excellent but smaller ecosystem + +--- + +### Styling: **Tailwind CSS + shadcn/ui** + +**Rationale**: +- **Tailwind CSS**: Utility-first, rapid development, consistent design system +- **shadcn/ui**: Beautifully designed components matching Linear/Vercel aesthetic +- **Dark/Light Mode**: Built-in support for theme switching +- **Customization**: Full control over design tokens (colors, spacing, typography) +- **Performance**: Only ships CSS actually used (tree-shaking) + +--- + +### CMS: **Sanity.io** + +**Rationale**: +- **Developer-Friendly**: Git-like workflow, version control for content +- **Flexible Schema**: Can model any content structure +- **Real-Time**: Live preview of content changes +- **Media Management**: Handles images, videos, files +- **Free Tier**: Generous limits for early stage +- **Self-Hosted Option**: Can run Sanity Studio anywhere + +**Alternatives Considered**: +- **Contentful**: More enterprise-focused, higher cost +- **Strapi**: Self-hosted but heavier infrastructure +- **MDX Files**: Simple but no non-technical user UI + +--- + +### Deployment: **Docker + nexus-vector (Self-Hosted)** + +**Rationale**: +- **Client Requirement**: Must be self-hosted on nexus-vector +- **Docker**: Consistent environments, easy to replicate +- **Nginx Reverse Proxy**: Handle SSL, routing, caching +- **CI/CD**: Can automate with Git hooks or GitHub Actions +- **Cost**: No third-party hosting fees + +**Deployment Stack**: +``` +nexus-vector (216.158.230.94) +├── Docker Container: next-app +│ ├── Next.js 14 production build +│ ├── Node.js 18+ runtime +│ └── Port: 3000 (internal) +├── Nginx Reverse Proxy +│ ├── SSL/TLS (Let's Encrypt) +│ ├── Domain: 1000planets.cloud +│ └── Port: 443 (external) +└── Sanity Studio (optional separate container) +``` + +--- + +### Analytics: **Plausible (Primary) + Google Analytics (Optional)** + +**Rationale**: +- **Plausible**: Privacy-focused, GDPR-compliant, lightweight +- **Google Analytics**: Optional for deeper insights +- **No A/B Testing** (initially): Keep it simple, iterate based on qualitative feedback + +--- + +### Additional Tools + +| Tool | Purpose | Rationale | +|------|---------|-----------| +| **TypeScript** | Type safety | Catch errors early, better DX | +| **Framer Motion** | Animations | Smooth, performant animations | +| **React Hook Form** | Forms | Trial signup, newsletter, contact | +| **Zod** | Validation | Type-safe form validation | +| **Resend** | Transactional email | Modern, developer-friendly | + +--- + +## Consequences + +### Positive +✅ Fast development velocity (proven stack) +✅ Excellent SEO out of the box +✅ Future-proof (can add features incrementally) +✅ Self-hosted (full control, no vendor lock-in) +✅ Spec-kit compliant (easy to document, test, deploy) + +### Negative +⚠️ Requires Node.js runtime (vs pure static) +⚠️ Need to manage Docker containers +⚠️ Sanity.io adds external dependency (but has self-hosted option) + +### Mitigations +- Use Docker Compose for easy container management +- Set up automated backups for Sanity content +- Document deployment process thoroughly +- Create rollback procedures + +--- + +## Implementation Plan + +1. ✅ Initialize Next.js 14 project with TypeScript +2. ✅ Configure Tailwind CSS + shadcn/ui +3. ✅ Set up Sanity.io project and schema +4. ✅ Create Docker configuration +5. ✅ Set up deployment pipeline +6. ✅ Configure analytics (Plausible) +7. ✅ Test on nexus-vector before launch + +--- + +## References + +- [Next.js Documentation](https://nextjs.org/docs) +- [Tailwind CSS](https://tailwindcss.com) +- [shadcn/ui](https://ui.shadcn.com) +- [Sanity.io](https://www.sanity.io) +- [Plausible Analytics](https://plausible.io) diff --git a/spec-kit/decisions/0002-brand-guidelines.md b/spec-kit/decisions/0002-brand-guidelines.md new file mode 100644 index 0000000..13dbf7c --- /dev/null +++ b/spec-kit/decisions/0002-brand-guidelines.md @@ -0,0 +1,333 @@ +# 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