Base on Socle

Overview

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, one page each.

Typography and text

Page	File	Selectors
Body	`base/body.css`	`body`: background, text color, font family, size, weight, line-height
Headings	`base/headings.css`	`h1` to `h6`, plus a per-level size from `--font-size-heading-01` to `-06`
Paragraphs	`base/typography.css`	`p`: block spacing and `--max-width-paragraph`
Links	`base/link.css`	`a`: colour, underline, focus ring, external-link marker
Lists	`base/list.css`	`ul`, `ol`, `li` in prose context, including nested indentation
Blockquotes	`base/blockquote.css`	`blockquote`, `blockquote cite`
Code	`base/code.css`	`code`, `kbd`, `samp`, `pre`, and inline `code` separately from block code
Address	`base/address.css`	`address`: removes the UA italic and resets inner paragraph spacing
Abbreviations	`base/abbr.css`	`abbr[title]`: dotted underline with its own offset and thickness
Superscript	`base/sup.css`	`sup`: raised without growing the line box

Media and embedded content

Page	File	Selectors
Figures	`base/figure.css`	`figure`, `figcaption`, and nested `picture`, `img`, `.credit`
Picture	`base/picture.css`	`picture`: `inline-block`
Video	`base/video.css`	`video`: fluid width, auto height
Tables	`base/table.css`	`table`, `thead`, `tbody`, `th`, `td`
Details	`base/details.css`	`details`, `summary`, `details[open]`, the marker and the disclosed panel

Forms

Six of these seven files are largely inspired by KNACSS.

Body

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

base/body.css sets the six properties that everything else inherits. It is the shortest file in the layer and the one with the widest reach.

body {
 background-color: var(--color-background);
 color: var(--color-text);
 font-family: var(--font-family-text);
 font-size: var(--font-size-text, 1rem);
 font-weight: var(--font-weight-text, 400);
 line-height: var(--line-height-text, 1.5);
}

Token	Sets
`--color-background`	Page background
`--color-text`	Default text colour
`--font-family-text`	Body typeface
`--font-size-text`	Base font size, falls back to `1rem`
`--font-weight-text`	Base weight, falls back to `400`
`--line-height-text`	Base line-height, falls back to `1.5`

The last three carry a literal fallback on purpose. The upstream reset this package is based on sets line-height: 1.5 on body; here that rule is commented out and the value comes from a token instead, with the fallback preserving the original behaviour when the token is missing.

Headings

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

base/headings.css styles h1 to h6 with a single rule, then gives each level its size by reassigning one custom property.

h1, h2, h3, h4, h5, h6 {
 color: var(--color-heading);
 font-family: var(--font-family-heading);
 font-size: var(--font-size-heading);
 font-weight: var(--font-weight-heading);
 letter-spacing: var(--letter-spacing-heading);
 line-height: var(--line-height-heading);
 margin-block: var(--spacing-heading);
 max-width: var(--max-width-heading);
 text-transform: var(--text-transform-heading);
}

h1 { --font-size-heading: var(--font-size-heading-01); }
h2 { --font-size-heading: var(--font-size-heading-02); }
/* … through h6 */

Why the indirection

font-size is declared once, against --font-size-heading, and each element supplies the value. That keeps the shared rule to a single block, and it gives you two override levels:

Paragraphs

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

base/typography.css styles p and nothing else.

p {
 margin-block: var(--spacing-typography);
 max-width: var(--max-width-paragraph);
}

Token	Role
`--spacing-typography`	The rhythm between blocks. Blockquotes and nested lists read the same token, so prose keeps one spacing unit
`--max-width-paragraph`	The measure cap, in `ch` or `rem`, so a paragraph wraps before it becomes hard to read

The measure cap is opt-out, not opt-in

--max-width-paragraph applies to every p on the page, including ones inside a layout that already constrains its width. Two files in this layer undo it where it would be wrong:

Links

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

base/link.css styles a directly. There is no .link class.

a {
 color: var(--color-link);
 text-underline-offset: var(--text-decoration-offset);
 text-decoration-color: var(--link-color-text-decoration);
 text-decoration-line: var(--link-text-decoration-line);
 text-decoration-thickness: var(--text-decoration-thickness);
}

Token	Role
`--color-link`	Link colour
`--color-link-hover`	Hover colour
`--link-text-decoration-line`	`underline` by default, set to `none` to drop it
`--link-color-text-decoration`	Underline colour, independent of the text colour
`--link-color-text-decoration-hover`	Underline colour on hover
`--text-decoration-offset`	Distance from the baseline
`--text-decoration-thickness`	Underline weight
`--link-transition`	The transition, applied only under `prefers-reduced-motion: no-preference`

