@uncinq/component-tokens 0.3.0 → 1.0.0

package/README.md

@@ -20,7 +20,7 @@ Where primitive and semantic tokens are provided by [@uncinq/design-tokens](http
 --color-brand: var(--color-indigo-600);
 
 /* component token from @uncinq/component-tokens */
---btn-color-bg: var(--color-brand);
+--btn-background-color: var(--color-brand);
 ```
 
 A component token answers: **"which semantic value does this part of this component use?"**
@@ -29,23 +29,34 @@ A component token answers: **"which semantic value does this part of this compon
 
 ## Naming convention
 
-All component tokens follow the pattern: `--{component}-{category?}-{property}`
+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.
 
 ```text
---{component}               --btn
-  -{category}               --btn-color
-    -{property}             --btn-color-bg
-      -{state}              --btn-color-bg-hover
+--{component}                    --btn
+  -{property}                    --btn-background-color
+    -{sub-property}              --btn-text-decoration-color
+      -{state}                   --btn-background-color-hover
 ```
 
 ### Rules
 
 - **Lowercase kebab-case** — always
 - **Component name first** — `--btn-*`, `--badge-*`, `--hero-*`
-- **`color-*` for all color values** — background, border, text all use `color-` prefix
+- **`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; group related tokens with a comment when the component has many properties:
+- **Alphabetical order** — tokens within a file are sorted alphabetically within each group; group related tokens with a comment when the component has many properties:
+
+| 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` |
 
 ```css
 /* Border */
@@ -53,29 +64,33 @@ All component tokens follow the pattern: `--{component}-{category?}-{property}`
 --btn-border-width:  var(--border-width-normal);
 
 /* Color */
---btn-color-bg:   var(--color-brand);
---btn-color-text: var(--color-text-on-brand);
+--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-sm);
---btn-padding-x: var(--spacing-control);
---btn-padding-y: var(--spacing-control);
+--btn-gap:                   var(--spacing-xs);
+--btn-padding-inline:        var(--spacing-control);
+--btn-padding-block:         var(--spacing-control);
 ```
 
 ### Examples
 
 ```css
---btn-color-bg:      var(--color-brand);
---btn-color-text:    var(--color-text-on-brand);
---btn-border-radius: var(--radius-control);
---btn-padding-x:     var(--spacing-control);
---btn-padding-y:     var(--spacing-control);
-
---badge-border-radius: var(--radius-sm);
---badge-color-bg:    var(--color-bg-muted);
-
---hero-color-bg:     var(--color-bg);
---hero-min-height:   50svh;
+--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-min-height:       50svh;
 ```
 
 ---
@@ -90,7 +105,7 @@ All tokens are declared inside `@layer config`, the lowest-priority layer in the
 /* your project overrides — same layer, wins by source order */
 @layer config {
   :root {
-    --btn-color-bg: var(--color-secondary);
+    --btn-color-background: var(--color-secondary);
     --hero-min-height: 80svh;
   }
 }
@@ -128,49 +143,86 @@ yarn add @uncinq/component-tokens
 
 ```css
 @import '@uncinq/design-tokens';
-@import '@uncinq/component-tokens/tokens/component/button.css';
-@import '@uncinq/component-tokens/tokens/component/badge.css';
+@import '@uncinq/component-tokens/css/component/button.css';
+@import '@uncinq/component-tokens/css/component/badge.css';
 ```
 
 ### Usage — CDN (no build step)
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens/tokens/index.css">
-<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens/tokens/index.css">
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens">
 ```
 
 ---
 
