# Retain Design System

A comprehensive design language for the Retain iOS app — colors, typography, spacing, and component patterns extracted from the live codebase.

SwiftUI · iOS 17+ · v1.0

## Colors

All colors are defined in `DesignSystem/Colors.swift` and accessed via `Color.retain.*`

### Brand Primary

Primary Light
#7B96DB
Primary
#5A7BCF
Primary Dark
#4A69BD

### Warm Accent

Accent Light
#E8956A
Warm Accent
#B85520

### Sign-In Gradient (Forest Green)

Gradient Top → Bottom
#3D5A4E → #344A40

### Warm Palette (Home)

Warm Background
#FFFFFF
Warm Card
#FBF6F4
Warm Border
#F3EBE7
Warm Divider
#FFFBF9

### Neutral Scale

Neutral 50
#FAFAFA
Neutral 100
#F5F5F5
Neutral 200
#E5E5E5
Neutral 300
#D4D4D4
Neutral 400
#A3A3A3
Neutral 500
#737373
Neutral 600
#525252
Neutral 700
#404040
Neutral 800
#262626
Neutral 900
#171717

### Semantic Colors

Blue 50
#EFF6FF
Blue 500
#3B82F6
Blue 600
#2563EB
Blue 700
#1D4ED8
Rose 50
#FFF1F2
Rose 500
#F43F5E
Green 50
#F0FDF4
Green 500
#22C55E
Amber 50
#FFFBEB
Amber 500
#F59E0B
Violet 50
#F5F3FF
Violet 500
#8B5CF6
Orange 50
#FFF7ED
Orange 500
#F97316
Red 50
#FEF2F2
Red 500
#EF4444
Purple 50
#FAF5FF
Purple 600
#9333EA
Teal 600
#0D9488

### Chat Colors

User Message
#5A7BCF @ 12%
Mention
#5A7BCF @ 15%
Assistant Message
secondaryBg

## Typography

Dual-mode system: Charter (serif) for reading surfaces, SF Pro (system) for control surfaces. Defined in `Typography.swift`, `AppFont.swift`, `StyleConfig.swift`.

### Type Scale — Control Surface (SF Pro)

Large Title The quick brown fox 34pt · Bold
Title The quick brown fox jumps over 22pt · Semibold
Headline The quick brown fox jumps over the lazy dog 17pt · Semibold
Body The quick brown fox jumps over the lazy dog 17pt · Regular
Callout The quick brown fox jumps over the lazy dog 16pt · Regular
Caption The quick brown fox jumps over the lazy dog 12pt · Regular
Caption 2 The quick brown fox jumps over the lazy dog 11pt · Regular

### Type Scale — Reading Surface (Charter)

Charter Roman Conversations become memories, memories become actions. Charter-Roman
Charter Bold Card titles, content headings, emphasis Charter-Bold
Charter Italic Quoted text, secondary emphasis Charter-Italic

### Monospace (Code)

JetBrains Mono let greeting = "Hello, Retain" Regular · Bold · Medium

### Usage Guidelines

Surface | Font | When to Use
--- | --- | ---
Reading | Charter | Titles, body text, content headings, card titles, quotes, long-form
Control | SF Pro | Buttons, tabs, pills, badges, metadata, navigation, search, labels
Code | JetBrains Mono | Code blocks, technical content, monospaced displays

## Spacing

7-step spacing scale defined in `DesignSystem/Spacing.swift`. All layout uses these tokens exclusively.

xs
4pt
sm
8pt
md
12pt
lg
16pt
xl
24pt
xxl
32pt
xxxl
48pt

### Corner Radius

sm
8pt
md
12pt
lg
16pt
xl
22pt
xxl
28pt
bubble
16pt
bubbleTail
8pt

## Buttons

Three button styles plus a floating action button. Height: 56pt, corner radius: 16pt. Defined in `DesignSystem/RetainButton.swift`.

