Init a single source of truth for tokens and wire a clean configjson-driven workflow to keep naming consistent across platforms. Write tokens once in the repo and extend through color and typography scales with style-dictionary-utils.
Within the repo, define a tight set of variables for color, spacing, and typography. If you are adding new tokens, maintain a clear naming pattern like colors.primary, font.body, and spacing.grid. You can find tokens via your source tree and automate updates with a simple write workflow that outputs JSON for web and mobile targets.
To enable cross-platform theming, use the init flow to import base tokens and then extend for each platform. The style-dictionary-utils map tokens to transforms for platform formats, so you can adding platform-specific transforms without duplicating definitions.
Keep the configjson entry minimal and explicit; declare colors, typography, and semantics in one place, then publish results through the build step. This approach helps teams have consistent themes shipped quickly and securely.
Ready to level up your UI system? Browse the repo, review the naming conventions, and start writing tokens that scale across web, iOS, and Android with Style Dictionary: Design Tokens for Cross-Platform Theming.
Install Guide: Quick Start for Web, iOS, and Android Projects
Install Style Dictionary with npm i -D style-dictionary, then create a minimal tokens file and a config that covers web, iOS, and Android outputs. Note that the configuration should emit CSS variables for web, Swift constants for iOS, and colors.xml for Android in one run. Use metadata to annotate tokens with origin, notes, and design intent; comments help teammates review decisions, thats useful for audits. Because tokens may reference each other, enable transitive references and use shouldoutputref to keep values consistent across platforms. Keep colorarray palettes clearly defined and tag tokens with a styledictionarycolor type when relevant. Use exports to expose values to downstream projects and organize your files into folders by platform and type so teammates can find what they need quickly. Start with a playground to preview values, and base typography on 1rem to maintain consistent sizing across outputs.
Web quick start: add a platforms.web section to sd.config.json and emit a tokens.css file at build/web/tokens.css. Map color tokens to CSS custom properties like --color-primary and --color-neutral-900, applying a normal naming scheme that mirrors the token path (e.g., color.primary, color.gray.900). For web, keep the CSS output lightweight, and expose a reference to color tokens so design decisions remain traceable via metadata. If you plan to reuse colors in UI frameworks, consider exporting a JS module as part of the same run to simplify integration, and use the styledictionarybuildallplatforms script alias to test end-to-end across all targets.
iOS quick start: configure the ios platform to generate a Swift file (Colors.swift or Tokens.swift) containing a struct with static constants for each color token. Example: static let colorPrimary = UIColor(named: "color_primary") or a direct hex initializer. Leverage transitive token references to keep palettes aligned, and mark values with styledictionarycolor for clarity in the playground. Ensure the output aligns with normal iOS color handling and includes a note in metadata to explain the design rationale. This approach keeps what users see consistent with the design system while simplifying code reviews and theming experiments.
Android quick start: set up the android platform to output colors.xml with entries like
| Step | Command / Output |
|---|---|
| 1. Install | npm i -D style-dictionary |
| 2. Prepare tokens | Create tokens/colors.json (or colors.yaml) with entries like "color": { "primary": { "value": "#FF3B30" } }; add comments to explain usage and set type to styledictionarycolor where applicable |
| 3. Configure | sd.config.json with platforms.web, platforms.ios, platforms.android; define buildPath and output files for each target; enable transitive references |
| 4. Build | npx style-dictionary build; or npm run styledictionarybuildallplatforms if you added a script alias |
| 5. Validate outputs | Web: build/web/tokens.css; iOS: build/ios/Colors.swift; Android: build/android/colors.xml; check color parity and metadata |
Token Modeling: Naming, Scopes, and Platform Specifics
Adopt platform-aware naming from the start: prefix tokens by platform and scope to keep cross-platform theming consistent. Use a single references map and maintain a flattened output per platform because a clear naming scheme reduces drift as formats evolve. This approach will streamline integration and relies on build-tokensjs to drive the pipeline across projects.
Name tokens with a stable, readable pattern: include base tokens such as color, size, and typography; use sizefontbase as the canonical font-size base token. Combine a category, a token role, and a platform suffix (for example button.size or text.color) so the same token name transforms cleanly when you switch formats. This means you can import a single source of truth and outputting per platform becomes straightforward.
Define scopes clearly: global handles system defaults; components cover UI primitives; themes map to palettes; define per-platform overrides within a platform scope (web, ios, android). The flattened structure helps when you generate references for code, ensuring tools can read them without parsing nested trees. Use filtering to prune unused tokens and keep the surface area tight, then document references in a central reference file for designers and developers.
Formats and tooling: choose formats that align with your framework and build environment. For cross-platform theming, javascriptesm modules support tree-shaking and easy import into web apps and native shells. Outputting the same tokens to multiple formats–json, style dictionary, and css variables–reduces friction in integration. Options include per-platform outputs, partial builds, and a grunt-driven watch that rebuilds on change. The toolchain should keep style tokens cohesive across platforms, while still allowing platform-specific overrides.
Workflow practices: define tokens with stable names, maintain a flattened reference map, and use filtering to avoid bleed of platform-specific quirks. Generate artifacts with build-tokensjs, then consume via javascriptesm streams in your app. Because the map is well-structured, teams can add new formats without breaking existing integrations, saving time and reducing errors.
Create Core Tokens: Colors, Typography, Spacing, and Shadows
Define core tokens now: Colors, Typography, Spacing, and Shadows as a single source of truth and publish them to every platform.
Colors define a colorbasegraydark baseline, with tokens for neutrals and accents. Store them in an nsarray for quick lookup, and assign a signed hex value to each. The system uses uicolor for iOS and emits CSS variables for the web, with a comment field describing usage. It will provide options for light and dark variants and returns color values in hex, rgba, or packed integer formats. The spec tells developers how to map tokens.
Typography tokens establish font families, weights, sizes, and line heights with a deep size scale. A function named dimensionpixeltorem converts pixel metrics to rem-based values. The nodejs tooling consumes starter templates and emits cross-platform typography definitions, plus comment blocks describing usage.
Spacing uses a deep size scale for margins, paddings, and gaps: 4, 8, 12, 16, 24, 32, 48. The spacing tokens feed into a transformgroup that composes layout blocks. From this single source you generate per-component spacings via templates.
Shadows encode depth with signed offsets, blur radii, and color derived from colorbasegraydark. Each shadow token maps to an elevation level and uses a color referenced from the base gray. The pipeline returns CSS box-shadow values and platform-specific representations for uicolor on iOS. Add comment for usage, and provide options to layer shadows over elements.
To operationalize, build a starter JSON that defines colors, typography, spacing, and shadows. The toolchain will call a transformer to produce CSS variables, Swift/ObjC UIColor values, and Android styles. From the JSON, a nodejs script returns a set of artifacts.
Take this approach and tie it to templates in your design system; the result is a cohesive starter that grows with your product and has been proven to streamline updates. This would stabilize theming across teams.
Migrate Legacy Tokens: Mapping Strategy and Common Pitfalls
Export your legacy tokens to configjson and map them to formatsscssvariables for immediate cross-platform theming.
Treat font_dimensxml as the typography baseline: capture font sizes, line heights, font weights, and family aliases in a basic token group feeding html and framework components.
Set up a mapping workflow that outputs two artifacts: html-ready tokens and typescriptesm-declarations, with a dedicated project to validate the results. Follow with a CI check using yarn and a small sample page.
Mapping Strategy
Define source categories: color, typography, spacing, and headers; keep headers tightly scoped to preserve semantic naming across platforms.
Align naming across configjson and the target outputs: formatsscssvariables for CSS, and a TS interface for javascriptesm and typescriptesm-declarations. Use styledictionaryregistertransform to enforce naming, and wire it to yarn scripts so you can run the transform in both modes from the root project. Looking at the following steps: 1) normalize naming, 2) generate outputs, 3) test against a small sample page. Looking across categories and looking for gaps; dont skip any step and avoid a process that feels like guesswork.
Look for overlaps and ensure a single source of truth; point every token back to its origin in font_dimensxml or color definitions to avoid drift across platforms. down and ensure consistency across the board.
Errori Comuni
Missing tokens in the target format causes runtime gaps; verify font_dimensxml, headers, and color tokens exist in both configjson and formatsscssvariables before release.
Inconsistent scales derail theming; lock typography scales and color ramps at the basic level and propagate those choices through downstream tokens.
Over-automation without validation invites regressions; keep a project-level test page to render the tokens and confirm the mapping aligns with the framework expectations.
Build, Validate, and Preview: CLI, Configs, and Visual QA
Run yarn build-tokensjs in the project root to generate the flattened file in the following directory: tokens/outputting. The CLI reads from your config and writes a static token map that you can reuse across platforms.
Load the config with the option --config path/to/config.json to keep the build deterministic and open the door for consistent results across teams.
- Build: From the root, the command traverses the file tree through the directory structure to group tokens by scope; it produces a flattened, static JSON file and writes assets to tokens/outputting. The build supports scssmap-deep to generate a deep SCSS map, and it references tokens like bodythemedark and styledictionarycolorh in color groups.
- Validate: Run a validation step that checks required fields, token naming, and path existence; when a token group is missing, the tool reports the missing path and you can fix it before awaiting a re-run. This ensures the file aligns with the config and the intended structure.
- Preview: Open a visual QA page that renders tokens as swatches and CSS vars; the static preview reads the output and renders the tokens in a scenario you add, so you can confirm contrast, grouping, and typography in a simple UI. Use the provided path to open the preview at open http://localhost:8080/preview.
Automation note: have a lightweight workflow that calls build-tokensjs, then run a separate validation, then generate the preview; you can add added tokens like buildts and describe how each token maps to a UI component such as bodythemedark or styledictionarycolorh.
Theming Strategies: Light/Dark, Theme Switching, and Runtime Overrides
Start with a single source of truth: implement light and dark tokens as CSS variables and expose them through a data-theme attribute on the root element. Use variablesscss to bind tokens to variables, and connect them to your mystyledictionary token named styledictionarycolorkt for color values.
Structure your data in the repo with templates for token files and globs that collect across formats. Keep a deep map of tokens and maintain a scssmap-deep that mirrors the hierarchy so components can reach color, typography, and spacing tokens without hardcoding values. Include metadata and a showfileheader flag to document changes, and keep the basic tokens in place so the layout remains predictable as times pass. The setup favors html-friendly output while staying language-agnostic in the data model.
Theme switching proceeds with a small, fast script that toggles the root data-theme attribute, then reflows only the affected styles. Respect OS preferences by reading matchMedia('(prefers-color-scheme: dark)'), and provide a user-facing option in templates to store the choice in localStorage so the setting survives reloads.
Runtime overrides let you extend a token set at the component level without touching the base theme. Use data- attributes or inline CSS variable overrides to point at a different palette for a dialog, a card, or a modal. When you override, extend the existing tokens instead of replacing them, so you keep the original mystyledictionary tokens intact and simply override values at the point of use.
Implementation notes
In the project configuration, enable included metadata, keep the scssmap-deep mapping, and use showfileheader to annotate changes. Maintain a single source of truth for the data layer, and keep the html output aligned with the CSS layer. Use a clear naming pattern and a minimal set of templates to reduce drift across platforms and times of scale, and ensure the repo ships with a ready-to-run example that demonstrates how to bridge html, variablesscss, and the token data.
