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