Declaring the underline colour separately from the text colour is what lets a link keep a full-contrast label with a lighter underline, which reads as a link without shouting.

Lists

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

base/list.css styles ul, ol and li for a prose context: a list inside running text, with markers and indentation.

:where(ul) {
 list-style-type: var(--list-style-type, revert-layer);
 padding-inline-start: var(--list-padding-inline-start, 1.5em);
}

:where(ol) {
 list-style-type: var(--list-ordered-style-type, revert-layer);
 padding-inline-start: var(--list-ordered-padding-inline-start, 2em);
}

:where(ul, ol) :where(ul, ol) {
 margin-block-end: var(--list-nested-margin-block-end, var(--spacing-typography));
 margin-block-start: var(--list-nested-margin-block-start, var(--spacing-typography));
}

:where(li) {
 margin-block: var(--list-item-gap, var(--spacing-2xs));
}

Rule	Effect
`:where(ul)`	Indents the list so the bullets sit inside it, from `--list-padding-inline-start`, and takes its marker from `--list-style-type` when set
`:where(ol)`	The same, with room for two-digit numbers, from `--list-ordered-padding-inline-start` and `--list-ordered-style-type`
Nested list	Block spacing above and below a list inside an item, from `--list-nested-margin-block-start` and `--list-nested-margin-block-end`
`:where(li)`	A small gap between items, from `--list-item-gap`

Nested lists get no indent rule, see nested lists.

Blockquotes

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

base/blockquote.css styles blockquote and the cite inside it.

blockquote {
 border-inline-start: var(--border-width-lg) var(--border-style-normal) var(--color-border);
 font-style: italic;
 margin-block: var(--spacing-typography);
 padding-inline-start: var(--spacing-sm);
}

blockquote cite {
 display: block;
 font-size: var(--font-size-xs);
 font-style: normal;
 margin-block-start: var(--spacing-typography);
}

<blockquote>
 <p>The best way to predict the future is to invent it.</p>
 <cite>Alan Kay</cite>
</blockquote>

The border is inline-start, not left

border-inline-start follows the writing direction, so the rule holds unchanged in a right-to-left document. The same goes for padding-inline-start. Nothing in this layer uses physical left or right properties.

Code

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

base/code.css covers four elements and draws one distinction the user agent does not: inline code is styled as a chip, code inside pre is not.

:where(code, kbd, samp) {
 font-family: var(--code-font-family, var(--font-family-code));
 font-size: var(--code-font-size, var(--font-size-xs));
}

:where(code):not(pre > code) {
 background-color: var(--code-color-background, var(--color-background-muted));
 border-radius: var(--code-border-radius, var(--radius-sm));
 color: var(--code-color-text, var(--color-on-muted));
 padding: var(--code-padding, var(--spacing-2xs));
}

Selector	Styled as
`code`, `kbd`, `samp`	Monospace, one step down in size
`code` not inside `pre`	A tinted chip with padding and a radius
`pre`	A scrollable block with its own background and padding
`pre > code`	The chip styling removed again: no background, no padding
`kbd`	A chip with a real border, so a key reads as a key

Why `pre > code` is undone rather than avoided

<pre><code> is the correct markup for a code block, so the inner code matches the chip rule. Rather than writing a more convoluted selector, the file lets it match and then resets the three properties that do not belong:

Address

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

base/address.css exists to undo two things rather than to add any.

address {
 font-style: normal;
 margin-block: 0;

 p {
 margin-block: 0;
 text-wrap: unset;
 }
}

Rule	Undoes
`font-style: normal`	The user agent italic, which reads as emphasis rather than as contact details
`margin-block: 0`	The block margin, left to the surrounding layout
`p { margin-block: 0 }`	The paragraph rhythm, which would space the lines of a single address apart
`p { text-wrap: unset }`	`text-wrap: pretty` from the reset

Why `text-wrap` is reset

The reset applies text-wrap: pretty to every p, which tunes the wrapping of running prose by avoiding a short last line. An address is a stack of short deliberate lines, usually broken with <br>, so there is nothing for the algorithm to improve and it can only move a break the author chose.

Abbreviations

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

base/abbr.css styles abbr only when it carries a title.

abbr[title] {
 text-decoration-line: dotted;
 text-decoration-thickness: 1px;
 text-underline-offset: 0.3rem;
}

<p>Published as <abbr title="Portable Document Format">PDF</abbr>.</p>

