Overview

The design system consists of design tokens expressed as css custom properties. The design tokens are then organized into two main layers, foundation and semantic.

Foundation tokens

Foundation tokens are the smallest building blocks. They are primitive values and their describe what they are. For example —radius-1 is the a value that should be used to specify, well how rounded the corners of an element should be.

They serve an important purpose, they constrain the possible values from anything to a subset of pre-defined ones. This both speeds up the decision process and improves consistency through the ui.

The foundational tokens in this design system are an adaptation of the fantastic open props

Semantic tokens

The semantic tokens is an abstraction on top of the foundation tokens that should encode a pattern that should be applied across multiple elements like —color-text.

Themes

A good rule of thumb is that themes should only change semantic layer tokens. This also gives a good indication on whether a token is foundational or semantic.

By default there are two themes setup; light and dark. These mainly changes the colors from light to dark. But there could be more themes that changes other custom properties in the semantic layer like input radius or spacing. These could even complement each other. For example having theme “light” and “spacious” applied at the same time (if a “spacious” theme was created).

For more info about the color setup in the themes see the Color system

Next

Next: Color system

Color system

As mentioned the semantic layer deals quite a bit with colors.

To make it easier to use accessible colors there is a color system in place that helps with generating pallets.

From 4 seed colors: neutral, primary, destructive and constructive 4 swatches are generated with the same names.

When picking seed colors use a neutral color any color in the 500-range on https://color.surf/ should be fine.

How it works

The system starts with four seed colors that define the base hue for each color family:

1. Seed colors

• --color-primary-seed - Main brand color
• --color-neutral-seed - Grayscale colors
• --color-constructive-seed - Success/positive actions
• --color-destructive-seed - Error/negative actions

2. Color scale generation

Each seed color is automatically expanded into an 11-step scale (50-950) using color-mix() in oklab color space:

• 50-400: Progressively lighter tints (mixed with white)
• 500: The seed color itself
• 600-950: Progressively darker shades (mixed with black)

3. Swatch mapping

The scale values are then mapped to semantic tokens that describe their purpose. These mappings flip between light and dark themes to maintain proper contrast.

Next

Next: Foundation tokens reference

Foundation-tokens-reference

Below is a list of all foundation tokens.

Radius

Size

Content Size

Fluid size

Layer

Shadows

Typography

Font Family

Font Size

Font Weight

Line Height

Letter Spacing

Next

Next: Semantic tokens reference

Semantic tokens reference

Semantic tokens come in all shapes and sizes, below is an overview of all the values.

Typography

For ui elements the typescale is limited to 4 sizes. --h1,--h2,--p and --p2. This combined with text color provides enough visual hierarcy for normal ui.

Long form text like the documentation you’re reading now might need a bigger typescale and for that usecase .typesetting exists, see #doc-css-restyle

Font Families

Type Scale

The type scale provides consistent sizing across all text elements:

Sizing

—menu-height Simply the height of the menu. Since the menu is position absolute this is usefull when creating page layouts that needs to add padding so the top element is not positioned below the menu

—body-margin This value referes to the inset or padding of the main content. Think of it as the closest content that is not full width should be from the edge of a element.

—radius-box UIs have a lot of boxes. We have a dedicated .box class that can be used, but for other places where box styling is disired —radius-box can be used

Input elements

There are a lot of input elements. They should all have consistent styling. These custom properties are used to style both the custom elements like <m-input> as well as the native <input/> elements

Borders

In adition to all the stroke variants of colors (like --color-primary-stroke), that can be used to set the border color, there are other custom propertise that should be used for consistent border styling

—border-width How thick should the border be.

—border Collects border widht, style and default-color into a variable that can be used with border: var(--border)

—border-strong Same as --border but the strong variant.

Colors

The color system adapts to light and dark themes. Each color is defined with multiple variants for different use cases.

Text Colors

Background Colors

Stroke Colors

