NibCSS

Design tokens

Name your colours, spacing and other values once in the config and reference them anywhere in a value.

1 min readv1

Defining tokens#

Tokens are two-level: group → key → value.

TypeScript
export default defineConfig({
  tokens: {
    color:  { brand: "#4F52D9", "brand-hover": "#3A3DBF", ink: "#0f172a" },
    space:  { sm: "8px", md: "16px", lg: "24px" },
    radius: { md: "10px", pill: "999px" },
    shadow: { card: "0 4px 16px rgba(15,23,42,.08)" },
  },
});

Referencing tokens#

Both spellings resolve tokens.space.md:

Spelling

Example

$group.key

p=$space.md

$group-key

p=$space-md

Keys containing a dash work with the dot form: $color.brand-hover.

Anywhere in a value#

HTML
<div nib="p=$space.sm $space.md; bd=1px solid $color.brand; bxsh=$shadow.card; bdrd=$radius.md">

Tokens inside recipes#

Recipes are resolved with the same tokens, so a recipe reads like a design spec:

TypeScript
components: {
  card: "p=$space.lg; bdrd=$radius.md; bxsh=$shadow.card; bgc=#fff",
}

Unknown tokens#

An unknown reference is left in the value (the browser ignores the declaration) and reported:

Text
Unknown token "$color.brnd" — did you mean "color.brand"?

Tokens vs CSS variables#

Tokens

CSS variables

Resolved

at compile time

in the browser

Can change at runtime

no

yes

Typo detection

yes

no

They combine well — a token can hold a variable: brand: "var(--brand)".

Next steps#