ikie on the web and on iPhone is the same app. The look can follow each platform, but if the purple is a different purple, or a sheet rises at a different speed, it stops feeling like one app.
So colors, type, spacing, corners, shadows and motion are written once, as tokens. Neither the web nor iOS copies the values by hand; both use files generated from them.
- 10/05 17:29Tokens, components, the /design reference page, contrast and screen CSS tests (#31)
- 10/05 18:02Redone on iOS grammar: Radix colors, Pretendard, spring motion (#35)
- 10/05 22:50The iOS app skeleton gets Tokens.swift from the same JSON (#49)
- 10/14Timeline hour labels count as text, and join the contrast rules (#410)
- 10/17Literal numbers blocked in the iOS calculation and use-case layers (#676)
One JSON source
Tokens are JSON in the W3C design tokens format (DTCG). Three files (light colors, dark colors, and the rest: type, spacing, motion and so on) hold 165 tokens. npm run tokens uses Style Dictionary to generate two files.
- Source
packages/tokens/tokens/*.json165 tokens. Colors point at Radix Colors steps by name, and each value says where it's used.
- Web
apps/web/app/tokens.cssCSS variables. Light is the default; when the device is in dark mode or data-theme is dark, only colors change.
- iOS
apps/ios/Ikie/Design/Tokens.swiftSwiftUI values: colors as light and dark pairs, motion as Animation.spring, shadows as a single layer.
- Reference page
/designDraws tokens and components with the real CSS, light and dark side by side. New components are added here too.
This is how often the iOS app calls the generated values.
Colors are called by name
There are 56 color tokens. Screens don't call a value like #6e56cf; they call meanings like accent (main actions, the selected day, checks), quiet (secondary text) and now (the now line). Those names in turn point at steps of Radix Colors. Rather than building our own scales, we used an open source set whose light and dark pairs and per-step uses are already defined.
| Name | Used for | Light | Dark |
|---|---|---|---|
| text | Body text | slate 12 | slate dark 12 |
| quiet | Secondary text | slate 11 | slate dark 11 |
| accent | Main actions, selected day, checks | violet 9 | violet dark 9 |
| event | Event blocks without a calendar color | violet 3 | violet dark 4 |
| sheet | Bottom sheet background | slate 3 | slate dark 2 |
35 of the 56 change with the mode. Of those, 31 light values and 33 dark values point at Radix steps; the rest, like the white background, are chosen on purpose. The 21 that must look the same in both modes, like the brand gradient and the colored icon tiles in settings, don't change. A test checks that "the colors dark mode changes" are exactly those 35, so adding a color and forgetting its dark value is blocked.
Tests measure contrast
Text needs 4.5:1 against its background, and graphics like icons and lines need 3:1 (WCAG 2.2 1.4.3 and 1.4.11). The test lists 48 pairs of "this text color sits on these backgrounds" and measures each in light and dark. That's 96 checks.
The rules grew with use. At first the timeline's hour labels (9 AM, 10 AM…) used faint. faint is for graphics like placeholders and disabled things, so it only keeps 3:1. But an hour label is text people read. So the hour labels on the web and iOS timelines both moved to quiet and are measured at 4.5:1 (#410). The same PR added the small tag background inside list rows (badge) to the backgrounds quiet sits on, and faint's description now says "not for text people read".
Write down where each color sits as pairs, and measure the pairs in both modes. Don't call it fine by eye.
Motion uses the same springs
iOS moves with SwiftUI springs (response and dampingFraction). Web CSS has no springs. So the same spring is sampled at 25 points over a set duration and written as a CSS linear() curve. One token carries both: the web reads the curve, iOS reads the spring values.
| Spring | SwiftUI values | Web duration | Used for |
|---|---|---|---|
| snappy | response 0.3, damping 0.86 | 390ms | Picking, toggling |
| smooth | response 0.45, damping 1 | 610ms | Moving into place |
| bouncy | response 0.4, damping 0.7 | 590ms | Done checks |
While writing this post we recomputed all three curves from the spring formula. All 25 points matched within 0.0005 (rounding at the third decimal). But until now no test held them to it. Edit a curve by hand and only the web would move differently. So we added a test: it computes each curve from the spring values in the JSON and fails if any point is off by more than 0.001. Changing a response from 0.3 to 0.35 breaks it, as it should.
On devices with reduce motion turned on, the web sets every duration token to 0ms. Screens don't have to turn motion off one by one.
Text follows the size people chose
The font is Pretendard. On Japanese and Chinese screens, that language's Noto Sans follows it, so kanji, kana and hanzi take the shapes that language expects. The same character can look different from language to language.
Font sizes are written in pt in the JSON. The web turns them into rem so they follow the browser's default font size, and iOS ties them to text styles (body, headline and so on) so they follow Dynamic Type. Spacing and box sizes stay put. In both apps the text grows and the frame stays.
Write a number and a test stops it
Tokens alone don't keep values together; once screens start writing numbers, they drift apart again. So tests block it.
- Web screen CSS: colors (
#hex,rgb(),oklch(),white) and font sizes or weights written as numbers are blocked. - Missing tokens:
var(--no-such-name)silently drops out in the browser. The test checks every CSS variable a screen calls exists. - Generated files: tokens.css and Tokens.swift must match what the JSON generates, character for character.
- iOS calculation and use-case layers: literal numbers are blocked, and each remaining one is listed per file with its reason (Gregorian calendar math, HTTP statuses and so on).
iOS screen files aren't held to this yet. Most call tokens, but some spacing and sizes are still written as numbers. That's the next place to close.
What we learned
- Values in one place, platform shapes in the generator. The JSON doesn't know about platforms. rem, Animation.spring and single-layer shadows are decided by the build script.
- Name by meaning. Screens don't ask for purple; they ask for "main action". So screens don't need to know about dark mode, and changing a color doesn't mean hunting through screens.
- Measure "looks the same" too. Contrast, and how the web and iOS move, become tests once you compare them as numbers.
The wider principle of doing each job in one place is in the principles post.