Oter — Design System Tokens

Status: Draft for reconciliation · Last updated: 2026-06-03 Goal of this doc: consolidate every design token across our three sources so we can agree on the final token set the codebase will be built on. Where the sources disagree or a token is missing, it’s flagged as a DECISION below.

0. Centralization sweep — mapping table & progress (started 2026-06-04)

Goal: make Oter.* the single color system across all platforms. Two parallel systems exist today: the new Oter.* tokens (good, ~4.4k usages) and a legacy OterDesignSystem / OterColors / OterGradients (ui/Color.kt, ui/DesignSystem.kt).

Canonical replacement map (every sweep edit must follow this — no guessing):

Rules: (1) only replace a hardcoded Color(0x..) when its hex exactly matches a token above — leave domain/macro colors (FatColor, CarbColor, category hexes that aren’t tokens) alone. (2) Static/non-composable contexts (enums, top-level vals, default args) use DarkOterColors.*. (3) Non-color legacy (OterDimensions, OterShapes, ComponentPresets) is a separate track — out of scope for the color sweep.

Progress

• Tag tokens (tagYellow/Pink/Purple) added to OterColorScheme.
• ButtonType.kt → DarkOterColors (static ctx).
• ScheduledTransactionForm.outlinedFieldColors() → Oter.colors.
• MaterialTheme.colors → Oter.colors — DONE across all platforms (171 commonMain+desktop + 7 android/iOS/jvm). 0 MaterialTheme.colors.<field> left. Compiles green on metadata(common)/JVM/desktop/iOS.
• Hardcoded Color(0x..) sweep — N/A: the remaining token-hex literals are all intentional categorical palette/data colors (category/chart/meal/event coloring, commented “palette data — not theme chrome”) or token definitions. Converting them would be wrong.
• Layout token layer added (OterScales.kt) — closes the gap that blocked legacy retirement: Oter.border (thin/medium/thick = 1/2/3), Oter.iconSize (xs..huge = 12/16/20/24/32/40/48), Oter.size (control heights 36/48/56, appBar 56, touchMin 44, avatars 32→120, max-widths card/dialog/content). Wired into the Oter accessor; compiles clean.
• Legacy retirement — DONE. SharedComponents.kt was 100% dead code → deleted. ui/DesignSystem.kt deleted. OterColors/OterGradients stripped from ui/Color.kt (domain flats kept), OterDimensions from ui/Dimension.kt (picker dims kept), OterShapes from ui/Shape.kt (Material Shapes kept). Finance OterDesignSystem.* refs → Oter.radius/Oter.elevation. Dead anchor constants removed from desktop ui/theme/Colors.kt. Zero OterDesignSystem/OterColors/OterGradients/OterDimensions/OterShapes references remain. Oter.* is now the single design system. Compiles clean on JVM/iOS/desktop (the only build error is an unrelated in-progress AuthViewModel.refreshUserTier visibility edit).

Layout token reference (new)

Android note: compileAndroidMain currently fails on an unrelated in-progress edit in api/HttpClientConfig.kt (configureAuth refactor) — not part of this sweep. The color migration itself is validated on the other four targets.

Sources of truth (today there are three — that’s the problem)

The product is dark-first (indigo-on-slate); light theme inverts surfaces and keeps the brand hue. The end state we want: Figma variables and code tokens are 1:1, name-for-name. This doc is the gap analysis to get there.

1. Token architecture

Figma models tokens in three tiers; code currently has only the middle tier.

Tier 1  PRIMITIVES        raw palette (indigo/500, slate/900, red/400…)   ← Figma only
Tier 2  SEMANTIC          themed aliases (brand/primary, status/danger…)  ← Figma + Code
Tier 3  SCALES            spacing / radius / elevation / motion / z       ← Figma(partial) + Code

DECISION 1 — Do we mirror Tier 1 (primitives) in code? Code jumps straight to semantic tokens. Figma has a 40-entry Primitives collection that semantic tokens alias. Options:

• (a) Keep code semantic-only (current). Simpler, but the palette lives only in Figma.
• (b) Add an internal OterPalette object (raw colors) that OterColorScheme references, mirroring Figma exactly. Recommended for traceability.

2. Color

2.1 Primitives (Figma Primitives collection — single mode)

2.2 Semantic — themed (Figma Color collection, modes Dark / Light)

