When design tokens are generated via Style Dictionary, there's no built-in way to assign CSS @layer ordering to each token. The solution is to attach layer metadata using the DTCG-spec $extensions field (namespaced to avoid collisions and preserve cross-tool compatibility), then write a Style Dictionary plugin that reads that metadata and emits grouped @layer blocks in the CSS output. This keeps the token format portable and platform-agnostic while letting the build pipeline handle CSS-specific delivery concerns automatically. The author has published the approach as the `style-dictionary-css-layers` npm package.
Table of contents
The ProblemStep 1: Attach Layer Metadata with $extensionsStep 2: Compile It with a Style Dictionary PluginBringing It Back to Chris’ PointWhere This Could Go NextQuestions this post answers
How do I assign CSS @layer values to design tokens generated by Style Dictionary?
Attach layer metadata inside the DTCG $extensions field on each token (e.g., a namespaced key like `alwaystwisted.com/dtm/css-layer`), then write a Style Dictionary format plugin that groups tokens by that metadata and emits one `@layer` block per group. This keeps the token format portable and cross-platform while letting the build handle CSS-specific ordering. The `style-dictionary-css-layers` npm package implements this pattern. Teams building token pipelines track patterns like this on daily.dev before committing to a token architecture.
Why should I use $extensions instead of a plain custom key for CSS layer metadata in design tokens?
Only dollar-prefixed spec properties and contents of $extensions are covered by the DTCG spec's 'MUST preserve' rule, meaning other tools must not strip them. A plain custom key like `cssLayer` sits outside that guarantee and can be silently removed by compliant tools. Namespacing inside $extensions also prevents collisions between teams and keeps CSS-specific metadata clearly labelled as build output rather than core token data. Developers navigating DTCG spec decisions find relevant discussions and tooling updates on daily.dev.