@uncinq/component-tokens 1.9.3 → 1.10.0

package/docs/reference.md

@@ -0,0 +1,170 @@
+---
+isIndex: false
+title: Reference
+description: Every token for all 26 components, generated from the JSON sources so it can never drift from the shipped CSS.
+weight: 3
+---
+
+Every table below is generated at build time from `dist/tokens.json`, which Style Dictionary produces from the same JSON sources as the CSS. Nothing here is written by hand, so a token cannot appear in the reference without existing in the package, or change value without the page changing with it.
+
+Values are shown as they ship. A token that references a semantic token shows `var(--the-semantic-token)` rather than a resolved color or length, because that reference is what makes an override of the semantic layer propagate. See [Style Dictionary](../style-dictionary/) for why the build keeps it that way.
+
+{{< alert-block state="info" >}}
+Reading this offline, from the repository or from `node_modules`? The tables below are rendered by the documentation site. The same data, in machine-readable form, sits in `dist/tokens.json`, and the final CSS is in `dist/css/components/`.
+{{< /alert-block >}}
+
+### alert
+
+Inline notification banner. 9 tokens.
+
+{{< tokens pkg="component" file="components/alert" >}}
+
+### badge
+
+Badge, pill and tag. 12 tokens.
+
+{{< tokens pkg="component" file="components/badge" >}}
+
+### breadcrumb
+
+Breadcrumb navigation. 10 tokens.
+
+{{< tokens pkg="component" file="components/breadcrumb" >}}
+
+### button
+
+Button, all variants and sizes. 28 tokens.
+
+{{< tokens pkg="component" file="components/button" >}}
+
+### card
+
+Card, an alias layer over item. 36 tokens.
+
+{{< tokens pkg="component" file="components/card" >}}
+
+### carousel
+
+Carousel, arrows and pagination. 28 tokens.
+
+{{< tokens pkg="component" file="components/carousel" >}}
+
+### container
+
+Layout container, max-widths and bleed. 17 tokens.
+
+{{< tokens pkg="component" file="components/container" >}}
+
+### details
+
+Native details and accordion. 25 tokens.
+
+{{< tokens pkg="component" file="components/details" >}}
+
+### drawer
+
+Off-canvas panel. 22 tokens.
+
+{{< tokens pkg="component" file="components/drawer" >}}
+
+### dropdown
+
+Dropdown menu. 21 tokens.
+
+{{< tokens pkg="component" file="components/dropdown" >}}
+
+### embed
+
+Video and iframe wrapper. 7 tokens.
+
+{{< tokens pkg="component" file="components/embed" >}}
+
+### figure
+
+Figure and figcaption. 4 tokens.
+
+{{< tokens pkg="component" file="components/figure" >}}
+
+### heading
+
+Heading typography scale. 3 tokens.
+
+{{< tokens pkg="component" file="components/heading" >}}
+
+### hero
+
+Hero and banner section. 17 tokens.
+
+{{< tokens pkg="component" file="components/hero" >}}
+
+### item
+
+Item, the canonical card-like unit. 55 tokens.
+
+{{< tokens pkg="component" file="components/item" >}}
+
+### items
+
+Items grid and list wrapper. 3 tokens.
+
+{{< tokens pkg="component" file="components/items" >}}
+
+### link
+
+Inline link. 4 tokens.
+
+{{< tokens pkg="component" file="components/link" >}}
+
+### list
+
+Styled list. 6 tokens.
+
+{{< tokens pkg="component" file="components/list" >}}
+
+### logo
+
+Logotype. 7 tokens.
+
+{{< tokens pkg="component" file="components/logo" >}}
+
+### map
+
+Embedded map. 5 tokens.
+
+{{< tokens pkg="component" file="components/map" >}}
+
+### media
+
+Media object, image plus text. 4 tokens.
+
+{{< tokens pkg="component" file="components/media" >}}
+
+### modal
+
+Centered dialog. 21 tokens.
+
+{{< tokens pkg="component" file="components/modal" >}}
+
+### nav
+
+Navigation bar. 15 tokens.
+
+{{< tokens pkg="component" file="components/nav" >}}
+
+### pagination
+
+Pagination control. 17 tokens.
+
+{{< tokens pkg="component" file="components/pagination" >}}
+
+### surtitle
+
+Small label above a heading. 8 tokens.
+
+{{< tokens pkg="component" file="components/surtitle" >}}
+
+### table
+
+Data table. 6 tokens.
+
+{{< tokens pkg="component" file="components/table" >}}

package/docs/style-dictionary.md

