@uncinq/component-tokens 1.9.3 → 1.10.0

package/README.md

@@ -4,233 +4,103 @@
 
 <img width="1280" height="640" alt="share-component-tokens" src="https://github.com/user-attachments/assets/ef2387ee-2c45-4706-9e28-0f0341a100ed" />
 
-## What are component tokens?
+Component tokens map semantic values onto the parts of a UI component. 26 components, 390 tokens, authored in [DTCG](https://tr.designtokens.org/format/) JSON and compiled to CSS custom properties.
 
-Component tokens are CSS custom properties scoped to a specific UI component. They sit at the top of the [DTCG](https://tr.designtokens.org/format/) three-layer model:
+## Installation
 
-```text
-primitive   →   semantic   →   component
-(raw values)    (purpose)      (component-scoped)
-```
+This package references semantic tokens from [@uncinq/design-tokens](https://github.com/uncinq/design-tokens), which must be imported first.
 
-Where primitive and semantic tokens are provided by [@uncinq/design-tokens](https://github.com/uncinq/design-tokens), component tokens map those semantic values to specific parts of a component:
+```bash
+npm install @uncinq/design-tokens @uncinq/component-tokens
+```
 
 ```css
-/* semantic token from @uncinq/design-tokens */
---color-brand: var(--color-indigo-600);
-
-/* component token from @uncinq/component-tokens */
---btn-color-background: var(--color-brand);
+@import '@uncinq/design-tokens';
+@import '@uncinq/component-tokens';
 ```
 
-A component token answers: **"which semantic value does this part of this component use?"**
-
----
+Per component:
 
-## Naming convention
-
-All component tokens follow the pattern: `--{component}-{property}-{sub-property?}-{state?}`
-
-The property mirrors the CSS property name, so the token reads the same way as the CSS declaration it controls — colors excepted, where `color` leads and the role follows (see the rules below).
-
-```text
---{component}                    --btn
-  -{property}                    --btn-padding-inline
-    -{sub-property}              --btn-color-text-decoration
-      -{state}                   --btn-color-background-hover
+```css
+@import '@uncinq/design-tokens';
+@import '@uncinq/component-tokens/css/components/button.css';
 ```
 
-### Rules
+Without a build step:
 
-- **Lowercase kebab-case** — always
-- **Component name first** — `--btn-*`, `--badge-*`, `--hero-*`
-- **`color-[role]` for all color tokens** — `color` is the category prefix, the UI role follows: `color-background`, `color-border`, `color-text`, `color-accent`, `color-placeholder`. This groups all color tokens alphabetically under `color-*`. `background` is never abbreviated: `color-background` not `color-bg`.
-- **States at the end** — `-hover`, `-focus`, `-active`, `-disabled`
-- **Reference semantic tokens** — never raw values; always `var(--semantic-token)`
-- **Alphabetical order** — tokens within a file are sorted alphabetically within each group; group related tokens with a comment when the component has many properties:
+```html
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens">
+```
 
-| Token | Role | CSS property |
-| --- | --- | --- |
-| `--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` |
+## Where this sits
 
-```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-inline:        var(--spacing-control);
---btn-padding-block:         var(--spacing-control);
 ```
-
-### Examples
+primitive   →   semantic   →   component
+(raw values)    (purpose)      (this package)
+```
 
 ```css
---btn-color-background: var(--color-brand);
---btn-color-border:     var(--color-brand);
---btn-color-text:       var(--color-text-on-brand);
---btn-border-radius:    var(--radius-control);
---btn-padding-inline:   var(--spacing-control);
---btn-padding-block:    var(--spacing-control);
-
---badge-border-radius:   var(--radius-sm);
---badge-color-background: var(--color-background-muted);
-
---hero-color-background: var(--color-background);
---hero-color-text:       var(--color-text);
---hero-media-brightness: 0.5;
+--color-sienna-600: oklch(0.53 0.195 22);    /* primitive */
+--color-brand:      var(--color-sienna-600);  /* semantic  */
+--btn-color-background: var(--color-brand);   /* component */
 ```
 
----
+A component token answers **"which semantic value does this part of this component use?"**. The extra hop is what lets a project restyle buttons alone without moving the brand color, and what records accessibility decisions such as `--btn-color-text: var(--color-text-on-brand)`.
 
-## CSS cascade layers
+## Overriding
 
-All tokens are declared inside `@layer tokens`, the lowest-priority layer in the stack. This means any project can override any token simply by declaring its own `@layer tokens` block after this package:
+All tokens live in `@layer tokens`. Re-declare any of them after the import, same layer, later source order wins:
 
 ```css
-@import '@uncinq/component-tokens';
-
-/* your project overrides — same layer, wins by source order */
 @layer tokens {
   :root {
     --btn-color-background: var(--color-light);
-    --hero-height: 80svh;
+    --btn-border-radius: 0;
   }
 }
 ```
 
----
-
-## Prerequisites
-
-This package references semantic tokens from [@uncinq/design-tokens](https://github.com/uncinq/design-tokens). Import it before this package:
+Because they are custom properties, a scoped override works too, and is usually the better tool for a contextual variation:
 
 ```css
-@import '@uncinq/design-tokens';
-@import '@uncinq/component-tokens';
-```
-
----
-
-## Installation
-
-```bash
-npm install @uncinq/component-tokens
-# or
-yarn add @uncinq/component-tokens
-```
-
-### Usage — full import
-
-```css
-@import '@uncinq/design-tokens';
-@import '@uncinq/component-tokens';
-```
-
-### Usage — per component
-
-```css
-@import '@uncinq/design-tokens';
-@import '@uncinq/component-tokens/css/components/button.css';
-@import '@uncinq/component-tokens/css/components/badge.css';
-```
-
-### Usage — CDN (no build step)
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
-<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens">
+.promo-section {
+  --btn-color-background: var(--color-light);
+}
 ```
 
----
+## Components covered
 
-## Customization
+`alert` `badge` `breadcrumb` `button` `card` `carousel` `container` `details` `drawer` `dropdown` `embed` `figure` `heading` `hero` `item` `items` `link` `list` `logo` `map` `media` `modal` `nav` `pagination` `surtitle` `table`
 
-### CSS override (recommended)
+## Documentation
 
-Re-declare any token inside `@layer tokens` after the import. Same layer, later source order wins:
+Full documentation: **[socle.uncinq.dev/docs/component-tokens/](https://socle.uncinq.dev/docs/component-tokens/)**
 
-```css
-@import '@uncinq/component-tokens';
+It is also versioned with the code in [`docs/`](docs/), and ships inside the npm package, so it is readable offline and from `node_modules`:
 
-@layer tokens {
-  :root {
-    --btn-color-background: var(--color-light);
-    --btn-border-radius: 0;
-  }
-}
-```
-
-### JSON + rebuild
+- [Naming](docs/naming.md) — the grammar, and why colors invert the property order
+- [Customizing](docs/customizing.md) — which layer to override, and when to add a token
+- [Reference](docs/reference.md) — every token for all 26 components, generated from the sources
+- [DTCG format](docs/dtcg.md) — the authoring format
+- [Style Dictionary](docs/style-dictionary.md) — the build and cross-package references
 
-For deeper changes (adding new tokens, renaming), fork the JSON source files and run the build pipeline locally:
+## Build
 
 ```bash
-npm install
-npm run build   # generates dist/css/components/*.css
+npm install     # @uncinq/design-tokens is required to resolve references
+npm run build   # tokens/**/*.json → dist/css/**
 ```
 
-See [docs/STYLE-DICTIONARY.md](docs/STYLE-DICTIONARY.md) for build pipeline details and token naming conventions.
-
----
-
-## File structure
-
-```text
-tokens/                     ← DTCG JSON source files (edit these)
-  components/
-    alert.json
-    badge.json
-    button.json
-    …
-
-dist/css/                   ← generated CSS (do not edit)
-  index.css                 ← imports all component token files
-  components/
-    alert.css               ← alert / notification banner
-    badge.css               ← badge / pill / tag
-    breadcrumb.css          ← breadcrumb navigation
-    button.css              ← button (all variants)
-    card.css                ← card (alias → item tokens)
-    carousel.css            ← carousel / slider
-    container.css           ← layout container + grid columns
-    details.css             ← <details> / accordion
-    drawer.css              ← off-canvas panel / drawer
-    dropdown.css            ← dropdown menu
-    embed.css               ← video / iframe embed wrapper
-    figure.css              ← <figure> + <figcaption>
-    heading.css             ← heading typography scale
-    hero.css                ← hero / banner section
-    item.css                ← item (canonical card-like unit)
-    items.css               ← items grid / list wrapper
-    link.css                ← inline link
-    list.css                ← styled list
-    logo.css                ← logotype
-    map.css                 ← embedded map
-    media.css               ← media object (image + text)
-    modal.css               ← centered dialog / modal
-    nav.css                 ← navigation bar
-    pagination.css          ← pagination control
-    surtitle.css            ← small label above a heading
-    table.css               ← data table
-```
-
----
+Token files are discovered from disk, so adding `tokens/components/{name}.json` needs no other edit: both the component CSS and `dist/css/index.css` are regenerated. `dist/` is generated and committed, never edit it by hand.
 
 ## References
 
 - [DTCG specification](https://tr.designtokens.org/format/) — W3C Community Group draft
-- [@uncinq/design-tokens](https://github.com/uncinq/design-tokens) — primitive + semantic layers
+- [`@uncinq/design-tokens`](https://github.com/uncinq/design-tokens) — primitive and semantic layers
+- [`@uncinq/css-components`](https://github.com/uncinq/css-components) — the CSS consuming these tokens
 - [MDN: CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)
+
+## License
+
+MIT © [Un Cinq](https://uncinq.dev/)

package/dist/css/components/drawer.css

@@ -13,6 +13,8 @@
     --drawer-color-background: var(--color-background-surface);
     --drawer-color-border: var(--color-border);
     --drawer-color-text: var(--color-text-on-surface);
+    --drawer-color-text-active: var(--color-text-on-surface);
+    --drawer-color-text-hover: var(--color-text-on-surface);
     --drawer-end: 0;
     --drawer-height: 50vh;
     --drawer-padding-block: var(--spacing-surface);

package/dist/css/components/modal.css

@@ -12,6 +12,8 @@
     --modal-color-background: var(--color-background-surface);
     --modal-color-border: var(--color-border);
     --modal-color-text: var(--color-text-on-surface);
+    --modal-color-text-active: var(--color-text-on-surface);
+    --modal-color-text-hover: var(--color-text-on-surface);
     --modal-margin: var(--spacing-sm);
     --modal-max-height: 100dvh;
     --modal-max-width: 30rem;