+## Customization
+
+### CSS override (recommended)
+
+Re-declare any token inside `@layer config` after the import. Same layer, later source order wins:
+
+```css
+@import '@uncinq/component-tokens';
+
+@layer config {
+  :root {
+    --btn-color-background: var(--color-secondary);
+    --btn-border-radius: 0;
+  }
+}
+```
+
+### JSON + rebuild
+
+For deeper changes (adding new tokens, renaming), fork the JSON source files and run the build pipeline locally:
+
+```bash
+npm install
+npm run build   # generates dist/css/component/*.css
+```
+
+See [docs/STYLE-DICTIONARY.md](docs/STYLE-DICTIONARY.md) for build pipeline details and token naming conventions.
+
+---
+
 ## File structure
 
 ```text
-tokens/
-  index.css               ← imports all component token files
+tokens/                     ← DTCG JSON source files (edit these)
+  component/
+    alert.json
+    badge.json
+    button.json
+    …
+
+dist/css/                   ← generated CSS (do not edit)
+  index.css                 ← imports all component token files
   component/
-    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)
-    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)
-    nav.css               ← navigation bar
-    pagination.css        ← pagination control
-    surtitle.css          ← small label above a heading
-    table.css             ← data table
+    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)
+    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)
+    nav.css                 ← navigation bar
+    pagination.css          ← pagination control
+    surtitle.css            ← small label above a heading
+    table.css               ← data table
 ```
 
 ---

package/{tokens/component → dist/css/components}/alert.css

