CSS-FIRST DESIGN TOKENS · COMPLETE IN 0.1

Theme variables

Define your project's colors, typography, spacing rhythm, breakpoints, shadows, animations, and other design decisions using CSS variables. Coordiation turns recognized namespaces into utility APIs without a JavaScript configuration file.

✓

Theme blocks are consumed at compile time, merged with the built-in theme, emitted as CSS variables, and exposed to utility resolution. No theme parser or configuration runtime is shipped to the browser.

MENTAL MODEL

One token powers variables and utilities

Declare a recognized variable inside @co-theme. The compiler registers its name, emits the CSS custom property, and makes matching utility candidates available.

01 · DECLARE

--co-color-product:
oklch(62% .2 260)

→

02 · EMIT

:root {
--co-color-product: …
}

→

03 · USE

co-bg-product
co-text-product
co-border-product

app.css

@co-theme {
  --co-color-product: oklch(62% 0.2 260);
}

@coordiation;

component.coord

<button class="co-bg-product co-text-white hover:co-bg-product/80">
  Continue
</button>

COMPLETE EXAMPLE

Define a small product theme

Theme variables can live beside the Coordiation directive in your main stylesheet. Keep values source-controlled and group related namespaces for review.

app.css

@co-theme {
  --co-color-product: oklch(62% 0.2 260);
  --co-color-canvas: #f7f7f4;
  --co-font-display: "Inter", ui-sans-serif, system-ui;
  --co-font-weight-book: 450;
  --co-text-display: 3.5rem;
  --co-text-display--line-height: 0.95;
  --co-text-display--letter-spacing: -0.045em;
  --co-radius-panel: 1.125rem;
  --co-shadow-panel: 0 24px 60px rgb(0 0 0 / 0.14);
  --co-breakpoint-workspace: 72rem;
  --co-ease-product: cubic-bezier(0.16, 1, 0.3, 1);
  --co-animate-wiggle: wiggle 650ms ease-in-out infinite;
}

@keyframes wiggle {
  0%, 100% { transform: rotate(-3deg); }
  50% { transform: rotate(3deg); }
}

@coordiation;

component.coord

<article class="co-bg-canvas co-rounded-panel co-shadow-panel workspace:co-grid">
  <h1 class="co-font-display co-font-book co-text-display">Coordiation</h1>
  <span class="hover:co-animate-wiggle">New</span>
</article>

NAMESPACE REFERENCE

Recognized theme variable families

The token name after each prefix becomes the value used by the matching utility. Use lowercase kebab-case names that remain readable in class strings.

NamespacePurpose and generated example

--co-color-*Colors
co-bg-product · co-text-product · co-border-product

--co-background-image-*Named images and gradients
co-bg-hero

--co-breakpoint-*Responsive viewport thresholds
tablet:co-grid

--co-aspect-*Aspect ratios
co-aspect-poster

--co-container-*Container max-width values
co-container-content

--co-perspective-*3D perspective distances
co-perspective-product

--co-ease-*Transition timing functions
co-ease-spring

--co-animate-*Animation shorthands
co-animate-wiggle

--co-font-*Font families
co-font-display

--co-font-weight-*Font weights
co-font-book

--co-text-*Font sizes with optional metadata
co-text-display

--co-tracking-*Letter spacing
co-tracking-display

--co-leading-*Line height
co-leading-copy

--co-tab-size-*Tab width
co-tab-size-code

--co-radius-*Border radius
co-rounded-panel

--co-shadow-*Box shadow
co-shadow-panel

--co-inset-shadow-*Inset shadow
co-inset-shadow-control

--co-text-shadow-*Text shadow
co-text-shadow-hero

--co-blur-*Blur filters
co-blur-glass

--co-drop-shadow-*Drop-shadow filters
co-drop-shadow-logo

EXTENSION AND OVERRIDES

Add a new token or replace a built-in value

A new name extends the theme. Reusing an existing name replaces that token while preserving the public utility class, which lets a product change its visual system without rewriting templates.

ADD

product

New utility name

OVERRIDE

brand-500

Same utility, new value

CONSUME

var(--co-color-product)

Available in authored CSS

app.css

@co-theme {
  /* add */
  --co-color-product: oklch(62% 0.2 260);

  /* override */
  --co-color-brand-500: #111111;
}

GLOBAL CONTROLS

Spacing rhythm and transition defaults