Style | Background | Text Color | Shadow
--- | --- | --- | ---
Primary | #3D5A4E → #344A40 gradient + white 20% stroke | White | rgba(52,74,64,0.25) · r12 · y4
Secondary | #FFFFFF | Neutral 900 | rgba(0,0,0,0.06) · r16 · y4
Destructive | #FFFFFF | Red 500 (#EF4444) | rgba(0,0,0,0.06) · r16 · y4
Compose FAB | #B85520 | White | rgba(184,85,32,0.3) · r12

### Button States

State | Behavior
--- | ---
Loading | ProgressView spinner replaces/accompanies text, button disabled
Disabled | 50% opacity, tap disabled
Default | Full opacity, interactive

## Components

Reusable building blocks from the `DesignSystem/` and `Features/` directories.

RetainCard
Generic content container with padding, rounded corners, and subtle shadow.
RetainCard
Surface-colored container with padding, corner radius, and elevation shadow
DesignSystem/RetainCard.swift
SkeletonView
Shimmer placeholder system — conversation cards, chat messages, empty states
DesignSystem/SkeletonView.swift
⚠️
Something went wrong
ErrorView / LoadingView
Full-screen centered states for loading spinners and error messages with retry
DesignSystem/ErrorView.swift
Review quarterly OKRs
High Product
TaskCardView
Checkbox + Charter title + priority/category badges with color coding
Features/Tasks/TaskCardView.swift
How was my meeting?
Your standup covered 3 action items and a blocker on the API migration.
Chat Bubbles
User (primary @ 12%) and assistant (secondary bg) with 16pt bubble radius
Features/Chat/ChatView2.swift
RR
Ryan Rapp
Pro Member since 2024
ProfileHeaderView
Avatar with initials fallback, name, email, plan badge, membership date
Features/Profile/ProfileHeaderView.swift

## Navigation

