Design tokens

v2 release candidate

How SquareKit names design decisions, connects them to components, and delivers them to Web, iOS, and Material.

Overview

Primitive paths

Semantics

Design tokens at a glance

Design tokens give shared design decisions stable names so Figma, code, and documentation can stay aligned.

Owner	Responsibility
SquareKit foundations	Shared Color values and approved Brand themes.
Web, iOS, and Material	Platform-specific roles, behavior, and accessibility.
Components	Use the approved roles owned by their platform UI Kit.

One simple rule

Choose the token that describes the role you need. Do not copy a value or connect a component directly to a shared Color or Brand token.

What v2 shares

The initial shared release covers Color and Brand themes. Spacing, typography, shape, elevation, motion, and interaction remain owned by Web, iOS, and Material until a shared contract is approved.

How tokens work

A shared value reaches a component through a small set of owned layers.

Layer	Example	What it does
Shared Color	Green, 600	Base values and reusable color ramps.
Brand themes	Primary, 600	Choose approved Primary and Secondary colors. Primary also selects matching neutrals.
Platform roles	Brand background	Give shared values clear meaning for Web, iOS, and Material.
Component	Button background	Uses platform roles, not raw values.

Choose roles, not values

A component asks its platform for a solid brand background, primary label, or scheme Primary role. It never reaches around that layer to copy a shared primitive or Brand selector.

Tokens replace hard-coded visual values with named, portable decisions. Changing an approved selector or semantic mapping can update every connected component without rewriting those components, while stable identities preserve review history across design tools and platform packages.

Designers choose approved variables in their design tool.
Engineers use exports from the versioned package.
Components use platform semantic or component-color roles.
Incorrect results are fixed in the layer that owns the decision, not with a local override.

Delivery

One versioned v2 release generates the formats each platform needs. The existing v1 packages and consumers remain unchanged.

Consumer	Release identity	What it provides
Web	`@parentsquare/squarekit-tokens-v2`	Scoped CSS variables, theme selectors, and package metadata.
iOS	`SquareKitTokensV2`	Swift APIs and resources generated from the same release contexts.
Material	`com.parentsquare:squarekit-tokens-v2`	Kotlin and Compose outputs generated from the same release contexts.
Design tools	Variables and mappings	Figma today, with stable SquareKit names preserved for future tools.

Color
  → Brand / Primary or Brand / Secondary
    → Web, iOS, or Material semantics
      → platform component

The repository release is the repeatable source for generated packages and documentation reference data.
Figma and Token Studio are current design and synchronization tools, not permanent package dependencies.
Design Systems coordinates the initial release. Platform teams can own defined areas later when ownership, tests, support, and rollback are in place.
SQRKT pins the exact React and token package versions shown in its examples.

Keeping design, code, and documentation aligned

A stable SquareKit name connects each design variable, code export, React component, and documentation page. Code Connect may help users find the right component, but it does not become the source of truth.

Current status

The v2 Color reference is generated from the verified repository release candidate. Production package publication and package-backed SQRKT components are still required before release.