styles: migrate design tokens to CSS custom properties
- Dominant language
- HTML
- Stars
- 7
- Forks
- 11
- Avg merge
- 18h 3m
- Merged PRs (30d)
- 14
Description
## What to build
Follow-up from PR #757 review ([discussion_r3641178348](https://github.com/GSA/sam-styles/pull/757#discussion_r3641178348)). While un-nesting typography selectors, a reviewer noted that hard-compiled token values (e.g. `u-text("base-dark")`, `u-display("block")`, `u-font("sans", "md")` in `_paragraph.scss`) could instead be exposed as **CSS custom properties**.
This is not limited to paragraph tokens — it's a library-wide question about how `sam-styles` emits design-token values.
### Problem
Today, USWDS mixins and SCSS variables resolve to **static values at compile time**. Consumers can't override colors, spacing, typography, etc. at runtime, and theming requires recompiling the SCSS.
### Proposal
Evaluate and (if aligned with the design-system strategy) migrate the component/branding layers to emit **CSS custom properties** for design tokens — colors, typography, spacing, borders — so values are:
- Overridable at runtime (theming, dark mode, per-context overrides)
- Inspectable/tweakable via DevTools without a rebuild
- Centralized as `:root` (or scoped) `--sds-*` variables
## Acceptance criteria
- [ ] Decision recorded on which token categories to migrate (color, typography, spacing, borders) and in what order
- [ ] Naming convention for the custom properties agreed (e.g. `--sds-*`)
- [ ] Strategy defined for bridging USWDS mixin output → CSS variables without losing USWDS theming
- [ ] Decision on whether to keep SCSS variables as fallbacks for older-browser support
- [ ] Migration path chosen: incremental (per component) vs. a dedicated token layer
- [ ] Impact on compiled bundle size and existing consumers assessed
- [ ] Follow-up AFK implementation issues spun off per the agreed scope
## Notes
This is an **HITL discovery/decision** ticket — the open questions above must be resolved before any implementation begins. Origin: PR #757 review comment by @mgetzflex.
Contributor guide
Research direction
Read the discussion on PR #757 and inspect `_paragraph.scss`, especially the `u-text("base-dark")`, `u-display("block")`, and `u-font("sans", "md")` usages. Map how current SCSS and USWDS tokens are emitted, then document the token categories, naming and fallback strategy, migration approach, bundle and consumer impact, and follow-up implementation issues.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css, scss
- Domain
- design, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100