token-workflow

To add new SGDS design tokens, update primitive tokens in root.css, map semantic values in day.css/night.css, and create Tailwind utilities in utility.css. This three-layer token architecture ensures consistency across themes and utility classes.

The design token workflow coordinates primitives, semantic mappings, and Tailwind utilities across three CSS layers. It enforces triple deliverables—utility.css mappings, playground HTML demos, and Storybook stories—to guarantee documentation and implementation alignment.

Yes, modifying Tailwind utility classes requires updating Storybook stories. The token workflow mandates three deliverables for any token change: utility.css mapping, playground HTML demo in playground/utility/, and Storybook story in stories/utilities/.

Yes, the token workflow supports day and night semantic mappings through day.css and night.css files. It coordinates these semantic mappings with primitive root.css tokens and Tailwind utility.css classes to maintain theme consistency.

Updating utility.css alone breaks the token workflow contract. Every token request must complete all three deliverables—utility.css mapping, playground HTML demo, and Storybook story—to ensure cross-team token work and documentation consistency across themes.

Use a three-layer token architecture when managing design systems that span primitive tokens, semantic theme mappings, and Tailwind utilities. It ensures consistency across day/night themes and enforces documentation deliverables that plain CSS variables cannot coordinate.