Special Colors

Color Scale Variants

The color system includes four semantic scales: primary, neutral, constructive, and destructive. Each scale has consistent variants:

Primary Colors

Neutral Colors

Constructive Colors

Destructive Colors

Css reset

Css restyle

Inputs

Typesetting

The .typesetting class creates consistent vertical rhythm for text-heavy content using CSS Grid. It styles headings, paragraphs, code blocks, horizontal rules, and maintains proper spacing between all elements.

Features

• All heading levels (h1-h6) with appropriate sizing
• Inline code and code blocks with styled borders
• Horizontal rules for section breaks
• Consistent vertical rhythm using 1rlh gap
• Extra spacing before headings for visual hierarchy

Use Cases

Apply .typesetting to containers with:

• Articles and blog posts
• Documentation pages
• Long-form written content
• Any content requiring consistent vertical rhythm

Comparison

function example() {
  return "Code blocks styled nicely";
}

function example() {
  return "Code blocks cramped";
}

Css utils

Utilities for spacing, borders, and layout using data attributes. All utilities use logical properties for better internationalization support.

Structure

CSS utilities use data attributes instead of classes. Write data-padding="3" instead of .p-3, or data-background="surface" instead of .bg-surface.

All utility values map to design system tokens.

Combining Values

Spacing utilities (margin, padding), borders, gaps, and alignment attributes support space-separated values:

<div data-padding="i-5 b-3">

This applies padding-inline: var(--size-5) and padding-block: var(--size-3).

<div data-margin="i-auto b-4">

This applies margin-inline: auto and margin-block: var(--size-4).

Directional Suffixes

Spacing and border utilities use logical property suffixes:

• -i — inline (left and right in LTR languages)
• -is — inline-start (left in LTR, right in RTL)
• -ie — inline-end (right in LTR, left in RTL)
• -b — block (top and bottom)
• -bs — block-start (top)
• -be — block-end (bottom)

Example: data-padding="i-5" applies horizontal padding, while data-padding="b-3" applies vertical padding.

Borders

Add borders to elements using the [data-border] attribute. Supports directional variants and combinations.

Directional Variants

• i — inline (left and right)
• is — inline-start (left in LTR)
• ie — inline-end (right in LTR)
• b — block (top and bottom)
• bs — block-start (top)
• be — block-end (bottom)

Combine directions:

<div data-border="bs be">  <!-- top and bottom -->

Use [data-variant] to change border color:

Text Colors

Text color utilities apply semantic text colors using the [data-text] attribute.

General Text

Text on Colored Backgrounds

Use these values when text appears on colored fills to ensure proper contrast:

• [data-text="on-{family}-soft"] — Text on soft backgrounds
• [data-text="on-{family}-mid"] — Text on mid backgrounds
• [data-text="on-{family}-loud"] — Text on loud backgrounds

Where {family} is primary, neutral, constructive, or destructive.

Backgrounds

Apply background colors using the [data-background] attribute. Color families include five intensity levels: softer, soft, mid, loud, and louder.

Use [data-text] for proper text contrast on colored backgrounds.

Surface Colors

Color Families

Gaps

Control spacing between flex or grid items using the [data-gap] attribute.

Row and Column Gaps

Use directional prefixes for independent row and column spacing:

• r- — row-gap (vertical spacing)
• c- — column-gap (horizontal spacing)

Combine row and column gaps:

<div data-gap="r-3 c-5">  <!-- row-gap: var(--size-3); column-gap: var(--size-5) -->

Examples

Available sizes: 0, 000, 00, 1-15, fluid-1 through fluid-10

Margin

Add space outside elements using the [data-margin] attribute.

Directional Control

Combine directions:

<div data-margin="i-5 b-3">  <!-- margin-inline: var(--size-5); margin-block: var(--size-3) -->

Available sizes: 0, 000, 00, 1-15, fluid-1-10, auto

