What optional CSS custom-property surface would help adopters? #6973

With HDS Core, we had the advantage of getting to build fresh on top of USWDS in 2026, and are trying out something that may be of interest here.

We have a DTCG-2025.10-compliant tokens.json file that serves as the source of truth for all our primitive tokens, then use Style Dictionary to auto-convert those into custom CSS properties and Sass variables, with the latter feeding some of our USWDS theme settings and all of our components. This ensures the CSS properties and Sass variables never drift apart, and keeps the naming consistent and predictable between them.

We have a few semantic properties (typography sets) but no component properties in tokens.json yet. Currently have a hand-built layer for semantic color tokens in palettes.scss that drives the auto-adapting color palette system, but hope to move those into tokens.json later once the DTCG Format spec is stable.

The CSS custom properties can then be used by no-build consumer sites to incrementally override their existing styles with HDS ones, especially if they aren't using USWDS markup already and aren't getting most of this for free. We use CSS @layers to give site owners a reserved @site layer at the top of the cascade that always wins over both HDS and USWDS styles, which helps with not having to slap !important on everything. And we still fully support the Sass path for sites who do have a build step.

Main challenges in doing this with USWDS so far have been the USWDS settings, which site owners can't override directly with their own theme file (since we already did). But the @layer approach still allows them (and us!) to have some control that wouldn't normally be possible with the theme file alone.

This approach was heavily inspired by the Github Primer and NYS design systems (the latter also based on USWDS). We're still in the early pre-v1.0 stages but have heard positive feedback from early NASA adopters, and would be excited to hear from others trying out a similar tokens.json and/or CSS property layer.