{"_id":"@design-tokens-manager/style-dictionary-css-layers","name":"@design-tokens-manager/style-dictionary-css-layers","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@design-tokens-manager/style-dictionary-css-layers","version":"0.0.1","description":"Style Dictionary plugin that emits CSS @layer blocks from $extensions layer metadata on design tokens.","type":"module","main":"index.js","exports":{".":"./index.js"},"scripts":{"test":"node --test test/*.test.js","build:example":"node example/build.js"},"keywords":["style-dictionary","design-tokens","css","css-layer","dtcg"],"author":"","license":"MIT","peerDependencies":{"style-dictionary":"^4.0.0"},"devDependencies":{"style-dictionary":"^4.0.0"},"engines":{"node":">=18"},"_id":"@design-tokens-manager/style-dictionary-css-layers@0.0.1","gitHead":"7476f1052337e4d8a220d8525b1025680397fd32","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-tFGhRVIBumyxfXqVqe1SRXqIbPMxuszlAp38vtxUR+NjYMkKlkbE2JLiTobx76mhqkrLBo9ewWVP2iKgy0hVqA==","shasum":"484ffce2cf69cbfeca24261691839e968b09cb16","tarball":"https://registry.npmjs.org/@design-tokens-manager/style-dictionary-css-layers/-/style-dictionary-css-layers-0.0.1.tgz","fileCount":4,"unpackedSize":9046,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGp5pyyIB9sUd28qcO/tumzonKydW/djWiqOhCrUy0BHAiBd54knPEjWuKsbhO/G9i/YIuPgmicoMko8//nQKnIzGg=="}]},"_npmUser":{"name":"design-tokens-manager","email":"dtm@sturobson.com"},"directories":{},"maintainers":[{"name":"design-tokens-manager","email":"dtm@sturobson.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/style-dictionary-css-layers_0.0.1_1786098446223_0.7387422560119985"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-07T10:27:26.047Z","0.0.1":"2026-08-07T10:27:26.369Z","modified":"2026-08-07T10:27:26.562Z"},"maintainers":[{"name":"design-tokens-manager","email":"dtm@sturobson.com"}],"description":"Style Dictionary plugin that emits CSS @layer blocks from $extensions layer metadata on design tokens.","keywords":["style-dictionary","design-tokens","css","css-layer","dtcg"],"license":"MIT","readme":"# Style Dictionary CSS @layer plugin\n\nA [Style Dictionary](https://styledictionary.com/) plugin that emits CSS\n`@layer` blocks from design token metadata, so component-level custom\nproperties land in a deliberately weak, overridable layer — no specificity\nhacks, no source-order drama.\n\nRead the background on the idea in [Extending Design Tokens With CSS\n@Layer](#) and Chris Coyier's original post on [horizontal thinking in CSS\n`@layer`](https://master.dev/blog/thinking-horizontally-in-css-layer/).\n\n## Why\n\nCSS `@layer` is a delivery concern, not a design decision, so it shouldn't\nlive in a token's `$value` or `$type`. This plugin reads layer information\nfrom a namespaced `$extensions` block on each token (per the [DTCG Format\nModule](https://www.designtokens.org/tr/2025.10/format/)) and groups the\ngenerated CSS custom properties into matching `@layer` blocks.\n\nTokens with no layer metadata are emitted in a plain `:root` block, untouched.\n\n## Install\n\nIf you are using this repository directly from GitHub, clone or download it and install it into your project from that local checkout:\n\n```bash\ngit clone https://github.com/<owner>/sd-css-layers.git\ncd your-project\nnpm install --save-dev ./sd-css-layers style-dictionary\n```\n\nIf you later publish the package to npm, the equivalent install command is:\n\n```bash\nnpm install --save-dev sd-css-layers style-dictionary\n```\n\n## Usage\n\n### 1. Add layer metadata to your tokens\n\n```json\n{\n  \"card\": {\n    \"background\": {\n      \"$value\": \"#1a1a1a\",\n      \"$type\": \"color\",\n      \"$extensions\": {\n        \"com.example/css-layer\": {\n          \"layer\": \"components.card\"\n        }\n      }\n    }\n  }\n}\n```\n\n### 2. Register the format in your Style Dictionary config\n\n```javascript\nimport StyleDictionary from 'style-dictionary';\nimport { cssLayersFormat } from 'sd-css-layers';\n\ncssLayersFormat(StyleDictionary);\n\nexport default {\n  source: ['tokens/**/*.json'],\n  platforms: {\n    css: {\n      transformGroup: 'css',\n      files: [\n        {\n          destination: 'variables.css',\n          format: 'css/variables-with-layers',\n        },\n      ],\n    },\n  },\n};\n```\n\n### 3. Build\n\n```bash\nnpx style-dictionary build\n```\n\n### Output\n\n```css\n:root {\n  --color-brand: #f97316;\n}\n\n@layer components.card {\n  :root {\n    --card-background: #1a1a1a;\n    --card-color: #ffffff;\n  }\n}\n```\n\nTokens without the ⁠com.example/css-layer extension are written to the plain\n⁠:root block above any ⁠@layer blocks, so they behave as normal unlayered\nCSS and can still override anything inside a layer.\n\n## API\n\nThe package exports a few named functions in case you want to build your own\nformat on top of the same grouping logic:\n\n| Export | Description |\n|---|---|\n| ⁠cssLayersFormat(StyleDictionary) | Registers the ⁠css/variables-with-layers format on the given Style Dictionary instance. |\n| ⁠getTokenLayer(token) | Reads the ⁠com.example/css-layer layer name off a single token, if present. |\n| ⁠groupTokensByLayer(tokens) | Splits an array of tokens into a ⁠Map of layer name → tokens, plus an ⁠unlayered array. |\n| ⁠renderCss({ layerGroups, unlayered }) | Renders the final CSS string from grouped tokens. |\n| ⁠CSS_LAYER_EXTENSION_KEY | The extension namespace string, ⁠com.example/css-layer. |\n| ⁠FORMAT_NAME | The registered format name, ⁠css/variables-with-layers. |\n\n## Namespacing your own extension key\n\n⁠com.example/css-layer is a placeholder namespace used in the article and\nexamples. In your own project, swap it for your own reverse-domain\nnamespace (e.g. ⁠com.yourcompany/css-layer) by importing the grouping\nhelpers directly and writing a small wrapper format, or by forking\n⁠index.js and changing the constant.\n\n## Example\n\nSee the ~[⁠example/](./example)~ directory for a full token set\n(⁠card.json, ⁠button.json, ⁠global.json), a Style Dictionary config, and\nthe expected CSS output.\n\n```bash\nnpm run build:example\n```\n\n## Tests\n\n```bash\nnpm test\n```\n\nRuns unit tests against the grouping/rendering logic plus an end-to-end\nStyle Dictionary build using Node's built-in test runner.\n\n## Roadmap\n\nThis is currently a vendor extension, which is exactly what ⁠$extensions is\nfor. If a ⁠$layer-style property is ever proposed as a first-class DTCG\nspec property (in the way ⁠$deprecated moved from convention to reserved\nkeyword), this plugin would migrate to read that instead, with the\nnamespaced extension kept as a fallback for older token sources.\n","readmeFilename":"README.md","_rev":"1-ad9049d5d2307f34442c2f34ee16aa3c"}