# Socle

The CSS foundation behind Un Cinq projects. Socle is French for foundation.

> Generated from https://socle.uncinq.dev/ on 2026-09-23.
> Each section below is maintained in its own package repository, under docs/,
> and mounted here from node_modules. Nothing is transcribed.



================================================================================
GETTING STARTED
================================================================================

Installing the four packages, declaring the cascade layer order, and wiring them into Hugo, Shopify or Symfony.


## Install

```bash
npm install @uncinq/design-tokens @uncinq/component-tokens @uncinq/css-base @uncinq/css-components
```

All four are plain CSS. There is no runtime, no JavaScript and no framework dependency.

## The entry stylesheet

This is the whole integration, and the order is not arbitrary.

```css
/* main.css */
@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;

@import '@uncinq/design-tokens';    /* @layer tokens */
@import '@uncinq/css-base';         /* @layer reset, base, layouts */
@import '@uncinq/component-tokens'; /* @layer tokens */
@import '@uncinq/css-components';   /* @layer components, utilities */
```

### Why the layer line comes first

CSS fixes a layer's position **the first time its name is seen**, and later re-declarations do not reorder it. If that line came after an import, the imported package would already have fixed the order and your project could never change it.

None of the four packages declares the order. Each one declares only the layers it writes to. Deciding the full order, including the `libs`, `vendors` and `pages` layers that belong to your project and not to any package, is your call to make, once, at the top of the entry file.

Read [cascade layers in css-base](../css-base/cascade-layers/) for the detail, including why `libs` and `vendors` are a pair and why an undeclared layer name is dangerous.

### Why tokens come before the CSS that uses them

Custom properties are resolved by the browser at use time, not at import time, so a missing token import does not raise an error. It silently yields invalid values and unstyled components, which is a harder failure to diagnose than a missing file. Import the tokens first.

## The build requirement

`@uncinq/css-base` ships `@custom-media` rules for its breakpoints, which no browser implements natively. Your build must run [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media).

```bash
npm install --save-dev postcss postcss-custom-media
```

```js
// postcss.config.js
module.exports = {
  plugins: [require('postcss-custom-media')],
};
```

Skipping it fails quietly: every `@media (--sm)` block is dropped, no error is raised, and the page renders at its mobile values on every screen size. If your layouts never respond to width, check this first.

## Hugo

Mount the packages into `assets/`, then build the entry stylesheet through PostCSS.

```yaml
# config/_default/module.yaml
mounts:
  - source: assets
    target: assets
  - source: node_modules/@uncinq/design-tokens/dist/css
    target: assets/css/design-tokens
  - source: node_modules/@uncinq/component-tokens/dist/css
    target: assets/css/component-tokens
  - source: node_modules/@uncinq/css-base/css
    target: assets/css/css-base
  - source: node_modules/@uncinq/css-components/css
    target: assets/css/css-components
```

Remember that declaring a mount into `assets` removes Hugo's default `assets` mount, which is why the first entry restores it.

## Shopify and Symfony

Both consume the packages as ordinary npm dependencies: point your bundler at the entry stylesheet above and ship the result.

The same four packages, the same entry file, the same layer order. That is the reason the packages emit CSS custom properties and nothing else: a JS or SCSS output would have to be regenerated per platform, whereas custom properties are understood everywhere without translation.