@@ -1,4 +1,8 @@
-/* tokens/component/alert.css */
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/alert.css */
 @layer config {
   :root {
     --alert-border-radius: var(--radius-none);

package/{tokens/component → dist/css/components}/badge.css

@@ -1,13 +1,17 @@
-/* tokens/component/badge.css */
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/badge.css */
 @layer config {
   :root {
-    --badge-color-border: transparent;
     --badge-border-radius: var(--radius-pill);
     --badge-border-style: solid;
     --badge-border-width: 0;
+    --badge-color-border: transparent;
     --badge-font-size: var(--font-size-2xs);
     --badge-font-weight: var(--font-weight-control);
-    --badge-padding-x: var(--spacing-xs);
-    --badge-padding-y: var(--spacing-2xs);
+    --badge-padding-inline: var(--spacing-xs);
+    --badge-padding-block: var(--spacing-2xs);
   }
 }

package/dist/css/components/breadcrumb.css

@@ -0,0 +1,20 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/breadcrumb.css */
+@layer config {
+  :root {
+    --breadcrumb-border: var(--breadcrumb-border-width) var(--breadcrumb-border-style) var(--breadcrumb-color-border);
+    --breadcrumb-border-style: var(--border-style-normal);
+    --breadcrumb-border-width: var(--border-width-sm);
+    --breadcrumb-color-border: var(--color-border);
+    --breadcrumb-color-separator: var(--color-text-muted);
+    --breadcrumb-color-text: var(--color-text-muted);
+    --breadcrumb-color-text-active: var(--color-text);
+    --breadcrumb-font-size: var(--font-size-xs);
+    --breadcrumb-gap: var(--spacing-xs);
+    --breadcrumb-padding-block: var(--spacing-xs);
+    --breadcrumb-separator: "/";
+  }
+}

package/dist/css/components/button.css

@@ -0,0 +1,36 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/button.css */
+@layer config {
+  :root {
+    --btn-border-radius: var(--radius-control);
+    --btn-border-style: var(--border-style-normal);
+    --btn-border-width: var(--border-width-sm);
+    --btn-color-background: var(--color-brand);
+    --btn-color-background-hover: var(--color-brand-hover);
+    --btn-color-border: var(--color-brand);
+    --btn-color-border-hover: var(--color-brand);
+    --btn-color-text: var(--color-text-on-brand);
+    --btn-color-text-hover: var(--color-text-on-brand);
+    --btn-color-text-decoration: transparent;
+    --btn-color-text-decoration-hover: transparent;
+    --btn-control-color-background: var(--color-background-muted);
+    --btn-control-color-background-hover: var(--color-background-muted-hover);
+    --btn-control-color-border: transparent;
+    --btn-control-color-border-hover: transparent;
+    --btn-control-color-text: var(--color-text);
+    --btn-control-color-text-hover: var(--color-text);
+    --btn-font-size: var(--font-size-sm);
+    --btn-font-weight: var(--font-weight-control);
+    --btn-gap: var(--spacing-xs);
+    --btn-padding-inline: var(--spacing-control);
+    --btn-padding-block: var(--spacing-control);
+    --btn-shadow: var(--shadow-control);
+    --btn-shadow-hover: var(--shadow-control-hover);
+    --btn-text-decoration-line: underline;
+    --btn-text-transform: none;
+    --btn-transition: var(--transition-color);
+  }
+}

package/dist/css/components/card.css

@@ -0,0 +1,31 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/card.css */
+@layer config {
+  :root {
+    --card-border: var(--card-border-width) var(--card-border-style) var(--card-color-border);
+    --card-border-radius: var(--item-border-radius);
+    --card-border-style: var(--item-border-style);
+    --card-border-width: var(--item-border-width);
+    --card-color-background: var(--item-color-background);
+    --card-color-border: var(--item-color-border);
+    --card-color-text: var(--item-color-text);
+    --card-color-text-muted: var(--item-color-text-muted);
+    --card-gap: var(--item-gap);
+    --card-media-color-background: var(--item-media-color-background);
+    --card-media-order: var(--item-media-order);
+    --card-media-ratio: var(--item-media-ratio);
+    --card-order: var(--item-order);
+    --card-padding-inline: var(--item-padding-inline);
+    --card-padding-block: var(--item-padding-block);
+    --card-shadow: var(--item-shadow);
+    --card-shadow-hover: var(--item-shadow-hover);
+    --card-title-color: var(--item-title-color);
+    --card-title-font-size: var(--item-title-font-size);
+    --card-title-font-weight: var(--item-title-font-weight);
+    --card-title-line-height: var(--item-title-line-height);
+    --card-transition: box-shadow var(--duration-normal) var(--easing-default);
+  }
+}

package/dist/css/components/container.css

@@ -0,0 +1,23 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/container.css */
+@layer config {
+  :root {
+    --columns: 12;
+    --container-max-width-mobile: 100%;
+    --container-max-width-tablet: 100%;
+    --container-max-width-tablet-wide: 100%;
+    --container-max-width-laptop: 100%;
+    --container-max-width-desktop: var(--size-desktop);
+    --gap: var(--spacing-sm);
+    --grid-column: var(--grid-column-mobile);
+    --grid-column-desktop: var(--span-quarter);
+    --grid-column-laptop: var(--span-quarter);
+    --grid-column-mobile: var(--span-full);
+    --grid-column-tablet: var(--span-half);
+    --grid-column-tablet-wide: var(--span-third);
+    --gutter: var(--spacing-fluid-md);
+  }
+}

package/dist/css/components/details.css

@@ -0,0 +1,26 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/details.css */
+@layer config {
+  :root {
+    --details-border-radius: var(--radius-surface);
+    --details-box-shadow: var(--shadow-sm);
+    --details-box-shadow-hover: var(--shadow-md);
+    --details-color-background: var(--color-background);
+    --details-color-border: var(--color-border);
+    --details-color-border-open: var(--color-border-hover);
+    --details-color-text: var(--color-text);
+    --details-icon: var(--icon-chevron);
+    --details-icon-size: var(--icon-size);
+    --details-margin: var(--spacing-sm);
+    --details-content-padding-inline: var(--spacing-sm);
+    --details-content-padding-block: var(--spacing-sm);
+    --details-summary-font-family: var(--font-family-heading);
+    --details-summary-font-size: var(--font-size-md);
+    --details-summary-font-weight: var(--font-weight-heading);
+    --details-summary-padding-inline: var(--spacing-sm);
+    --details-summary-padding-block: var(--spacing-sm);
+  }
+}

package/dist/css/components/drawer.css

@@ -0,0 +1,26 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/drawer.css */
+@layer config {
+  :root {
+    --drawer-backdrop-blur: var(--blur-backdrop);
+    --drawer-backdrop-color: var(--color-backdrop);
+    --drawer-bottom: 0;
+    --drawer-color-background: var(--color-background-surface);
+    --drawer-color-border: var(--color-border);
+    --drawer-color-text: var(--color-text-on-surface);
+    --drawer-end: 0;
+    --drawer-height: 50vh;
+    --drawer-padding: var(--spacing-surface);
+    --drawer-shadow: var(--shadow-surface);
+    --drawer-start: auto;
+    --drawer-top: 0;
+    --drawer-transition-duration: var(--duration-slow);
+    --drawer-transition-easing: var(--easing-out-expo);
+    --drawer-translate: translateX(100%);
+    --drawer-width: 320px;
+    --drawer-z-index: var(--z-index-drawer);
+  }
+}

package/dist/css/components/dropdown.css

@@ -0,0 +1,30 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/dropdown.css */
+@layer config {
+  :root {
+    --dropdown-border-radius: var(--radius-surface);
+    --dropdown-border-style: var(--border-style-normal);
+    --dropdown-border-width: var(--border-width-sm);
+    --dropdown-color-background: var(--color-background-surface);
+    --dropdown-color-border: var(--color-border);
+    --dropdown-color-text: var(--color-text-on-surface);
+    --dropdown-icon: var(--icon-chevron);
+    --dropdown-icon-size: var(--icon-size);
+    --dropdown-item-border-radius: var(--radius-xs);
+    --dropdown-item-color-background: var(--color-background);
+    --dropdown-item-color-background-hover: var(--color-background-muted);
+    --dropdown-item-font-size: var(--font-size-xs);
+    --dropdown-item-padding-inline: var(--spacing-2xs);
+    --dropdown-item-padding-block: var(--spacing-2xs);
+    --dropdown-min-width: 12rem;
+    --dropdown-padding: var(--size-4);
+    --dropdown-shadow: var(--shadow-sm);
+    --dropdown-transition-duration: var(--duration-fast);
+    --dropdown-transition-easing: var(--easing-out);
+    --dropdown-translate-y: -4px;
+    --dropdown-z-index: var(--z-index-dropdown);
+  }
+}

package/dist/css/components/embed.css

@@ -0,0 +1,17 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/embed.css */
+@layer config {
+  :root {
+    --embed-border: var(--embed-border-width) var(--embed-border-style) var(--embed-color-border);
+    --embed-border-radius: var(--radius-none);
+    --embed-border-style: var(--border-style-normal);
+    --embed-border-width: var(--border-width-sm);
+    --embed-box-shadow: none;
+    --embed-color-border: var(--color-border);
+    --embed-max-width: 100%;
+    --embed-ratio: var(--ratio-video);
+  }
+}

package/dist/css/components/figure.css

@@ -0,0 +1,13 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/figure.css */
+@layer config {
+  :root {
+    --figure-figcaption-font-size: var(--font-size-sm);
+    --figure-figcaption-gap: var(--spacing-xs);
+    --figure-gap: var(--spacing-xs);
+    --figure-margin-block: var(--spacing-md);
+  }
+}

package/dist/css/components/heading.css

@@ -0,0 +1,11 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/heading.css */
+@layer config {
+  :root {
+    --heading-gap: var(--spacing-xs);
+    --heading-margin-block-end: var(--spacing-fluid-md);
+  }
+}

package/dist/css/components/hero.css

@@ -0,0 +1,20 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/hero.css */
+@layer config {
+  :root {
+    --hero-color-background: var(--color-background);
+    --hero-color-link: var(--color-text);
+    --hero-color-text: var(--color-text);
+    --hero-cover-brightness: 0.3;
+    --hero-gap: var(--spacing-sm);
+    --hero-min-height: 25rem;
+    --hero-min-height-tablet: 37.5rem;
+    --hero-min-height-desktop: 50rem;
+    --hero-padding: var(--spacing-md) 0;
+    --hero-title-color: var(--color-text);
+    --hero-title-font-size: var(--font-size-heading-01);
+  }
+}

package/dist/css/components/item.css

@@ -0,0 +1,44 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/item.css */
+@layer config {
+  :root {
+    --item-border-radius: var(--radius-surface);
+    --item-border-style: var(--border-style-normal);
+    --item-border-width: var(--border-width-sm);
+    --item-btn-border-width: 0;
+    --item-btn-color-background: transparent;
+    --item-btn-color-text: var(--color-brand);
+    --item-btn-padding: 0;
+    --item-btn-text-decoration: none;
+    --item-btn-text-decoration-hover: underline;
+    --item-color-background: var(--color-background);
+    --item-color-border: var(--color-border);
+    --item-color-text: var(--color-text);
+    --item-color-text-muted: var(--color-text-muted);
+    --item-gap: var(--spacing-sm);
+    --item-media-color-background: var(--media-color-background);
+    --item-media-order: -2;
+    --item-media-ratio: var(--media-ratio);
+    --item-metas-border: var(--border-width-sm) var(--border-style-normal) var(--color-border);
+    --item-metas-border-end: 0;
+    --item-metas-border-start: 0;
+    --item-metas-color-background: var(--item-color-background);
+    --item-metas-font-size: var(--font-size-2xs);
+    --item-metas-order: -1;
+    --item-metas-padding-inline: var(--spacing-card);
+    --item-metas-padding-block: var(--spacing-card) 0;
+    --item-order: none;
+    --item-padding-inline: var(--spacing-card);
+    --item-padding-block: var(--spacing-card);
+    --item-shadow: var(--shadow-sm);
+    --item-shadow-hover: var(--shadow-md);
+    --item-title-color: var(--color-text);
+    --item-title-font-size: var(--font-size-md);
+    --item-title-font-weight: var(--font-weight-heading);
+    --item-title-line-height: var(--line-height-heading);
+    --item-transition: box-shadow var(--duration-normal) var(--easing-default);
+  }
+}

package/dist/css/components/items.css

@@ -0,0 +1,13 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/items.css */
+@layer config {
+  :root {
+    --items-cols: auto-fill;
+    --items-gap: var(--gap);
+    --items-max-width: 100%;
+    --items-min-width: 30ch;
+  }
+}

package/{tokens/component → dist/css/components}/link.css

@@ -1,8 +1,13 @@
-/* tokens/component/link.css */
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/link.css */
 @layer config {
   :root {
     --link-color-text-decoration: initial;
     --link-color-text-decoration-hover: transparent;
     --link-text-decoration-line: underline;
+    --link-transition: var(--transition-color);
   }
 }

package/dist/css/components/list.css

@@ -0,0 +1,15 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/list.css */
+@layer config {
+  :root {
+    --list-item-font-size: var(--font-size-sm);
+    --list-item-gap: var(--spacing-2xs);
+    --list-item-marker: '-';
+    --list-item-marker-gap: var(--spacing-2xs);
+    --list-label-font-weight: var(--font-weight-bold);
+    --list-label-margin-block: var(--spacing-2xs);
+  }
+}

package/dist/css/components/logo.css

@@ -0,0 +1,16 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/logo.css */
+@layer config {
+  :root {
+    --logo-color: var(--color-text);
+    --logo-font-family: var(--font-family-heading);
+    --logo-font-size: var(--font-size-md);
+    --logo-font-weight: var(--font-weight-heading);
+    --logo-height: var(--size-24);
+    --logo-height-tablet: var(--size-32);
+    --logo-letter-spacing: 0;
+  }
+}

package/dist/css/components/map.css

@@ -0,0 +1,13 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/map.css */
+@layer config {
+  :root {
+    --map-color-background: var(--color-background-muted);
+    --map-margin-block: var(--spacing-md);
+    --map-ratio: var(--ratio-cinema);
+    --map-ratio-mobile: var(--ratio-landscape);
+  }
+}

package/dist/css/components/media.css

@@ -0,0 +1,11 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+/* components/media.css */
+@layer config {
+  :root {
+    --media-color-background: var(--color-background-media);
+    --media-ratio: var(--ratio-video);
+  }
+}