Padding

Add space inside elements using the [data-padding] attribute.

Directional Control

Combine directions:

<div data-padding="i-body b-3">  <!-- padding-inline: var(--body-margin); padding-block: var(--size-3) -->

Available sizes: body, 000, 00, 1-15, fluid-1-10

Alignment

Control flexbox and grid alignment using [data-align] and [data-justify] attributes.

data-align

Controls vertical alignment in flex layouts and block-axis alignment in grid.

align-items (default):

• start, center, end, baseline, stretch

align-content (prefix: content-):

• content-start, content-center, content-end
• content-between, content-around, content-evenly
• content-baseline, content-stretch

Use -items to align individual items. Use content- when working with wrapped flex items or grid tracks.

data-justify

Controls horizontal alignment in flex layouts and inline-axis alignment in grid.

justify-items (default):

• start, center, end, stretch

justify-content (prefix: content-):

• content-start, content-center, content-end
• content-between, content-around, content-evenly

Use -items to align individual items. Use content- when working with wrapped flex items or grid tracks.

Combining Values

Combine values within each attribute:

<div data-align="center content-start">  <!-- align-items + align-content -->
<div data-justify="start content-between">  <!-- justify-items + justify-content -->

Combine both attributes for full control:

<div data-align="center" data-justify="content-between">

Css layout primitives

A set of layout primitives that can be used to build interfaces with.

Grid

Flexible grid layout with configurable columns and spanning capabilities.

• .grid — creates a grid layout (defaults to 1 column)
• [data-cols="1-12"] — set number of columns
• [data-span="1-12"] — span multiple columns
• [data-row-span="1-12"] — span multiple rows

Combine with [data-gap] for spacing between grid items, or combine with [data-justify] and [data-align] for cell alignment.

Basic Grid

A 3-column grid with equal-width columns.

<div class="grid" data-cols="3" data-gap="2">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2</div>
<div class="box" data-variant="surface">Item 3</div>
</div>

Column Spanning

Items can span multiple columns using data-span.

<div class="grid" data-cols="3" data-gap="2">
<div class="box" data-variant="surface" data-span="2">Spans 2 columns</div>
<div class="box" data-variant="surface">Item</div>
</div>

Row and Column Spanning

Items can span both rows and columns simultaneously.

<div class="grid" data-cols="3" data-gap="2">
<div class="box" data-variant="surface" data-row-span="2">Spans 2 rows</div>
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2</div>
<div class="box" data-variant="surface" data-span="2">Spans 2 columns</div>
</div>

Collection

Responsive grid layout that automatically adapts to available space. Items wrap to new rows as needed, maintaining a minimum card width.

• .collection — responsive grid (defaults to --size-fluid-8 minimum width)
• [data-size="1-10"] — adjust minimum card width using fluid size scale
• [data-variant="fit"] — collapse empty columns and stretch items to fill available space

Behavior

By default, Collection uses auto-fill which creates as many columns as will fit, leaving empty space if items don’t fill the row. Use data-variant="fit" to collapse empty columns and stretch items to fill the container.

Combine with [data-gap] for spacing between items.

Basic Collection

Default collection with automatic column creation based on available space.

<div class="collection">
<div class="box" data-variant="surface">Card 1</div>
<div class="box" data-variant="surface">Card 2</div>
<div class="box" data-variant="surface">Card 3</div>
</div>

Custom Card Size

Use data-size to control minimum card width. Larger sizes create wider cards that wrap earlier.

<div class="collection" data-size="7" data-gap="3">
<div class="box" data-variant="surface">Card 1</div>
<div class="box" data-variant="surface">Card 2</div>
<div class="box" data-variant="surface">Card 3</div>
<div class="box" data-variant="surface">Card 4</div>
</div>

Auto-Fit Variant

With data-variant="fit", empty columns collapse and items stretch to fill available space.

