@uncinq/design-tokens 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Un Cinq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @uncinq/design-tokens
+
+> Framework-agnostic design tokens for Un Cinq projects — Hugo, Symfony, Shopify, or any CSS environment.
+
+<img width="1280" height="640" alt="share-design-tokens" src="https://github.com/user-attachments/assets/66b8ce73-b07d-4cd0-bcb7-f8e0f7a5bb98" />
+
+## What are design tokens?
+
+Design tokens are the atomic decisions of a design system: colors, spacing, typography, motion. Instead of hardcoding `#ae003f` or `1rem` throughout your codebase, you name the decision — `--color-brand`, `--spacing-md` — and reference that name everywhere.
+
+## Token architecture
+
+This package follows the [DTCG](docs/dtcg.md) three-layer model — primitive → semantic → component:
+
+```
+primitive   →   semantic   →   component
+(raw values)    (purpose)      (component-scoped, not in this package)
+```
+
+### Layer 1 — Primitive
+
+Raw, context-free values. No opinions about where they're used.
+
+```css
+--color-indigo-600: #4338ca;
+--size-16: 1rem;
+--font-weight-bold: 700;
+```
+
+A primitive token answers: **"what is the value?"**
+
+### Layer 2 — Semantic
+
+Named by purpose, not by appearance. References primitives via CSS `var()`.
+
+```css
+--color-brand:   var(--color-indigo-600);
+--spacing-md:    var(--size-30);
+--font-weight-heading: var(--font-weight-bold);
+```
+
+A semantic token answers: **"what is this value for?"**
+
+This is the layer that gives portability: all projects consuming `@uncinq/design-tokens` share the same semantic API. When the brand color changes, you update one primitive — all semantic tokens that reference it update automatically.
+
+### Layer 3 — Component
+
+Scoped to a specific component. Generic component tokens are provided by [@uncinq/component-tokens](https://github.com/uncinq/component-tokens); project-specific ones live in each project's own design system.
+
+```css
+--alert-border-radius: var(--radius-none);
+--btn-padding: var(--spacing-control);
+```
+
+---
+
+## Naming convention
+
+All tokens follow the pattern: `--{category}-{subcategory?}-{variant}-{state?}`
+
+```
+--{category}                     --color
+  -{subcategory}                 --color-text
+    -{variant}                   --color-text-muted
+      -{state}                   --color-text-disabled
+```
+
+### Rules
+
+- **Lowercase kebab-case** — always
+- **No component names** in primitive or semantic tokens (`--button-*` belongs in component tokens, not here)
+- **Semantic tokens are named by intent** — they may reference a primitive via `var()` or carry a raw value when the value itself has design intent (e.g. `--z-index-modal: 400`, `--radius-pill: 9999px`)
+- **States at the end** — `-hover`, `-focus`, `-active`, `-disabled`, `-checked`
+- **`color-*` prefix for all color values** — even when the CSS property is `background-color`, `border-color`, etc.
+- **Alphabetical order** — tokens within a file are sorted alphabetically; group related tokens with a comment when the file has many entries:
+
+```css
+/* Brand */
+--color-brand:       var(--color-indigo-600);
+--color-brand-hover: var(--color-indigo-700);
+
+/* Text */
+--color-text:        var(--color-gray-900);
+--color-text-muted:  var(--color-gray-500);
+```
+
+### Scales
+
+| Use case | Scale | Example |
+| --- | --- | --- |
+| Color palettes | Numeric `100–900` | `--color-gray-500` |
+| Heading levels | Zero-padded `01–06` | `--font-size-heading-01` |
+| Layout / spacing | T-shirt `2xs xs sm md lg xl 2xl` | `--spacing-md` |
+| Radius, shadow, size | T-shirt `2xs xs sm md lg xl 2xl` | `--radius-sm` |
+| Purposeful aliases | Named | `--radius-control`, `--radius-pill` |
+
+### Category reference
+
+| Category | Covers | Example tokens |
+| --- | --- | --- |
+| `color` | All color values | `--color-brand`, `--color-bg-muted`, `--color-text-on-dark` |
+| `font-family` | Typefaces | `--font-family-sans`, `--font-family-heading` |
+| `font-size` | Text sizes | `--font-size-sm`, `--font-size-heading-01` |
+| `font-weight` | Weight values | `--font-weight-bold`, `--font-weight-heading` |
+| `line-height` | Line heights | `--line-height-tight`, `--line-height-heading` |
+| `letter-spacing` | Tracking | `--letter-spacing-large` |
+| `text-decoration` | Decoration props | `--text-decoration-underline`, `--text-decoration-offset` |
+| `spacing` | Margin / padding | `--spacing-md`, `--spacing-section` |
+| `size` | Width / height | `--size-16`, `--size-tablet` |
+| `radius` | Border radius | `--radius-md`, `--radius-pill` |
+| `border` | Border style/width | `--border-width-normal`, `--border-style-solid` |
+| `shadow` | Box shadows | `--shadow-md`, `--shadow-center-sm` |
+| `duration` | Animation timing | `--duration-fast` |
+| `easing` | Timing functions | `--easing-bounce` |
+| `transition` | Shorthand transitions | `--transition-normal`, `--transition-color` |
+| `ratio` | Aspect ratios | `--ratio-16-9` |
+| `flex` | Flex-basis fractions | `--flex-half`, `--flex-third` |
+| `fluid-text` | Responsive fluid type scale (Utopia) | `--fluid-text-sm`, `--fluid-text-xl` |
+| `fluid-spacing` | Responsive fluid spacing scale (Utopia) | `--fluid-spacing-sm`, `--fluid-spacing-lg` |
+| `focus` | Focus ring tokens | `--focus-color`, `--focus-outline-width` |
+| `opacity` | Opacity values | `--opacity-disabled`, `--opacity-overlay` |
+| `span` | Grid column spans | `--span-6`, `--span-4` |
+| `z-index` | Stacking order | `--z-index-modal`, `--z-index-dropdown` |
+| `max-width` | Readability caps | `--max-width-paragraph` |
+
+---
+
+## CSS cascade layers
+
+All tokens are declared inside `@layer config`, the lowest-priority layer in the stack:
+
+```css
+@layer config, base, layouts, vendors, components;
+```
+
+This means any project can **override any token** in its own `@layer config` block, simply by importing after this package:
+
+```css
+@import '@uncinq/design-tokens/tokens/index.css'; /* package defaults */
+
+/* your project overrides — same layer, wins by order */
+@layer config {
+  :root {
+    --color-brand: #0070f3;
+    --font-family-sans: 'Inter', system-ui, sans-serif;
+  }
+}
+```
+
+→ MDN: [Using CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)
+
+---
+
+## Installation
+
+```bash
+npm install @uncinq/design-tokens
+# or
+yarn add @uncinq/design-tokens
+```
+
+### Usage — CSS import
+
+```css
+/* everything */
+@import '@uncinq/design-tokens';
+
+/* or by layer */
+@import '@uncinq/design-tokens/tokens/primitive.css';
+@import '@uncinq/design-tokens/tokens/semantic.css';
+
+/* or file by file */
+@import '@uncinq/design-tokens/tokens/primitive/color.css';
+@import '@uncinq/design-tokens/tokens/semantic/color.css';
+```
+
+### Usage — CDN (no build step)
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens/tokens/index.css">
+```
+
+---
+
+## File structure
+
+```
+tokens/
+  index.css               ← imports all layers in order
+  primitive/
+    color.css             ← color palette (Tailwind v3 — amber, blue, gray, green…)
+    font.css              ← font families, weights, line-heights, text-decoration
+    opacity.css           ← opacity scale (0 → 1)
+    shadow.css            ← box-shadow scale
+    size.css              ← rem scale (--size-1 → --size-1920)
+  semantic/
+    border.css            ← border styles and widths
+    color.css             ← purposeful color aliases (--color-brand, --color-bg…)
+    fluid.css             ← responsive clamp() scales (--fluid-text-*, --fluid-spacing-*)
+    focus.css             ← focus ring tokens (color, style, width, offset)
+    form.css              ← form control tokens (input, label, checkbox, switch…)
+    grid.css              ← columns, gap, flex fractions, integer spans (--span-1 → --span-24)
+    motion.css            ← duration, easing (standard + expressive + spring), transitions
+    opacity.css           ← purposeful opacity aliases (disabled, overlay)
+    radius.css            ← border-radius scale + purposeful aliases
+    ratio.css             ← aspect-ratio values (16/9, 4/3…)
+    size.css              ← T-shirt scale + breakpoint aliases
+    spacing.css           ← spacing scale + purposeful aliases
+    typography.css        ← font-size scale (fixed + fluid), heading sizes, max-widths
+    z-index.css           ← stacking order (below → tooltip)
+```
+
+---
+
+## References
+
+- [DTCG — format and concepts](docs/dtcg.md)
+- [DTCG specification](https://tr.designtokens.org/format/) — W3C Community Group draft
+- [Style Dictionary](https://amzn.github.io/style-dictionary/) — token build pipeline (JSON → CSS/SCSS/JS)
+- [MDN: CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@uncinq/design-tokens",
+  "version": "0.1.0",
+  "description": "Framework-agnostic CSS design tokens — primitive and semantic layers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uncinq/design-tokens.git"
+  },
+  "homepage": "https://github.com/uncinq/design-tokens#readme",
+  "author": {
+    "name": "Un Cinq",
+    "url": "https://uncinq.dev/"
+  },
+  "keywords": [
+    "design-tokens",
+    "css",
+    "custom-properties",
+    "design-system"
+  ],
+  "files": [
+    "tokens/"
+  ],
+  "exports": {
+    ".": "./tokens/index.css",
+    "./tokens/index.css": "./tokens/index.css",
+    "./tokens/primitive.css": "./tokens/primitive.css",
+    "./tokens/semantic.css": "./tokens/semantic.css",
+    "./tokens/primitive/*": "./tokens/primitive/*",
+    "./tokens/semantic/*": "./tokens/semantic/*"
+  },
+  "style": "./tokens/index.css",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tokens/index.css

@@ -0,0 +1,10 @@
+/* @uncinq/design-tokens — index.css */
+/*
+ * Imports all layers in order: primitives first, then semantic.
+ * Use this file to get everything, or import primitive.css / semantic.css individually.
+ *
+ * Usage:
+ *   @import '@uncinq/design-tokens/tokens/index.css';
+ */
+@import 'primitive.css';
+@import 'semantic.css';

package/tokens/primitive/color.css

@@ -0,0 +1,128 @@
+/* primitive/color.css */
+@layer config {
+  :root {
+    --color-black: #000000;
+
+    --color-amber-100: #fef3c7;
+    --color-amber-200: #fde68a;
+    --color-amber-300: #fcd34d;
+    --color-amber-400: #fbbf24;
+    --color-amber-500: #f59e0b;
+    --color-amber-600: #d97706;
+    --color-amber-700: #b45309;
+    --color-amber-800: #92400e;
+    --color-amber-900: #78350f;
+
+    --color-blue-100: #dbeafe;
+    --color-blue-200: #bfdbfe;
+    --color-blue-300: #93c5fd;
+    --color-blue-400: #60a5fa;
+    --color-blue-500: #3b82f6;
+    --color-blue-600: #2563eb;
+    --color-blue-700: #1d4ed8;
+    --color-blue-800: #1e40af;
+    --color-blue-900: #1e3a8a;
+
+    --color-gray-100: #f3f4f6;
+    --color-gray-200: #e5e7eb;
+    --color-gray-300: #d1d5db;
+    --color-gray-400: #9ca3af;
+    --color-gray-500: #6b7280;
+    --color-gray-600: #4b5563;
+    --color-gray-700: #374151;
+    --color-gray-800: #1f2937;
+    --color-gray-900: #111827;
+
+    --color-green-100: #dcfce7;
+    --color-green-200: #bbf7d0;
+    --color-green-300: #86efac;
+    --color-green-400: #4ade80;
+    --color-green-500: #22c55e;
+    --color-green-600: #16a34a;
+    --color-green-700: #15803d;
+    --color-green-800: #166534;
+    --color-green-900: #14532d;
+
+    --color-cyan-100: #cffafe;
+    --color-cyan-200: #a5f3fc;
+    --color-cyan-300: #67e8f9;
+    --color-cyan-400: #22d3ee;
+    --color-cyan-500: #06b6d4;
+    --color-cyan-600: #0891b2;
+    --color-cyan-700: #0e7490;
+    --color-cyan-800: #155e75;
+    --color-cyan-900: #164e63;
+
+    --color-indigo-100: #e0e7ff;
+    --color-indigo-200: #c7d2fe;
+    --color-indigo-300: #a5b4fc;
+    --color-indigo-400: #818cf8;
+    --color-indigo-500: #4f46e5;
+    --color-indigo-600: #4338ca;
+    --color-indigo-700: #3730a3;
+    --color-indigo-800: #312e81;
+    --color-indigo-900: #2e1065;
+
+    --color-orange-100: #ffedd5;
+    --color-orange-200: #fed7aa;
+    --color-orange-300: #fdba74;
+    --color-orange-400: #fb923c;
+    --color-orange-500: #f97316;
+    --color-orange-600: #ea580c;
+    --color-orange-700: #c2410c;
+    --color-orange-800: #9a3412;
+    --color-orange-900: #431407;
+
+    --color-pink-100: #fce7f3;
+    --color-pink-200: #fbcfe8;
+    --color-pink-300: #f9a8d4;
+    --color-pink-400: #f472b6;
+    --color-pink-500: #ec4899;
+    --color-pink-600: #db2777;
+    --color-pink-700: #be185d;
+    --color-pink-800: #9d174d;
+    --color-pink-900: #831843;
+
+    --color-purple-100: #f3e8ff;
+    --color-purple-200: #e9d5ff;
+    --color-purple-300: #d8b4fe;
+    --color-purple-400: #c084fc;
+    --color-purple-500: #a855f7;
+    --color-purple-600: #9333ea;
+    --color-purple-700: #7e22ce;
+    --color-purple-800: #6b21a8;
+    --color-purple-900: #581c87;
+
+    --color-red-100: #fee2e2;
+    --color-red-200: #fecaca;
+    --color-red-300: #fca5a5;
+    --color-red-400: #f87171;
+    --color-red-500: #ef4444;
+    --color-red-600: #dc2626;
+    --color-red-700: #b91c1c;
+    --color-red-800: #991b1b;
+    --color-red-900: #7f1d1d;
+
+    --color-teal-100: #ccfbf1;
+    --color-teal-200: #99f6e4;
+    --color-teal-300: #5eead4;
+    --color-teal-400: #2dd4bf;
+    --color-teal-500: #14b8a6;
+    --color-teal-600: #0d9488;
+    --color-teal-700: #0f766e;
+    --color-teal-800: #115e59;
+    --color-teal-900: #134e4a;
+
+    --color-white: #ffffff;
+
+    --color-yellow-100: #fef9c3;
+    --color-yellow-200: #fef08a;
+    --color-yellow-300: #fde047;
+    --color-yellow-400: #facc15;
+    --color-yellow-500: #eab308;
+    --color-yellow-600: #ca8a04;
+    --color-yellow-700: #a16207;
+    --color-yellow-800: #854d0e;
+    --color-yellow-900: #713f12;
+  }
+}

package/tokens/primitive/font.css

@@ -0,0 +1,30 @@
+/* primitive/font.css */
+@layer config {
+  :root {
+    /* Families */
+    --font-family-mono:  ui-monospace, monospace;
+    --font-family-sans:  system-ui, sans-serif;
+    --font-family-serif: Georgia, serif;
+
+    /* Weights */
+    --font-weight-thin:     100;
+    --font-weight-light:    300;
+    --font-weight-normal:   400;
+    --font-weight-medium:   500;
+    --font-weight-semibold: 600;
+    --font-weight-bold:     700;
+    --font-weight-black:    900;
+
+    /* Line heights */
+    --line-height-tight:   1.1;
+    --line-height-snug:    1.25;
+    --line-height-normal:  1.5;
+    --line-height-relaxed: 1.75;
+
+    /* Text decoration */
+    --text-decoration-none:      none;
+    --text-decoration-underline: underline;
+    --text-decoration-offset:    0.25rem;
+    --text-decoration-thickness: 1px;
+  }
+}

package/tokens/primitive/opacity.css

@@ -0,0 +1,12 @@
+/* primitive/opacity.css */
+@layer config {
+  :root {
+    --opacity-0:   0;
+    --opacity-10:  0.1;
+    --opacity-25:  0.25;
+    --opacity-50:  0.5;
+    --opacity-75:  0.75;
+    --opacity-90:  0.9;
+    --opacity-100: 1;
+  }
+}

package/tokens/primitive/shadow.css

@@ -0,0 +1,16 @@
+/* primitive/shadow.css */
+@layer config {
+  :root {
+    --shadow-none: none;
+
+    /* Directional (top-left light source) */
+    --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+    --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+    --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+
+    /* Centered (ambient glow) */
+    --shadow-center-sm: 0 0 2px  2px  rgb(0 0 0 / 0.05);
+    --shadow-center-md: 0 0 5px  5px  rgb(0 0 0 / 0.05);
+    --shadow-center-lg: 0 0 10px 10px rgb(0 0 0 / 0.05);
+  }
+}

package/tokens/primitive/size.css

@@ -0,0 +1,57 @@
+/* primitive/size.css */
+/*
+ * Pixel-named rem scale.
+ * Name = equivalent px value at 16px base, value = rem equivalent.
+ * e.g. --size-16 = 1rem = 16px
+ */
+@layer config {
+  :root {
+    --size-1:  0.0625rem;
+    --size-2:  0.125rem;
+    --size-3:  0.1875rem;
+    --size-4:  0.25rem;
+    --size-5:  0.3125rem;
+    --size-6:  0.375rem;
+    --size-7:  0.4375rem;
+    --size-8:  0.5rem;
+    --size-9:  0.5625rem;
+    --size-10: 0.625rem;
+    --size-11: 0.6875rem;
+    --size-12: 0.75rem;
+    --size-13: 0.8125rem;
+    --size-14: 0.875rem;
+    --size-15: 0.9375rem;
+    --size-16: 1rem;
+    --size-17: 1.0625rem;
+    --size-18: 1.125rem;
+    --size-19: 1.1875rem;
+    --size-20: 1.25rem;
+    --size-22: 1.375rem;
+    --size-24: 1.5rem;
+    --size-25: 1.5625rem;
+    --size-26: 1.625rem;
+    --size-28: 1.75rem;
+    --size-30: 1.875rem;
+    --size-32: 2rem;
+    --size-40: 2.5rem;
+    --size-48: 3rem;
+    --size-50: 3.125rem;
+    --size-52: 3.25rem;
+    --size-56: 3.5rem;
+    --size-60: 3.75rem;
+    --size-64: 4rem;
+    --size-68: 4.25rem;
+    --size-72: 4.5rem;
+    --size-80: 5rem;
+    --size-88: 5.5rem;
+    --size-96: 6rem;
+    --size-100: 6.25rem;
+    --size-150: 9.375rem;
+
+    /* Screen widths */
+    --size-768:  48rem;
+    --size-1024: 64rem;
+    --size-1440: 90rem;
+    --size-1920: 120rem;
+  }
+}

package/tokens/primitive.css

@@ -0,0 +1,8 @@
+/* @uncinq/design-tokens — primitive.css */
+@layer config;
+
+@import 'primitive/color.css';
+@import 'primitive/font.css';
+@import 'primitive/opacity.css';
+@import 'primitive/shadow.css';
+@import 'primitive/size.css';

package/tokens/semantic/border.css

@@ -0,0 +1,15 @@
+/* semantic/border.css */
+@layer config {
+  :root {
+    /* Styles */
+    --border-style-dotted: dotted;
+    --border-style-dashed: dashed;
+    --border-style-solid:  solid;
+
+    /* Widths */
+    --border-width-none:   0px;
+    --border-width-normal: 1px;
+    --border-width-large:  2px;
+    --border-width-xl:     4px;
+  }
+}

package/tokens/semantic/color.css

@@ -0,0 +1,88 @@
+/* semantic/color.css */
+/*
+ * Purposeful color aliases — reference primitives, never raw values.
+ * Override --color-brand (and optionally --color-*) in your project to rebrand.
+ *
+ * Default brand: claret (deep red).
+ */
+@layer config {
+  :root {
+    /* ── Brand ─────────────────────────────────────────────────────────── */
+    --color-brand:       var(--color-indigo-600);
+    --color-brand-muted: var(--color-indigo-100);
+    --color-brand-hover: var(--color-indigo-700);
+    --color-brand-strong: var(--color-indigo-900);
+
+    /* ── Backgrounds ───────────────────────────────────────────────────── */
+    --color-bg:       var(--color-white);
+    --color-bg-accent: var(--color-brand);
+    --color-bg-media: var(--color-gray-200);
+    --color-bg-muted: var(--color-gray-100);
+
+    /* ── Borders & focus ───────────────────────────────────────────────── */
+    --color-border: var(--color-gray-200);
+    --color-focus:  var(--color-brand);
+
+    /* ── Text ──────────────────────────────────────────────────────────── */
+    --color-active:          var(--color-brand);
+    --color-credit:          var(--color-text-muted);
+    --color-heading:         var(--color-black);
+    --color-link:            var(--color-black);
+    --color-text:            var(--color-gray-900);
+    --color-text-muted:      var(--color-gray-500);
+    --color-text-disabled:   var(--color-gray-300);
+    --color-text-on-accent:    var(--color-white);
+    --color-text-on-brand:     var(--color-white);
+    --color-text-on-danger:    var(--color-white);
+    --color-text-on-dark:      var(--color-white);
+    --color-text-on-info:      var(--color-white);
+    --color-text-on-light:     var(--color-gray-900);
+    --color-text-on-primary:   var(--color-white);
+    --color-text-on-secondary: var(--color-white);
+    --color-text-on-success:   var(--color-white);
+    --color-text-on-warning:   var(--color-gray-900);
+
+    /* ── Semantic variants ─────────────────────────────────────────────── */
+
+    /* Primary (alias of brand) */
+    --color-primary:       var(--color-brand);
+    --color-primary-muted: var(--color-brand-muted);
+    --color-primary-hover: var(--color-brand-hover);
+    --color-primary-strong: var(--color-brand-strong);
+
+    /* Secondary */
+    --color-secondary:       var(--color-gray-500);
+    --color-secondary-muted: var(--color-gray-100);
+    --color-secondary-strong: var(--color-gray-800);
+
+    /* Danger */
+    --color-danger:       var(--color-red-500);
+    --color-danger-muted: var(--color-red-100);
+    --color-danger-strong: var(--color-red-900);
+
+    /* Dark */
+    --color-dark:        var(--color-gray-900);
+    --color-dark-muted:  var(--color-gray-100);
+    --color-dark-strong: var(--color-black);
+
+    /* Info */
+    --color-info:       var(--color-blue-500);
+    --color-info-muted: var(--color-blue-100);
+    --color-info-strong: var(--color-blue-900);
+
+    /* Light */
+    --color-light:       var(--color-gray-200);
+    --color-light-muted: var(--color-gray-100);
+    --color-light-strong: var(--color-gray-700);
+
+    /* Success */
+    --color-success:       var(--color-green-500);
+    --color-success-muted: var(--color-green-100);
+    --color-success-strong: var(--color-green-900);
+
+    /* Warning */
+    --color-warning:       var(--color-yellow-500);
+    --color-warning-muted: var(--color-yellow-100);
+    --color-warning-strong: var(--color-yellow-900);
+  }
+}

package/tokens/semantic/fluid.css

@@ -0,0 +1,30 @@
+/* semantic/fluid.css */
+/*
+ * Responsive fluid scales using clamp().
+ * Viewport range: 360px → 1440px (1080px range).
+ * preferred = intercept + slope×vw  (exact linear interpolation, no approximation)
+ * $type: dimension
+ *
+ * https://utopia.fyi/clamp/calculator/
+ */
+@layer config {
+  :root {
+
+    /* ── Fluid text scale ───────────────────────────────────────────────── */
+    --fluid-text-2xs: clamp(0.5625rem, 0.5rem + 0.2778vw, 0.75rem);   /*  9 →  12px */
+    --fluid-text-xs:  clamp(0.75rem, 0.625rem + 0.5556vw, 1.125rem);  /* 12 →  18px */
+    --fluid-text-sm:  clamp(1.125rem, 1rem + 0.5556vw, 1.5rem);       /* 18 →  24px */
+    --fluid-text-md:  clamp(1.5rem, 1.25rem + 1.1111vw, 2.25rem);     /* 24 →  36px */
+    --fluid-text-lg:  clamp(2.25rem, 2rem + 1.1111vw, 3rem);          /* 36 →  48px */
+    --fluid-text-xl:  clamp(3rem, 2.5rem + 2.2222vw, 4.5rem);         /* 48 →  72px */
+    --fluid-text-2xl: clamp(4.5rem, 4rem + 2.2222vw, 6rem);           /* 72 →  96px */
+
+    /* ── Fluid spacing scale ────────────────────────────────────────────── */
+    --fluid-spacing-xs: clamp(0.625rem, 0.4167rem + 0.9259vw, 1.25rem);   /* 10 →  20px */
+    --fluid-spacing-sm: clamp(1.25rem, 0.8333rem + 1.8519vw, 2.5rem);     /* 20 →  40px */
+    --fluid-spacing-md: clamp(1.875rem, 1.25rem + 2.7778vw, 3.75rem);     /* 30 →  60px */
+    --fluid-spacing-lg: clamp(2.5rem, 1.6667rem + 3.7037vw, 5rem);        /* 40 →  80px */
+    --fluid-spacing-xl: clamp(3.125rem, 2.0833rem + 4.6296vw, 6.25rem);   /* 50 → 100px */
+
+  }
+}

package/tokens/semantic/focus.css

@@ -0,0 +1,9 @@
+/* semantic/focus.css */
+@layer config {
+  :root {
+    --focus-color:           var(--color-focus);
+    --focus-outline-style:   solid;
+    --focus-outline-width:   2px;
+    --focus-outline-offset:  2px;
+  }
+}

package/tokens/semantic/form.css

@@ -0,0 +1,93 @@
+/* semantic/form.css */
+@layer config {
+  :root {
+    /* ── Base form ─────────────────────────────────────────────────────── */
+    --form-color-accent:     var(--color-black);
+    --form-color-background: var(--color-white);
+    --form-color-border:     var(--color-border);
+    --form-color-text:       var(--color-text);
+    --form-border-radius:    var(--radius-xs);
+    --form-border-width:     var(--border-width-normal);
+
+    /* ── Input ─────────────────────────────────────────────────────────── */
+    --input-color-background:   var(--form-color-background);
+    --input-color-border:       var(--form-color-border);
+    --input-color-border-hover: var(--form-color-accent);
+    --input-color-placeholder:  var(--color-text-muted);
+    --input-color-text:         var(--form-color-text);
+    --input-border-radius:      var(--form-border-radius);
+    --input-border-width:       var(--form-border-width);
+    --input-padding:            var(--spacing-control);
+
+    /* ── Textarea ──────────────────────────────────────────────────────── */
+    --textarea-color-background:   var(--form-color-background);
+    --textarea-color-border:       var(--form-color-border);
+    --textarea-color-border-hover: var(--textarea-color-border);
+    --textarea-color-placeholder:  var(--color-text-muted);
+    --textarea-color-text:         var(--form-color-text);
+    --textarea-border-radius:      var(--form-border-radius);
+    --textarea-border-width:       var(--form-border-width);
+
+    /* ── Select ────────────────────────────────────────────────────────── */
+    --select-color-background:   var(--form-color-background);
+    --select-color-border:       var(--form-color-border);
+    --select-color-border-hover: var(--select-color-border);
+    --select-color-optgroup:     var(--color-text-muted);
+    --select-color-text:         var(--form-color-text);
+    --select-border-radius:      var(--form-border-radius);
+    --select-border-width:       var(--form-border-width);
+
+    /* ── Label ─────────────────────────────────────────────────────────── */
+    --label-color-text:     var(--form-color-text);
+    --label-font-size:      var(--font-size-xs);
+    --label-font-weight:    var(--font-weight-medium);
+    --label-padding:        var(--spacing-2xs) 0;
+    --label-text-transform: uppercase;
+
+    /* ── Help text ─────────────────────────────────────────────────────── */
+    --help-color-text:  var(--color-text-muted);
+    --help-font-size:   var(--font-size-xs);
+    --help-font-weight: var(--font-weight-normal);
+    --help-margin:      0;
+
+    /* ── Checkables (checkbox + radio shared) ──────────────────────────── */
+    --checkable-color-border:         var(--form-color-border);
+    --checkable-color-border-checked: transparent;
+
+    /* ── Checkbox ──────────────────────────────────────────────────────── */
+    --checkbox-color-background:         var(--form-color-background);
+    --checkbox-color-background-checked: transparent;
+    --checkbox-color-border:             var(--checkable-color-border);
+    --checkbox-color-border-hover:       var(--checkbox-color-border);
+    --checkbox-color-checked:            var(--form-color-accent);
+    --checkbox-border-radius:            0;
+    --checkbox-border-width:             var(--form-border-width);
+
+    /* ── Radio ─────────────────────────────────────────────────────────── */
+    --radio-color-background:    var(--form-color-background);
+    --radio-color-border:        var(--checkable-color-border);
+    --radio-color-border-checked: var(--checkable-color-border-checked);
+    --radio-color-border-hover:  var(--radio-color-border);
+    --radio-color-checked:       var(--form-color-accent);
+    --radio-border-radius:       var(--radius-pill);
+    --radio-border-width:        var(--form-border-width);
+
+    /* ── Switch ────────────────────────────────────────────────────────── */
+    --switch-color-border:         var(--checkable-color-border);
+    --switch-color-thumb:          var(--color-white);
+    --switch-color-track:          var(--form-color-background);
+    --switch-color-track-checked:  var(--form-color-accent);
+    --switch-border-radius:        var(--radius-pill);
+    --switch-border-width:         var(--border-width-normal);
+    --switch-height:               var(--size-24);
+    --switch-width:                var(--size-40);
+
+    /* ── Range ─────────────────────────────────────────────────────────── */
+    --range-color-accent:       var(--form-color-accent);
+    --range-color-track:        var(--form-color-border);
+    --range-thumb-color-border: var(--color-white);
+    --range-thumb-border-width: var(--size-4);
+    --range-thumb-size:         var(--size-24);
+    --range-track-height:       calc(var(--border-width-normal) + 2px);
+  }
+}

package/tokens/semantic/grid.css

@@ -0,0 +1,53 @@
+/* semantic/grid.css */
+@layer config {
+  :root {
+    /* ── Grid base ──────────────────────────────────────────────────────── */
+    --columns: 12;
+    --gap:     var(--spacing-md);
+
+    /* ── Flex fractions ─────────────────────────────────────────────────── */
+    --flex-full:            100%;
+    --flex-eleven-twelfths: 91.6666666667%;
+    --flex-five-sixths:     83.3333333333%;
+    --flex-four-fifths:     80%;
+    --flex-three-quarters:  75%;
+    --flex-two-thirds:      66.6666666667%;
+    --flex-half:            50%;
+    --flex-third:           33.3333333333%;
+    --flex-quarter:         25%;
+    --flex-fifth:           20%;
+    --flex-sixth:           16.6666666667%;
+    --flex-twelfth:         8.3333333333%;
+
+    /* ── Grid column spans ──────────────────────────────────────────────── */
+    /* Integer spans — grid-agnostic. Comments show col-12 / col-24 fractions. */
+    --span-full: span var(--columns);
+    --span-half: span calc(var(--columns) / 2);
+    --span-quarter: span calc(var(--columns) / 4);
+    --span-third: span calc(var(--columns) / 3);
+    --span-24:   span 24;
+    --span-23:   span 23;
+    --span-22:   span 22;
+    --span-21:   span 21;
+    --span-20:   span 20;
+    --span-19:   span 19;
+    --span-18:   span 18;
+    --span-17:   span 17;
+    --span-16:   span 16;
+    --span-15:   span 15;
+    --span-14:   span 14;
+    --span-13:   span 13;
+    --span-12:   span 12;
+    --span-11:   span 11;
+    --span-10:   span 10;
+    --span-9:    span 9; 
+    --span-8:    span 8; 
+    --span-7:    span 7;
+    --span-6:    span 6; 
+    --span-5:    span 5;
+    --span-4:    span 4; 
+    --span-3:    span 3; 
+    --span-2:    span 2; 
+    --span-1:    span 1; 
+  }
+}

package/tokens/semantic/motion.css

@@ -0,0 +1,43 @@
+/* semantic/motion.css */
+@layer config {
+  :root {
+    /* ── Duration ───────────────────────────────────────────────────────── */
+    --duration-fast:   150ms;
+    --duration-normal: 300ms;
+    --duration-slow:   600ms;
+
+    /* ── Easing — standard ──────────────────────────────────────────────── */
+    --easing-linear:  linear;
+    --easing-default: ease-in-out;
+    --easing-in:      ease-in;
+    --easing-out:     ease-out;
+
+    /* ── Easing — expressive ─────────────────────────────────────────────── */
+    /* Fast deceleration, natural feel — good for elements entering the screen */
+    --easing-out-circ: cubic-bezier(0, 0.55, 0.45, 1);
+    /* Dramatic deceleration — good for modals, drawers */
+    --easing-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+    /* Slight overshoot then settle — good for confirmations, badges */
+    --easing-out-back: cubic-bezier(0.34, 1.56, 0.64, 1);
+    /* Bounce — ease-out-quart curve */
+    --easing-bounce:   cubic-bezier(0.165, 0.84, 0.44, 1);
+
+    /* ── Easing — physics (requires modern browser linear() support) ─────── */
+    /* Spring — overshoots slightly, settles naturally */
+    --easing-spring: linear(
+      0, 0.006, 0.025 2.8%, 0.101, 0.197, 0.325, 0.474, 0.638, 0.806,
+      0.962, 1.065, 1.12, 1.14, 1.12 30.9%, 1.034, 0.997, 0.986, 0.998, 1
+    );
+
+    /* ── Transition shorthands ──────────────────────────────────────────── */
+    --transition-fast:   all var(--duration-fast)   var(--easing-default);
+    --transition-normal: all var(--duration-normal) var(--easing-default);
+    --transition-slow:   all var(--duration-slow)   var(--easing-default);
+    /* Targeted transitions — prefer over `all` for performance */
+    --transition-opacity:   opacity   var(--duration-normal) var(--easing-default);
+    --transition-transform: transform var(--duration-normal) var(--easing-default);
+    /* Targeted color transitions */
+    --transition-property-color: color, background-color, border-color, outline-color, fill, stroke;
+    --transition-color: var(--transition-property-color) var(--duration-normal) var(--easing-default);
+  }
+}

package/tokens/semantic/opacity.css

@@ -0,0 +1,8 @@
+/* semantic/opacity.css */
+@layer config {
+  :root {
+    --opacity-disabled: var(--opacity-25);
+    --opacity-overlay:  var(--opacity-75);
+    --opacity-subtle:   var(--opacity-10);
+  }
+}

package/tokens/semantic/radius.css

@@ -0,0 +1,19 @@
+/* semantic/radius.css */
+@layer config {
+  :root {
+    /* ── T-shirt scale ──────────────────────────────────────────────────── */
+    --radius-2xs: var(--size-2);
+    --radius-xs:  var(--size-4);
+    --radius-sm:  var(--size-8);
+    --radius-md:  var(--size-12);
+    --radius-lg:  var(--size-16);
+    --radius-xl:  var(--size-24);
+    --radius-2xl: var(--size-32);
+
+    /* ── Purposeful aliases ─────────────────────────────────────────────── */
+    --radius-none:    0;                  /* no rounding — sharp edges */
+    --radius-control: var(--radius-sm);   /* button, input, select */
+    --radius-surface: var(--radius-md);   /* card, modal, panel */
+    --radius-pill:    9999px;             /* badge, tag, avatar */
+  }
+}

package/tokens/semantic/ratio.css

@@ -0,0 +1,13 @@
+/* semantic/ratio.css */
+@layer config {
+  :root {
+    --ratio-1-1:   1 / 1;
+    --ratio-2-3:   2 / 3;
+    --ratio-3-2:   3 / 2;
+    --ratio-3-4:   3 / 4;
+    --ratio-4-3:   4 / 3;
+    --ratio-9-16:  9 / 16;
+    --ratio-16-9:  16 / 9;
+    --ratio-21-9:  21 / 9;
+  }
+}

package/tokens/semantic/size.css

@@ -0,0 +1,19 @@
+/* semantic/size.css */
+@layer config {
+  :root {
+    /* ── Breakpoints ────────────────────────────────────────────────────── */
+    --size-tablet:      var(--size-768);   /* 48rem  — 768px  */
+    --size-tablet-wide: var(--size-1024);  /* 64rem  — 1024px */
+    --size-laptop:      var(--size-1440);  /* 90rem  — 1440px */
+    --size-desktop:     var(--size-1920);  /* 120rem — 1920px */
+
+    /* ── T-shirt scale ──────────────────────────────────────────────────── */
+    --size-2xs: var(--size-5);
+    --size-xs:  var(--size-10);
+    --size-sm:  var(--size-20);
+    --size-md:  var(--size-40);
+    --size-lg:  var(--size-60);
+    --size-xl:  var(--size-80);
+    --size-2xl: var(--size-100);
+  }
+}

package/tokens/semantic/spacing.css

@@ -0,0 +1,21 @@
+/* semantic/spacing.css */
+@layer config {
+  :root {
+    /* ── T-shirt scale ──────────────────────────────────────────────────── */
+    --spacing-2xs: var(--size-5);
+    --spacing-xs:  var(--size-10);
+    --spacing-sm:  var(--size-20);
+    --spacing-md:  var(--size-30);
+    --spacing-lg:  var(--size-40);
+    --spacing-xl:  var(--size-60);
+    --spacing-2xl: var(--size-100);
+    --spacing-3xl: var(--size-150);
+
+    /* ── Purposeful aliases ─────────────────────────────────────────────── */
+    --spacing-control:    var(--spacing-xs);   /* padding inside interactive controls */
+    --spacing-heading:    var(--spacing-sm);   /* gap below headings */
+    --spacing-section:    var(--spacing-2xl);  /* vertical rhythm between sections */
+    --spacing-surface:    var(--spacing-sm);   /* padding inside surfaces (card, panel) */
+    --spacing-typography: var(--spacing-xs);   /* gap between typographic elements */
+  }
+}

package/tokens/semantic/typography.css

@@ -0,0 +1,66 @@
+/* semantic/typography.css */
+@layer config {
+  :root {
+    /* ── Font families ──────────────────────────────────────────────────── */
+    --font-family-code:    var(--font-family-mono);
+    --font-family-heading: var(--font-family-sans);
+    --font-family-text:    var(--font-family-sans);
+
+    /* ── Font weights ───────────────────────────────────────────────────── */
+    --font-weight-control: var(--font-weight-medium);
+    --font-weight-heading: var(--font-weight-bold);
+    --font-weight-text:    var(--font-weight-normal);
+
+    /* ── Letter spacing ─────────────────────────────────────────────────── */
+    --letter-spacing-normal: 0;
+    --letter-spacing-medium: 0.025em;
+    --letter-spacing-large:  0.05em;
+
+    /* ── Line heights ───────────────────────────────────────────────────── */
+    --line-height-heading: var(--line-height-tight);
+    --line-height-text:    var(--line-height-normal);
+
+    /* ── Font size scale (T-shirt) ──────────────────────────────────────── */
+    --font-size-2xs:     var(--size-12);
+    --font-size-xs:      var(--size-14);
+    --font-size-sm:      var(--size-16);
+    --font-size-md:      var(--size-18);
+    --font-size-lg:      var(--size-24);
+    --font-size-xl:      var(--size-40);
+    --font-size-2xl:     var(--size-64);
+    --font-size-display: var(--size-96);  /* hero / marketing */
+
+    /* ── Body ───────────────────────────────────────────────────────────── */
+    --font-size-text: var(--font-size-sm);
+
+    /* ── Headings ───────────────────────────────────────────────────────── */
+    --font-size-heading-01: var(--font-size-xl);
+    --font-size-heading-02: var(--font-size-lg);
+    --font-size-heading-03: var(--font-size-md);
+    --font-size-heading-04: var(--font-size-sm);
+    --font-size-heading-05: var(--font-size-sm);
+    --font-size-heading-06: var(--font-size-sm);
+
+    /* ── Fluid font sizes ───────────────────────────────────────────────── */
+    /*
+     * clamp(min, preferred, max) — scales between ~320px and ~1440px viewport.
+     * Use these instead of fixed sizes for responsive typography without breakpoints.
+     * $type: dimension
+     */
+    --font-size-fluid-xs:      clamp(0.875rem, 1.5vw, 1rem);    /* 14 → 16px */
+    --font-size-fluid-sm:      clamp(1rem,     2vw,   1.125rem); /* 16 → 18px */
+    --font-size-fluid-md:      clamp(1.125rem, 2.5vw, 1.5rem);  /* 18 → 24px */
+    --font-size-fluid-lg:      clamp(1.5rem,   4vw,   2.5rem);  /* 24 → 40px */
+    --font-size-fluid-xl:      clamp(2.5rem,   6vw,   4rem);    /* 40 → 64px */
+    --font-size-fluid-display: clamp(4rem,     8vw,   6rem);    /* 64 → 96px */
+
+    /* ── Readability ────────────────────────────────────────────────────── */
+    /*
+     * Max line length in ch units (width of "0" character).
+     * Prevents overly long lines causing reading fatigue (WCAG 1.4.8).
+     * Headings use a shorter value: larger font = physically wider chars.
+     */
+    --max-width-heading:   40ch;
+    --max-width-paragraph: 70ch;
+  }
+}

package/tokens/semantic/z-index.css

@@ -0,0 +1,14 @@
+/* semantic/z-index.css */
+@layer config {
+  :root {
+    --z-index-below:     -1;   /* background decorative elements */
+    --z-index-base:       0;
+    --z-index-raised:    10;   /* cards, sticky elements within flow */
+    --z-index-dropdown:  100;  /* dropdowns, popovers */
+    --z-index-sticky:    200;  /* sticky header/sidebar */
+    --z-index-offcanvas: 300;  /* drawer, side panel */
+    --z-index-modal:     400;  /* modal dialogs */
+    --z-index-toast:     500;  /* notifications, toasts */
+    --z-index-tooltip:   600;  /* tooltips (always on top) */
+  }
+}

package/tokens/semantic.css

@@ -0,0 +1,17 @@
+/* @uncinq/design-tokens — semantic.css */
+@layer config;
+
+@import 'semantic/border.css';
+@import 'semantic/color.css';
+@import 'semantic/fluid.css';
+@import 'semantic/focus.css';
+@import 'semantic/form.css';
+@import 'semantic/grid.css';
+@import 'semantic/motion.css';
+@import 'semantic/opacity.css';
+@import 'semantic/radius.css';
+@import 'semantic/ratio.css';
+@import 'semantic/size.css';
+@import 'semantic/spacing.css';
+@import 'semantic/typography.css';
+@import 'semantic/z-index.css';