@uncinq/css-base

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

What's included

Reset

Based on the Josh W Comeau custom CSS reset, with additions by Un Cinq:

• Box model normalization (box-sizing: border-box)
• Default margin removal
• interpolate-size: allow-keywords for keyword animations (behind prefers-reduced-motion: no-preference)
• Text rendering (-webkit-font-smoothing, text-rendering, font-variant-ligatures)
• Media defaults (display: block, max-width: 100% on img, picture, video, canvas, svg)
• Form controls font inheritance
• Overflow wrap on headings and paragraphs
• text-wrap: pretty on p, text-wrap: balance on headings

Base

Styles for native HTML elements, each driven by design tokens from @uncinq/design-tokens and @uncinq/component-tokens:

| File | Element(s) | | --- | --- | | base/accessibility.css | .visually-hidden, .visually-hidden-focusable — a11y visibility helpers | | base/body.css | body — background, text color, font family/size/weight/line-height | | base/headings.css | h1–h6 — color, font, size scale via --font-size-heading-01…06 | | base/typography.css | p — spacing, max-width | | base/link.css | a — color, underline style, hover transition | | base/blockquote.css | blockquote, cite — border-left, italic, muted color | | base/code.css | code, pre, kbd, samp — monospace font, background, inline vs block | | base/list.css | ul, ol, li — content list indent and spacing (prose context) | | base/address.css | address — removes italic, resets paragraph spacing | | base/details.css | details, summary — border, padding, open state, hover shadow | | base/figure.css | figure, figcaption — flex layout, responsive caption direction | | base/form.css | label, legend, input, select, textarea, [type='checkbox'], [type='radio'] | | base/picture.css | picture — inline-block display | | base/table.css | table, th, td, thead — collapse, padding, header weight | | base/time.css | time — small font size | | base/video.css | video — fluid width, auto height |

Layouts

Reusable layout utility classes:

| File | Class(es) | | --- | --- | | layouts/container.css | .container — centered, max-width responsive container with gutter | | layouts/grid.css | .grid — CSS grid wrapper with responsive --grid-column custom property | | layouts/row.css | .row, .col-xsmall, .col-small, .col-medium, .col-large, .offset-center, .offset-end |

CSS cascade layers

css-base scopes its rules to three cascade layers it owns:

| Layer | Contents | | --- | --- | | @layer reset | CSS reset — foundational baseline | | @layer base | Native element styles | | @layer layouts | Layout utility classes |

(Custom media queries live in mediaqueries.css and are not layered — @custom-media is resolved at build time.)

Declare the order in your project

The full layer order — including layers owned by sibling packages (tokens, vendors, components) — is the consuming project's responsibility, not this package's. css-base deliberately does not declare it.

CSS fixes a layer's position the first time its name is seen; later re-declarations don't reorder it. So declare the order once, at the very top of your entry CSS, before any @import:

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

@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 (lowest priority) so reset and token defaults never accidentally override base, layout, vendor, or component styles. If the @layer …; line comes after an import, it's too late — the imported package will already have fixed the order — so keep it first.

Override any layer from your project by writing to the same layer name after the imports:

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

→ MDN: Using CSS cascade layers

Installation

npm install @uncinq/css-base
# or
yarn add @uncinq/css-base

Usage

/* everything — reset + base + layouts */
@import '@uncinq/css-base';

/* or by group */
@import '@uncinq/css-base/css/reset.css';
@import '@uncinq/css-base/css/base.css';
@import '@uncinq/css-base/css/layouts.css';

/* or file by file */
@import '@uncinq/css-base/css/base/body.css';
@import '@uncinq/css-base/css/base/headings.css';
@import '@uncinq/css-base/css/layouts/container.css';
@import '@uncinq/css-base/css/layouts/row.css';

File structure

css/
  index.css                   ← imports reset, base, layouts (layer order is set by the project — see above)
  reset.css                   ← Josh W Comeau reset + Un Cinq additions, in @layer reset
  base.css                    ← barrel, imports all base/*
  layouts.css                 ← barrel, imports all layouts/*
  base/
    accessibility.css         ← .visually-hidden, .visually-hidden-focusable
    blockquote.css            ← blockquote + cite — border-left, italic, muted color
    code.css                  ← code, pre, kbd, samp — monospace, background, padding
    list.css                  ← ul, ol, li — content list indent and spacing
    address.css               ← address — removes italic, resets paragraph spacing
    body.css                  ← body — background, color, font, rendering
    details.css               ← details + summary — border, padding, open/hover states
    figure.css                ← figure + figcaption — flex layout, responsive captions
    form.css                  ← label, input, select, textarea, checkbox, radio
    headings.css              ← h1–h6 — color, font family, size scale
    link.css                  ← a — color, underline, hover transition
    picture.css               ← picture — inline-block display
    table.css                 ← table, th, td — collapse, padding, header weight
    time.css                  ← time — xs font size
    typography.css            ← p — spacing, max-width
    video.css                 ← video — fluid width
  layouts/
    container.css             ← .container — centered, responsive max-width
    grid.css                  ← .grid — CSS grid with responsive column custom property
    row.css                   ← .row + column/offset modifiers

Peer dependencies

This package requires @uncinq/design-tokens and @uncinq/component-tokens to resolve the CSS custom properties it references. It does not bundle any token values itself.

Token categories referenced across base and layout files include:

• --color-background, --color-text, --color-heading, --color-link, --color-border
• --font-family-text, --font-family-heading
• --font-size-*, --font-weight-*, --line-height-*
• --spacing-*, --max-width-*
• --transition-normal
• --border-width-*, --border-style-*, --radius-*
• Component-scoped tokens: --input-*, --select-*, --textarea-*, --checkbox-*, --radio-*, --details-*, --table-*, --figure-*, --label-*
• Layout tokens: --gutter, --gap, --columns, --container-max-width-*, --spacing-section

Install both peer dependencies:

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

→ @uncinq/design-tokens — primitive and semantic design tokens (color, typography, spacing, …) → @uncinq/component-tokens — component-scoped tokens (form, table, figure, …)

Then import them before this package so the tokens resolve correctly:

@import '@uncinq/design-tokens';
@import '@uncinq/component-tokens';
@import '@uncinq/css-base';

References

• @uncinq/design-tokens — primitive and semantic design tokens
• @uncinq/component-tokens — component-scoped tokens
• Josh W Comeau custom CSS reset — the reset foundation used in css/reset.css
• MDN: CSS cascade layers