<div class="collection" data-variant="fit" data-gap="3">
<div class="box" data-variant="surface">Card 1</div>
<div class="box" data-variant="surface">Card 2</div>
<div class="box" data-variant="surface">Card 3</div>
</div>

Content Grid

Full-width grid layout with centered content area and optional breakout zones.

• .content-grid — creates three-column grid (full-width, breakout, content)
• Children get content width by default
• [data-width="breakout"] — wider than content, but not full-width
• [data-width="full"] — spans entire viewport width

CSS Variables

Control content grid widths with CSS custom properties:

• --content-width — maximum width for default content (default: 1600px)
• --content-breakout-width — maximum width for breakout content (default: 1800px)
• --body-margin — inline padding for all content (default: var(--size-fluid-2))

Use Cases

Use Content Grid for article layouts, documentation pages, or any content where most elements should be constrained to a readable width, but some elements (like images or code blocks) need to break out wider or span the full viewport.

Content grids can be nested to create different content width zones within a page.

Width Zones

Children default to content width. Use data-width to break out to wider zones.

<div class="content-grid" data-gap="2">
<div class="box" data-variant="surface">Content width (default)</div>
<div class="box" data-variant="surface" data-width="breakout">Breakout width</div>
<div class="box" data-variant="surface" data-width="full">Full width</div>
</div>

Custom Width Variables

Override width variables for specific content grids.

<div class="content-grid" style="--content-width: 200px; --content-breakout-width: 300px;">
<div class="box" data-variant="surface">Narrower content (800px max)</div>
<div class="box" data-variant="surface" data-width="breakout">Narrower breakout (1000px max)</div>
</div>

Nested Content Grids

Content grids can be nested to create sections with different width constraints.

<div class="content-grid">
<div class="box" data-variant="surface">Outer content width</div>

<div class="box content-grid" style="--content-width: 200px; --content-breakout-width: 300px;" data-width="full">
  <div class="box" data-variant="surface">Nested content grid with narrower width</div>
  <div class="box" data-variant="surface" data-width="breakout">Nested content grid with narrower width</div>
</div>

<div class="box" data-variant="surface">Back to outer content width</div>
</div>

Stack

Flex layout for arranging items in a single direction with optional spacing and alignment.

• .stack — vertical stack (column, default)
• [data-direction="row"] — horizontal stack

Combine with [data-gap] for spacing. Control alignment with:

• [data-align] — cross-axis alignment (horizontal in column, vertical in row)
• [data-justify] — main-axis alignment (vertical in column, horizontal in row)

Use Cases

Use Stack when you need a single column or row of items with consistent spacing. For multi-dimensional layouts where items wrap, use Collection instead.

Vertical Stack

Default stack direction is vertical (column).

<div class="stack">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2</div>
</div>

Vertical Stack with Gap

Add spacing between stacked items.

<div class="stack" data-gap="3">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2</div>
</div>

Horizontal Stack

Use data-direction="row" for horizontal layout.

<div class="stack" data-direction="row">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2</div>
</div>

Horizontal Stack with Gap

Combine direction and gap for horizontal spacing.

<div class="stack" data-direction="row" data-gap="3">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2<br>More content</div>
</div>

Vertical Alignment (Cross-Axis)

In horizontal stacks, data-align controls vertical alignment.

<div class="stack" data-direction="row" data-gap="3" data-align="start">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2<br>More content</div>
</div>

<div class="stack" data-direction="row" data-gap="3" data-align="end">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2<br>More content</div>
</div>

<div class="stack" data-direction="row" data-gap="3" data-align="stretch">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2<br>More content</div>
</div>

Horizontal Alignment (Main-Axis)

In horizontal stacks, data-justify controls horizontal alignment.

<div class="stack" data-direction="row" data-gap="3" data-justify="center">
<div class="box" data-variant="surface">Item 1</div>
<div class="box" data-variant="surface">Item 2<br>More content</div>
</div>