Three special variables influence many utilities or the default transition contract instead of creating a named suffix.

VariableEffect

--co-space-unitBase multiplier used by numeric spacing and sizing utilities. Default: 0.25rem.

--co-default-transition-durationDuration emitted by co-transition when no duration utility overrides it.

--co-default-transition-timing-functionEasing emitted by the default transition utility.

app.css

@co-theme {
  --co-space-unit: 0.25rem;
  --co-default-transition-duration: 180ms;
  --co-default-transition-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}

Changing the spacing unit is a system-wide decision.

co-p-4, co-gap-6, co-size-10, and other numeric utilities derive from the same unit. Review the complete interface before changing it.

COMPOSITE TYPOGRAPHY

Attach metadata to fonts and text sizes

Double-hyphen metadata lets one semantic text token carry its line height, tracking, and weight. Font-family tokens can also provide OpenType feature and variable-font settings.

app.css

@co-theme {
  --co-font-editorial: "Editorial Variable", Georgia, serif;
  --co-font-editorial--font-feature-settings: "liga" 1, "kern" 1;
  --co-font-editorial--font-variation-settings: "opsz" 72, "wdth" 96;

  --co-text-display: 4.5rem;
  --co-text-display--line-height: 0.92;
  --co-text-display--letter-spacing: -0.055em;
  --co-text-display--font-weight: 680;
}

component.coord

<h1 class="co-font-editorial co-text-display">
  Designed for clarity.
</h1>

Metadata follows the selected token.

co-text-display emits the attached typography metadata together, while an explicit co-leading-*, co-tracking-*, or co-font-* utility can override individual decisions.

MOTION TOKENS

Pair animation shorthand with authored keyframes

The theme stores the animation shorthand; your stylesheet owns custom keyframes. Hover the preview to see the same relationship.

HOVER · WIGGLE

app.css

@co-theme {
  --co-animate-wiggle: wiggle 650ms ease-in-out infinite;
}

@keyframes wiggle {
  0%, 100% { transform: rotate(-3deg); }
  50% { transform: rotate(3deg); }
}

component.coord

<span class="motion-safe:hover:co-animate-wiggle motion-reduce:co-animate-none">
  New
</span>

COLOR METADATA

Pair Display-P3 with a same-name fallback

The --p3 companion is compiler metadata, not a second public utility. Coordiation promotes it only when the browser understands Display-P3 and the output device reports a P3 gamut.

app.css

@co-theme {
  --co-color-signal: oklch(64% 0.22 29);
  --co-color-signal--p3: color(display-p3 1 0.16 0.08);
}

component.coord

<button class="co-bg-signal co-text-white hover:co-bg-signal/80">
  Publish
</button>

Learn about OKLCH, opacity mixing, and progressive wide gamut →

DIRECT CSS ACCESS

Reference emitted variables in authored styles

Theme tokens remain ordinary CSS custom properties, so component layers and third-party integrations can consume the same source of truth as utility classes.

app.css

@layer components {
  .product-card {
    color: var(--co-color-neutral-950);
    background: var(--co-color-canvas);
    border-radius: var(--co-radius-panel);
    box-shadow: var(--co-shadow-panel);
  }

  .product-card a:hover {
    color: var(--co-color-product);
  }
}

NAMING GUIDANCE

Prefer intent over accidental values

01
Scales: use predictable numeric levels for graduated systems such as brand-50 through brand-950.
02
Semantic roles: use names like canvas, surface, danger, or panel when the role should remain stable as values change.
03
Lowercase kebab-case: token names should remain readable inside utility candidates and registry output.
04
Promote repetition: turn a repeated arbitrary value into a named theme token once it becomes a design decision.
05
Avoid component coordinates: prefer surface-raised to dashboard-card-top-right.

AI GENERATION CONTRACT

Keep theme decisions inspectable

Agents should inspect existing variables before introducing new names and keep design decisions traceable across generated markup.

Reuse an existing semantic token when its intent matches; do not create synonyms for the same decision.
Verify the namespace is recognized before expecting a utility class to be generated.
Pair every --co-color-…--p3 token with a safe same-name fallback.
Define application-owned keyframes whenever a custom animation token references them.
Keep @co-theme values source-controlled; never interpolate untrusted runtime input.
Promote repeated arbitrary values and document the reason for any global default change.

Previous← Conditional variants NextCustom utilities →