govtechsg Tailwind Mapping
Conversion Pattern
--sgds-{category} → --{property}-{category} → sgds:{property}-{category}
| SGDS Variable Pattern | Tailwind Property | Generated Class |
|---|---|---|
--sgds-{v}-bg-{m} |
--background-color-{v}-{m} |
sgds:bg-{v}-{m} |
--sgds-{v}-surface-{m} |
--background-color-{v}-surface-{m} |
sgds:bg-{v}-surface-{m} |
--sgds-{v}-color-{m} |
--text-color-{v}-{m} |
sgds:text-{v}-{m} |
--sgds-{v}-border-color-{m} |
--border-color-{v}-{m} |
sgds:border-{v}-{m} |
--sgds-line-height-{m} |
--leading-{m} |
sgds:leading-{m} |
--sgds-font-size-{m} |
--text-{m} |
sgds:text-{m} |
--sgds-spacer-{m} |
--spacing-{m} |
sgds:m-{m}, sgds:p-{m}, etc. |
See reference/conversion-rules.md for full per-category details (form colors, typography types, modifiers).
Playground HTML Format
Each playground/utility/*.html table section follows this structure:
<section class="sgds:mb-2-xl">
<h2>Category Name</h2>
<sgds-table>
<sgds-table-row>
<sgds-table-head>SGDS Tailwind Token</sgds-table-head>
<sgds-table-head>CSS Variable</sgds-table-head>
<sgds-table-head>Preview</sgds-table-head>
</sgds-table-row>
<sgds-table-row>
<sgds-table-cell><code>sgds:bg-primary-default</code></sgds-table-cell>
<sgds-table-cell><code>--sgds-primary-bg-default</code></sgds-table-cell>
<sgds-table-cell>
<div class="sgds:bg-primary-default sgds:text-fixed-light sgds:p-md">
Primary background
</div>
</sgds-table-cell>
</sgds-table-row>
</sgds-table>
</section>
Contrast rules: Fixed-light surfaces → sgds:text-fixed-dark. Fixed-dark/dark surfaces → sgds:text-fixed-light. Warning/yellow → sgds:text-fixed-dark. Borders → use sgds:border-2 sgds:border-{color} sgds:p-md.
Workflow: Adding a New Token Mapping
- Add token to theme file (
root.css,day.css, ornight.css) - Add mapping to
src/css/utility.cssinside the correct existing@theme {}section — follow the conversion pattern table above - Create/update
playground/utility/[name].htmlwith a live preview table - Run
pnpm run utility:devand verify the utility class renders in light and dark mode - Create
stories/utilities/[name].stories.jsStorybook story
Commands
| Command | Purpose |
|---|---|
pnpm run utility:dev |
Tailwind watches playground/utility/*.html |
pnpm run dev |
Preview playground in browser |
pnpm storybook |
Preview Storybook documentation |
- Storybook:
pnpm run storybook(preview Storybook documentation)
Production
- Build:
pnpm build(production build)
Related Skills
- token-workflow - For high-level token architecture and documentation patterns