If a project needs the token values inside JavaScript, generate that from the same JSON sources rather than hand-maintaining a second list. See [customizing design-tokens](../design-tokens/customizing/#2-json-plus-build).

## Verifying the setup

Four checks, in the order things usually break:

1. **Tokens resolve.** In devtools, inspect `<html>` and confirm `--color-brand` has a computed value. If it is empty, the token import is missing or came too late.
2. **Layers are ordered.** In the devtools style pane, the layer order should match your `@layer` line. If a layer you never declared appears at the end, something was imported without a `layer()` and is outranking your CSS.
3. **Breakpoints work.** Resize past 768px and confirm a `.row` switches to horizontal. If it never does, postcss-custom-media is not running.
4. **Components are styled.** Drop a `<button class="btn">` on a page. Unstyled means `@uncinq/component-tokens` is missing, since the component CSS is there but has no values to read.

## What to read next

| If you want to | Go to |
| --- | --- |
| Change the brand color | [design-tokens, customizing](../design-tokens/customizing/) |
| Know what a token is worth | [design-tokens, reference](../design-tokens/reference/) |
| Style a form | [css-base, base](../css-base/base/#forms) and [css-components, forms](../css-components/forms/) |
| Build a modal or a drawer | [css-components, overlays](../css-components/overlays/) |
| Understand the layer order in depth | [css-base, cascade layers](../css-base/cascade-layers/) |



================================================================================
DESIGN-TOKENS
================================================================================

Framework-agnostic primitive and semantic design tokens, authored in DTCG JSON and shipped as CSS custom properties.


Design tokens are the atomic decisions of a design system: colors, spacing, typography, motion. Instead of hardcoding `#ae003f` or `1rem` throughout a codebase, you name the decision, `--color-brand` or `--spacing-md`, and reference that name everywhere.

`@uncinq/design-tokens` holds the primitive and semantic layers of that vocabulary. It is authored in [DTCG JSON](dtcg/) and compiled to CSS custom properties by [Style Dictionary](style-dictionary/). It works anywhere CSS does: Hugo, Symfony, Shopify, or a plain HTML page.

## Token architecture

The package follows the DTCG three-layer model.

```
primitive   →   semantic   →   component
(raw values)    (purpose)      (component-scoped, not in this package)
```

### Layer 1, primitive

Raw, context-free values. No opinion about where they are used.

```css
--color-indigo-600: oklch(0.511 0.262 276.966);
--size-16: 1rem;
--font-weight-bold: 700;
```

A primitive token answers **"what is the value?"**.

### Layer 2, semantic

Named by purpose rather than by appearance. References a primitive through `var()`.

```css
--color-brand: var(--color-sienna-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. Every project consuming this package shares the same semantic API, so when the brand color changes you update one primitive and every semantic token referencing it follows.

### Layer 3, component

Scoped to a single component. The generic ones live in [@uncinq/component-tokens](https://github.com/uncinq/component-tokens); project-specific ones belong in each project's own design system.

```css
--alert-border-radius: var(--radius-none);
--btn-padding-inline: var(--spacing-control);
```

## Installation

```bash
npm install @uncinq/design-tokens
```

```css
/* everything */
@import '@uncinq/design-tokens';

/* or by layer */
@import '@uncinq/design-tokens/css/primitive.css';
@import '@uncinq/design-tokens/css/semantic.css';

/* or file by file */
@import '@uncinq/design-tokens/css/semantic/color.css';
```

Without a build step, over a CDN:

```html
<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
```

Every generated file declares `@layer tokens` itself, so the package never fixes the layer order. Declaring that order is the consuming project's job, and it has to happen before any import. See [cascade layers in css-base](../css-base/cascade-layers/).

## Where to go next

| Page | Covers |
| --- | --- |
| [Naming](naming/) | The naming grammar, the rules, the scales, the full category list |
| [Colors](colors/) | OKLCH, the primitive palette, semantic color roles, WCAG guidance |
| [Dark mode](dark-mode/) | How the dark theme overlay works and how to opt out |
| [Customizing](customizing/) | The two override strategies and when each applies |
| [Reference](reference/) | Every token, generated from the JSON sources |
| [DTCG format](dtcg/) | The authoring format |
| [Style Dictionary](style-dictionary/) | The build pipeline |
| [Fluid scales](utopia/) | The Utopia method behind the fluid tokens |

## File structure

The JSON sources under `tokens/` are the only files to edit. Everything under `dist/` is generated by `npm run build`.

```
tokens/
  primitive/   blur, color, font, shadow, size
  semantic/    blur, border, color, focus, form, gradient, grid, icon,
               motion, opacity, radius, ratio, shadow, size, spacing,
               typography, z-index
  themes/      dark

dist/css/
  index.css      imports primitive, semantic, themes/dark
  primitive.css  barrel
  semantic.css   barrel
  primitive/  semantic/  themes/   one CSS file per JSON source
```

## References

- [DTCG specification](https://tr.designtokens.org/format/), W3C Community Group draft
- [Style Dictionary v5](https://styledictionary.com/)
- [Utopia](https://utopia.fyi), the fluid scale method



--------------------------------------------------------------------------------
design-tokens / Naming
https://socle.uncinq.dev/docs/design-tokens/naming/
--------------------------------------------------------------------------------

The naming grammar for semantic and component tokens, the rules that keep it consistent, and the scales in use.


A token name is an API. Once a project references `--color-text-muted`, renaming it is a breaking change, so the grammar below is worth following closely.

## Semantic tokens

```
--{category}-{subcategory?}-{variant?}-{state?}
```

| Pattern | Example |
| --- | --- |
| `--{category}` | `--color` |
| `--{category}-{subcategory}` | `--color-text` |
| `--{category}-{subcategory}-{variant}` | `--color-text-muted` |
| `--{category}-{subcategory}-{state}` | `--color-text-disabled` |

## Component tokens

```
--{component}-{property}-{sub-property?}-{state?}
```

The property mirrors the CSS property name, so the token reads the same way as the declaration it controls. Colors are the exception: `color` leads and the role follows, for the reason given in the rules below.

| Pattern | Example |
| --- | --- |
| `--{component}` | `--btn` |
| `--{component}-{property}` | `--btn-padding-inline` |
| `--{component}-{property}-{sub-property}` | `--btn-color-text-decoration` |
| `--{component}-{property}-{state}` | `--btn-color-background-hover` |

## Rules

**Lowercase kebab-case**, always.

**No component names in primitive or semantic tokens.** `--button-*` belongs in [@uncinq/component-tokens](https://github.com/uncinq/component-tokens), not here. A semantic token that names a component has stopped being semantic.

**Semantic tokens are named by intent.** They usually reference a primitive through `var()`, but they may carry a raw value when the value itself is the design decision, such as `--z-index-modal: 400` or `--radius-pill: 9999px`.

**`color-[role]` for every color token.** `color` is the category prefix and the UI role follows: `color-background`, `color-border`, `color-text`, `color-accent`, `color-placeholder`. This groups all color tokens alphabetically under `color-*`, and it makes the component token mirror the global one, `--color-background` becoming `--btn-color-background`. `background` is never abbreviated, so `color-background` and never `color-bg`.

| 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` |

**States go last**: `-hover`, `-focus`, `-active`, `-disabled`, `-checked`.

**Alphabetical order within a file**, grouped with a comment once a file has many entries.

```css
/* Brand */
--color-brand:       var(--color-sienna-600);
--color-brand-hover: var(--color-sienna-700);

/* Text */
--color-text:        var(--color-gray-900);
--color-text-muted:  var(--color-gray-500);
```

## 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, so `color.brand.default` becomes `--color-brand` while `color.brand.hover` becomes `--color-brand-hover`.

```json
"brand": {
  "default": { "$value": "{color.sienna.600}", "$type": "color" },
  "hover":   { "$value": "{color.sienna.700}", "$type": "color" }
}
```

This is what lets `--color-brand` and `--color-brand-hover` sit in the same group without one of them being named `--color-brand-default`. See [DTCG format](../dtcg/) for the full set of authoring conventions.

## Scales

| Use case | Scale | Example |
| --- | --- | --- |
| Color palettes | Numeric, 50 to 950 | `--color-gray-500` |
| Heading levels | Zero-padded, 01 to 06 | `--font-size-heading-01` |
| Layout and spacing | T-shirt, `2xs xs sm md lg xl 2xl` | `--spacing-md` |
| Radius, shadow, size | T-shirt | `--radius-sm` |
| Purposeful aliases | Named | `--radius-control`, `--radius-pill` |

The zero-padding on heading levels is there so that `01` through `06` sort correctly as text, which matters because the generated CSS is ordered alphabetically.

## Category reference

| Category | Covers | Example |
| --- | --- | --- |
| `color` | All color values | `--color-brand`, `--color-text-on-dark` |
| `font-family` | Typefaces | `--font-family-heading` |
| `font-size` | Text sizes | `--font-size-sm`, `--font-size-heading-01` |
| `font-size-fluid` | Responsive fluid type scale | `--font-size-fluid-xl` |
| `font-weight` | Weight values | `--font-weight-bold` |
| `line-height` | Line heights | `--line-height-heading` |
| `letter-spacing` | Tracking | `--letter-spacing-md` |
| `text-decoration` | Decoration properties | `--text-decoration-offset` |
| `spacing` | Margin and padding | `--spacing-md`, `--spacing-section` |
| `spacing-fluid` | Responsive fluid spacing scale | `--spacing-fluid-lg` |
| `size` | Width and height | `--size-16`, `--size-tablet` |
| `max-width` | Readability caps | `--max-width-paragraph` |
| `radius` | Border radius | `--radius-md`, `--radius-pill` |
| `border` | Border style and width | `--border-width-sm` |
| `shadow` | Box shadows | `--shadow-md` |
| `blur` | Blur values | `--blur-md` |
| `gradient` | Overlay gradients | `--gradient-darken-color-from` |
| `opacity` | Opacity values | `--opacity-disabled` |
| `duration` | Animation timing | `--duration-fast` |
| `easing` | Timing functions | `--easing-out-expo` |
| `transition` | Shorthand transitions | `--transition-normal` |
| `ratio` | Aspect ratios | `--ratio-video` |
| `focus` | Focus ring tokens | `--focus-outline-width` |
| `grid` | Column counts, gaps, fractions | `--columns-tablet`, `--gap` |
| `icon` | SVG icons as data URIs | `--icon-arrow` |
| `z-index` | Stacking order | `--z-index-modal` |

For the actual values behind each of these, see the [Reference](../reference/), which is generated from the JSON sources and cannot drift.


--------------------------------------------------------------------------------
design-tokens / Colors
https://socle.uncinq.dev/docs/design-tokens/colors/
--------------------------------------------------------------------------------

The OKLCH color space, the 19-hue primitive palette, the semantic color roles, and WCAG guidance for using them.


## Color space, OKLCH

Every primitive color is defined in OKLCH.

| Channel | Range | Meaning |
| --- | --- | --- |
| `L` | 0 to 1 | Perceptual lightness, 0 is black and 1 is white |
| `C` | 0 to about 0.4 | Chroma, or colorfulness, where 0 is gray |
| `H` | 0 to 360 degrees | Hue angle |

Why OKLCH rather than hex or HSL:

- **Perceptually uniform.** Equal steps in `L` produce equal perceived brightness differences, whatever the hue. HSL does not guarantee this: `hsl(60, 100%, 50%)` yellow looks far brighter than `hsl(240, 100%, 50%)` blue at the same stated lightness.
- **Predictable contrast.** You can reason about WCAG contrast by comparing `L` values, without converting to relative luminance first.
- **Better interpolation.** Gradients and animations between two OKLCH colors do not pass through muddy grays.
- **Composable.** The relative color syntax, `oklch(from var(--color-text) l c h / 0.6)`, lets a token derive from another without duplicating its value. Several semantic tokens in this package rely on it.

Browser support is Chrome 111, Firefox 113 and Safari 15.4 and above. No sRGB fallback is generated, so every value ships as `oklch()` and anything older needs a fallback of its own.

## Primitive palette

19 hues, 11 steps each (50 to 950), plus flat `--color-black` and `--color-white`. These are raw values with no opinion about usage.

| Hue | H angle | Character |
| --- | --- | --- |
| `amber` | 70 | Golden yellow-orange |
| `blue` | 260 | Classic blue |
| `cyan` | 215 | Bright cyan |
| `emerald` | 162 | Deep blue-green |
| `fuchsia` | 322 | Vivid magenta |
| `gray` | 264 | Cool neutral, chroma about 0.02 |
| `green` | 150 | Lush green |
| `indigo` | 277 | Blue-violet |
| `lime` | 131 | Electric yellow-green |
| `orange` | 48 | Vivid orange |
| `pink` | 354 | Bright pink |
| `purple` | 304 | Rich purple |
| `red` | 25 | Classic red |
| `rose` | 16 | Pink-red |
| `sienna` | 24 | Brick-red, the default brand |
| `sky` | 237 | Soft sky blue |
| `teal` | 183 | Blue-green |
| `violet` | 293 | Modern violet |
| `yellow` | 86 | Pure yellow |

### Step guide

`L` values below are measured from the actual palette, not estimated.

| Step | L, cool hues | L, amber / yellow / lime | L, gray | Typical use |
| --- | --- | --- | --- | --- |
| 50 | 0.97 | 0.99 | 0.98 | Tinted page backgrounds, hover on white |
| 100 | 0.95 | 0.97 | 0.97 | Muted backgrounds, badges, tags |
| 200 | 0.90 | 0.94 | 0.93 | Borders, dividers |
| 300 | 0.83 | 0.89 | 0.87 | Disabled elements, placeholder text |
| 400 | 0.73 | 0.84 | 0.71 | Secondary icons, decorative |
| 500 | 0.66 | 0.78 | 0.56 | Mid-tone, pair with dark text |
| 600 | 0.58 | 0.67 | 0.44 | **Default brand and status background.** White text passes WCAG AA for UI |
| 700 | 0.50 | 0.55 | 0.37 | Hover state, colored text on white |
| 800 | 0.44 | 0.47 | 0.28 | Deep accents, high-contrast text |
| 900 | 0.39 | 0.41 | 0.21 | Near-dark, very high contrast |
| 950 | 0.27 | 0.28 | 0.14 | Darkest tint, almost black |

Two things to read out of that table. Intrinsically bright hues (amber, yellow, lime) carry noticeably higher `L` at steps 400 to 700; that is expected behaviour of a perceptual space, not a calibration error. Gray goes the other way and runs darker than the chromatic hues from step 400 down, because it has almost no chroma to contribute to perceived brightness.

## Semantic color tokens

Semantic tokens are named by purpose and reference primitives through `var()`.

### Brand and accent

```css
--color-brand         /* primary brand color: button background, active states */
--color-brand-hover   /* hover state */
--color-brand-muted   /* tinted background for brand areas */
--color-brand-strong  /* darkest brand shade */

--color-accent        /* equals brand by default, override independently if needed */
```

The default brand is **sienna**, a warm brick-red. `--color-accent` and its variants alias brand, so overriding brand alone moves both.

```css
@layer tokens {
  :root {
    --color-brand:        var(--color-violet-600);
    --color-brand-hover:  var(--color-violet-700);
    --color-brand-muted:  var(--color-violet-100);
    --color-brand-strong: var(--color-violet-900);
  }
}
```

### Backgrounds

| Token | Default | Usage |
| --- | --- | --- |
| `--color-background` | white | Page background |
| `--color-background-surface` | equals `--color-background` | Card and panel backgrounds |
| `--color-background-muted` | gray-100 | Subtle section backgrounds |
| `--color-background-muted-hover` | gray-200 | Hover on a muted surface |
| `--color-background-media` | gray-200 | Image placeholders, skeletons |
| `--color-background-disabled` | gray-100 | Disabled controls |
| `--color-background-accent` | equals `--color-accent` | Highlighted sections |

### Text

| Token | Default | Usage |
| --- | --- | --- |
| `--color-text` | gray-900 | Body text |
| `--color-text-hover` | gray-700 | Text hover |
| `--color-text-muted` | `--color-text` at `--opacity-muted` | Secondary text, captions |
| `--color-text-disabled` | gray-300 | Disabled UI |
| `--color-heading` | black | Headings |
| `--color-link` | equals `--color-text` | Default link color |
| `--color-link-hover` | equals `--color-accent` | Link hover |
| `--color-link-active` | equals `--color-active` | Current link |
| `--color-credit` | equals `--color-text-muted` | Bylines, captions |

`--color-text-muted` is derived rather than aliased: `oklch(from var(--color-text) l c h / var(--opacity-muted))`. It therefore follows any override of `--color-text` automatically, which is why it is not simply an alias of gray-500. The dark theme is the one place that overrides it outright, to gray-400, because a transparent text color over a dark background does not mute the same way it does over a light one.

### Text on colored backgrounds

These exist so that contrast holds when a color becomes the background.

```css
--color-text-on-brand      /* white */
--color-text-on-accent     /* white */
--color-text-on-dark       /* white */
--color-text-on-black      /* white */
--color-text-on-light      /* gray-900 */
--color-text-on-white      /* black */
--color-text-on-surface    /* equals --color-text */
--color-text-on-muted      /* gray-900 */
--color-text-on-neutral    /* white */
--color-text-on-danger     /* white */
--color-text-on-info       /* white */
--color-text-on-success    /* white */
--color-text-on-highlight  /* gray-900 */
--color-text-on-warning    /* gray-900, amber is bright so dark text is required */
```

### Status and surface variants

| Token | Primitive | Notes |
| --- | --- | --- |
| `--color-danger` | red-600 | Errors, destructive actions |
| `--color-success` | green-600 | Confirmations |
| `--color-warning` | amber-500 | Warnings, pair with `--color-text-on-warning` |
| `--color-info` | blue-600 | Informational |
| `--color-highlight` | yellow-100 | Marked or highlighted text |
| `--color-neutral` | gray-500 | Neutral emphasis |
| `--color-dark` | gray-900 | Dark surfaces |
| `--color-light` | gray-200 | Light surfaces |

Each of these carries a `-hover`, `-muted` and `-strong` companion:

```css
--color-danger:        var(--color-red-600);
--color-danger-hover:  var(--color-red-700);
--color-danger-muted:  var(--color-red-100);
--color-danger-strong: var(--color-red-800);
```

### Derived utility colors

Four tokens use relative color syntax rather than an alias, so they track their base automatically:

| Token | Derived from |
| --- | --- |
| `--color-backdrop` | `--color-black` at `--opacity-backdrop` |
| `--color-shadow-light` | `--color-shadow` at `--opacity-shadow` |
| `--color-shadow-medium` | `--color-shadow` at `--opacity-backdrop` |
| `--color-shadow-strong` | `--color-shadow` at `--opacity-overlay` |

`--color-shadow` is one of the tokens the dark theme flips, from black to white. Because the three shadow variants derive from it, the whole shadow system inverts with a single override. See [Dark mode](../dark-mode/).

## Accessibility

| Ratio | Requirement |
| --- | --- |
| 4.5 : 1 | Normal text, under 18px, or non-bold under 14px. WCAG AA |
| 3 : 1 | Large text and UI components such as buttons, inputs, icons. WCAG AA |
| 7 : 1 | Any text. WCAG AAA |

Rules of thumb for this palette:

- **White text on a colored background** needs step **600 or darker**. Step 500 and below typically land around 3 to 3.5 : 1, which fails for normal text.
- **Colored text on white** needs step **700 or darker** for normal text.
- **Warning** is the exception that proves the rule. `--color-warning` is amber-500, whose `L` is about 0.78, so it must be paired with `--color-text-on-warning` (gray-900). Never put white text on it.
- **Decorative use** is unconstrained. Any step is fine when color carries no information, as in borders, illustrations or icons that duplicate a visible label.

These are starting points, not a substitute for measuring. Contrast depends on both colors, and an override of `--color-brand` invalidates the assumptions above.

## Adding a custom hue

Add a primitive scale in `tokens/primitive/color.json`, one DTCG color object per step:

```json
{
  "color": {
    "coral": {
      "50":  { "$value": { "colorSpace": "oklch", "components": [0.975, 0.014, 35.0] }, "$type": "color" },
      "100": { "$value": { "colorSpace": "oklch", "components": [0.948, 0.032, 35.0] }, "$type": "color" },
      "950": { "$value": { "colorSpace": "oklch", "components": [0.225, 0.078, 35.0] }, "$type": "color" }
    }
  }
}
```

Run `npm run build`, then reference the generated `--color-coral-*` from `tokens/semantic/color.json`, or from your own project's `@layer tokens` override. Keeping `H` constant across the steps and varying `L` and `C` is what makes a scale read as one hue.


--------------------------------------------------------------------------------
design-tokens / Dark mode
https://socle.uncinq.dev/docs/design-tokens/dark-mode/
--------------------------------------------------------------------------------

How the dark theme overlays 13 semantic tokens, how a page opts out, and why there is no forced-dark selector.


The dark theme is an **overlay**, not a second palette. `tokens/themes/dark.json` re-declares 13 semantic tokens and nothing else. Every other token, including the whole primitive palette, is shared.

That is the point of the semantic layer: if a component reads `--color-background` rather than `--color-white`, it needs no dark-mode branch of its own.

## What it overrides

| Token | Light | Dark |
| --- | --- | --- |
| `--color-background` | white | gray-950 |
| `--color-background-disabled` | gray-100 | gray-900 |
| `--color-background-media` | gray-200 | gray-800 |
| `--color-background-muted` | gray-100 | gray-900 |
| `--color-background-muted-hover` | gray-200 | gray-800 |
| `--color-border` | gray-200 | gray-800 |
| `--color-heading` | black | white |
| `--color-shadow` | black | white |
| `--color-text` | gray-900 | gray-200 |
| `--color-text-disabled` | gray-300 | gray-600 |
| `--color-text-hover` | gray-700 | gray-300 |
| `--color-text-muted` | derived from `--color-text` | gray-400 |
| `--form-color-background` | white | gray-900 |

Two of these do more work than they look. `--color-shadow` flipping to white inverts the entire shadow system in one line, because `--color-shadow-light`, `-medium` and `-strong` all derive from it with relative color syntax. And `--color-background-surface` is not in the list at all, because it aliases `--color-background` and follows for free.

## The generated selector

```css
@layer tokens {
  @media (prefers-color-scheme: dark) {
    :root:not([data-color-scheme="light"]) {
      --color-background: var(--color-gray-950);
      /* ... */
    }
  }
}
```

Read that selector carefully, because it encodes two deliberate decisions.

**The dark scheme follows the operating system.** It activates under `prefers-color-scheme: dark` and nowhere else.

**There is no forced-dark selector.** No `[data-color-scheme="dark"]` exists, so the package will never turn a page dark on a light OS. Only the opposite is offered: `data-color-scheme="light"` on `<html>` opts a page out of dark mode even when the OS asks for it.

```html
<html data-color-scheme="light">
```

If your project needs a three-way toggle with a forced-dark option, add the missing selector in your own `@layer tokens` block after the import. The package deliberately stops short of that, because a forced-dark selector has to be paired with UI and persistence that belong to the project, not to a token package.

## Importing it

The theme ships with the full bundle:

```css
@import '@uncinq/design-tokens';       /* primitive + semantic + dark */
```

Importing a group on its own leaves it out:

```css
@import '@uncinq/design-tokens/css/primitive.css';
@import '@uncinq/design-tokens/css/semantic.css';
/* no dark theme here */
```

Add it back explicitly when you need it:

```css
@import '@uncinq/design-tokens/css/themes/dark.css';
```

## How the build resolves it

The dark pass is a second Style Dictionary build, not a post-processing step. It sources the base tokens **and** `themes/dark.json` together, so references such as `{color.gray.950}` resolve normally, then filters the output down to the dark file alone.

Without that, a dark token referencing a primitive would emit a broken reference. See [Style Dictionary](../style-dictionary/) for the config.

## Adding another theme

Drop a JSON file in `tokens/themes/`, overriding only the tokens that change, then register its selector in `style-dictionary.config.js`:

```js
'themes/dark': [{
  selector: ':root:not([data-color-scheme="light"])',
  media: '(prefers-color-scheme: dark)',
}]
```

A theme with no `media` entry generates a plain selector, which is what a forced, user-chosen theme needs. Keep the overlay small: a theme that re-declares more than a couple of dozen tokens is usually a sign that a component is reading primitives directly instead of semantic tokens.


--------------------------------------------------------------------------------
design-tokens / Customizing
https://socle.uncinq.dev/docs/design-tokens/customizing/
--------------------------------------------------------------------------------

The two override strategies, CSS layer override and JSON plus build, and when each one is the right tool.


There are two ways to change what this package produces. Pick by how deep the change goes, not by preference.

| Need | Approach |
| --- | --- |
| Change the brand, the typography, a handful of tokens | CSS `@layer tokens` |
| Add a few project-specific tokens | CSS `@layer tokens` |
| Redefine the primitive palette entirely | JSON plus build |
| Add many project tokens, or generate other formats | JSON plus build |

## 1. CSS override

Every token lives in `@layer tokens`, the lowest-priority layer in the recommended order. Any `@layer tokens` block imported **after** this package wins on source order, with no specificity tricks required.

```css
@import '@uncinq/design-tokens';

@layer tokens {
  :root {
    --color-brand:        var(--color-violet-600);
    --color-brand-hover:  var(--color-violet-700);
    --color-brand-muted:  var(--color-violet-100);
    --color-brand-strong: var(--color-violet-900);
    --font-family-sans:   'Inter', system-ui, sans-serif;
  }
}
```

This covers most cases. Note that you are overriding the *semantic* layer while still referencing the *primitive* layer, which is exactly what the two-layer split is for: the palette stays intact and you only restate the intent.

Three things worth knowing:

**Override the semantic token, not the component token,** when you want the change to propagate. Setting `--color-brand` moves every component that reads it. Setting `--btn-color-background` moves only buttons.

**Derived tokens follow automatically.** `--color-accent` aliases `--color-brand`, and `--color-text-muted` derives from `--color-text`, so overriding the base moves the derivations too. Check [Colors](../colors/) before overriding a derived token by hand, because doing so breaks the link.

**The layer order must already be declared.** If `@layer tokens` has not been named before the first import, the cascade fixes its position at that first import and your override may not land where you expect. See [cascade layers](../../css-base/cascade-layers/).

## 2. JSON plus build

The package exports its raw DTCG sources under `./tokens/*`. A consuming project can feed them into its own [Style Dictionary](https://styledictionary.com/) config alongside its own token files.

```js
// style-dictionary.config.js, in the consuming project
export default {
  usesDtcg: true,
  source: [
    'node_modules/@uncinq/design-tokens/tokens/**/*.json',
    'tokens/**/*.json', // project tokens, extending or overriding the package
  ],
  // ...
};
```

A project token file that defines the same path as a package token overrides it during the build. New paths are additive.

Use this approach to:

- Redefine the primitive palette entirely, for a different brand hue or a different scale
- Add semantic tokens that do not exist in the package
- Generate output formats the package does not ship, such as JS, SCSS or JSON

That last point is the common reason to reach for it. This package emits **CSS only**, on purpose: CSS custom properties are the one format that works unchanged in Hugo, Symfony, Shopify and a plain HTML page. A project that needs the same values inside JavaScript should generate that itself from the same sources, so the two outputs cannot drift.

## What not to do

**Do not edit `dist/`.** It is generated by `npm run build` and overwritten on every build. The header of each generated file says so.

**Do not fork to change one color.** The CSS override above exists precisely so that a brand change does not require a fork. A fork inherits the maintenance of 19 hues and 660 tokens for a single line of difference.

**Do not override a primitive to change a semantic meaning.** Redefining `--color-gray-100` to make one muted background darker will move every other token referencing gray-100, most of which you have not thought about. Override the semantic token instead.


--------------------------------------------------------------------------------
design-tokens / Reference
https://socle.uncinq.dev/docs/design-tokens/reference/
--------------------------------------------------------------------------------

Every token in the package, generated from the JSON sources so it can never drift from the shipped CSS.


Every table below is generated at build time from `dist/tokens.json`, which Style Dictionary produces from the same JSON sources as the CSS. Nothing here is written by hand, so a token cannot appear in the reference without existing in the package, or change value without the page changing with it.

Values are shown as they are emitted. A semantic token that references a primitive shows `var(--the-primitive)` rather than a flattened value, because that is literally what ships, and it is what makes an override of the primitive propagate.

{{< alert-block state="info" >}}
Reading this offline, from the repository or from `node_modules`? The tables below are rendered by the documentation site. The same data, in machine-readable form, sits in `dist/tokens.json`, and the final CSS is in `dist/css/`.
{{< /alert-block >}}

## Primitive

Raw, context-free values. These answer "what is the value?" and carry no opinion about usage.

### Color palette

19 hues at 11 steps, plus black and white. See [Colors](../colors/) for the hue table and the step guide.

{{< tokens pkg="design" file="primitive/color" >}}

### Size scale

{{< tokens pkg="design" file="primitive/size" >}}

### Font primitives

{{< tokens pkg="design" file="primitive/font" >}}

### Shadow scale

{{< tokens pkg="design" file="primitive/shadow" >}}

### Blur scale

{{< tokens pkg="design" file="primitive/blur" >}}

## Semantic

Named by purpose. These answer "what is this value for?" and are the layer a project should override.

### Color roles

{{< tokens pkg="design" file="semantic/color" >}}

### Typography

Font sizes (fixed and fluid), heading sizes, line heights, letter spacing, and the `--max-width-*` readability caps, which are authored as a `maxWidth` group in this file.

{{< tokens pkg="design" file="semantic/typography" >}}

### Spacing

{{< tokens pkg="design" file="semantic/spacing" >}}

### Size aliases

{{< tokens pkg="design" file="semantic/size" >}}

### Grid

{{< tokens pkg="design" file="semantic/grid" >}}

### Radius

{{< tokens pkg="design" file="semantic/radius" >}}

### Border

{{< tokens pkg="design" file="semantic/border" >}}

### Shadow aliases

{{< tokens pkg="design" file="semantic/shadow" >}}

### Blur aliases

{{< tokens pkg="design" file="semantic/blur" >}}

### Gradient

{{< tokens pkg="design" file="semantic/gradient" >}}

### Opacity

{{< tokens pkg="design" file="semantic/opacity" >}}

### Motion

Durations, easing curves and the transition shorthands built from them.

{{< tokens pkg="design" file="semantic/motion" >}}

### Ratio

{{< tokens pkg="design" file="semantic/ratio" >}}

### Focus

{{< tokens pkg="design" file="semantic/focus" >}}

### Form

The largest semantic file. It covers inputs, labels, checkboxes, radios, switches, selects and textareas, and is what [@uncinq/css-base](../../css-base/base/) reads to style native form controls.

{{< tokens pkg="design" file="semantic/form" >}}

### Icon

SVG icons encoded as `url('data:image/svg+xml;utf8,...')`, usable as a `background-image` or a `mask-image`.

{{< tokens pkg="design" file="semantic/icon" >}}

### Z-index

{{< tokens pkg="design" file="semantic/z-index" >}}

## Themes

### Dark

The overlay applied under `prefers-color-scheme: dark`. See [Dark mode](../dark-mode/) for how the selector works and how to opt out.

{{< tokens pkg="design" file="themes/dark" >}}


--------------------------------------------------------------------------------
design-tokens / DTCG format
https://socle.uncinq.dev/docs/design-tokens/dtcg/
--------------------------------------------------------------------------------

The Design Tokens Community Group JSON format, its keys, types and naming conventions as used in this package.



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 |
| `$extensions` | optional | Vendor-specific metadata (e.g. Figma) |

---

## 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.

---

## 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` |
| `"textAlign"` | `--btn-text-align` |
| `"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)


--------------------------------------------------------------------------------
design-tokens / Style Dictionary
https://socle.uncinq.dev/docs/design-tokens/style-dictionary/
--------------------------------------------------------------------------------

How the JSON token sources are compiled into CSS custom properties, including the dark theme pass.



[Style Dictionary v5](https://styledictionary.com/) transforms the DTCG JSON token files into CSS custom properties.

## Run the build

```bash
npm run build
```

Output is written to `dist/css/`. One CSS file is generated per JSON source file, preserving the same directory structure:

```
tokens/primitive/color.json   →   dist/css/primitive/color.css
tokens/semantic/color.json    →   dist/css/semantic/color.css
```

---

## Config — `style-dictionary.config.js`

The config is a single ES module. It registers a custom name transform and a custom format, then maps every JSON file to a CSS output.

### Name transform — `name/kebab/strip-default`

Converts the token path to a kebab-case CSS custom property name, dropping any `default` segment:

```
color.background.default   →   --color-background
color.text.muted           →   --color-text-muted
```

### Format — `css/layer-tokens`

All tokens are wrapped in `@layer tokens { :root { … } }`. This is a low-priority layer in the Un Cinq stack (order: `reset, tokens, base, layouts, vendors, components`), so any project can override any token by importing after this package inside its own `@layer tokens` block.

References are preserved as `var()` — tokens are **not** resolved to their final values:

```css
/* output */
--color-text: var(--color-gray-900);   /* not oklch(0.208 0.006 264.542) */
```

This is done by reading `token.original.$value` and replacing every `{path.to.token}` reference with `var(--path-to-token)`. References embedded in a string value are also handled:

```json
{ "$value": "{size.8} {size.12}" }
```

```css
--file-button-padding: var(--size-8) var(--size-12);
```

### Composite tokens

Tokens whose `$value` is an object or an array of objects (e.g. `shadow`) are serialized as a space-separated CSS value. References inside the composite are converted to `var()`.

**Property order matters** — list properties in the order CSS expects them. For `box-shadow`:

```json
{
  "shadow": {
    "sm": {
      "$type": "shadow",
      "$value": [
        {
          "offsetX": "0",
          "offsetY": "1px",
          "blur": "2px",
          "spread": "0",
          "color": "{color.shadow.light}",
          "inset": false
        }
      ]
    }
  }
}
```

```css
--shadow-sm: 0 1px 2px 0 var(--color-shadow-light);
```

`inset` is always treated as a boolean prefix (`inset` or nothing), not a positional value.

---

## Dark mode — `themes/dark.json`

Dark mode is a **separate token set**, `tokens/themes/dark.json` — **not** declared inline on tokens (there is no `$mods`/`$modes` extension).

The model is **default + override**:

- The `semantic` layer carries the **default (light)** values, at their natural place (`semantic/color.json`, `semantic/form.json`). There is **no** `themes/light.json` — light is the baseline, not a mode you switch into.
- `themes/dark.json` holds **only the tokens that differ** in dark mode (background, text, heading, shadow, border, form background). Everything mode-invariant (brand, accent, status, …) is inherited automatically through `var()`.

This mirrors the DTCG **Resolver** philosophy (a base set + an overlay holding only the differences), so it stays forward-compatible as the Resolver spec stabilises.

### Generated output

The build emits `dist/css/themes/dark.css` with a single rule, inside `@layer tokens`:

```css
@layer tokens {
  @media (prefers-color-scheme: dark) {
    :root:not([data-color-scheme="light"]) {
      --color-background: var(--color-gray-950);
      /* … */
    }
  }
}
```

The light defaults stay in `dist/css/semantic/*.css` on `:root`. The dark file is purely additive — a light-only (mono-mode) site never needs to load it.

### Activation matrix

Dark mode follows the OS preference. The only attribute that does anything is `data-color-scheme="light"`, which **forces light** even when the OS prefers dark. Forcing dark against a light OS is intentionally **not** supported (there is no `[data-color-scheme="dark"]` rule).

| `data-color-scheme` on `<html>` | OS preference | Result | Why |
| --- | --- | --- | --- |
| *(none)* | light | **light** | `:root` defaults; the media query is inactive |
| *(none)* | dark | **dark** | the media rule matches `:root` (not forced light) |
| `light` | dark | **light** | `:not([data-color-scheme="light"])` excludes it → `:root` defaults |
| `light` | light | **light** | `:root` defaults; the media query is inactive |
| *(any other)* | dark | **dark** | the media rule still matches — only `light` opts out |

> **Note** — `color-scheme: dark` is intentionally absent from the generated block. The `color-scheme` property is managed at the HTML level by the consuming application (e.g. via `<meta name="color-scheme">`), not by the token layer.

### Rules

- Only colour tokens that actually change between modes belong in `themes/dark.json`; everything mode-invariant stays in `semantic`.
- Dark values follow the same `{dotted.path}` reference syntax as `$value` (e.g. `{color.gray.950}`).

---

## Adding a new token file

1. Create a JSON file anywhere under `tokens/` with DTCG structure.
2. Run `npm run build` — the file is detected automatically.
3. A matching CSS file is generated in `dist/css/`.

No changes to `style-dictionary.config.js` are needed.

---

## References

- [Style Dictionary v5 docs](https://styledictionary.com/)
- [DTCG format](DTCG.md) — token structure and types
- [Utopia fluid scales](UTOPIA.md) — `clamp()` values in spacing and typography tokens

---

## The JSON manifest

Alongside the CSS, the build writes `dist/tokens.json`: a flat array of every token the package ships.

```json
[
  {
    "name": "--color-brand",
    "value": "var(--color-sienna-600)",
    "type": "color",
    "file": "semantic/color",
    "description": ""
  }
]
```

The documentation site renders its reference tables from this file, which is why the reference cannot drift from the stylesheets.

The guarantee comes from a single shared function. `tokenToCssValue()` serializes a token to its CSS value, and **both** the CSS format and the manifest format call it. There is no second implementation of the naming or the value logic to fall out of step, and the build asserts the equivalence: the manifest holds exactly one entry per declaration emitted in `dist/css/`, with the same name and the same value.

`description` comes from the DTCG `$description` key. Adding one to a token source makes it appear in the published reference with no other change.


--------------------------------------------------------------------------------
design-tokens / Fluid scales
https://socle.uncinq.dev/docs/design-tokens/utopia/
--------------------------------------------------------------------------------

The Utopia method behind the fluid font-size and spacing tokens, and when to reach for them.



Source: <https://utopia.fyi>

## Principle

Each fluid token is a `clamp()` expression that scales linearly between a minimum and a maximum value, with no breakpoints.

```css
property: clamp(min, intercept + slope × 1vw, max);
```

```text
slope     = (max_px − min_px) / (viewport_max − viewport_min)
intercept = min_px − slope × viewport_min   (÷ 16 → rem)
```

---

## Viewport range

All fluid tokens use the same viewport range: **375 px → 1440 px** (range = 1065).

```text
slope     = (max_px − min_px) / 1065
intercept = min_px − slope × 375   (÷ 16 → rem)
```

This range covers modern phones (375 px) to wide desktop screens (1440 px). Tokens are clamped at both ends — below 375 px they stay at `min`, above 1440 px they stay at `max`.

---

## Usage

- **Fluid** (`--spacing-fluid-*`, `--font-size-fluid-*`) for layout and headings, anything that should breathe across screen sizes.
- **Fixed** (`--spacing-*`, `--font-size-*`) for UI components where continuous scaling would break the layout: badges, labels, icons, internal gaps.

The rule of thumb is whether the element has room to grow. A heading in a page flow does. A badge sitting inside a button does not, and scaling it continuously leaves it visually unrelated to the text it labels at one end of the range or the other.

## Worked example

`--font-size-fluid-2xs` is declared as:

```css
clamp(0.625rem, 0.5810rem + 0.1878vw, 0.75rem)
```

It reads as: never smaller than `0.625rem` (10px), never larger than `0.75rem` (12px), and in between it grows linearly with the viewport. At 375px wide the middle term evaluates to the minimum, at 1440px to the maximum, which is what ties every fluid token in the package to the same two anchor widths.


================================================================================
COMPONENT-TOKENS
================================================================================

Component-scoped CSS design tokens, layer 3 of the architecture, mapping semantic values onto the parts of a component.


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/)



--------------------------------------------------------------------------------
component-tokens / Naming
https://socle.uncinq.dev/docs/component-tokens/naming/
--------------------------------------------------------------------------------

The component token naming grammar, the rules behind it, and why colors invert the usual property order.


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.


--------------------------------------------------------------------------------
component-tokens / Customizing
https://socle.uncinq.dev/docs/component-tokens/customizing/
--------------------------------------------------------------------------------

How to override a component token, which layer to reach for, and when a new token is warranted.


## 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.


--------------------------------------------------------------------------------
component-tokens / Reference
https://socle.uncinq.dev/docs/component-tokens/reference/
--------------------------------------------------------------------------------

Every token for all 26 components, generated from the JSON sources so it can never drift from the shipped CSS.


Every table below is generated at build time from `dist/tokens.json`, which Style Dictionary produces from the same JSON sources as the CSS. Nothing here is written by hand, so a token cannot appear in the reference without existing in the package, or change value without the page changing with it.

Values are shown as they ship. A token that references a semantic token shows `var(--the-semantic-token)` rather than a resolved color or length, because that reference is what makes an override of the semantic layer propagate. See [Style Dictionary](../style-dictionary/) for why the build keeps it that way.

{{< alert-block state="info" >}}
Reading this offline, from the repository or from `node_modules`? The tables below are rendered by the documentation site. The same data, in machine-readable form, sits in `dist/tokens.json`, and the final CSS is in `dist/css/components/`.
{{< /alert-block >}}

### alert

Inline notification banner. 9 tokens.

{{< tokens pkg="component" file="components/alert" >}}

### badge

Badge, pill and tag. 12 tokens.

{{< tokens pkg="component" file="components/badge" >}}

### breadcrumb

Breadcrumb navigation. 10 tokens.

{{< tokens pkg="component" file="components/breadcrumb" >}}

### button

Button, all variants and sizes. 28 tokens.

{{< tokens pkg="component" file="components/button" >}}

### card

Card, an alias layer over item. 36 tokens.

{{< tokens pkg="component" file="components/card" >}}

### carousel

Carousel, arrows and pagination. 28 tokens.

{{< tokens pkg="component" file="components/carousel" >}}

### container

Layout container, max-widths and bleed. 17 tokens.

{{< tokens pkg="component" file="components/container" >}}

### details

Native details and accordion. 25 tokens.

{{< tokens pkg="component" file="components/details" >}}

### drawer

Off-canvas panel. 22 tokens.

{{< tokens pkg="component" file="components/drawer" >}}

### dropdown

Dropdown menu. 21 tokens.

{{< tokens pkg="component" file="components/dropdown" >}}

### embed

Video and iframe wrapper. 7 tokens.

{{< tokens pkg="component" file="components/embed" >}}

### figure

Figure and figcaption. 4 tokens.

{{< tokens pkg="component" file="components/figure" >}}

### heading

Heading typography scale. 3 tokens.

{{< tokens pkg="component" file="components/heading" >}}

### hero

Hero and banner section. 17 tokens.

{{< tokens pkg="component" file="components/hero" >}}

### item

Item, the canonical card-like unit. 55 tokens.

{{< tokens pkg="component" file="components/item" >}}

### items

Items grid and list wrapper. 3 tokens.

{{< tokens pkg="component" file="components/items" >}}

### link

Inline link. 4 tokens.

{{< tokens pkg="component" file="components/link" >}}

### list

Styled list. 6 tokens.

{{< tokens pkg="component" file="components/list" >}}

### logo

Logotype. 7 tokens.

{{< tokens pkg="component" file="components/logo" >}}

### map

Embedded map. 5 tokens.

{{< tokens pkg="component" file="components/map" >}}

### media

Media object, image plus text. 4 tokens.

{{< tokens pkg="component" file="components/media" >}}

### modal

Centered dialog. 21 tokens.

{{< tokens pkg="component" file="components/modal" >}}

### nav

Navigation bar. 15 tokens.

{{< tokens pkg="component" file="components/nav" >}}

### pagination

Pagination control. 17 tokens.

{{< tokens pkg="component" file="components/pagination" >}}

### surtitle

Small label above a heading. 8 tokens.

{{< tokens pkg="component" file="components/surtitle" >}}

### table

Data table. 6 tokens.

{{< tokens pkg="component" file="components/table" >}}


--------------------------------------------------------------------------------
component-tokens / DTCG format
https://socle.uncinq.dev/docs/component-tokens/dtcg/
--------------------------------------------------------------------------------

The Design Tokens Community Group JSON format as used for component tokens, including group-level types.



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)


--------------------------------------------------------------------------------
component-tokens / Style Dictionary
https://socle.uncinq.dev/docs/component-tokens/style-dictionary/
--------------------------------------------------------------------------------

How component token JSON is compiled to CSS, and how cross-package references to design-tokens are resolved.



[Style Dictionary v5](https://styledictionary.com/) transforms the DTCG JSON token files into CSS custom properties.

## Run the build

```bash
npm run build
```

Output is written to `dist/css/components/`. One CSS file is generated per JSON source file.

```
tokens/components/button.json   →   dist/css/components/button.css
tokens/components/badge.json    →   dist/css/components/badge.css
```

`dist/css/index.css` is auto-generated too, in a step that runs after Style Dictionary. It discovers the token files from disk, so adding a JSON source needs no manual edit anywhere. Each generated file declares its own `@layer tokens`, which is why a plain `@import` is enough and no `layer()` qualifier is used.

---

## Cross-package references

Component tokens reference semantic tokens from `@uncinq/design-tokens` using DTCG `{dotted.path}` syntax:

```json
{
  "btn": {
    "border": {
      "radius": { "$value": "{radius.control}", "$type": "dimension" }
    }
  }
}
```

The design-tokens sources are loaded as `include`, from `node_modules/@uncinq/design-tokens/tokens`, so these references do resolve at build time. The build fails fast with a clear message if that package is missing:

```js
const designTokensPath = './node_modules/@uncinq/design-tokens/tokens';
if (!fs.existsSync(designTokensPath)) {
  throw new Error('Missing @uncinq/design-tokens — run npm install first.');
}
```

Resolution is only used for validation, though. The output deliberately keeps the reference rather than the resolved value: the format reads `token.original.$value` and rewrites the DTCG reference as a CSS `var()`.

```
{radius.control}   →   var(--radius-control)
{color.text.muted} →   var(--color-text-muted)
```

That is what makes the layering work at runtime. A project that overrides `--color-brand` moves every component token pointing at it, because the component CSS still says `var(--color-brand)` rather than a baked-in color.

`log: { errors: { brokenReferences: 'console' } }` remains set as a safety net, so a typo in a reference reports on the console instead of aborting the whole build.

Path segments named `default` are stripped, mirroring the `@uncinq/design-tokens` convention:

```
{color.brand.default}   →   var(--color-brand)
{color.text.default}    →   var(--color-text)
```

---

## Adding a new component

1. Create `tokens/components/{name}.json` with DTCG structure.
2. Run `npm run build`.

That is the whole procedure. `dist/css/components/{name}.css` is generated, and the `@import` is added to `dist/css/index.css` automatically, because both the build and the index step discover token files from disk rather than from a hardcoded list.

---

## Token naming

Token JSON paths map directly to CSS custom property names. Use camelCase for compound CSS property names — the build converts them to kebab-case:

| JSON path | CSS variable |
| --- | --- |
| `btn.border.radius` | `--btn-border-radius` |
| `btn.color.background` | `--btn-color-background` |
| `btn.color.background.hover` | `--btn-color-background-hover` |
| `btn.color.textDecoration` | `--btn-color-text-decoration` |
| `btn.color.background.default` | `--btn-color-background` (default stripped) |
| `btn.text.decorationLine` | `--btn-text-decoration-line` |

States (`hover`, `active`, `focus`, `disabled`, `checked`) are nested one level deeper under the property group.

---

## References

- [Style Dictionary v5 docs](https://styledictionary.com/)
- [@uncinq/design-tokens](https://github.com/uncinq/design-tokens) — primitive and semantic tokens referenced by this package

---

## The JSON manifest

Alongside the CSS, the build writes `dist/tokens.json`: a flat array of every token the package ships.

```json
[
  {
    "name": "--btn-color-background",
    "value": "var(--color-brand)",
    "type": "color",
    "file": "components/button",
    "description": ""
  }
]
```

The documentation site renders its reference tables from this file, which is why the reference cannot drift from the stylesheets.

The guarantee comes from a single shared function. `tokenToCssValue()` serializes a token to its CSS value, and **both** the CSS format and the manifest format call it. There is no second implementation of the naming or the value logic to fall out of step, and the build asserts the equivalence: the manifest holds exactly one entry per declaration emitted in `dist/css/`, with the same name and the same value.

`description` comes from the DTCG `$description` key. Adding one to a token source makes it appear in the published reference with no other change.


================================================================================
CSS-BASE
================================================================================

Framework-agnostic CSS foundation, providing a reset, native element styles and layout primitives.


`@uncinq/css-base` is the CSS foundation the other Un Cinq packages build on. It styles native HTML elements and provides a handful of layout primitives, without introducing a component system and without any framework dependency.

It ships plain CSS source files. There is no build step, no preprocessor and no JavaScript.

## What is included

| Group | Scope |
| --- | --- |
| [Reset](reset/) | Baseline normalization, based on the Josh W Comeau custom CSS reset |
| [Base](base/) | Styles for native HTML elements, driven entirely by design tokens |
| [Layouts](layouts/) | `.container`, `.grid`, `.row` and their modifiers |
| [Media queries](mediaqueries/) | The `--sm` / `--md` / `--lg` / `--xl` custom media scale |

Each group scopes itself to a cascade layer it owns. Read [Cascade layers](cascade-layers/) before your first import: the layer order is the consuming project's responsibility, and getting it wrong is the most common source of surprises.

## Installation

```bash
npm install @uncinq/css-base
```

This package carries no token values of its own. It resolves every custom property it references from two peer dependencies, which must be installed and imported first:

```bash
npm install @uncinq/design-tokens @uncinq/component-tokens
```

## Usage

Import everything at once:

```css
@import '@uncinq/css-base';
```

Import a single group:

```css
@import '@uncinq/css-base/css/reset.css';
@import '@uncinq/css-base/css/base.css';
@import '@uncinq/css-base/css/layouts.css';
```

Or import file by file, when you want only part of the base layer:

```css
@import '@uncinq/css-base/css/base/body.css';
@import '@uncinq/css-base/css/base/headings.css';
@import '@uncinq/css-base/css/layouts/container.css';
```

The full import order, tokens before CSS, looks like this:

```css
@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;

@import '@uncinq/design-tokens';    /* @layer tokens */
@import '@uncinq/css-base';         /* @layer reset, base, layouts */
@import '@uncinq/component-tokens'; /* @layer tokens */
@import '@uncinq/css-components';   /* @layer components */
```

## Build requirement

`css/mediaqueries.css` declares `@custom-media` rules, which no browser implements natively. Your build must run [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media), otherwise every `@media (--sm)` query in the layout files is dropped and the layouts stay at their mobile values. See [Media queries](mediaqueries/).

## File structure

```
css/
  index.css           imports mediaqueries, reset, base, layouts
  mediaqueries.css    @custom-media scale, outside any layer
  reset.css           @layer reset
  base.css            barrel, imports all base/*
  layouts.css         barrel, imports all layouts/*
  base/               23 files, @layer base
  layouts/            3 files, @layer layouts
```

## References

- [@uncinq/design-tokens](https://github.com/uncinq/design-tokens), primitive and semantic tokens
- [@uncinq/component-tokens](https://github.com/uncinq/component-tokens), component-scoped tokens
- [@uncinq/css-components](https://github.com/uncinq/css-components), the component layer built on this package



--------------------------------------------------------------------------------
css-base / Cascade layers
https://socle.uncinq.dev/docs/css-base/cascade-layers/
--------------------------------------------------------------------------------

The three layers this package owns, and why declaring the full order is the consuming project's job.


css-base scopes every rule it ships to one of three cascade layers it owns.

| Layer | Contents |
| --- | --- |
| `@layer reset` | The CSS reset, the foundational baseline |
| `@layer base` | Native element styles |
| `@layer layouts` | Layout primitives |

Custom media queries in `css/mediaqueries.css` are the exception: `@custom-media` is resolved at build time, so it is never subject to the cascade and sits outside any layer.

## Declare the order in your project

The full layer order, including layers owned by sibling packages (`tokens`, `components`) and by the project itself (`libs`, `vendors`, `pages`, `utilities`), belongs to the **consuming project**. css-base deliberately does not declare it.

The reason is a rule of the cascade: a layer's position is fixed the **first time its name is seen**, and later re-declarations do not reorder it. If an imported package declared the order, it would win, and your project could never change it.

So declare the order once, at the very top of your entry stylesheet, before any `@import`:

```css
/* your project entry, e.g. main.css */
@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;

@import '@uncinq/design-tokens';    /* @layer tokens */
@import '@uncinq/css-base';         /* @layer reset, base, layouts */
@import '@uncinq/component-tokens'; /* @layer tokens */
@import '@uncinq/css-components';   /* @layer components */
```

The last layer wins. `reset` and `tokens` come first, at the lowest priority, so reset rules and token defaults never accidentally override base, layout, vendor or component styles.

If the `@layer ...;` line comes *after* an import, it is already too late: the imported package has fixed the order. Keep it first, always.

## Why `libs` and `vendors` are a pair

A third-party stylesheet goes into `libs`; the CSS you write to dress it goes into `vendors`, immediately after. Keeping them separate matters whenever the library is loaded lazily: it then arrives after your own CSS, and inside a single shared layer it would win every tie on source order.

Declare `libs` even when nothing imports into it yet. An undeclared layer name is appended **last**, above `utilities`, and CSS outside any layer is stronger still. A library imported with no `layer()` at all would therefore beat everything you write.

## Overriding from your project

Write to the same layer name after the imports:

```css
@layer base {
  a {
    --color-link: #0070f3;
  }
}
```

Because css-base uses low-specificity selectors throughout, and `:where()` in several files, an override rarely needs to escalate specificity. Prefer redefining the custom property, as above, over rewriting the declaration.

## Reference

[MDN: Using CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)


--------------------------------------------------------------------------------
css-base / Reset
https://socle.uncinq.dev/docs/css-base/reset/
--------------------------------------------------------------------------------

The baseline normalization applied in @layer reset, based on the Josh W Comeau custom CSS reset.


`css/reset.css` is a single file scoped to `@layer reset`. It is based on the [Josh W Comeau custom CSS reset](https://www.joshwcomeau.com/css/custom-css-reset/), with a few additions by Un Cinq.

Being the first layer in the recommended order, everything here is the weakest thing in the stylesheet. Any base, layout or component rule overrides it without needing extra specificity.

## What it does

| Rule | Effect |
| --- | --- |
| `box-sizing: border-box` | Applied to every element and pseudo-element |
| `margin: 0` | Removed from everything except `dialog`, whose centering depends on its own margin |
| `interpolate-size: allow-keywords` | Enables animating to and from `auto`, `min-content` and friends. Applied only under `prefers-reduced-motion: no-preference` |
| Text rendering on `body` | `-webkit-font-smoothing: antialiased`, `-moz-osx-font-smoothing: grayscale`, `text-rendering: optimizelegibility`, `font-variant-ligatures: common-ligatures` |
| Media defaults | `display: block` and `max-width: 100%` on `img`, `picture`, `video`, `canvas`, `svg` |
| Form control fonts | `font: inherit` on `input`, `button`, `textarea`, `select` |
| Overflow | `overflow-wrap: break-word` on `p` and `h1` to `h6` |
| Line wrapping | `text-wrap: pretty` on `p`, `text-wrap: balance` on `h1` to `h6` |

## Deviations from the original reset

Two rules from the upstream reset are present but commented out, on purpose.

**`line-height: 1.5` on `body`** is left to the tokens. `css/base/body.css` sets `line-height: var(--line-height-text, 1.5)`, so the value is a design decision rather than a reset concern, and the fallback preserves the original behaviour when the token is missing.

**The root stacking context** (`isolation: isolate` on `#root` or `#__next`) targets framework-specific mount points that do not exist in a framework-agnostic package. Add it in your own project if your framework needs it.

The additions by Un Cinq, absent from the upstream reset, are `-moz-osx-font-smoothing`, `text-rendering`, `font-variant-ligatures`, and the `:not(dialog)` exception on the margin reset.

## Using it alone

```css
@import '@uncinq/css-base/css/reset.css';
```

The reset references no custom property, so unlike the rest of the package it works without the token peer dependencies.


--------------------------------------------------------------------------------
css-base / Base
https://socle.uncinq.dev/docs/css-base/base/
--------------------------------------------------------------------------------

Styles for native HTML elements, one file per element or element family, all in @layer base.


`@layer base` styles native HTML elements so that unstyled markup already looks right. There is no class to apply: write `<table>`, `<blockquote>` or `<input type="date">` and they are styled.

Every value comes from a custom property resolved by [@uncinq/design-tokens](https://github.com/uncinq/design-tokens) and [@uncinq/component-tokens](https://github.com/uncinq/component-tokens). This package hardcodes almost nothing, so restyling is a matter of changing a token, not overriding a rule.

`css/base.css` imports all 23 files below.

## Typography and text

| File | Selectors |
| --- | --- |
| `base/body.css` | `body`: background, text color, font family, size, weight, line-height |
| `base/headings.css` | `h1` to `h6`: color, font family, weight, letter-spacing, line-height, margin, plus a per-level size from `--font-size-heading-01` to `-06` |
| `base/typography.css` | `p`: block spacing and `--max-width-paragraph` |
| `base/link.css` | `a`: color, underline offset, thickness and color, hover transition, focus-visible outline |
| `base/blockquote.css` | `blockquote`, `blockquote cite`: inline-start border, italic, muted cite block |
| `base/list.css` | `ul`, `ol`, `li` in prose context, including nested list indentation |
| `base/code.css` | `code`, `kbd`, `samp`, `pre`, and inline `code` outside `pre` styled separately from block code |
| `base/address.css` | `address`: removes the UA italic and resets inner paragraph spacing |
| `base/abbr.css` | `abbr[title]`: dotted underline with its own offset and thickness |
| `base/sup.css` | `sup`: raised without growing the line box, see the note below |

## Media and embedded content

| File | Selectors |
| --- | --- |
| `base/figure.css` | `figure`, `figcaption`, and nested `picture`, `img`, `.credit`. Flex column layout with responsive caption direction |
| `base/picture.css` | `picture`: `inline-block` |
| `base/video.css` | `video`: fluid width, auto height |
| `base/table.css` | `table`, `thead`, `tbody`, `th`, `td`: collapsed borders, cell padding, header weight, no border on the last row |
| `base/details.css` | `details`, `summary`, `details[open]`, the `summary::after` marker and the disclosed panel |

## Forms

Six of these seven files are largely inspired by [KNACSS](https://knacss.com/).

| File | Selectors |
| --- | --- |
| `base/form.css` | `label`, `legend`, and `input` excluding button, reset, submit, checkbox, radio and range. Adds per-type handling for `search`, `number`, `date`, `time`, `datetime-local` and `file`, including the `::file-selector-button` |
| `base/form-checkbox.css` | `[type='checkbox']` when it is not a switch, plus its adjacent `label` |
| `base/form-radio.css` | `[type='radio']` plus its adjacent `label` |
| `base/form-range.css` | `[type='range']`, the `.range` wrapper, `.range-value` output, and the WebKit and Gecko track and thumb pseudo-elements |
| `base/form-select.css` | `select` and `optgroup`, with a token-driven chevron background image |
| `base/form-switch.css` | `[role="switch"]`, rendered as a track and knob |
| `base/form-textarea.css` | `textarea`, including `field-sizing: content` and a `--textarea-min-height` default of `5lh` |

Text-like controls (`input`, `textarea`, `select`, `checkbox`, `radio`) draw their outline with `box-shadow: inset` and `border: 0`, so that focus and hover states change color without shifting layout by a pixel. The switch and the range thumb are the exceptions: both need a real `border`, since their outline is part of a shape that moves.

Every hover style in this layer is guarded by `@media (hover: hover) and (pointer: fine)`, so nothing sticks on touch. Transitions are guarded by `@media (prefers-reduced-motion: no-preference)`.

## Accessibility helpers

`base/accessibility.css` is the only file in this layer that ships classes rather than element selectors.

| Class | Behaviour |
| --- | --- |
| `.visually-hidden` | Hidden visually, still exposed to assistive technology |
| `.visually-hidden-focusable` | The same, but revealed on `:focus` or `:focus-within`. Intended for skip links |

```html
<button>
  <svg aria-hidden="true">...</svg>
  <span class="visually-hidden">Close</span>
</button>
```

Do not use these to hide decorative content. Decorative content should be removed from the accessibility tree with `aria-hidden="true"` instead, which is the opposite trade-off.

## Why `sup` zeroes its line-height

The user agent default, `vertical-align: super`, raises the glyph inside the line box, so the line box grows. A block containing a `<sup>` then becomes taller than one without it.

Zeroing `line-height` takes the superscript out of the line box calculation, and relative positioning raises it without affecting layout. A label carrying a required marker then measures exactly like a label without one, and two fields side by side stay aligned.

## Overriding

Redefine the token rather than the rule:

```css
@layer base {
  :root {
    --table-cell-padding-block: 0.5rem;
  }
}
```

Several files read a component-scoped property with a semantic fallback, for example `var(--code-font-family, var(--font-family-code))`. That gives you two levels: change the component token to affect only that element, or the semantic token to affect everything that inherits from it.


--------------------------------------------------------------------------------
css-base / Layouts
https://socle.uncinq.dev/docs/css-base/layouts/
--------------------------------------------------------------------------------

The .container, .grid and .row primitives, and the --container-bleed contract.


`@layer layouts` ships three primitives. They are deliberately few: everything else is a component's job.

All three read the responsive column count and gutter from tokens, so a project changes its grid by changing tokens rather than by rewriting layout rules.

## `.container`

A centered wrapper with a responsive max-width and a gutter on both sides.

```html
<div class="container">...</div>
```

| Property read | Role |
| --- | --- |
| `--container-max-width-*` | Max-width per breakpoint rung |
| `--container-bleed-*` | Bleed allowance per rung, the paired token |
| `--gutter` | Inline padding |

It also **publishes** one property of its own, `--container-bleed`.

### The `--container-bleed` contract

`--container-bleed` says how far a child may pull out of the container to reach the edge of the screen.

The property inherits, so it reaches a child from a `.container` however far up the tree it sits. That makes the `var()` fallback each consumer writes its answer to a single question: what should happen when there is no `.container` above me at all?

There are exactly two answers, and which one you want depends on the direction the child pulls:

| The child... | Falls back to | Why |
| --- | --- | --- |
| Pulls out, via a negative margin or inset | `0px` | With nothing published, the child has no idea what its parent has to give. A gutter pulled out of a card, or out of a full-bleed block that is already full width, is a guess that overflows |
| Puts room back inside its own box | `var(--gutter)` | A full-bleed block spans the viewport with no inset of its own, so without this the content would touch the screen edge |

Inside a container the two collapse to the published value and the pair cancels out exactly.

```css
/* pulls out */
margin-inline: calc(var(--container-bleed, 0px) * -1);

/* puts room back in */
padding-inline: var(--container-bleed, var(--gutter));
```

### Keeping the token pair in sync

`--container-bleed-*` is a token per rung, and it is the sibling of `--container-max-width-*` in `@uncinq/component-tokens`. The two must change together:

- A rung whose max-width is `100%` bleeds by one `--gutter`. The container spans the viewport, so the child does reach the edge.
- A rung that caps bleeds by `0`. Dead space then sits on both sides, and a negative margin would stop short of the edge, reading as a misalignment rather than a bleed.

The two decisions live side by side in the same token file, so changing one without the other is a visible omission:

```css
--container-max-width-desktop: 100%;
--container-bleed-desktop: var(--gutter);
```

## `.grid`

A CSS grid wrapper whose column count follows the breakpoint.

```html
<div class="grid">
  <div>...</div>
  <div>...</div>
</div>
```

Children inherit `--grid-column` and apply it as their `grid-column`. To give one child a different span from its siblings, override the per-breakpoint property on that child:

```css
.featured {
  --grid-column-tablet: span 2;
  --grid-column-laptop: span 3;
}
```

The gap comes from `var(--grid-gap, var(--gap))`, so a local `--grid-gap` overrides the global gap without touching it.

## `.row`

A flex wrapper, stacked on mobile and turning into a row at the `--tablet` breakpoint and above.

Its column modifiers apply to direct children. Each one spans a share of the active column count, so the proportion holds whatever that count is, and lands on whole columns whenever the count is divisible, such as 12, 24 or 48.

| Modifier | Span | At 12 columns |
| --- | --- | --- |
| `.col-xsmall` | `cols / 3` | 1/3 |
| `.col-small` | `cols / 2` | 1/2 |
| `.col-medium` | `cols * 2 / 3` | 2/3 |
| `.col-large` | `cols * 5 / 6` | 5/6 |

The computed width is `span/cols * 100% - (1 - span/cols) * gap`. The second term gives back the gaps the item does not occupy, which is what keeps the proportions exact rather than approximate.

Two offset modifiers are available, from the `--tablet` breakpoint (768px) upwards, alongside the column modifiers:

| Modifier | Effect |
| --- | --- |
| `.offset-center` | `margin-inline: auto` |
| `.offset-end` | `margin-inline-start: auto` |

```html
<div class="row">
  <div class="col-small">...</div>
  <div class="col-small">...</div>
</div>
```

`.row` mirrors the grid's responsive column count into its own `--columns`, so `.col-*` resolves against the same tracks as `.grid`. A row and a grid placed side by side line up.

## Build requirement

All three files use `@media (--tablet)` and friends, which are `@custom-media` rules. Without [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media) in your build, those blocks are dropped and the layouts stay at their mobile values. See [Media queries](../mediaqueries/).


--------------------------------------------------------------------------------
css-base / Media queries
https://socle.uncinq.dev/docs/css-base/mediaqueries/
--------------------------------------------------------------------------------

The --sm to --xl custom media scale, the deprecated device aliases, and the PostCSS plugin the package requires.


`css/mediaqueries.css` declares the breakpoint scale as `@custom-media` rules. It is imported first by `css/index.css` and sits outside any cascade layer, because `@custom-media` is resolved at build time and is never subject to the cascade.

## The scale

| Custom media | Min width | Pixels at 16px root |
| --- | --- | --- |
| `--sm` | `48rem` | 768 |
| `--md` | `64rem` | 1024 |
| `--lg` | `90rem` | 1440 |
| `--xl` | `100rem` | 1600 |

```css
.thing {
  @media (--md) {
    display: grid;
  }
}
```

These are rungs on a ladder, not devices. A width tells you nothing about the hardware: a 1024px window on a 27 inch monitor is not a tablet. Naming the steps after devices is also what left the previous scale with a compound name, `--tablet-wide`, which belongs to no device at all.

Intent belongs one layer up, in the semantic custom media a component defines for itself, such as `--toc-expand` or `--header-expand`. That way the component states the width at which *its own* behaviour changes, and the generic scale stays free of assumptions.

## Deprecated device aliases

The previous names are kept as aliases so existing stylesheets keep working.

| Deprecated | Use instead |
| --- | --- |
| `--tablet` | `--sm` |
| `--tablet-wide` | `--md` |
| `--laptop` | `--lg` |
| `--desktop` | `--xl` |

They are removed in the next major version. Prefer the scale in new code.

Note that the layout files shipped by this package, `container.css`, `grid.css` and `row.css`, still use the deprecated names internally. That is a migration still to be done, and it does not affect consumers: both sets of names resolve to the same widths.

The token names follow the same device vocabulary (`--container-max-width-tablet`, `--columns-laptop`), and those are token concerns rather than media query concerns. They are not affected by this deprecation.

## Required build step

No browser implements `@custom-media`. Your build must run [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media).

```bash
npm install --save-dev postcss postcss-custom-media
```

```js
// postcss.config.js
module.exports = {
  plugins: [require('postcss-custom-media')],
};
```

This failure is quiet rather than loud: without the plugin every `@media (--sm)` block is simply dropped, no error is raised, and the page renders at its mobile values on every screen size. If your layouts never respond to width, check this first.


================================================================================
CSS-COMPONENTS
================================================================================

Framework-agnostic CSS component implementations, driven entirely by component tokens and scoped to @layer components.


`@uncinq/css-components` is the top of the stack: 29 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](../component-tokens/) and adding no values of their own.

```
@uncinq/design-tokens      primitive + semantic values
@uncinq/component-tokens   component-scoped values
@uncinq/css-base           reset, native elements, layouts
@uncinq/css-components     ← this package
```

Every rule lives in `@layer components`, except the scroll-snap utility which lives in `@layer utilities`. There is no build step, no preprocessor, and no JavaScript shipped in the package. Three components do expect a script you provide, and each one documents the contract it needs.

## The components

| Page | Covers |
| --- | --- |
| [Buttons](buttons/) | `.btn` with its colour, size and style variants, plus 7 specialised buttons |
| [Overlays](overlays/) | `.panel`, `.modal`, `.drawer`, `.dropdown` |
| [Content](content/) | `.alert`, `.badge`, `.banner`, `.card`, `.items`, `.list`, `.media`, `.surtitle` |
| [Navigation](navigation/) | `.nav`, `.nav-title`, `.nav-accessibility`, `.breadcrumb-wrapper`, `.pagination` |
| [Embeds](embeds/) | `.embed`, `.video`, `.map` |
| [Forms](forms/) | `.form`, `.form-check` and the form layout helpers |
| [Utilities](utilities/) | `.scrollsnap`, turning a grid into a snap carousel |

Read [Cascade layers](cascade-layers/) first if you are wiring this into a project for the first time.

## Installation

All three packages below are required. The tokens resolve the custom properties, and css-base provides the reset and the element styles the components build on.

```bash
npm install @uncinq/design-tokens @uncinq/component-tokens @uncinq/css-base @uncinq/css-components
```

```css
@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;

@import '@uncinq/design-tokens';    /* @layer tokens */
@import '@uncinq/css-base';         /* @layer reset, base, layouts */
@import '@uncinq/component-tokens'; /* @layer tokens */
@import '@uncinq/css-components';   /* @layer components, utilities */
```

Per component, when you only need a few:

```css
@import '@uncinq/css-components/css/components/button.css';
@import '@uncinq/css-components/css/components/alert.css';
@import '@uncinq/css-components/css/utilities/scrollsnap.css';
```

Without a build step:

```html
<link rel="stylesheet" href="https://unpkg.com/@uncinq/css-components">
```

Note that `@uncinq/css-base` is a genuine prerequisite but is **not** declared in `peerDependencies`. Install it explicitly.

## Import order inside the package

`css/index.css` imports the components alphabetically, with two deliberate exceptions.

`components/panel.css` is imported **last** among the components. Its `.panel-inline-*` variants have to beat `.modal` and `.drawer`, and they do so on source order rather than on specificity, because most of the file is wrapped in `:where()` and carries no specificity at all.

`utilities/scrollsnap.css` comes after everything, in `@layer utilities`, because it has to win over the grid a component declares for itself in `@layer components`.

If you import file by file rather than using the barrel, preserve those two positions.

## What this package does not include

**No JavaScript.** `.modal`, `.drawer` and `.dropdown` expect a script. The CSS defines the classes and attributes that script must toggle, and each page documents the contract.

**No `.item`.** Despite what a couple of source comments still suggest, `.item` is not defined here. It lives in the Hugolify design system theme. This package ships `.card`, a complete implementation in its own right, and `.items`, a grid whose children you provide. See [Content](content/).

**No icons.** Components that show a glyph, such as `.pagination` controls, expect the theme to supply it through `::before` or `::after` content.

## References

- [@uncinq/component-tokens](https://github.com/uncinq/component-tokens), the values these components read
- [@uncinq/css-base](https://github.com/uncinq/css-base), the foundation underneath
- [MDN: CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)



--------------------------------------------------------------------------------
css-components / Cascade layers
https://socle.uncinq.dev/docs/css-components/cascade-layers/
--------------------------------------------------------------------------------

The two layers this package owns, why panel.css is imported last, and how to override a component cleanly.


This package writes to two layers.

| Layer | Contents |
| --- | --- |
| `@layer components` | All 29 components |
| `@layer utilities` | `.scrollsnap`, the only utility |

The full order, including layers owned by the sibling packages and by the project itself, is the **consuming project's** responsibility. Declare it once, at the very top of your entry stylesheet, before any `@import`:

```css
@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;
```

CSS fixes a layer's position the first time its name is seen, and later re-declarations do not reorder it. If that line comes after an import, it is already too late. See [the css-base page](../../css-base/cascade-layers/) for the full explanation, including why `libs` and `vendors` are a pair.

## Why `utilities` is last

`.scrollsnap` changes the `grid-template-columns` that a component such as `.items` declares for itself in `@layer components`. A later layer beats an earlier one regardless of specificity, so putting it in `utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.

This is also why it is a utility rather than a component rule: it is a modifier applied to something else, not a thing of its own.

## Why `panel.css` is imported last

Inside `@layer components`, source order breaks ties between rules of equal specificity. Two facts combine here:

1. Most of `panel.css` is wrapped in `:where()`, so it carries **zero specificity**. That is deliberate: it lets `.modal`, `.drawer` and your own overrides win without escalating.
2. The `.panel-inline-*` variants must beat `.modal` and `.drawer`, and they are plain class selectors.

Because those variants have no specificity advantage over the host components, they rely on arriving later in the file. Hence `@import 'components/panel.css';` sits last among the component imports in `css/index.css`.

If you import files individually, keep `panel.css` after `modal.css` and `drawer.css`.

## Overriding a component

Write to the same layer after the imports:

```css
@layer components {
  .alert {
    --alert-border-radius: 0;
  }
}
```

Prefer redefining the token over rewriting the declaration. Almost every value in this package comes from a `--component-*` custom property, so an override usually needs no selector work at all.

Better still, when the change is contextual rather than global, set the property on an ancestor and let it inherit:

```css
.sidebar {
  --alert-padding-inline: var(--spacing-sm);
}
```

That is a normal declaration on a normal selector, competing on specificity like any other rule, not on layer order. It restyles a region without adding a variant class to the system.

## Overriding a `:where()` rule

Because `panel.css` uses `:where()` throughout, its rules have zero specificity and a single class selector of yours already outranks them:

```css
.modal {
  border-radius: 0;
}
```

No `!important`, no repeated class, no `:is()` trick. This is the main practical benefit of the `:where()` convention, and it is worth preserving if you contribute to the package.


--------------------------------------------------------------------------------
css-components / Buttons
https://socle.uncinq.dev/docs/css-components/buttons/
--------------------------------------------------------------------------------

The .btn base class with its colour, size and style variants, and the seven specialised buttons built on it.


## `.btn`

The base class. Works on `<button>`, `<a>` and `<input type="submit">`, and reads `--btn-*` from [@uncinq/component-tokens](../../component-tokens/reference/).

```html
<button class="btn">Send</button>
<a class="btn btn-secondary" href="/contact">Contact</a>
```

### Colour variants

| Class | Intent |
| --- | --- |
| `.btn-primary` | Primary action |
| `.btn-secondary` | Secondary action |
| `.btn-brand` | Brand-coloured |
| `.btn-neutral` | Neutral emphasis |
| `.btn-dark` | Dark surface |
| `.btn-light` | Light surface |
| `.btn-success` | Confirmation |
| `.btn-danger` | Destructive action |
| `.btn-warning` | Warning |
| `.btn-info` | Informational |

Each variant sets `--btn-color-background`, `--btn-color-border` and `--btn-color-text` together. The text colour always comes from the matching `--color-text-on-*` semantic token, so contrast is preserved when the underlying colour is overridden. That pairing is the reason to change `--color-brand` rather than `--btn-color-background` when rebranding.

### Sizes

| Class | Use |
| --- | --- |
| `.btn-xs` | Dense UI, inline controls |
| `.btn-sm` | Compact |
| `.btn-md` | Default, can be omitted |
| `.btn-lg` | Prominent |
| `.btn-xl` | Hero call to action |

### Style variants

| Class | Effect |
| --- | --- |
| `.btn-ghost` | Transparent background, visible border |
| `.btn-link` | Renders as a link, no background or border |
| `.btn-control` | Form control styling, transparent border, for buttons sitting next to inputs |

Variants compose: `class="btn btn-danger btn-sm btn-ghost"`.

## Specialised buttons

Seven single-purpose buttons. Read the second column before using one: whether `.btn` is required differs between them.

| Class | Needs `.btn` | Icon | Purpose |
| --- | --- | --- | --- |
| `.btn-close` | no | `--icon-close` | Close control, used inside panels and alerts |
| `.btn-menu` | no | `--icon-menu` | Menu toggle, typically the burger in a header |
| `.btn-search` | yes | `--icon-search` | Search toggle |
| `.btn-filter` | yes | `--icon-filter` | Filters toggle |
| `.btn-share` | yes | `--icon-share` | Share control |
| `.btn-toc` | yes | `--icon-toc` | Table of contents toggle |
| `.btn-toggle-video` | yes | child elements | Play and pause control overlaid on a video |

```html
<!-- self-contained -->
<button class="btn-close" aria-label="Close"></button>

<!-- modifier on .btn -->
<button class="btn btn-search" aria-label="Search"></button>
```

`.btn-close` and `.btn-menu` redeclare everything they need, with `--btn-close-*` and `--btn-menu-*` falling back to the matching `--btn-*` token. They therefore look consistent with `.btn` without depending on it. The other five are modifiers, and omitting the base class leaves them largely unstyled.

Six of the seven **do ship their icon**, drawn as a `mask` on `::before` from the icon tokens in [@uncinq/design-tokens](../../design-tokens/reference/#icon). Because it is a mask rather than a background image, the glyph takes `currentColor` and follows the button's text colour through every state. Size it with `--icon-size`, or per button with `--btn-close-icon-size` and its siblings.

`.btn-toggle-video` is the exception and expects two child elements, for the reason given below.

When a button has no visible text, give it an accessible name with `aria-label`, or a `.visually-hidden` span from [css-base](../../css-base/base/#accessibility-helpers). None of these buttons provides one for you.

## `.btn-toggle-video`

The one worth explaining, because its behaviour is driven by a state class rather than by CSS alone.

It is a play and pause control overlaid on a video that autoplays without native controls, which WCAG requires to be pausable. It stays transparent so the video shows through, and the `.is-playing` class, toggled by whatever script drives the video, decides which of the two icons is shown.

```html
<div class="video">
  <video autoplay muted loop playsinline></video>
  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
    <span class="icon-pause"></span>
    <span class="icon-play"></span>
  </button>
</div>
```

The `.video` wrapper is what positions it. See [Embeds](../embeds/).

Your script owns two things: toggling `.is-playing` in step with the video's actual state, and keeping the accessible name in sync, since the control means "pause" while playing and "play" while paused.


--------------------------------------------------------------------------------
css-components / Overlays
https://socle.uncinq.dev/docs/css-components/overlays/
--------------------------------------------------------------------------------

The shared panel skeleton behind .modal and .drawer, the two opening strategies, and the .dropdown contract.


## The shared panel skeleton

`.modal` and `.drawer` are the same panel. Same structure (header, content, footer), same open and closed contract, same backdrop. They differ only in where they sit: modal centres them, drawer sticks them to an edge.

`components/panel.css` owns every rule. The two variants are **pure configuration**: `modal.css` and `drawer.css` declare nothing but `--panel-*` tokens.

There is **no `.panel` class to apply.** The file targets `:where(.modal, .drawer)` directly, so the skeleton arrives with either variant class. `panel` names the shared concept and the token namespace, not a class.

```html
<dialog class="modal" id="contact" aria-labelledby="contactLabel">
  <div class="header">
    <p class="title" id="contactLabel">Contact</p>
    <button class="btn-close js-dialog-close" aria-label="Close"></button>
  </div>
  <div class="content">...</div>
  <div class="footer">...</div>
</dialog>
```

Each variant aliases `--panel-*` from its own namespace, so `--modal-*` and `--drawer-*` remain the public API. Override those, not `--panel-*`.

## Two ways to open a panel

**The tag picks the strategy, not the class.** Either variant works both ways.

### `<dialog>` with `showModal()`

The browser handles Escape, the focus trap and making the rest of the page inert. You get `[open]`, the native `::backdrop` and the top layer for free.

This is the right choice when the panel is **always** a dialog.

### `popover="auto"` with `showPopover()`

Same top layer, same native `::backdrop`, but the element carries no implicit role.

Use this when the panel becomes a static region of the page above a breakpoint, which is what the `.panel-inline-*` variants do. The reason is an accessibility one: a `<dialog>` is exposed as `role="dialog"` even when it is only styled as a sidebar, whereas a script can set that role solely while the panel is actually open.

## `.modal`

A centred panel. Size a single instance by overriding `--modal-max-width` on the element itself.

```html
<dialog class="modal" style="--modal-max-width: 40rem">...</dialog>
```

## `.drawer`

A panel sliding in from an edge.

| Class | Edge |
| --- | --- |
| `.drawer-start` | Inline start, left in a left-to-right document |
| `.drawer-end` | Inline end |
| `.drawer-top` | Top |
| `.drawer-bottom` | Bottom |

## `.panel-inline-*`

Turns a panel into an ordinary region of the page from a breakpoint upwards, while it stays an overlay below.

| Class | Becomes inline at |
| --- | --- |
| `.panel-inline-sm` | `--sm`, 768px |
| `.panel-inline-md` | `--md`, 1024px |
| `.panel-inline-lg` | `--lg`, 1440px |
| `.panel-inline-xl` | `--xl`, 1600px |

This is the case that calls for `popover="auto"` rather than `<dialog>`. A filters sidebar that is a drawer on mobile and a column on desktop should not announce itself as a dialog while it is a column.

These variants beat `.modal` and `.drawer` on **source order**, not specificity, which is why `panel.css` is imported last. See [Cascade layers](../cascade-layers/).

## `.panel-trigger-*`

The companion to `.panel-inline-*`, applied to the **trigger button** rather than to the panel. It hides the trigger at the breakpoint where the panel stops being an overlay.

| Class | Trigger hidden from |
| --- | --- |
| `.panel-trigger-sm` | `--sm`, 768px |
| `.panel-trigger-md` | `--md`, 1024px |
| `.panel-trigger-lg` | `--lg`, 1440px |
| `.panel-trigger-xl` | `--xl`, 1600px |

Pair the suffixes: a panel carrying `.panel-inline-md` needs its button carrying `.panel-trigger-md`, otherwise a button that opens nothing remains on screen at desktop width.

The reason this is a second class rather than something CSS derives on its own is worth knowing, because it looks like a redundancy. Nothing structurally connects a trigger to its panel: the only link is `data-target` matching an `id`, and no selector can compare two attribute values. A positional rule would work only until somebody moved the markup, and a filter button typically lives in the page heading rather than beside the panel it opens. In practice both classes come from the same configuration value, so the pair cannot disagree.

## The JavaScript contract

This package ships no JavaScript. `.modal` and `.drawer` expect a script that provides:

| Hook | Role |
| --- | --- |
| `.js-dialog-toggle[data-target="#id"]` | Opens the panel it points at |
| `.js-dialog-close` | Any element inside the panel that closes it |

Closing must also work on Escape and on a click outside. With `<dialog>` and `showModal()` the browser already does both. With `popover="auto"` the platform handles light dismiss and Escape too, so in practice the script mainly manages the role and the open call.

## `.dropdown`

A contextual menu, with a tighter JavaScript contract because it animates.

```html
<div class="dropdown">
  <button class="js-dropdown-toggle" aria-expanded="false">Label</button>
  <ul class="dropdown-menu" role="menu">
    <li><a class="dropdown-item" href="#">Item</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><a class="dropdown-item" href="#">Item</a></li>
  </ul>
</div>
```

The trigger is `.js-dropdown-toggle`, and its **next element sibling must be** `.dropdown-menu`.

The script toggles three classes on the menu, in this sequence:

| Class | Meaning |
| --- | --- |
| `.showing` | Opening transition has started |
| `.show` | Fully open |
| `.hiding` | Closing transition has started |

It must also keep `aria-expanded` on the toggle in sync. The three-class sequence exists so the menu can animate out before being removed from the flow; a single `.show` class would make the closing transition impossible.

`.dropdown-menu-end` aligns the menu to the inline end of its trigger rather than the start.


--------------------------------------------------------------------------------
css-components / Content
https://socle.uncinq.dev/docs/css-components/content/
--------------------------------------------------------------------------------

Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.


## `.alert`

An inline notification block.

```html
<div class="alert alert-info">
  <p class="alert-heading">Heads up</p>
  <p>Your changes were saved.</p>
</div>
```

Variants: `.alert-primary`, `.alert-secondary`, `.alert-brand`, `.alert-neutral`, `.alert-dark`, `.alert-light`, `.alert-success`, `.alert-danger`, `.alert-warning`, `.alert-info`.

Each sets the background, border and text colour from the matching `-muted` and `-strong` semantic tokens, so the pairing stays legible if the underlying colour changes.

Two behaviours are worth knowing. `--color-link` is reassigned to the alert's own text colour, so links inside an alert do not fall back to the page link colour against a tinted background. And an alert whose first child is an `.icon`, with no `.alert-heading`, switches to a horizontal layout automatically.

`.container` inside an alert inherits the same flex layout, which is what lets a full-bleed alert keep its content aligned with the rest of the page.

## `.banner`

A thin variation on the alert, centred rather than start-aligned. It sets `--alert-align: center` and flattens paragraph margins, and nothing else.

```html
<div class="alert banner">
  <p>Site-wide announcement.</p>
</div>
```

It is a modifier on `.alert`, so use both classes.

## `.badge`

A small inline label.

```html
<span class="badge badge-success">Published</span>
<a class="badge" href="/tag/css">css</a>
```

Variants mirror the alert set: `.badge-primary`, `.badge-secondary`, `.badge-brand`, `.badge-neutral`, `.badge-dark`, `.badge-light`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info`.

Hover styles apply only to `a.badge`, guarded by `@media (hover: hover) and (pointer: fine)`, so a static badge never looks interactive.

## `.card`

A self-contained content card.

```html
<article class="card">
  <div class="content">
    <p class="surtitle">Category</p>
    <p class="title">Card title</p>
    <p class="description">Short description.</p>
  </div>
  <div class="media">
    <picture>...</picture>
  </div>
</article>
```

The media block sits first visually, through `--card-media-order: -1`, regardless of its position in the markup. Put it after the content so that screen readers and search engines reach the text first.

Wrapping the content in `a.content` makes the whole card clickable, using a `::before` overlay that covers the card. Focus is then handled on the card itself with `:has(a.content:focus-visible)`, so the focus ring outlines the card rather than an invisible box. Nested interactive elements inside such a card will be unreachable, which is the known trade-off of this pattern.

Sizing with `--card-max-width` and `--card-width` is unset by default. Prefer `ch` units, so the width tracks the text measure.

{{< alert-block state="info" >}}
The source comment in `card.css` describes `.card` as a backwards-compatible alias for `.item` and recommends using `.item` directly. That is misleading for anyone consuming this package on its own: **`.item` is not defined here**. It lives in the Hugolify design system theme. Within `@uncinq/css-components`, `.card` is a complete implementation and the class to use.
{{< /alert-block >}}

## `.items`

A responsive grid, and the usual container for cards.

```html
<div class="items">
  <article class="card">...</article>
  <article class="card">...</article>
</div>
```

The column count is intrinsic rather than breakpoint-driven:

```css
grid-template-columns: repeat(
  var(--items-cols, auto-fill),
  minmax(min(var(--items-min-width, var(--max-width-item)), 100%), 1fr)
);
```

Items wrap when they no longer fit at `--items-min-width`, with no media query involved. Set `--items-cols` to a number to force a fixed count instead.

It also declares `container-type: inline-size` and `container-name: items`, so children can use container queries against the grid rather than the viewport.

Pair it with [`.scrollsnap`](../utilities/) to turn the grid into a horizontal carousel below a given breakpoint.

## `.list`

A compact labelled list with dash markers.

```html
<div class="list">
  <p>Optional label</p>
  <ul>
    <li>First</li>
    <li>Second</li>
  </ul>
</div>
```

The wrapper is a `div`, with the label as a sibling of the list rather than inside it. Either `ul` or `ol` works.

## `.media`

The structural base for media blocks, controlling aspect ratio, background and border.

| Class | Use |
| --- | --- |
| `.media` | Base, for a picture or video |
| `.media-logo` | Logo, typically contained rather than cropped |
| `.media-icon` | Icon, sized from `--icon-size` |

`.media-logo` and `.media-icon` build on `.media`. Inside a `.card`, the card reassigns `--media-color-background` and `--media-ratio` from its own `--card-media-*` tokens, so a media block adapts to its context without a variant class.

A `.video` inside a `.media` is stretched to fill it. See [Embeds](../embeds/).

## `.surtitle`

An eyebrow label above a heading.

```html
<p class="surtitle">Category</p>
<h2>Main title</h2>
```

Inside a `.card` it gets a negative `--surtitle-margin-block-end`, pulling it closer to the title so the pair reads as one unit.


--------------------------------------------------------------------------------
css-components / Navigation
https://socle.uncinq.dev/docs/css-components/navigation/
--------------------------------------------------------------------------------

Navigation lists, skip links, breadcrumbs and pagination.


## `.nav`

The base navigation list, vertical by default.

```html
<ul class="nav">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
</ul>
```

Works on `ul` or `ol`. **Direction is set by context, not by a modifier class**: a header lays its nav out horizontally by setting `flex-direction: row` on it. That keeps the component free of layout variants that would only ever be used in one place.

## `.nav-title`

A title within a navigation block, for labelling a group of links.

## `.nav-accessibility`

Skip links, for keyboard and assistive technology users.

```html
<ul class="nav nav-accessibility">
  <li><a href="#main">Skip to content</a></li>
  <li><a href="#navigation">Skip to navigation</a></li>
  <li><a href="#footer">Skip to footer</a></li>
</ul>
```

Three things matter here, and getting any of them wrong defeats the purpose:

**It must be the first focusable element in `<body>`.** A skip link that comes after the navigation it skips is useless.

**It is hidden off-screen, not hidden.** It slides into view when a child receives focus. Using `display: none` would remove it from the tab order entirely.

**It requires the `.nav` base class** alongside it.

The targets must exist and be focusable. An `id` on a non-interactive element needs `tabindex="-1"` for the jump to move focus rather than just scroll.

## `.breadcrumb-wrapper`

The breadcrumb trail. Note that the class goes on the **wrapper**, not on the list itself.

```html
<nav class="breadcrumb-wrapper" aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/docs">Docs</a></li>
    <li aria-current="page">Navigation</li>
  </ol>
</nav>
```

The separator is drawn from `--breadcrumb-separator`, which defaults to `"/"`. Mark the current page with `aria-current="page"` rather than relying on it being last.

## `.pagination`

A page navigation list.

```html
<nav role="navigation" aria-label="Pagination">
  <ul class="pagination">
    <li class="disabled"><a class="first">First</a></li>
    <li><a class="previous">Previous</a></li>
    <li class="item active"><a href="?page=1">1</a></li>
    <li class="item item-adjacent"><a href="?page=2">2</a></li>
    <li><a class="next">Next</a></li>
    <li><a class="last">Last</a></li>
  </ul>
</nav>
```

| Class | Role |
| --- | --- |
| `.first`, `.previous`, `.next`, `.last` | Navigation controls, on the `a` |
| `.item` | A page number, on the `li` |
| `.item-adjacent` | A page number next to the current one |
| `.active` | The current page |
| `.disabled` | An unavailable control, on the `li` |

`.item-adjacent` exists so that a responsive paginator can hide distant page numbers while keeping the immediate neighbours visible, which is the usual mobile treatment.

**The glyphs for `.first`, `.last`, `.previous` and `.next` are not provided.** This package positions and spaces them; the theme supplies the arrow through `a::before` or `a::after` content. A paginator with no theme styling will show the text labels only, which is a reasonable fallback but rarely what you want visually.

Note that `.item` here means a pagination entry, and is unrelated to the `.item` card unit mentioned in [Content](../content/).


--------------------------------------------------------------------------------
css-components / Embeds
https://socle.uncinq.dev/docs/css-components/embeds/
--------------------------------------------------------------------------------

Aspect-ratio wrappers for third-party embeds, native video and maps.


## `.embed`

A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow once the iframe loads.

```html
<div class="embed">
  <iframe src="https://..." title="Video title" allowfullscreen></iframe>
</div>
```

Accepts `iframe`, `video`, `embed` or `object` as its child. The ratio comes from `--embed-ratio`, which defaults to the video ratio token. Override it per instance for a square or portrait embed:

```html
<div class="embed" style="--embed-ratio: 1">...</div>
```

Always give the `iframe` a `title`. It is the only accessible name an embedded frame has.

## `.video`

A wrapper for a **native** `<video>`, as opposed to an embedded player.

```html
<div class="video">
  <video autoplay muted loop playsinline></video>
  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
    <span class="icon-pause"></span>
    <span class="icon-play"></span>
  </button>
</div>
```

The wrapper positions the optional toggle control over the video. Inside a `.media`, the wrapper is stretched to fill it, so a video and an image are interchangeable within a card.

The control is there for a reason rather than for decoration. A video that autoplays without native controls must be pausable to meet WCAG, which is exactly what `.btn-toggle-video` provides. If your video carries `controls`, you do not need it. See [Buttons](../buttons/#btn-toggle-video) for the `.is-playing` contract.

## `.map`

A map container, driven by Leaflet through a `js-map` hook.

```html
<div class="map js-map"
     data-markers="[...]"
     data-zoom="12"
     data-tile="3"
     data-marker-hidden="false"></div>
```

| Attribute | Role |
| --- | --- |
| `data-markers` | The markers to plot |
| `data-zoom` | Initial zoom level |
| `data-tile` | Tile layer selection |
| `data-marker-hidden` | Whether markers start hidden |

This package provides the container only: sizing, background and border. Leaflet itself, its stylesheet and the script reading those attributes are yours to supply.

Leaflet's own CSS is a good example of why the layer order matters. Import it into `@layer libs` and any adjustments you write into `@layer vendors`, so that a lazily loaded Leaflet cannot outrank your own rules on source order. See [Cascade layers](../cascade-layers/).


--------------------------------------------------------------------------------
css-components / Forms
https://socle.uncinq.dev/docs/css-components/forms/
--------------------------------------------------------------------------------

The .form grid, its layout helpers, and where the actual control styling lives.


Form **controls** are styled by [@uncinq/css-base](../../css-base/base/#forms), on the native elements themselves. There is no `.input` or `.select` class to apply.

This package adds only what css-base cannot: the layout around those controls.

## `.form`

A responsive two-column grid that collapses to one column when there is not enough room.

```html
<form class="form">
  <div>
    <label for="first">First name</label>
    <input id="first" type="text">
  </div>
  <div>
    <label for="last">Last name</label>
    <input id="last" type="text">
  </div>
  <div class="full">
    <label for="message">Message</label>
    <textarea id="message"></textarea>
    <p class="help">Markdown is supported.</p>
  </div>
  <div class="actions">
    <button class="btn" type="submit">Send</button>
  </div>
</form>
```

The column rule is worth reading once:

```css
grid-template-columns: repeat(
  auto-fill,
  minmax(max(var(--form-col-min-width, 25ch), calc(50% - var(--gap) / 2)), 1fr)
);
```

The `max()` sets a floor of `25ch` **and** caps the result at half the width. The effect is a form that is one column or two, never three, however wide the container gets. A three-column form is almost never what you want, because it breaks the vertical reading order of a sequence of fields.

Change the floor with `--form-col-min-width`.

## Layout helpers

| Class | Effect |
| --- | --- |
| `.full` | Spans both columns, `grid-column: 1 / -1` |
| `.actions` | Spans both columns and stacks its children vertically |
| `.help` | Help text under a field |
| `.form-check` | A checkbox or radio laid out inline with its label |

```html
<div class="form-check">
  <input id="terms" type="checkbox">
  <label for="terms">I accept the terms</label>
</div>
```

`.form-check` is deliberately minimal, just `display: flex`. The checkbox and radio appearance, including the gap with the adjacent label, comes from css-base, which styles `[type='checkbox'] + label` directly.

## Accessibility

Nothing here supplies an accessible name. Every control needs a `<label for>` pointing at its `id`, or a `.visually-hidden` label when the design has no room for a visible one.

Tie `.help` text to its field with `aria-describedby`, otherwise it is visible but never announced:

```html
<input id="message" aria-describedby="message-help">
<p class="help" id="message-help">Markdown is supported.</p>
```

For error states, use `aria-invalid="true"` on the control and point `aria-describedby` at the error message.


--------------------------------------------------------------------------------
css-components / Utilities
https://socle.uncinq.dev/docs/css-components/utilities/
--------------------------------------------------------------------------------

The .scrollsnap utility, which turns a grid into a horizontal snap carousel below a breakpoint.


## `.scrollsnap`

Turns a grid into a horizontal carousel with snap points. Items keep their own width, the grid stops wrapping, and the row scrolls sideways, bleeding into the gutter so the next item peeks in.

```html
<div class="items scrollsnap-md">
  <article class="card">...</article>
  <article class="card">...</article>
  <article class="card">...</article>
</div>
```

It is opt-in, applied to the element that owns the grid, so the same component is a carousel in one context and a plain grid in another.

## The suffix names where the carousel stops

This is the one thing to get right, and it reads backwards from most responsive utilities.

| Class | Carousel below | Grid from |
| --- | --- | --- |
| `.scrollsnap` | every width | never |
| `.scrollsnap-sm` | `--sm`, 768px | 768px |
| `.scrollsnap-md` | `--md`, 1024px | 1024px |
| `.scrollsnap-lg` | `--lg`, 1440px | 1440px |
| `.scrollsnap-xl` | `--xl`, 1600px | 1600px |

**The suffix names the rung where the carousel STOPS and the grid comes back.** `.scrollsnap-md` is a carousel on mobile and tablet, and a grid from 1024px up.

## Why it is a utility

It has to win over the `grid-template-columns` that a component such as `.items` declares for itself in `@layer components`. `@layer utilities` comes later in the order, so it wins regardless of specificity. See [Cascade layers](../cascade-layers/).

## Item width

```css
grid-auto-columns: min(
  var(--items-min-width, var(--max-width-item)),
  var(--items-carousel-max-width, 75vw)
);
```

Items take `--items-min-width`, the same value that drives the grid, capped by `--items-carousel-max-width` (default `75vw`). The cap is what guarantees the next item always peeks in, which is the affordance that tells a reader the row scrolls at all. Without it, a wide item on a narrow screen would fill the viewport and the carousel would look like a static card.

## The bleed, and why margin and padding disagree

The row pulls out to the screen edge using `--container-bleed`, published by `.container` in [css-base](../../css-base/layouts/#the-container-bleed-contract). The property inherits, so it reaches the row from a `.container` however far up it sits.

Outside a container there is no published value, and the two `var()` fallbacks differ **on purpose**, because margin and padding answer different questions:

| | Question | Fallback |
| --- | --- | --- |
| `margin` | How far may I pull out of my parent? | `0`, since nothing published a bleed. The parent may be a card or a column with no room to give, and pulling a gutter out of it would overflow |
| `padding` | How far in from my own edge should the first item sit? | `var(--gutter)`, the breathing room every other box gets, so a full-bleed block does not let the cards touch the screen |

Inside a container the two collapse to one value: both read the published bleed, and the padding puts back inside the scroll box exactly what the negative margin took out. The first item lands on the container's content edge, aligned with everything else on the page.

`scroll-margin-inline` follows the **padding**, not the margin. It is what makes an item snap flush with the content edge rather than the padding edge, so it has to cancel the padding whatever the margin does.

This is the same reasoning as the `--container-bleed` contract itself, applied to a scroll container. If you write your own full-bleed component, copy the pair rather than picking one fallback for both.