Only with a title

An <abbr> with no title expands to nothing, so there is nothing to signal and the element is left unstyled. The attribute selector makes that explicit: the dotted underline is a promise that hovering or focusing reveals an expansion.

The values are hardcoded

This is the one file in @layer base that does not read tokens. The dotted line is a convention rather than a design decision, and 1px and 0.3rem are tuned to it: a token-scaled thickness would turn the dots into dashes at large sizes, and the offset has to clear the descenders without drifting into the line below.

Superscript

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

base/sup.css replaces the user agent’s vertical-align: super with a relative offset.

sup {
 font-size: 0.75em;
 inset-block-start: -0.5em;
 line-height: 0;
 margin-inline: 0.1em;
 position: relative;
 vertical-align: baseline;
}

Why `line-height` is zeroed

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.

Figures

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

base/figure.css lays out figure as a flex column and gives figcaption a responsive direction.

<figure>
 <picture>
 <img src="…" alt="…">
 </picture>
 <figcaption>
 <p>The caption.</p>
 <span class="credit">© Photographer</span>
 </figcaption>
</figure>

Selector	Role
`figure`	Flex column, `--figure-gap` between image and caption, `--figure-margin-block` around
`figure picture`	Forced to `display: block`, overriding the `inline-block` default
`figure img`	`width: 100%`, `height: auto`
`figure figcaption`	Flex column, `--figure-figcaption-font-size`, `--figure-figcaption-gap`
`figure p`	`margin-block: 0`, since the figure owns the spacing
`picture + figcaption`	`align-items: baseline`, `justify-content: space-between`

The caption is a column, then a row

@media (min-width: 48rem) {
 figcaption {
 flex-direction: row;
 }
 .credit {
 margin-inline-start: auto;
 }
}

Below 48rem the caption and the credit stack. Above it they sit on one line, with margin-inline-start: auto pushing the credit to the far end. The baseline alignment is what keeps the two aligned on their text rather than on their boxes, which matters when the credit is smaller than the caption.

Picture

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

base/picture.css is the shortest file in the package.

picture {
 display: inline-block;
}

Why it exists

<picture> has no user agent styling of its own. It is an inline wrapper whose only job is to hold <source> elements around an <img>, and by default it is display: inline, which means it cannot take a width, a height or a vertical margin.

inline-block makes it a box: it sizes to its <img>, it flows with the text, and it accepts dimensions when a component needs to give it some.

Video

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

base/video.css makes the native element fluid and stops there.

video {
 height: auto;
 max-width: 100%;
}

max-width: 100% keeps a video inside its container whatever its intrinsic width, and height: auto keeps the aspect ratio while it does so. The reset already sets display: block and max-width: 100% on video among the other media elements; this file adds the height: auto that makes the scaling proportional rather than squashed.

What this file deliberately does not do

It reserves no space. A <video> sized only by max-width takes its height once the metadata loads, which shifts the rest of the page at an unpredictable moment. Reserving the box is the job of .video in @uncinq/css-components, which declares an aspect-ratio from a token so the box exists at its final size from the first paint.

Tables

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

base/table.css styles table, th and td directly. There is no .table class.

table {
 border-collapse: collapse;
 font-size: var(--table-font-size);
 width: 100%;
}

th, td {
 border-block-end: var(--border-width-sm) var(--border-style-normal) var(--table-color-border);
 padding-block: var(--table-cell-padding-block);
 padding-inline: var(--table-cell-padding-inline);
 text-align: start;
 vertical-align: top;
}

Token	Role
`--table-font-size`	Table text size, usually a step down from the body
`--table-color-border`	The horizontal rule under each row
`--table-cell-padding-block`	Vertical cell padding
`--table-cell-padding-inline`	Horizontal cell padding
`--table-color-background-header`	`thead th` background

Rules under rows, not around cells

Only border-block-end is declared, so the table reads as a set of rows rather than as a grid. border-collapse: collapse is what keeps adjacent rules to a single line rather than doubling them.

Details

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

base/details.css is the largest non-form file in the layer. It styles the native disclosure element as a bordered card, replaces the user agent marker with a masked icon, and expects one structural convention.

<details>
 <summary>How does the cascade work?</summary>
 <div>
 <p>The disclosed content.</p>
 </div>
</details>

The wrapping <div> is required. The file targets summary + div for the content padding, so content placed directly inside <details> is disclosed but unpadded.

Inputs and labels

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

base/form.css is the largest file in the layer. It styles label, legend and every input that is not a button, a checkbox, a radio or a range. Largely inspired by KNACSS.