Each row = one semantic variable aliasing a primitive per mode. ✅ = present in code (OterColorScheme).

Note *-light flips meaning by theme: in dark it’s a lighter tint (red/400), in light it’s a darker shade (red/600) — i.e. “the legible accent tint for the current theme.”

2.3 Eisenhower (theme-independent in both Figma & code)

2.4 Auth gradient

linear-gradient(to bottom right, #4338CA, #6B21A8) (indigo-700 → purple-800).

• Code: authGradientStart / authGradientEnd + authGradient Brush. ✅
• Figma: primitives exist (indigo/700, purple/800) but there is no gradient variable (Figma can’t store gradients as variables). Documented, not tokenized.

3. The translucent-fill problem (QuadBadge & friends) — DECISION 2: RESOLVED ✅

The Eisenhower badges use a translucent fill + soft stroke + solid light text:

fill   = categoryColor @ 18%   ← now a *-subtle token
stroke = categoryColor @ 35%   ← now a *-outline token
text   = <color>-light  @ 100%

Why paint-opacity failed (the original symptom): Figma hides the opacity field once a color variable is bound to a fill, and re-binding resets opacity to 100%. The QuadBadge Schedule fill silently reverted to solid twice because of this — paint opacity is not durable when a variable is bound.

Resolution — alpha is now baked into tokens. Implemented 2026-06-04:

Tier 1 — new primitive alpha colors (Primitives collection, scopes []):

Tier 2 — new semantic tokens (Color collection, same value Dark/Light, aliasing the primitives):

Decisions taken (defaults — adjust if needed):

• (a) Scoped to the 4 colors QuadBadge actually uses (not all 6 Eisenhower colors). Easy to extend.
• (b) All four badges now bind to the eisenhower/* namespace (Do/Delegate were previously on status/danger/status/warning — rebound for a consistent namespace and theme-independent behaviour).
• (c) Canonical alphas locked to 18% fill / 35% outline. (The old QuadrantButton 0.1–0.18 / 0.5 values should be migrated to these.)
• (d) Naming chosen: -subtle (fill) / -outline (stroke), extending the brand/tint-* alpha precedent.

QuadBadge variant bindings are now 100% token-driven (paint opacity = 1.0; transparency comes from the variable), so the solid-fill regression cannot recur.

4. Spacing — 4px base (Figma Spacing ✅ matches code OterSpacing)

No conflicts. (Note: there is intentionally no 12px spacing step; 12 exists only in Radius.)

5. Radius (Figma Radius ✅ matches code OterRadius)

QuadBadge uses sm (6). No conflicts.

6. Elevation / Motion / Z-index — code-only (not in Figma variables)

These live only in OterScales.kt (mirroring the prototype spec). Figma has no variables for them. DECISION 3: leave as code-only, or also create Figma number variables for parity? (Low priority — shadows/motion rarely bound in Figma.)

• Elevation: none 0 · sm 1 · md 4 · lg 10 · xl 20 (dp; maps from CSS box-shadow y-offsets)
• Motion: easing cubic-bezier(.4,0,.2,1); fast 150ms · base 200ms · slow 300ms
• Z-index: base 0 · dropdown 1000 · sticky 1020 · fixed 1030 · modalBackdrop 1040 · modal 1050 · toast 1060 · tooltip 1070

7. Typography — code-only (not in Figma variables)

Family: Lexend (mobile) / Geist (web/desktop), mono = Geist Mono. Defined in OterTypeScale.kt. Figma has no type variables/styles captured yet — DECISION 4: publish these as Figma text styles for parity?

8. Summary of open decisions

9. Token gaps to close in code (once decisions land)

• dangerLight, warningLight, infoLight (theme-aware) — added to OterColorScheme
• tagYellow, tagPink, tagPurple
• Eisenhower *-subtle (18%) and *-outline (35%) — created in Figma and mirrored in OterColorScheme (urgencyUrgent/Moderate/Not + importanceHigh, each Subtle/Outline).
• OterQuadBadge composable + QuadBadgeType enum — ui/components/primitives/OterBadges.kt, token-driven, compiles on JVM.
• (optional) OterPalette raw-primitive layer — pending DECISION 1
• Migrate the legacy QuadrantButton (EisenhowerQuadrantSelector.kt) off its hardcoded 0.1–0.18 / 0.5 alphas onto the new subtle/outline tokens.