Get started

Tokens are the single source of truth for color, type, spacing, radius, stroke, and elevation. You never hand-author these values in product code — you reference the generated token and let it resolve. This page covers everything you need to wire the system into iOS, Android, or a Figma file, and how new tokens get added.

The token model

There are two tiers, and the rule between them is the whole game:

Components consume semantics. Always. A button reads color.background.action.primary.default — not color.brand.500, and never #4B56C7. The semantic layer is what lets a single rebrand, a dark theme, or a platform tweak flow through the whole app without touching a component.

Use the token, not the value

This is the one mistake that quietly breaks the system. When you inspect a layer in Figma, the dev panel resolves a semantic token down to a literal — you’ll see something like background → #4B56C7. That hex is the answer to “what color is it right now,” not the thing you should paste.

Same token color.background.action.primary.default, the right way and the wrong way on each platform:

Naming per platform

One canonical token, shaped to each platform’s convention. The name is the same across the two frameworks withina platform (SwiftUI wraps UIKit; Compose reads the same XML resource), so there’s no framework sub-switch to learn.

In short: dotted in Figma, camelCase on iOS, snake_caseon Android. The platform switch in the floating bar on every token page shows you the exact identifier for the platform you’re building for.

Light, Dark & platform modes

A semantic token resolves to a different primitivedepending on the active mode. You don’t branch on theme in code — you reference the one token and the generated file carries the right value for each appearance.

Type works the same way across iOS and Android: font family and the size / line-height pairs resolve per platform. Flip the platform switch on the Tokens page to compare. The takeaway is identical — reference the token; the mode resolution is not your job.

Export & use the tokens

Open any token page (Primitives or Semantics → Tokens). The floating bar carries a platform switch and a Download menu — one canonical deliverable per platform, in its native format.

A button background, end to end, on each platform:

// iOS — UIKit
button.backgroundColor = TellusTokens.colorBackgroundActionPrimaryDefault
// iOS — SwiftUI
.background(Color(TellusTokens.colorBackgroundActionPrimaryDefault))

<!-- Android — XML -->
<View android:background="@color/color_background_action_primary_default" />

// Android — Compose
Modifier.background(colorResource(R.color.color_background_action_primary_default))

Adding or requesting a token

Tokens originate in Figma and flow into the portal through the Tellus Token Sync plugin. You don’t edit the JSON by hand — you change the variable in Figma, sync, review the diff, and apply.

1. 1

   Edit in Figma

   Add or change the variable in the right file — primitives in Foundations 2.0, semantics in Tellus UI Kit. A new semantic must alias a primitive (never a raw value).
2. 2

   Run the plugin → Sync

   The plugin auto-detects which file is open and pushes that source to the portal. Run it once per file — primitives and semantics each.
3. 3

   Review the diff in Admin

   The portal stages the change and shows an added / changed / removed diff. Apply requires bothprimitives and semantics to be staged, so a semantic can never reference a primitive that isn’t there yet.
4. 4

   Apply

   Applying regenerates every platform file, refreshes the docs, and writes a changelog entry. New tokens appear on the docs automatically — there’s no hardcoded list to update.

Not an admin? Request the token from the design-system owners with the intent (what it’s for), and they’ll add it. Every applied change is visible on the Changelog.

Reference