GSA / GSA/sam-styles

styles: migrate design tokens to CSS custom properties

Open
#769 0 comments 0 reactions 0 assignees View on GitHub
refactor tech-debt
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.