Skip to content
v0.1.1

Foundations

Design tokens

The Stance token pipeline: one W3C-format source that generates CSS, TypeScript, Swift and Kotlin, with validation, parity and contrast checks.

Every value in Stance is written once, in a platform-independent source that follows the W3C Design Tokens format. A generator validates the source and produces the files each platform consumes.

Pipeline

text
packages/tokens/source/**/*.json      the only place values are written
        │  validate → resolve aliases → generate
        ├── CSS custom properties           @bindshq/stance-tokens/css
        ├── TypeScript constants            @bindshq/stance-tokens
        ├── Tailwind v3 preset / v4 theme   @bindshq/stance-tokens/tailwind
        ├── Swift constants                 StanceTokens (Swift Package)
        ├── Kotlin constants                com.bindshq.stance.tokens
        └── Resolved JSON                   for any other tool

Source format

Themes reference primitives by alias, so a role always traces back to a brand-derived value.

json
// source/semantic/light.json
{
  "color": {
    "$type": "color",
    "bg-canvas":  { "$value": "{color.brand.ivory}" },
    "fg-default": { "$value": "{color.brand.indigo}" },
    "fg-muted":   { "$value": "{color.ink.600}" }
  }
}

The same role on each platform

css
/* Web */
color: var(--st-color-fg-muted);
swift
// iOS
StanceTokens.light.colors.fgMuted   // StanceRGBA(hex: 0x555169)
kotlin
// Android
StanceTokens.light.colors.fgMuted   // 0xFF555169

Dimensions are generated in each platform’s unit: rem on the web, points on iOS, dp and sp on Android (1rem = 16).

Guarantees

  • Validated. Every token has a type, every alias resolves, and all three themes define exactly the same roles.
  • Reproducible. Generated files are committed, and CI fails if they differ from what the source produces.
  • In parity. Tests compare the Swift and Kotlin values with the source for every role in every theme.
  • Accessible. Contrast for every text and boundary pair is tested in light, dark and high contrast.
  • Brand-locked. The build fails if the two brand colours are ever changed.

Changing a token

bash
# 1. edit packages/tokens/source/...
npm run tokens        # regenerate CSS, TypeScript, Swift, Kotlin
npm test              # contrast and cross-platform parity