Locara

Design Tokens (Style Dictionary, DTCG, Tokens Studio)

What it is: A formalization of design decisions as named, structured values — colors, spacing, typography, radii, shadows, motion — distributed as data (JSON) rather than baked into CSS or component code. The dominant tooling: Salesforce’s Theo (early, mostly historical), Amazon’s Style Dictionary (the current de facto standard, MIT-licensed), the W3C Design Tokens Community Group (DTCG) format (the emerging cross-tool standard), and Tokens Studio (the Figma plugin for authoring tokens visually). Status: Style Dictionary is the production standard at most large design-system teams. The DTCG format hit a stable draft in 2024 and is being implemented across tools (Figma’s native variables, Style Dictionary’s JSON output, Tokens Studio, Penpot). Adoption is mainstream-and-rising. Most relevant to Locara: A Locara design system that can be consumed by humans, LLMs, native Mac apps, and webviews simultaneously — and contributed to by the community — needs design tokens as a portable artifact. Components-as-source (shadcn) gives you behavior; tokens give you the coherent visual language across them.

Background

Design tokens started as an internal Salesforce idea in 2014–15. Jina Anne and the Salesforce Design Systems team coined the term and shipped Theo as the first cross-platform tooling: define a value once (e.g., color.brand.primary = #0070d2), generate platform-specific outputs (CSS variables, iOS Swift constants, Android XML, Sketch palettes). The thesis: design decisions are data; treat them as such.

Style Dictionary (Amazon, 2017) generalized the pattern. Take a tree of JSON files describing tokens; transform them into any output format via a configurable pipeline. Style Dictionary became the production standard at companies running large multi-platform design systems — it’s used inside companies and shipped publicly (IBM Carbon, Adobe Spectrum, etc.).

In parallel, the W3C Design Tokens Community Group (DTCG) has been working since 2019 on a vendor-neutral JSON format for tokens — what Style Dictionary, Tokens Studio, Figma, Penpot, and others should all read and write. The DTCG format hit a stable working draft around 2023–24 and tooling has been catching up.

Tokens Studio is the Figma plugin that authors tokens visually inside Figma, exports DTCG-compatible JSON, and rounds-trips with code. As of 2026 it’s the most-popular bridge between designers (in Figma) and engineers (consuming tokens).

Key design decisions

  • Tokens are named values, not raw values. Code references color.surface.primary, not #fafafa. The naming is the abstraction.
  • Tokens have types. Color, dimension, fontFamily, fontWeight, duration, cubicBezier, shadow, gradient, transition — DTCG specifies a type system.
  • Tiers of tokens (the recurring 3-tier pattern):
    • Primitive / global tokens — raw values: color.blue.500 = #3b82f6.
    • Semantic tokens — meaning-bearing aliases: color.surface.primary → color.blue.500.
    • Component tokens — component-specific: button.background.primary → color.surface.primary.
  • JSON as the canonical format. Tokens are data, version-controllable, diffable, programmatically transformable.
  • Output transformation. A single token tree generates CSS variables, iOS constants, Android XML, Tailwind config, Figma styles — whatever the toolchain needs.
  • Modes / themes are first-class. Light/dark, density variations, brand variants are token-level concerns, not component-level.
  • MIT licenses across the major tooling.

What worked

  • Designer-engineer alignment. A token tree is a contract both sides can read. Designers change color.surface.primary in Tokens Studio; engineers consume the new value via Style Dictionary; the change ripples through the codebase coherently.
  • Multi-platform consistency. A web app, an iOS app, an Android app, and a Figma file can all reference the same color or spacing value, generated from one source of truth. Brand consistency without duplication.
  • Theme switching is structural. Light mode / dark mode / high-contrast / brand-variant is a matter of swapping the resolved token values, not rewriting components.
  • Mature tooling. Style Dictionary is battle-tested in production. Tokens Studio has reached a usable maturity. Figma’s native variables (added 2023) interoperate with DTCG-style JSON.
  • DTCG standardization. The vendor-neutral format unblocked tools to interop. Pre-DTCG, every tool had its own token schema; post-DTCG, they’re converging.
  • AI-readability. Tokens-as-JSON is exactly what LLMs are good at reading and modifying. Cursor or Claude can refactor a token tree confidently in a way they can’t refactor stylesheet pixel values scattered through component code.

What failed / criticisms

  • Naming is the hardest part — and there’s no consensus. Should it be color.surface.primary, color.background.primary, surface.color.primary, bg.primary? Every team picks differently; tokens don’t transfer across organizations cleanly.
  • Three-tier hierarchy is overhead. For small projects, the primitive→semantic→component layering feels bureaucratic. Tokens shine at design-system scale; for 10-component projects, plain CSS variables work fine.
  • Tooling still has rough edges. Style Dictionary is powerful but configuration-heavy. Tokens Studio has occasional sync issues. Figma’s native variables don’t fully implement DTCG.
  • DTCG format is still evolving. Some token types (typography, motion, gradient) have lower interoperability than colors and dimensions.
  • Round-tripping designer-engineer changes is fragile. Tokens Studio + Git + Figma + code is a multi-tool dance; getting it consistently right requires discipline.
  • Tokens don’t replace good naming sense. A bad token taxonomy is worse than no tokens — it locks bad mental models into the system.
  • Component tokens proliferate. Every component has button-background, button-border, button-text, button-hover-background, button-disabled-background — the count grows fast.

Specific learnings for Locara

  1. Locara needs a token tree, not just CSS variables. Components-as-source (shadcn pattern) gives behavior; tokens give the coherent visual language across components and across apps. Without tokens, every Locara app drifts visually; with tokens, the design system is a single source of truth even if the components are copied.
  2. Adopt DTCG-format tokens from day one. Don’t invent a Locara-specific format. DTCG is the emerging standard; pick the format that interoperates with Style Dictionary, Tokens Studio, Figma, and downstream tooling.
  3. Style Dictionary is the right transformation pipeline. Production-tested, MIT-licensed, configurable. Locara’s component build outputs CSS variables for Tailwind, Swift constants for native Mac UI, and JSON tokens for AI tools — all generated from one source.
  4. Three-tier token structure (primitive → semantic → component) maps perfectly onto Locara. Primitive tokens are the brand palette. Semantic tokens are the abstract roles (surface, accent, error). Component tokens are per-component values. App authors rebrand Locara apps by overriding only the primitive tier; everything else cascades.
  5. Modes / themes are first-class. Light, dark, high-contrast, brand variants are token-level concerns. Locara apps should support all of these via token swaps, not via component rewrites.
  6. AI-friendly tokens are a feature. A model that needs to “make this app’s accent color match the user’s macOS accent” can do that confidently if it’s a token edit, not a search-and-replace across 50 component files. Tokens are LLM-modifiable infrastructure.
  7. Tokens are the natural extension of the shadcn pattern. shadcn copies component code into your repo; tokens give those components a coherent visual contract. The combination is “behavior owned by the app, design language owned by Locara.” This is exactly the boundary you want.
  8. Native Mac apps consume tokens too. A Locara app written in Swift+SwiftUI can consume Locara’s token tree via a generated Swift file (Style Dictionary supports Swift output). Mac-native and webview apps share visual identity without code duplication.
  9. Don’t lock in to Figma. Tokens Studio is great today; Figma is acquiring/integrating tokens natively. Locara’s design system should be authored in DTCG-format JSON files in the repo, with Figma as one consumer (via Tokens Studio sync), not the canonical source. Avoids vendor lock-in and Figma-acquisition risk.
  10. Treat token taxonomy as a public artifact. Locara’s token names will be referenced by every Locara app and every community contribution. Naming choices have to be deliberate, documented, and stable. Bad names lock in bad mental models.
  11. Don’t ship 200 tokens on day one. Like all design systems: start narrow. ~20 primitives, ~15 semantic, component tokens added per-component. Easier to add tokens than to remove them.

References