There is no .input or .label class. The selectors are the native elements.

Labels and legends

label, legend {
 color: var(--label-color-text);
 display: block;
 font-size: var(--label-font-size);
 font-weight: var(--label-font-weight);
 line-height: var(--label-line-height);
 padding-block: var(--label-padding-block);
 padding-inline: var(--label-padding-inline);
 text-align: var(--label-text-align);
 text-transform: var(--label-text-transform);
}

display: block puts the label on its own line, which is the layout a stacked form wants. The checkbox and radio files override the padding through --label-padding-block and --label-padding-inline for their inline rows.

Checkboxes

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

base/form-checkbox.css replaces the native checkbox with a box this package draws itself. Largely inspired by KNACSS.

[type='checkbox']:not([role='switch']) { … }

The :not([role='switch']) is what keeps this file and the switch apart: a switch is a checkbox with a role, and it needs a different shape entirely.

The box

Token	Role
`--checkable-size`	Width and height, falls back to `1.25rem`. Shared with radio and switch
`--checkbox-color-background`	Unchecked background
`--checkbox-color-background-checked`	Checked background
`--checkbox-color-border`	Border colour, drawn as an inset shadow
`--checkbox-color-border-checked`	Checked border colour
`--checkbox-color-border-hover`	Hover border colour
`--checkbox-border-width`	Border thickness
`--checkbox-border-radius`	Corner radius. Set it to a pill value and the checkbox reads as a round one
`--checkbox-mask-checked`	The tick glyph
`--checkbox-mask-indeterminate`	The dash glyph
`--checkbox-scale-checked`	Tick size inside the box, falls back to `0.7`
`--form-color-accent`	Tick colour

flex: 0 0 auto matters more than it looks: in a flex row next to a long label, a checkbox without it is compressed into an ellipse.

Radios

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

base/form-radio.css mirrors the checkbox almost rule for rule, with one structural difference: the dot is a real element that scales, not a mask that appears. Largely inspired by KNACSS.

[type='radio'] {
 appearance: none;
 border-radius: var(--radio-border-radius);
 box-shadow: inset 0 0 0 var(--radio-border-width) var(--radio-color-border);
 display: inline-grid;
 height: var(--checkable-size, 1.25em);
 place-content: center;
 width: var(--checkable-size, 1.25em);
}

Token	Role
`--checkable-size`	Width and height, falls back to `1.25em`. Shared with checkbox and switch
`--radio-color-background`	Track background
`--radio-border-radius`	Corner radius, a pill value in practice
`--radio-border-width`	Border thickness, drawn as an inset shadow
`--radio-color-border`	Border colour
`--radio-color-border-hover`	Hover border colour
`--radio-color-background-checked`	Dot fill
`--radio-color-border-checked`	Dot border
`--radio-border-width-checked`	Dot border thickness
`--radio-scale-checked`	Dot size when checked, falls back to `0.7`

The dot is always there

&::before {
 border-radius: var(--radius-pill, 9999px);
 content: '';
 scale: 0;
 /* … */
}

&:checked::before {
 scale: var(--radio-scale-checked, 0.7);
}

The ::before exists at every moment; only its scale changes. That is what makes the transition possible: scale animates, while a ::before toggled between content: none and content: '' would pop in.

Range

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

base/form-range.css styles [type='range'] plus two optional classes, .range and .range-value.

<div class="range" data-range-output="anchor">
 <label for="volume">Volume</label>
 <input type="range" id="volume" min="0" max="100" value="50">
 <output class="range-value" for="volume">50</output>
</div>

Two vendor implementations, not one

A range input has no common styling API. WebKit and Gecko expose different pseudo-elements, so the track and the thumb are declared twice:

Pseudo-element	Engine	Styles
`::-webkit-slider-runnable-track`	WebKit, Blink	Track
`::-webkit-slider-thumb`	WebKit, Blink	Thumb
`::-moz-range-track`	Gecko	Track
`::-moz-range-thumb`	Gecko	Thumb
`::-moz-range-progress`	Gecko	The filled part before the thumb

They cannot be combined into one selector list: an unrecognised pseudo-element invalidates the whole rule, so each engine needs its own block.

Select

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

base/form-select.css styles select and optgroup. Largely inspired by KNACSS.

select {
 appearance: none;
 background-image: var(--select-icon);
 background-position: right var(--select-icon-size) center;
 background-repeat: no-repeat;
 background-size: var(--select-icon-size);
 border: 0;
 box-shadow: inset 0 0 0 var(--select-border-width) var(--select-color-border);
 padding: var(--select-padding);
 padding-inline-end: var(--select-padding-end);
 width: 100%;
}