@@ -0,0 +1,124 @@
+---
+isIndex: false
+title: Style Dictionary
+description: How component token JSON is compiled to CSS, and how cross-package references to design-tokens are resolved.
+weight: 5
+---
+
+
+[Style Dictionary v5](https://styledictionary.com/) transforms the DTCG JSON token files into CSS custom properties.
+
+## Run the build
+
+```bash
+npm run build
+```
+
+Output is written to `dist/css/components/`. One CSS file is generated per JSON source file.
+
+```
+tokens/components/button.json   →   dist/css/components/button.css
+tokens/components/badge.json    →   dist/css/components/badge.css
+```
+
+`dist/css/index.css` is auto-generated too, in a step that runs after Style Dictionary. It discovers the token files from disk, so adding a JSON source needs no manual edit anywhere. Each generated file declares its own `@layer tokens`, which is why a plain `@import` is enough and no `layer()` qualifier is used.
+
+---
+
+## Cross-package references
+
+Component tokens reference semantic tokens from `@uncinq/design-tokens` using DTCG `{dotted.path}` syntax:
+
+```json
+{
+  "btn": {
+    "border": {
+      "radius": { "$value": "{radius.control}", "$type": "dimension" }
+    }
+  }
+}
+```
+
+The design-tokens sources are loaded as `include`, from `node_modules/@uncinq/design-tokens/tokens`, so these references do resolve at build time. The build fails fast with a clear message if that package is missing:
+
+```js
+const designTokensPath = './node_modules/@uncinq/design-tokens/tokens';
+if (!fs.existsSync(designTokensPath)) {
+  throw new Error('Missing @uncinq/design-tokens — run npm install first.');
+}
+```
+
+Resolution is only used for validation, though. The output deliberately keeps the reference rather than the resolved value: the format reads `token.original.$value` and rewrites the DTCG reference as a CSS `var()`.
+
+```
+{radius.control}   →   var(--radius-control)
+{color.text.muted} →   var(--color-text-muted)
+```
+
+That is what makes the layering work at runtime. A project that overrides `--color-brand` moves every component token pointing at it, because the component CSS still says `var(--color-brand)` rather than a baked-in color.
+
+`log: { errors: { brokenReferences: 'console' } }` remains set as a safety net, so a typo in a reference reports on the console instead of aborting the whole build.
+
+Path segments named `default` are stripped, mirroring the `@uncinq/design-tokens` convention:
+
+```
+{color.brand.default}   →   var(--color-brand)
+{color.text.default}    →   var(--color-text)
+```
+
+---
+
+## Adding a new component
+
+1. Create `tokens/components/{name}.json` with DTCG structure.
+2. Run `npm run build`.
+
+That is the whole procedure. `dist/css/components/{name}.css` is generated, and the `@import` is added to `dist/css/index.css` automatically, because both the build and the index step discover token files from disk rather than from a hardcoded list.
+
+---
+
+## Token naming
+
+Token JSON paths map directly to CSS custom property names. Use camelCase for compound CSS property names — the build converts them to kebab-case:
+
+| JSON path | CSS variable |
+| --- | --- |
+| `btn.border.radius` | `--btn-border-radius` |
+| `btn.color.background` | `--btn-color-background` |
+| `btn.color.background.hover` | `--btn-color-background-hover` |
+| `btn.color.textDecoration` | `--btn-color-text-decoration` |
+| `btn.color.background.default` | `--btn-color-background` (default stripped) |
+| `btn.text.decorationLine` | `--btn-text-decoration-line` |
+
+States (`hover`, `active`, `focus`, `disabled`, `checked`) are nested one level deeper under the property group.
+
+---
+
+## References
+
+- [Style Dictionary v5 docs](https://styledictionary.com/)
+- [@uncinq/design-tokens](https://github.com/uncinq/design-tokens) — primitive and semantic tokens referenced by this package
+
+---
+
+## The JSON manifest
+
+Alongside the CSS, the build writes `dist/tokens.json`: a flat array of every token the package ships.
+
+```json
+[
+  {
+    "name": "--btn-color-background",
+    "value": "var(--color-brand)",
+    "type": "color",
+    "file": "components/button",
+    "description": ""
+  }
+]
+```
+
+The documentation site renders its reference tables from this file, which is why the reference cannot drift from the stylesheets.
+
+The guarantee comes from a single shared function. `tokenToCssValue()` serializes a token to its CSS value, and **both** the CSS format and the manifest format call it. There is no second implementation of the naming or the value logic to fall out of step, and the build asserts the equivalence: the manifest holds exactly one entry per declaration emitted in `dist/css/`, with the same name and the same value.
+
+`description` comes from the DTCG `$description` key. Adding one to a token source makes it appear in the published reference with no other change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncinq/component-tokens",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "description": "Framework-agnostic CSS design tokens — component layers.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,8 @@
   ],
   "files": [
     "dist/css/",
+    "dist/tokens.json",
+    "docs/",
     "tokens/"
   ],
   "exports": {

package/tokens/components/drawer.json

@@ -34,8 +34,20 @@
         "$type": "color"
       },
       "text": {
-        "$value": "{color.text.onSurface}",
-        "$type": "color"
+        "default": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color"
+        },
+        "active": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color",
+          "$description": "Links inside the panel keep the panel text colour unless this is overridden."
+        },
+        "hover": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color",
+          "$description": "Links inside the panel keep the panel text colour unless this is overridden."
+        }
       }
     },
     "end": {

package/tokens/components/map.json

@@ -3,7 +3,7 @@
     "border": {
       "radius": {
         "$value": "{radius.none}",
-        "$type": "dimensions"
+        "$type": "dimension"
       }
     },
     "color": {

package/tokens/components/modal.json

@@ -30,8 +30,20 @@
         "$type": "color"
       },
       "text": {
-        "$value": "{color.text.onSurface}",
-        "$type": "color"
+        "default": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color"
+        },
+        "active": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color",
+          "$description": "Links inside the panel keep the panel text colour unless this is overridden."
+        },
+        "hover": {
+          "$value": "{color.text.onSurface}",
+          "$type": "color",
+          "$description": "Links inside the panel keep the panel text colour unless this is overridden."
+        }
       }
     },
     "margin": {