@uncinq/component-tokens 1.9.2 → 1.10.0

package/docs/_index.md

@@ -0,0 +1,102 @@
+---
+isIndex: false
+title: component-tokens
+description: Component-scoped CSS design tokens, layer 3 of the architecture, mapping semantic values onto the parts of a component.
+weight: 3
+icon: puzzle
+---
+
+Component tokens are CSS custom properties scoped to a single UI component. They sit at the top of the [DTCG](dtcg/) three-layer model.
+
+```
+primitive   →   semantic   →   component
+(raw values)    (purpose)      (component-scoped)
+```
+
+Where primitive and semantic tokens come from [@uncinq/design-tokens](../design-tokens/), component tokens map those semantic values onto specific parts of a component.
+
+```css
+/* semantic token, from @uncinq/design-tokens */
+--color-brand: var(--color-sienna-600);
+
+/* component token, from this package */
+--btn-color-background: var(--color-brand);
+```
+
+A component token answers **"which semantic value does this part of this component use?"**.
+
+## Why the indirection is worth it
+
+A component could read `--color-brand` directly. The extra hop buys two things.
+
+**A seam to override.** A project can restyle buttons alone by setting `--btn-color-background`, without touching the brand color and therefore without moving every other branded element.
+
+**A place to record intent.** `--btn-color-text: var(--color-text-on-brand)` documents that button text has to contrast against the brand color, which is an accessibility decision. Read directly, that decision would be invisible.
+
+The rule that keeps the indirection honest: a component token **always references a semantic token**, never a raw value and never a primitive. When you find yourself wanting a raw value, the semantic layer is usually missing a token.
+
+## What is covered
+
+26 components, one JSON source and one generated CSS file each, 390 tokens in total.
+
+| | | |
+| --- | --- | --- |
+| `alert` | `figure` | `map` |
+| `badge` | `heading` | `media` |
+| `breadcrumb` | `hero` | `modal` |
+| `button` | `item` | `nav` |
+| `card` | `items` | `pagination` |
+| `carousel` | `link` | `surtitle` |
+| `container` | `list` | `table` |
+| `details` | `logo` | |
+| `drawer` | | |
+| `dropdown` | | |
+| `embed` | | |
+
+`card` is an alias layer over `item`, which is the canonical card-like unit. See the [Reference](reference/) for what each one actually declares.
+
+## Installation
+
+This package resolves its references against `@uncinq/design-tokens`, which must be imported first.
+
+```bash
+npm install @uncinq/design-tokens @uncinq/component-tokens
+```
+
+```css
+@import '@uncinq/design-tokens';
+@import '@uncinq/component-tokens';
+```
+
+Per component, when you only need a few:
+
+```css
+@import '@uncinq/design-tokens';
+@import '@uncinq/component-tokens/css/components/button.css';
+@import '@uncinq/component-tokens/css/components/badge.css';
+```
+
+Without a build step:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens">
+```
+
+Import order matters here in a way it does not for most packages. These tokens are `var()` references, resolved by the browser at use time rather than at import time, so a missing design-tokens import does not error: it silently yields invalid values and unstyled components.
+
+## Where to go next
+
+| Page | Covers |
+| --- | --- |
+| [Naming](naming/) | The naming grammar and the rules that keep it consistent |
+| [Customizing](customizing/) | Overriding a component token, and when to add one |
+| [Reference](reference/) | Every token for all 26 components, generated from the sources |
+| [DTCG format](dtcg/) | The authoring format, including group-level types |
+| [Style Dictionary](style-dictionary/) | The build, and how cross-package references resolve |
+
+## References
+
+- [@uncinq/design-tokens](https://github.com/uncinq/design-tokens), the primitive and semantic layers
+- [@uncinq/css-components](https://github.com/uncinq/css-components), the CSS that consumes these tokens
+- [DTCG specification](https://tr.designtokens.org/format/)

package/docs/customizing.md

@@ -0,0 +1,75 @@
+---
+isIndex: false
+title: Customizing
+description: How to override a component token, which layer to reach for, and when a new token is warranted.
+weight: 2
+---
+
+## CSS override
+
+Every token is declared in `@layer tokens`, the lowest-priority layer in the recommended order. Re-declare any of them in your own `@layer tokens` block after the import. Same layer, later source order wins, and no specificity escalation is needed.
+
+```css
+@import '@uncinq/design-tokens';
+@import '@uncinq/component-tokens';
+
+@layer tokens {
+  :root {
+    --btn-color-background: var(--color-light);
+    --btn-border-radius: 0;
+    --hero-height: 80svh;
+  }
+}
+```
+
+## Choosing the right layer to override
+
+This is the decision that matters, and it is easy to get wrong in a way that only shows up later.
+
+| You want to change | Override | Effect |
+| --- | --- | --- |
+| The brand color everywhere | `--color-brand` (semantic) | Every component reading brand follows |
+| Buttons only | `--btn-color-background` (component) | Buttons alone, brand untouched |
+| One button variant | The variant's own token, or a local scope | Narrower still |
+
+Reach for the **semantic** layer by default. Overriding a component token is the right call only when you genuinely mean "buttons differ from everything else here". Doing it because it was the first token you found produces a design system that drifts component by component, which is the exact failure mode the three-layer split exists to prevent.
+
+## Scoped overrides
+
+Because these are custom properties, they inherit. Setting one on a container rather than on `:root` restyles a region without a new class or a new token.
+
+```css
+.promo-section {
+  --btn-color-background: var(--color-light);
+  --btn-color-text: var(--color-text-on-light);
+}
+```
+
+Every button inside `.promo-section` picks it up. This is usually better than inventing `--btn-promo-color-background`, because the variation is contextual rather than a new permanent concept.
+
+Note that this works outside `@layer tokens` too. A scoped override is a normal declaration on a normal selector, so it competes on specificity like any other rule, not on layer order.
+
+## Adding a token
+
+Only add a component token when a component genuinely needs a knob that does not exist. Before doing so, check three things:
+
+1. **Does a semantic token already express it?** If so, reference it rather than creating a new name.
+2. **Does the semantic layer need it instead?** If two components would want the same value for the same reason, it belongs in [@uncinq/design-tokens](../../design-tokens/), not here.
+3. **Does the name follow the grammar?** See [Naming](../naming/). A token that does not sort with its siblings will be missed by whoever looks for it next.
+
+To add one, edit the JSON source and rebuild:
+
+```bash
+npm install
+npm run build
+```
+
+Nothing else needs updating. Both the per-component CSS and `dist/css/index.css` are generated from files discovered on disk, so a new `tokens/components/*.json` is picked up automatically. See [Style Dictionary](../style-dictionary/).
+
+## What not to do
+
+**Do not edit `dist/`.** Every file there carries a generated header and is overwritten on the next build.
+
+**Do not override a token to a raw value when a semantic one exists.** `--btn-color-background: #3f51b5` works, but it leaves dark mode, theming and contrast pairing behind. `var(--color-indigo-600)` keeps the value inside the system.
+
+**Do not fork the package to change values.** The CSS override above exists so that you do not have to. A fork means inheriting the maintenance of 26 components for what is usually a handful of lines.

package/docs/dtcg.md

@@ -0,0 +1,249 @@
+---
+isIndex: false
+title: DTCG format
+description: The Design Tokens Community Group JSON format as used for component tokens, including group-level types.
+weight: 4
+---
+
+
+The [W3C Design Token Community Group (DTCG)](https://www.w3.org/community/design-tokens/) defines a standard interchange format for design tokens, so they can travel between tools (Figma, code, documentation) without loss of meaning.
+
+`@uncinq/design-tokens` uses DTCG JSON as its source format. [Style Dictionary v5](https://styledictionary.com/) transforms those JSON files into CSS custom properties — see [STYLE-DICTIONARY.md](STYLE-DICTIONARY.md) for the build pipeline. The DTCG spec informs the architecture (primitive → semantic → component, naming conventions, token types).
+
+---
+
+## The DTCG format
+
+The [DTCG spec](https://tr.designtokens.org/format/) defines tokens as JSON objects with reserved `$`-prefixed keys:
+
+```json
+{
+  "color": {
+    "brand": {
+      "$value": "oklch(0.530 0.195 22.0)",
+      "$type": "color",
+      "$description": "Primary brand color — used for CTAs and highlights."
+    }
+  }
+}
+```
+
+> **Note on OKLCH:** The DTCG `color` type accepts any valid CSS color value, including `oklch(…)`. `@uncinq/design-tokens` uses OKLCH throughout — perceptually uniform, wide-gamut, and natively supported in modern browsers.
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `$value` | ✅ | The token's value |
+| `$type` | recommended | The token type (see below) |
+| `$description` | optional | Human-readable documentation |
+
+---
+
+## DTCG token types
+
+### Scalar types
+
+| Type | Example value | CSS usage |
+| --- | --- | --- |
+| `color` | `oklch(0.530 0.195 22.0)` | `color`, `background-color` |
+| `dimension` | `1rem`, `4px` | `width`, `padding`, `font-size` |
+| `fontFamily` | `"system-ui, sans-serif"` | `font-family` |
+| `fontWeight` | `700` | `font-weight` |
+| `duration` | `300ms` | `transition-duration` |
+| `cubicBezier` | `[0.165, 0.84, 0.44, 1]` | `animation-timing-function` |
+| `number` | `1.5` | `line-height`, `opacity` |
+| `string` | `"uppercase"` | free-form text values |
+| `strokeStyle` | `"solid"`, `"dashed"` | `border-style` |
+
+### Composite types
+
+| Type | Shape | CSS usage |
+| --- | --- | --- |
+| `shadow` | `{offsetX, offsetY, blur, spread, color}` | `box-shadow` |
+| `border` | `{width, style, color}` | `border` shorthand |
+| `transition` | `{duration, delay, timingFunction}` | `transition` shorthand |
+| `typography` | `{fontFamily, fontSize, fontWeight, letterSpacing, lineHeight}` | typography rules |
+| `gradient` | `{gradientType, stops[]}` | `background: linear-gradient(…)` |
+
+→ Full type list: [tr.designtokens.org/format/#types](https://tr.designtokens.org/format/#types)
+
+> **Note on `clamp()` values:** DTCG has no native `fluid` type. Fluid tokens (`--font-size-fluid-sm`, `--font-size-fluid-md`, `--spacing-fluid-*`) use `$type: "dimension"` as the closest match — a documented gap in the spec.
+
+---
+
+## Token groups
+
+Tokens are organized in nested objects. Groups share a `$type` by inheritance:
+
+```json
+{
+  "color": {
+    "$type": "color",
+    "gray": {
+      "100": { "$value": "oklch(0.967 0.003 264.542)" },
+      "900": { "$value": "oklch(0.208 0.006 264.542)" }
+    }
+  }
+}
+```
+
+→ [tr.designtokens.org/format/#groups](https://tr.designtokens.org/format/#groups)
+
+---
+
+## Naming conventions
+
+### CSS compound properties → camelCase
+
+CSS property names that are two words (kebab-case in CSS) are written as a single **camelCase key** — not as a nested group. The `pathToKebab` transform converts them back to kebab-case for the CSS output, so the result is identical either way.
+
+| JSON key | CSS custom property |
+| --- | --- |
+| `"fontFamily"` | `--btn-font-family` |
+| `"fontSize"` | `--btn-font-size` |
+| `"fontStyle"` | `--btn-font-style` |
+| `"fontWeight"` | `--btn-font-weight` |
+| `"lineHeight"` | `--btn-line-height` |
+| `"maxHeight"` | `--btn-max-height` |
+| `"maxWidth"` | `--btn-max-width` |
+| `"textDecoration"` | `--btn-text-decoration` |
+| `"textTransform"` | `--btn-text-transform` |
+
+```json
+// ✅ correct
+"btn": {
+  "fontSize": { "$value": "{fontSize.sm}", "$type": "dimension" },
+  "fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
+}
+
+// ❌ wrong
+"btn": {
+  "font": {
+    "size": { "$value": "{fontSize.sm}", "$type": "dimension" },
+    "weight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
+  }
+}
+```
+
+**Exception — semantic namespaces:** `border`, `color`, `padding`, `margin`, `shadow` used to group multiple sub-properties stay nested, because the group key itself is not a CSS property compound word.
+
+```json
+// ✅ border as a namespace grouping multiple properties
+"border": {
+  "radius": { "$value": "{radius.control}", "$type": "dimension" },
+  "width":  { "$value": "{border.width.sm}", "$type": "dimension" }
+}
+
+// ✅ color as a semantic grouping
+"color": {
+  "background": { "$value": "{color.background.default}", "$type": "color" },
+  "text":       { "$value": "{color.text.default}", "$type": "color" }
+}
+```
+
+### Logical properties → sub-keys of `padding` / `margin`
+
+Sub-axes of `padding` and `margin` use **CSS logical property names** as sub-keys — not physical directions (`x`, `y`, `top`, `bottom`, `left`, `right`).
+
+| Sub-key | CSS logical property | Physical equivalent |
+| --- | --- | --- |
+| `"inline"` | `padding-inline` / `margin-inline` | left + right |
+| `"block"` | `padding-block` / `margin-block` | top + bottom |
+| `"inlineStart"` | `padding-inline-start` / `margin-inline-start` | left (LTR) |
+| `"inlineEnd"` | `padding-inline-end` / `margin-inline-end` | right (LTR) |
+| `"blockStart"` | `padding-block-start` / `margin-block-start` | top |
+| `"blockEnd"` | `padding-block-end` / `margin-block-end` | bottom |
+
+```json
+// ✅ correct
+"padding": {
+  "inline": { "$value": "{spacing.sm}", "$type": "dimension" },
+  "block":  { "$value": "{spacing.xs}", "$type": "dimension" }
+}
+
+// ❌ wrong
+"padding": {
+  "x": { "$value": "{spacing.sm}", "$type": "dimension" },
+  "y": { "$value": "{spacing.xs}", "$type": "dimension" }
+}
+```
+
+**Exception — CSS `top`/`bottom`/`left`/`right` as positioning values** (not margin/padding sub-keys) keep their physical names, since they map to CSS position properties, not logical shorthands.
+
+```json
+// ✅ positioning — physical names are correct here
+"sticky": {
+  "top": { "$value": "4rem", "$type": "dimension" }
+}
+```
+
+### States → nested sub-keys
+
+Interactive states (`default`, `hover`, `active`, `disabled`…) are expressed as **nested keys** under the property they modify. The `default` key is automatically stripped by the build transform.
+
+```json
+"color": {
+  "background": {
+    "default": { "$value": "{color.brand.default}", "$type": "color" },
+    "hover":   { "$value": "{color.brand.hover}",   "$type": "color" }
+  }
+}
+```
+
+```css
+/* output */
+--btn-color-background: var(--color-brand);
+--btn-color-background-hover: var(--color-brand-hover);
+```
+
+States and camelCase properties compose naturally:
+
+```json
+"color": {
+  "textDecoration": {
+    "default": { "$value": "transparent", "$type": "color" },
+    "hover":   { "$value": "{color.link.default}", "$type": "color" }
+  }
+}
+```
+
+```css
+--btn-color-text-decoration: transparent;
+--btn-color-text-decoration-hover: var(--color-link);
+```
+
+---
+
+## References (aliases)
+
+Tokens can reference other tokens using `{dotted.path}` syntax:
+
+```json
+{
+  "color": {
+    "link": {
+      "default": {
+        "$value": "{color.brand.default}",
+        "$type": "color"
+      }
+    }
+  }
+}
+```
+
+In CSS, this maps to `var()`:
+
+```css
+--color-link: var(--color-brand);
+```
+
+This is the key mechanism behind the **primitive → semantic → component** hierarchy.
+
+→ [tr.designtokens.org/format/#alias](https://tr.designtokens.org/format/#alias)
+
+---
+
+## References
+
+- [DTCG specification](https://tr.designtokens.org/format/) — W3C Community Group draft
+- [DTCG GitHub](https://github.com/design-tokens/community-group) — issues, discussion
+- [Style Dictionary v5](https://styledictionary.com/) — token build pipeline, see [STYLE-DICTIONARY.md](STYLE-DICTIONARY.md)

package/docs/naming.md

@@ -0,0 +1,118 @@
+---
+isIndex: false
+title: Naming
+description: The component token naming grammar, the rules behind it, and why colors invert the usual property order.
+weight: 1
+---
+
+Every component token follows one pattern:
+
+```
+--{component}-{property}-{sub-property?}-{state?}
+```
+
+| Pattern | Example |
+| --- | --- |
+| `--{component}` | `--btn` |
+| `--{component}-{property}` | `--btn-padding-inline` |
+| `--{component}-{property}-{sub-property}` | `--btn-color-text-decoration` |
+| `--{component}-{property}-{state}` | `--btn-color-background-hover` |
+
+The property mirrors the CSS property name, so a token reads the same way as the declaration it controls. `--btn-padding-inline` drives `padding-inline`. Colors are the one exception, explained below.
+
+## Rules
+
+**Lowercase kebab-case**, always.
+
+**Component name first**: `--btn-*`, `--badge-*`, `--hero-*`. This is what makes the tokens greppable and what keeps them sorted together in the generated CSS.
+
+**Reference a semantic token whenever the value is a shared design decision.** Colors, spacing, radii, typography and motion should all be `var(--some-semantic-token)`, so that overriding the semantic layer moves every component at once.
+
+About 80% of the tokens in this package do exactly that. The remaining fifth carry raw values, and legitimately so. They fall into four groups:
+
+| Group | Examples |
+| --- | --- |
+| CSS keywords with no semantic equivalent | `transparent`, `none`, `solid`, `start`, `auto`, `underline` |
+| Identity values | `--badge-border-width: 0`, `--container-max-width-mobile: 100%` |
+| Geometry specific to one component | `--drawer-width: 320px`, `--dropdown-min-width: 12rem`, `--drawer-translate: translateX(100%)` |
+| Content and computed values | `--breadcrumb-separator: "/"`, `--hero-height: clamp(...)`, `--hero-media-brightness: 0.5` |
+
+The test to apply is whether another component would ever want the same value for the same reason. If yes, it belongs in the semantic layer and should be referenced from there. If no, a raw value here is correct, and inventing a semantic token for it would only add a hop that means nothing.
+
+**States go last**: `-hover`, `-focus`, `-active`, `-disabled`.
+
+**Alphabetical order within each group**, with a comment introducing each group once a component has many properties.
+
+```css
+/* Border */
+--btn-border-radius: var(--radius-control);
+--btn-border-width:  var(--border-width-sm);
+
+/* Color */
+--btn-color-background:      var(--color-brand);
+--btn-color-border:          var(--color-brand);
+--btn-color-text:            var(--color-text-on-brand);
+--btn-color-text-decoration: transparent;
+
+/* Spacing */
+--btn-gap:            var(--spacing-xs);
+--btn-padding-block:  var(--spacing-control);
+--btn-padding-inline: var(--spacing-control);
+```
+
+## Why colors invert the order
+
+For every other property the token mirrors the CSS property name. For colors it does not: `color` leads and the UI role follows.
+
+| Token | Role | CSS property it drives |
+| --- | --- | --- |
+| `--btn-color-background` | background | `background-color` |
+| `--btn-color-border` | border | `border-color` |
+| `--btn-color-text` | text | `color` |
+| `--btn-color-text-decoration` | text-decoration | `text-decoration-color` |
+| `--form-color-accent` | accent | `color` |
+| `--input-color-placeholder` | placeholder | `color` |
+
+Writing `--btn-background-color` would have been more faithful to CSS, but it scatters a component's colors across the alphabet, between `--btn-border-radius` and `--btn-padding-block`. Leading with `color` groups them into one contiguous block in the generated file and in an editor's autocomplete.
+
+It also makes the component token mirror the global one. `--color-background` becomes `--btn-color-background`, so the relationship between the two layers is visible in the name.
+
+`background` is never abbreviated. It is `color-background`, never `color-bg`.
+
+## The `default` convention
+
+In the JSON source, a state lives in a nested key, and `default` is the unstated one. The build strips it from the generated name.
+
+```json
+{
+  "btn": {
+    "color": {
+      "background": {
+        "default": { "$value": "{color.brand.default}", "$type": "color" },
+        "hover":   { "$value": "{color.brand.hover}",   "$type": "color" }
+      }
+    }
+  }
+}
+```
+
+produces:
+
+```css
+--btn-color-background: var(--color-brand);
+--btn-color-background-hover: var(--color-brand-hover);
+```
+
+Note that the stripping happens on both sides. `{color.brand.default}` becomes `var(--color-brand)`, matching what `@uncinq/design-tokens` actually emits.
+
+## Compound CSS properties
+
+A CSS property with a hyphen is written in camelCase in JSON, and the build converts it back.
+
+| JSON path | CSS custom property |
+| --- | --- |
+| `btn.paddingInline` | `--btn-padding-inline` |
+| `btn.color.textDecoration` | `--btn-color-text-decoration` |
+| `item.borderRadius` | `--item-border-radius` |
+
+Use logical properties (`inline`, `block`, `inlineStart`, `blockEnd`) rather than physical ones (`left`, `right`, `top`, `bottom`), so that a component works in a right-to-left context without a second set of tokens. See [DTCG format](../dtcg/) for the full list of conventions.