CORRECTIV Design Tokens

Shared design tokens for CORRECTIV web projects. Provides CSS custom properties and a Tailwind v4 theme config as a single source of truth.

Table of Contents

• Usage
  • Tailwind theme
  • Typography classes
  • Utility classes
• Available Design Tokens
  • Typography
  • Layout
  • Colors
  • Radius
  • Duration
• Updating Tokens

Usage

Add to package.json devDependencies (you can reference any Git ref):

"wp-design-tokens": "correctiv/wp-design-tokens#<ref>"

Import whichever files you need in your CSS entry point after installing the package:

/* CSS custom properties + Tailwind theme */
@import "wp-design-tokens/theme.css";

/* CSS custom properties + Tailwind theme, with a Tailwind prefix */
@import "wp-design-tokens/theme.css" prefix(tw);

/* Composite typography utilities */
@import "wp-design-tokens/typography.css";

/* Custom Tailwind utilities (baseline grid, duration) */
@import "wp-design-tokens/utility.css";

Tailwind theme

theme.css wires all design tokens into Tailwind's utility system via @theme inline, replacing the entire default Tailwind theme. Every token becomes a utility class — colors, spacing, typography, radius, and duration — with no configuration needed in the consuming project.

<p
  class="tw:font-serif tw:text-article tw:tracking-wider tw:leading-looser tw:text-grey-700"
>
  …
</p>
<div class="tw:bg-emphasis tw:p-m tw:rounded-md">…</div>

The full list of available tokens, class names, and values is in Available Design Tokens.

Typography classes

typography.css provides ready-made composite Tailwind utilities that bundle font-family, size, weight, letter-spacing, and line-height:

• Text: tw:ty-text-article, tw:ty-text-s, tw:ty-text-m, tw:ty-text-l
• Headlines: tw:ty-headline-xs … tw:ty-headline-xxl
• Button: tw:ty-button

Utility classes

utility.css registers two custom Tailwind utilities:

• baseline-{V} / baseline-{V}/{M} — snaps an element to the 24 px baseline grid. V is the target line height in grid lines; optional M overrides the push (e.g. tw:baseline-2/1).
• duration-fast / duration-slow — maps the theme duration tokens to transition-duration (Tailwind v4 does not expose these natively via @theme).
• word-spacing-normal — applies --var-word-spacing-normal to word-spacing (Tailwind v4 has no built-in word-spacing utility).

Available Design Tokens

All tokens are defined in css/theme.css. --var-* properties can be used directly in any CSS; Tailwind utility classes are derived from the @theme inline block. Note that --*: initial resets all Tailwind defaults — only the tokens below are available as utilities.

Tailwind class names below omit any project-level prefix (e.g. tw:). If a prefix is configured, prepend it: tw:text-article.

Typography

Fonts

Font Weights

Font Sizes

Font sizes are responsive; values change at the 48rem (768 px) breakpoint. A single value means no breakpoint change. --text-* tokens are Tailwind font-size utilities; --headline-* tokens are CSS variables used via the arbitrary-value shorthand.

Letter Spacing

Word Spacing

* Requires utility.css.

Leading (line height)

Layout

Container Widths

Spacing Scale

Tokens are available for all spacing utilities: p-{name}, m-{name}, gap-{name}, w-{name}, h-{name}, etc. The base unit --spacing (0.125 rem) drives numeric utilities: p-4 = 4 × 0.125 rem = 0.5 rem.

Colors

Color tokens are available with any Tailwind color utility prefix: bg-{name}, text-{name}, border-{name}, etc.

Tokens are layered: primitives are the raw palette; semantic tokens describe an intended use (accent, background, foreground, stroke) and are built from primitives. Prefer semantic tokens in product code - primitives exist mainly to back them.

Primitives

Neutrals use a numeric scale rather than "grey", to distinguish this tonal ramp from chromatic color families - lower numbers are lighter, and only the positions currently needed are defined. Black and white are named independently, as absolute endpoints rather than designed tonal steps. Red and yellow are individual brand colors rather than full ramps; their numeric position (red-500, yellow-400) reflects where they'd sit in a future ramp, so more steps can be added later without renaming – red-500 anchors the pure hue at the ramp's center (no tints or shades mixed in), while yellow-400 is positioned slightly higher to preserve room for lighter variants and prevent compression of darker tones.

Semantic

Accent colors are used to draw attention. Named functionally rather than brand-primary/-secondary, though "accent" is effectively CORRECTIV's branding - there is deliberately no top-level "brand" family, since every color here is assumed to express brand.

Background describes context via 3 roles, named rather than numbered (-1/-2/-3) for memorable, readable usage; the "-background" suffix is omitted since the names already say so:

• background - "ground zero", the overall page background
• canvas - the white background of sections/post content, where content is "painted on"
• surface - the grey background that separates content from canvas (accordions, info boxes, ...)

Foreground (aka text) colors pick up a background role with an "-on-" prefix, to express which context they're intended for. Named "foreground" rather than "text" since it also covers icons and other non-text elements. Modifiers (-muted, -accent) can be appended as needed.

Stroke describes colors for linear elements - borders, dividers, line iconography - that provide structure without competing with content.

Deprecated (v1)

Superseded by the primitive/semantic tokens above. Values are unchanged - kept as aliases until all submodules migrate, then removed in a future version.

Radius

Duration

* Requires utility.css.

Updating Tokens

Apply changes

1. Edit the relevant file under css/.
2. Update the README to reflect current state.
3. Commit & push your changes (follow conventional commit format).

Publish changes

1. git tag -a v0.4.0 -m "v0.4.0 – Summary of changes" – instead of "v0.4.0" put the actual semantic version number.
2. Create a release via the Github Release feature (using "v0.4.0 – Summary of changes" as the release title).

Update consuming repos

1. Pin the new version in package.json: "wp-design-tokens": "correctiv/wp-design-tokens#v0.4.0"
2. Run npm install.