Token	Role
`--select-color-background`	Background
`--select-color-border`	Border colour, drawn as an inset shadow
`--select-color-border-hover`	Hover border colour
`--select-border-width`	Border thickness
`--select-border-radius`	Corner radius
`--select-color-text`	Text colour
`--select-icon`	The chevron, as a `url()` or `image-set()`
`--select-icon-size`	Chevron size, and the inset it sits at
`--select-padding`	Padding
`--select-padding-end`	Inline-end padding, wider to clear the chevron
`--select-color-optgroup`	`optgroup` label colour

The chevron is a background image, not a mask

Unlike the details marker or the checkbox tick, this glyph is a background-image. A select already uses its background for the control surface, and an element has one mask but can layer several backgrounds, so the image is the workable option here.

Switch

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

base/form-switch.css styles [role="switch"]. Largely inspired by KNACSS.

<input type="checkbox" role="switch" id="notify">
<label for="notify">Email notifications</label>

The markup is a checkbox carrying the role. That is what makes the state work for free: the browser tracks :checked and assistive technology announces on and off rather than checked and unchecked, with no JavaScript involved.

base/form-checkbox.css excludes it explicitly, with [type='checkbox']:not([role='switch']), so the two files never both apply.

The track and the knob

Token	Role
`--switch-width`	Track width
`--checkable-size`	Track height and knob diameter, falls back to `1.25rem`
`--switch-track-color`	Track colour, unchecked
`--switch-track-color-checked`	Track colour, checked
`--switch-thumb-color`	Knob colour, unchecked
`--switch-thumb-color-checked`	Knob colour, checked
`--switch-thumb-scale`	Knob size inside the track
`--switch-color-border`	Track border colour
`--switch-border-width`	Track border thickness
`--switch-border-radius`	Corner radius, shared by track and knob

The knob is ::after, and ::before is an empty spacer.

Textarea

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

base/form-textarea.css styles textarea with the same box as the text inputs, plus three declarations specific to a multi-line control. Largely inspired by KNACSS.

textarea {
 field-sizing: content;
 min-height: var(--textarea-min-height, 5lh);
 resize: vertical;
 /* … the shared input box … */
}

Token	Role
`--textarea-color-background`	Background
`--textarea-color-border`	Border colour, drawn as an inset shadow
`--textarea-color-border-hover`	Hover border colour
`--textarea-border-width`	Border thickness
`--textarea-border-radius`	Corner radius
`--textarea-color-text`	Text colour
`--textarea-color-placeholder`	Placeholder colour
`--textarea-padding`	Padding, falls back to `0.75rem 1rem`
`--textarea-min-height`	Minimum height, falls back to `5lh`

`field-sizing: content`

The textarea grows as the user types, instead of scrolling inside a fixed box. It is a progressive enhancement: in a browser without support the declaration is ignored and the control behaves exactly as it always has, at min-height with a scrollbar.

Accessibility helpers

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

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

.visually-hidden,
.visually-hidden-focusable:not(:focus):not(:focus-within) {
 clip: rect(0 0 0 0);
 clip-path: inset(50%);
 height: 1px;
 overflow: hidden;
 position: absolute;
 white-space: nowrap;
 width: 1px;
}

Why not `display: none`

display: none and visibility: hidden remove the element from the accessibility tree as well as from the page, so a screen reader never reaches it. These declarations shrink the element to a single clipped pixel instead: it stays in the tree, stays focusable, and is announced normally.

Base on Socle

Overview

Typography and text

Media and embedded content

Forms

Body

Headings

Why the indirection

Paragraphs

The measure cap is opt-out, not opt-in

Links

Lists

Blockquotes

The border is inline-start, not left

Code

Why pre > code is undone rather than avoided

Address

Why text-wrap is reset

Abbreviations

Only with a title

The values are hardcoded

Superscript

Why line-height is zeroed

Figures

The caption is a column, then a row

Picture

Why it exists

Video

What this file deliberately does not do

Tables

Rules under rows, not around cells

Details

Inputs and labels

Labels and legends

Checkboxes

The box

Radios

The dot is always there

Range

Two vendor implementations, not one

Select

The chevron is a background image, not a mask

Switch

The track and the knob

Textarea

field-sizing: content

Accessibility helpers

Why not display: none

Why `pre > code` is undone rather than avoided

Why `text-wrap` is reset

Why `line-height` is zeroed

`field-sizing: content`

Why not `display: none`