Token reconciliation
Mapping between the design system's tokens.css and Gagan's colors_and_type.css. Same hex values, different names. This document exists so both files can converge on a single namespace before the app codebase starts.
Action required
Gagan's
colors_and_type.css uses a completely different token namespace than the design system. The hex values are identical, but the variable names diverge across surfaces, ink, spacing, type scale, and avatar palette. This will cause confusion the moment anyone tries to use both files. One namespace must win — the design system's tokens.css is the canonical source.
Surfaces
All four surface tokens share the same hex value but different names. Gagan's names are shorter but less systematic — they don't group under a common prefix.
| Design system | Gagan's file | Value | Severity |
|---|---|---|---|
--s-canvas |
--bg |
#F6F1E6 |
High |
--s-warm |
--bg-warm |
#F1E9D5 |
High |
--s-deep |
--bg-deep |
#E8DEC5 |
High |
--s-paper |
--paper |
#FBF8F0 |
High |
Recommendation
Adopt
--s-* prefix. It groups cleanly in autocomplete and is self-documenting ("surface"). Gagan should find-and-replace: --bg → --s-canvas, --bg-warm → --s-warm, --bg-deep → --s-deep, --paper → --s-paper.
Ink scale
Two of four ink tokens match. The body and hairline tokens diverge.
| Design system | Gagan's file | Value | Severity |
|---|---|---|---|
--ink |
--ink |
#171513 |
Match |
--ink-body |
--ink-soft |
#4A443D |
High |
--ink-mute |
--ink-mute |
#8A8276 |
Match |
--ink-line |
--line |
#DDD2B8 |
High |
Recommendation
--ink-body reads better than --ink-soft ("body text" is universally understood). --ink-line is more specific than --line and groups under the --ink-* namespace. Gagan should rename: --ink-soft → --ink-body, --line → --ink-line.
Dark mode
The design system has a full dark mode token set. Gagan's file only defines one dark surface token with a different name.
| Design system | Gagan's file | Value | Severity |
|---|---|---|---|
--dark-canvas |
--moments-bg |
#1E1A16 |
Medium |
--dark-elevated |
Not defined | #2A2521 |
Low |
--dark-border |
Not defined | #3D3630 |
Low |
--dark-text |
Not defined | #FBF8F0 |
Low |
Recommendation
Gagan's file doesn't need the full dark mode token set yet since his prototypes don't have a dark mode toggle. But
--moments-bg should be renamed to --dark-canvas for consistency. The name "moments" is from the landing page section — it shouldn't leak into the app's token namespace.
Accent tokens
All accent tokens match exactly — teal, coral, butter, and glass. No action needed.
| Design system | Gagan's file | Value | Status |
|---|---|---|---|
--teal | --teal | #0E7C66 | Match |
--teal-deep | --teal-deep | #0A5F4F | Match |
--teal-pale | --teal-pale | #D6EAE2 | Match |
--coral | --coral | #E76F51 | Match |
--coral-pale | --coral-pale | #FADED4 | Match |
--butter | --butter | #F4C94E | Match |
Semantic aliases
Gagan's file defines additional semantic aliases that the design system doesn't have. These aliases are thin wrappers — they point to existing tokens.
| Design system | Gagan's file | Resolves to | Severity |
|---|---|---|---|
| Not defined | --color-success |
var(--teal) |
Medium |
| Not defined | --color-warning |
var(--coral) |
Medium |
| Not defined | --color-fg |
var(--ink) |
Low |
| Not defined | --color-fg-soft |
var(--ink-soft) |
Low |
| Not defined | --color-fg-mute |
var(--ink-mute) |
Low |
| Not defined | --color-bg |
var(--bg) |
Low |
Recommendation
The design system already has
--success, --warning, --error as semantic tokens in tokens.css. Gagan's --color-success/--color-warning should use those directly. The --color-fg-* aliases add indirection without value — use --ink/--ink-body/--ink-mute directly.
Spacing scale
Both files use an 8px grid, but the naming convention and scale steps diverge significantly. This is the most structurally different area.
| Design system | Gagan's file | Value | Note |
|---|---|---|---|
--sp-1 | --space-1 | 4px | Same value, different prefix |
--sp-2 | --space-2 | 8px | Same value, different prefix |
--sp-3 | --space-3 | 12px | Same value, different prefix |
--sp-4 | --space-4 | 16px | Same value, different prefix |
--sp-5 | --space-5 | 20px | Same value, different prefix |
--sp-6 | --space-6 | 24px | Same value, different prefix |
--sp-8 (32px) | --space-7 (32px) | 32px | Same value, numbering diverges |
--sp-10 (40px) | --space-8 (44px) | Different values | Gagan has 44px; DS has 40px |
--sp-16 (64px) | --space-9 (64px) | 64px | Same value, numbering diverges |
| Not defined | --space-10 (88px) | 88px | Not on 8px grid |
| Not defined | --space-11 (120px) | 120px | Not on 8px grid |
| Not defined | --space-12 (160px) | 160px | Not on 8px grid |
Structural divergence
The numbering systems are incompatible. The design system uses
--sp-N where N roughly tracks the value (sp-8 = 32px, sp-10 = 40px). Gagan uses sequential numbering (space-7, space-8, space-9...) with different step sizes. Gagan also includes non-8px-grid values (44, 88, 120, 160px). One system needs to adopt the other. The design system's scale is more predictable. Gagan should map his values to the nearest --sp-* token and drop the off-grid steps, or the design system should formally add those breakpoints if they're needed for app layouts.
Type scale
Gagan's file defines a full type scale with fluid clamp values. The design system's tokens.css does not include a type scale — sizes are hardcoded per-component in shared.css. This is a gap in the design system, not an inconsistency from Gagan.
| Gagan's token | Value | Design system equivalent |
|---|---|---|
--t-hero | clamp(56px, 9.4vw, 132px) | No token; used inline in landing page |
--t-section | clamp(40px, 5.4vw, 64px) | No token; page title uses clamp(32px, 4vw, 48px) |
--t-h2 | clamp(32px, 4vw, 52px) | No token; ds-h2 hardcodes 24px |
--t-h3 | 28px | No token; ds-h3 hardcodes 18px |
--t-body-lg | 19px | No token |
--t-body | 17px | Hardcoded 15px in body |
--t-body-sm | 15px | No token |
--t-meta | 13px | No token |
--t-eyebrow | 12px | No token; eyebrows use 10-11px inline |
--t-micro | 11px | No token |
Recommendation
The design system should adopt Gagan's type scale tokens into
tokens.css. His naming convention (--t-*) is clean and the scale is well-considered. Note: the body font size differs — Gagan uses 17px (matching the landing page), the design system docs use 15px for information density. Both are valid; the app should use 17px (Gagan's value), while the docs site can keep 15px.
Avatar palette
The design system defines avatar colors as tokens. Gagan hardcodes them inline in JSX.
| Design system token | Value | Gagan's usage |
|---|---|---|
--av-you (#171513) |
#171513 |
Not used; "you" avatar uses --ink directly |
--av-coral (#E76F51) |
#E76F51 |
Hardcoded as { bg: '#FADED4', fg: '#8B3722' } |
--av-teal (#0E7C66) |
#0E7C66 |
Hardcoded as { bg: '#D6EAE2', fg: '#0A5F4F' } |
--av-butter (#D4940A) |
#D4940A |
Hardcoded as { bg: '#F5E4A8', fg: '#6B5208' } |
Structural mismatch
The design system defines single-color avatar tokens (
--av-coral etc.) — just the dot/badge color. Gagan uses paired bg/fg tuples for full avatar circles (e.g. pale coral bg + dark coral fg for text). Both approaches are valid, but they need to converge. The design system should expand avatar tokens to include both bg and fg for each tone: --av-coral-bg: #FADED4; --av-coral-fg: #8B3722.
Radius, motion, shadow
These three token groups match exactly across both files. No action needed.
| Category | Status |
|---|---|
Radius (--r-xs through --r-pill) | All match |
Motion (--ease-out, --ease-spring, --ease-ios, durations) | All match |
Shadow (--shadow-sm through --shadow-float) | All match |
Summary of required changes
Ranked by priority:
- Surface tokens — Gagan renames
--bg/--bg-warm/--bg-deep/--paperto--s-canvas/--s-warm/--s-deep/--s-paper - Ink tokens — Gagan renames
--ink-soft→--ink-body,--line→--ink-line - Spacing scale — Gagan adopts
--sp-*naming; the team decides on off-grid values (44, 88, 120, 160px) - Type scale — Design system adopts Gagan's
--t-*tokens intotokens.css - Avatar palette — Design system expands
--av-*tokens to bg/fg pairs - Dark mode — Gagan renames
--moments-bg→--dark-canvas - Semantic aliases — Gagan drops
--color-fg-*aliases, uses--ink-*directly
Needs team alignment
·
Source: Gagan's new_designs_gagan.zip · 2026-05-26