styles: migrate design tokens to CSS custom properties #769

What to build

Follow-up from PR #757 review (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.