Socle

Cascade layers

Mon, 01 Jan 0001 00:00:00 +0000

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.

Cascade layers

Mon, 01 Jan 0001 00:00:00 +0000

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:

@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 for the full explanation, including why libs and vendors are a pair.

Naming

Mon, 01 Jan 0001 00:00:00 +0000

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.

Naming

Mon, 01 Jan 0001 00:00:00 +0000

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.

Buttons

Mon, 01 Jan 0001 00:00:00 +0000

`.btn`

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

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

Colors

Mon, 01 Jan 0001 00:00:00 +0000

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.

Customizing

Mon, 01 Jan 0001 00:00:00 +0000

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.

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

Reset

Mon, 01 Jan 0001 00:00:00 +0000

css/reset.css is a single file scoped to @layer reset. It is based on the Josh W Comeau 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.

Base

Mon, 01 Jan 0001 00:00:00 +0000

@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 and @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.

Dark mode

Mon, 01 Jan 0001 00:00:00 +0000

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.

Overlays

Mon, 01 Jan 0001 00:00:00 +0000

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.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

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 for why the build keeps it that way.

Content

Mon, 01 Jan 0001 00:00:00 +0000

`.alert`

An inline notification block.

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

Customizing

Mon, 01 Jan 0001 00:00:00 +0000

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.

DTCG format

Mon, 01 Jan 0001 00:00:00 +0000

The W3C Design Token Community Group (DTCG) 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 transforms those JSON files into CSS custom properties — see 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 defines tokens as JSON objects with reserved $-prefixed keys:

Layouts

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Media queries

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Navigation

Mon, 01 Jan 0001 00:00:00 +0000

`.nav`

The base navigation list, vertical by default.

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

Reference

Mon, 01 Jan 0001 00:00:00 +0000

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.

Style Dictionary

Mon, 01 Jan 0001 00:00:00 +0000

Style Dictionary v5 transforms the DTCG JSON token files into CSS custom properties.

Run the build

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.

DTCG format

Mon, 01 Jan 0001 00:00:00 +0000

The W3C Design Token Community Group (DTCG) defines a standard interchange format for design tokens, so they can travel between tools (Figma, code, documentation) without loss of meaning.

The DTCG format

The DTCG spec defines tokens as JSON objects with reserved $-prefixed keys:

Embeds

Mon, 01 Jan 0001 00:00:00 +0000

`.embed`

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

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

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

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

Forms

Mon, 01 Jan 0001 00:00:00 +0000

Form controls are styled by @uncinq/css-base, 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.

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

Style Dictionary

Mon, 01 Jan 0001 00:00:00 +0000

Style Dictionary v5 transforms the DTCG JSON token files into CSS custom properties.

Run the build

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.

Fluid scales

Mon, 01 Jan 0001 00:00:00 +0000

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.

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

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

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.

Utilities

Mon, 01 Jan 0001 00:00:00 +0000

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

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

Socle

Cascade layers

Declare the order in your project

Cascade layers

Naming

Rules

Naming

Semantic tokens

Component tokens

Buttons

.btn

Colour variants

Colors

Color space, OKLCH

Customizing

CSS override

Choosing the right layer to override

Reset

What it does

Deviations from the original reset

Base

Typography and text

Media and embedded content

Forms

Dark mode

What it overrides

Overlays

The shared panel skeleton

Reference

Content

.alert

Customizing

1. CSS override

DTCG format

The DTCG format

Layouts

.container

Media queries

The scale

Navigation

.nav

.nav-title

Reference

Style Dictionary

Run the build

DTCG format

The DTCG format

Embeds

.embed

Forms

.form

Style Dictionary

Run the build

Config — style-dictionary.config.js

Fluid scales

Principle

Viewport range

Utilities

.scrollsnap

`.btn`

`.alert`

`.container`

`.nav`

`.nav-title`

`.embed`

`.form`

Config — `style-dictionary.config.js`

`.scrollsnap`