InnerOS/DESIGN.md

# Design System — Inner OS

## Product Context
- **What this is:** AI-driven inner development operating system — generates one personalized daily mental training task, explains why it's chosen, collects post-session reflection, updates user state, and delivers internal reward feedback.
- **Who it's for:** Solo inner development practitioners who want structured mental training without a human coach.
- **Space/industry:** Mental wellness / inner development (adjacent to Headspace, Calm, Waking Up)
- **Project type:** Web app (mobile-first, journal-width constrained)

## Aesthetic Direction
- **Direction:** Editorial/Organic hybrid — typographic warmth with natural earth tones
- **Decoration level:** Intentional — subtle warmth cues (cream background, soft rounded corners) without decorative blobs or gradients. The "decoration" IS the typography and whitespace.
- **Mood:** Calm companion. The UI should feel like a well-printed private journal, not a SaaS dashboard. Paper texture, ink-color text, breathing room. The app recedes; the practice is center stage.
- **Memorable thing:** "It feels like a private journal, not an app."
- **Reference sites:** None (greenfield design system)

## Typography
- **Display/Headings:** Fraunces (serif, wght 300-700, opsz 16-48) — Literary, warm serif with variable optical size. Feels like a book, not a browser. Soft curves and humanist proportions serve the private journal metaphor.
- **Body:** DM Sans (sans-serif, wght 400-500-700) — Clean geometric sans with humanist warmth. High x-height for readability at 16px.
- **UI/Labels:** DM Sans (500 weight) — Same family, slightly bolder.
- **Data/Tables:** DM Sans (tabular-nums enabled) — Built-in tabular figures for progress charts and metrics.
- **Code:** JetBrains Mono (developer tooling only, never user-facing)
- **Loading:** Google Fonts CDN with `font-display: swap`
- **Scale:**

| Level | Size / Line-height | Use |
|-------|-------------------|-----|
| xs    | 12px / 1.5 (18px) | Captions, timestamps |
| sm    | 14px / 1.5 (21px) | Secondary text, labels |
| base  | 16px / 1.6 (25.6px) | Body text |
| md    | 18px / 1.5 (27px) | Card headings, emphasized body |
| lg    | 22px / 1.4 (30.8px) | Section headings |
| xl    | 28px / 1.3 (36.4px) | Page titles |
| 2xl   | 36px / 1.2 (43.2px) | Hero/day heading |

## Color
- **Approach:** Restrained — one accent (amber), one secondary (sage), warm neutrals. Color is rare and meaningful — it signals action, progress, or reward, never decoration.

### Light Mode
| Token | Hex | Role |
|-------|-----|------|
| Primary/Accent | `#C8834A` (Amber) | CTAs, active states, streak indicators |
| Secondary | `#7A9A8B` (Sage) | Success states, progress fill, calm indicators |
| Background | `#FAF7F2` (Cream) | Page background |
| Surface | `#F3EFE8` (Sand) | Cards, elevated surfaces |
| Border | `#E6E0D4` (Stone) | Dividers, input borders |
| Text Primary | `#2C2416` (Ink) | Body text, headings |
| Text Secondary | `#6B5E4A` (Muted ink) | Captions, secondary labels |
| Text Tertiary | `#9B8E7A` (Faded ink) | Placeholders, disabled |

### Semantic
| Token | Hex | Use |
|-------|-----|-----|
| Success | `#7A9A8B` (Sage) | Completion confirmations, progress |
| Warning | `#C8834A` (Amber) | Streak-at-risk, attention needed |
| Error | `#C45A4A` | Session expired, validation errors |
| Info | `#5A8AB5` | Neutral status, tips |

### Dark Mode
- **Strategy:** Redesign surfaces, reduce saturation 15%. Warm dark background instead of cool dark. Amber and sage stay — they read warm against dark.
- **Tokens:**

| Token | Hex | Role |
|-------|-----|------|
| Background | `#1E1A14` (Night ink) | Page background |
| Surface | `#292418` (Dark sand) | Cards, elevated surfaces |
| Border | `#3D3528` (Dark stone) | Dividers, input borders |
| Text Primary | `#F3EFE8` (Warm sand) | Body text, headings |
| Text Secondary | `#B8A892` (Muted cream) | Captions, secondary labels |
| Text Tertiary | `#8A7D6B` | Placeholders, disabled |

## Spacing
- **Base unit:** 8px
- **Density:** Comfortable

| Token | Value | Use |
|-------|-------|-----|
| 2xs | 4px | Icon-text gap, inline spacing |
| xs | 8px | Tight gaps, chip padding |
| sm | 12px | Card padding (compact) |
| md | 16px | Standard padding, card gaps |
| lg | 24px | Section gap, card padding (comfortable) |
| xl | 32px | Page-level spacing |
| 2xl | 48px | Major section divisions |
| 3xl | 64px | Top/bottom page breathing room |

## Shape
- **Border radius (hierarchical):**

| Token | Value | Use |
|-------|-------|-----|
| sm | 6px | Inputs, buttons |
| md | 12px | Cards, modals |
| lg | 16px | Large surfaces |
| full | 9999px | Pills, badges, stage indicators |

## Layout
- **Approach:** Hybrid — single-column journal-width (640px max, centered) for reading/reflection pages; grid-disciplined for progress charts
- **Grid:** 1 column (mobile), centered 640px (desktop)
- **Max content width:** 640px
- **Navigation:** Bottom tab bar, 4 tabs (Today, Progress, Rewards, Settings), fixed position, 56px height, 44px minimum touch targets

## Motion
- **Approach:** Intentional — transitions that aid comprehension without calling attention
- **Easing:** enter(ease-out), exit(ease-in), move(ease-in-out)
- **Duration:**
  - Micro: 150ms (button hover)
  - Short: 200ms (page transitions, fade + 4px Y shift)
  - Medium: 400ms (reward animations, scale + fade)
  - Long: 600ms (progress bar fill)

## Accessibility
- **Baseline:** WCAG AA
- **Touch targets:** 44px minimum
- **Contrast:** All body text meets 4.5:1 against background
- **Keyboard:** All interactive elements keyboard-navigable
- **Focus:** Visible focus ring (amber outline, 2px) on all interactive elements
- **Screen readers:** ARIA landmarks on all pages (banner, main, navigation, complementary)

## Decisions Log
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-05-20 | Initial design system created | Created by /design-consultation based on CEO plan, eng review, and 10 design review decisions |
| 2026-05-20 | Practice journal aesthetic | User's memorable thing: "It feels like a private journal, not an app" |
| 2026-05-20 | Fraunces + DM Sans typography | Literary serif for journal feel; clean sans for readability |
| 2026-05-20 | Cream/Amber/Sage/Ink palette | Warm, grounded, non-clinical colors that serve the journal metaphor |
| 2026-05-20 | Journal-width max 640px centered | Matches reading column width; mobile-first, not responsive-gimmick |
| 2026-05-20 | Bottom tab bar navigation | Standard mobile pattern, no learning curve, 4 primary destinations |
| 2026-05-20 | Calm companion emotional tone | Warm but not saccharine, grounded but not clinical |