ikieEngineeringGet started
All posts

Design systemTokensWeb and iOSAccessibility

Colors, type and motion live in one JSON, shared by web and iOS

ikie's colors, type, spacing, corners and motion are 165 tokens. Written once in JSON, they become web CSS and iOS Swift, and tests measure 96 contrast pairs and the spring curves. Screen CSS can't spell out a color or font size as a number.

한국어

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.

  1. 10/05 17:29Tokens, components, the /design reference page, contrast and screen CSS tests (#31)
  2. 10/05 18:02Redone on iOS grammar: Radix colors, Pretendard, spring motion (#35)
  3. 10/05 22:50The iOS app skeleton gets Tokens.swift from the same JSON (#49)
  4. 10/14Timeline hour labels count as text, and join the contrast rules (#410)
  5. 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.

  1. Sourcepackages/tokens/tokens/*.json

    165 tokens. Colors point at Radix Colors steps by name, and each value says where it's used.

  2. Webapps/web/app/tokens.css

    CSS variables. Light is the default; when the device is in dark mode or data-theme is dark, only colors change.

  3. iOSapps/ios/Ikie/Design/Tokens.swift

    SwiftUI values: colors as light and dark pairs, motion as Animation.spring, shadows as a single layer.

  4. Reference page/design

    Draws tokens and components with the real CSS, light and dark side by side. New components are added here too.

People edit only the JSON. Both generated files say 'don't edit' on their first line, and a test checks they match what the JSON generates.

This is how often the iOS app calls the generated values.

See the numbers
GroupCalls in iOS code
Color Tokens.Colors922
Spacing Tokens.Space614
Spring Tokens.Spring137
Font size Tokens.FontSize135
Font weight Tokens.FontWeight83
Control size Tokens.Control69
Corner Tokens.Radius57
Counted across 182 Swift files in apps/ios, excluding the generated Tokens.swift. All groups together come to 2,108.

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.

NameUsed forLightDark
textBody textslate 12slate dark 12
quietSecondary textslate 11slate dark 11
accentMain actions, selected day, checksviolet 9violet dark 9
eventEvent blocks without a calendar colorviolet 3violet dark 4
sheetBottom sheet backgroundslate 3slate 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.

LightDark
See the numbers
PairLightDark
Secondary text quiet / background5.94:19.06:1
White text / purple button5.39:15.39:1
Accent text / soft purple5.51:17.34:1
Placeholder faint / background (graphic)3.3:13.68:1
Now line / background (graphic)5.39:13.5:1
Contrast for a few pairs. Text must pass 4.5:1 and graphics 3:1 for the test to pass.

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.

SpringSwiftUI valuesWeb durationUsed for
snappyresponse 0.3, damping 0.86390msPicking, toggling
smoothresponse 0.45, damping 1610msMoving into place
bouncyresponse 0.4, damping 0.7590msDone 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.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.