5-tab bottom navigation with a centered compose FAB. Active state uses warm accent (#B85520).

🏠Home
⏱Memories
✏️
⚡Actions
👤Profile

### Navigation Structure

Element | Spec
--- | ---
Tab bar | 5 items, center is 48pt circular FAB (warm accent), standard tab icons below
Active color | #B85520 warm accent
Inactive color | System tertiary label
Badge | Unread dot on Actions & Profile tabs; count badge on Actions
Routing | NavigationStack with path-based routing, 10 screen destinations
Back gesture | Edge swipe — 60pt trigger zone, 120pt vertical tolerance

## Memory Types

9 distinct memory categories, each with a unique icon, color, and background.

⚡
Quick Capture
👥
Meeting
🤝
One-on-One
🎙️
Interview
❓
Q&A Session
✅
Action Plan
⚖️
Decision Record
📖
Research Notes
💡
Idea Brainstorm

## Badges

Color-coded badge system for task priority and category.

### Priority

● High ● Medium ● Low None

### Category

Product Finance Engineering Design Personal Research

## Icon System

SF Symbols throughout with consistent sizing. No custom icon library — all icons from Apple's system set.

### Core Navigation Icons

Tab | SF Symbol | Usage
--- | --- | ---
Home | house.fill | Home tab
Memories | timelapse | Memories tab
Compose | pencil.line | Center FAB
Actions | bolt.fill | Actions tab (with badge)
Profile | person.fill | Profile tab

### Common Action Icons

Action | SF Symbol
--- | ---
Checkmark | checkmark / checkmark.circle
Error/Warning | exclamationmark.triangle
Play | play.fill
Record | mic.fill / waveform
Meeting | person.2.fill
Chat | bubble.left.and.bubble.right.fill
Checklist | checklist
Knowledge | book.fill
Ideas | lightbulb.fill

## Figma Setup Guide

How to translate these tokens into your Figma design system.

### 1. Color Variables

Create a Figma Variables collection called Retain/Colors with these groups. Use variable modes for Light/Dark where iOS uses system-adaptive colors.

Group | Variables | Note
--- | --- | ---
Brand | primary, primary-light, primary-dark | Fixed hex values
Accent | warm-accent, warm-accent-light | Fixed hex values
Surface | surface, surface-secondary, surface-tertiary | Light/Dark modes
Text | text-primary, text-secondary, text-tertiary | Light/Dark modes
Warm | warm-bg, warm-card, warm-input, warm-border, warm-divider | Light mode only
Neutral | 50 through 900 (10 steps) | Fixed hex values
Semantic | blue, rose, green, amber, violet, orange, red, purple, teal (50–700 each) | Fixed hex values
Chat | chat-user, chat-assistant, mention | Derived with opacity
System | separator, destructive, success, warning | Light/Dark modes

### 2. Typography Styles

Create two style families. Use Charter (bundled, available in Figma) for reading and SF Pro for controls.

Style Name | Font | Size | Weight
--- | --- | --- | ---
Control/LargeTitle | SF Pro Display | 34 | Bold
Control/Title | SF Pro Display | 22 | Semibold
Control/Headline | SF Pro Text | 17 | Semibold
Control/Body | SF Pro Text | 17 | Regular
Control/Callout | SF Pro Text | 16 | Regular
Control/Caption | SF Pro Text | 12 | Regular
Control/Caption2 | SF Pro Text | 11 | Regular
Reading/Body | Charter | 17 | Roman
Reading/Body Bold | Charter | 17 | Bold
Reading/Body Italic | Charter | 17 | Italic
Code/Regular | JetBrains Mono | 14 | Regular

### 3. Spacing & Radius Variables

Create a Retain/Spacing number variables collection.

Token | Value | Usage
--- | --- | ---
spacing/xs | 4 | Tight inline spacing
spacing/sm | 8 | Icon-to-text, compact padding
spacing/md | 12 | Default internal padding
spacing/lg | 16 | Section padding, card padding
spacing/xl | 24 | Major section gaps
spacing/xxl | 32 | Screen margins, large gaps
spacing/xxxl | 48 | Hero spacing
radius/sm | 8 | Inputs, small elements
radius/md | 12 | Cards, badges
radius/lg | 16 | Buttons, chat bubbles
radius/xl | 22 | Modals, pills
radius/xxl | 28 | Sheets, overlays

### 4. Component Structure

Create these as Figma components with variants and auto-layout.

Component | Variants | Key Properties
--- | --- | ---
Button | Primary, Secondary, Destructive × Default, Loading, Disabled | h56, r16, full-width, headline font
FAB | Default | 48×48 circle, warm accent bg
Card | Warm, Simple, Default | r12, lg padding, subtle shadow
TaskCard | By priority × By category | Checkbox + Charter title + badges
ChatBubble | User, Assistant | r16 (r8 tail corner), max 85% width
Badge | Priority (High/Med/Low) + Category (6 types) | Pill shape, border, semantic colors
MemoryBadge | 9 memory types | Icon + colored background + label
TabBar | 5 tabs with active states | Center FAB, warm accent active
Skeleton | Card, Message, List | Shimmer gradient placeholder
EmptyState | Default | Icon + title + subtitle + CTA
ErrorState | With/without retry | Warning icon + message + button
ProfileHeader | Default | Avatar (initials fallback) + info

## Code Reference

Quick reference for how tokens are accessed in the SwiftUI codebase.

// Colors Color.retain.primary Color.retain.warmAccent Color.retain.neutral500 // Typography (Control surface) .font(.retain.headline) .font(.retain.body) // Typography (Reading surface) .font(AppFont.charter(14, weight: .bold)) .font(AppFont.charterItalic(16)) // Spacing .padding(Spacing.lg) .padding(.horizontal, Spacing.xl) // Corner Radius .clipShape(RoundedRectangle(cornerRadius: CornerRadius.lg)) // Buttons RetainButton(title: "Save", style: .primary) { save() } RetainButton(title: "Delete", style: .destructive, isLoading: true) { delete() }