SynthCSS

SynthCSS

CSS designed to be written by machines and used by humans.

A lightweight, opinionated CSS framework: a small set of design tokens and intent-named layout primitives that respond to the space they are given, plus eight semantic components for common app UI.

Built for AI-generated interfaces. SynthCSS targets interfaces written by AI agents and code generators, so its vocabulary is small, semantic and predictable.

This page is built with SynthCSS itself. SynthCSS is crowdfunded on nabled.ai.

Why SynthCSS

  • Frameworks are built for humans

    Traditional frameworks are optimized for people hand-writing every class.

  • AI output is inconsistent

    Models generating free-form CSS produce different values and patterns every time.

  • A small, predictable vocabulary

    SynthCSS offers a few semantic tokens and classes that mean one thing each.

  • Designed for model ergonomics

    Class names state intent, so a model can map a request to markup reliably.

Design tokens

Every swatch and specimen below is drawn with the framework's own custom properties from src/tokens.css. Values are read live from the stylesheet.

Colors

  • --color-background
  • --color-surface
  • --color-surface-elevated
  • --color-text
  • --color-text-secondary
  • --color-text-muted
  • --color-border
  • --color-primary
  • --color-primary-hover
  • --color-on-primary
  • --color-success
  • --color-warning
  • --color-danger
  • --color-info
  • --color-accent

Typography

Families

--font-sans The quick brown fox jumps over the lazy dog.

--font-mono The quick brown fox jumps over the lazy dog.

Weights

Normal --weight-normal

Medium --weight-medium

Semibold --weight-semibold

Bold --weight-bold

Sizes

Aa Interface --text-3xl

Aa Interface --text-2xl

Aa Interface --text-xl

Aa Interface --text-lg

Aa Interface --text-base

Aa Interface --text-sm

Line heights

--leading-tight Short headings and labels use a tight line height so stacked lines stay together.

--leading-normal Body text uses the normal line height for comfortable reading at any width.

--leading-relaxed Long-form text can use a relaxed line height for extra breathing room.

Spacing

  • --space-1
  • --space-2
  • --space-3
  • --space-4
  • --space-5
  • --space-6

Radius

  • --radius-sm
  • --radius-md
  • --radius-lg
  • --radius-full

Shadows

  • --shadow-sm
  • --shadow-md
  • --shadow-lg

Borders

--border-width in --border-color, which points at --color-border.

Focus states

Press Tab to move focus. The ring uses --focus-color, --focus-width and --focus-offset.

Focus ring preview

Motion

Easing --ease-standard. Durations drop to 0ms when reduced motion is requested.

  • --duration-fast
  • --duration-normal
  • --duration-slow

Sizing

  • --grid-min
  • --sidebar-width
  • --content-width
  • --container-width (bars are capped at the card width)

Layouts

Eight intent-named primitives. No media queries, no breakpoint classes. Dashed outlines show each primitive's box.

.container

A centered page-width wrapper with fluid side padding.

Page content
<main class="container">
  <h1>Settings</h1>
</main>

.stack

Children placed one below the other with an even gap.

First
Second
Third
<form class="stack">
  <label>Email <input type="email"></label>
  <button type="submit">Sign in</button>
</form>

.cluster

A row of small items that wraps onto more lines when it runs out of space.

  • design
  • tokens
  • layout
  • ai
  • css
<ul class="cluster" role="list">
  <li><a href="/docs">Docs</a></li>
  <li><a href="/blog">Blog</a></li>
</ul>

.grid

As many equal columns as fit, each at least --grid-min wide.

  • 1
  • 2
  • 3
  • 4
<ul class="grid" role="list">
  <li>…</li>
  <li>…</li>
  <li>…</li>
</ul>

.sidebar

A narrow first child next to a main area; they stack when space runs out.

<div class="sidebar">
  <nav class="stack">…</nav>
  <main class="stack">…</main>
</div>

.split

Two groups pushed to opposite ends of a row.

Brand
DocsLogin
<header class="split">
  <a href="/">Brand</a>
  <nav class="cluster">…</nav>
</header>

.center

A readable column, never wider than --content-width, centered horizontally.

A readable, centered column of text.

<article class="center stack">
  <h1>Release notes</h1>
  <p>…</p>
</article>

.cover

At least one viewport tall, with its main child vertically centered.

Header
Centered main
Footer
<section class="cover">
  <header>…</header>
  <div class="cover-main">…</div>
  <footer>…</footer>
</section>

Responsive demos

Change the width of each frame with its slider, or drag its bottom-right corner. The primitives respond to the width of their container, not the viewport.

.grid: columns reduce

  • Card 1
  • Card 2
  • Card 3
  • Card 4
  • Card 5
  • Card 6

.sidebar: stacks when narrow

.cluster: wraps

  • accessible
  • semantic
  • predictable
  • token-based
  • intrinsic
  • no breakpoints
  • AI-first

.split: adapts

Project dashboard
New report Export

Components

Thirteen semantic components built only from tokens. State comes from native attributes such as disabled, checked, aria-busy, aria-invalid, aria-current and aria-selected. Press Tab to see the focus rings.

.button

A native <button> or link styled as an action, with primary, secondary and danger variants, two sizes and disabled, loading and icon-only states.

Link button
<div class="cluster-sm">
  <button type="submit" class="button button-primary">Save</button>
  <button type="button" class="button button-secondary">Cancel</button>
  <button type="button" class="button button-danger button-sm">Delete</button>
  <button type="button" class="button" disabled>Disabled</button>
  <button type="submit" class="button button-primary" aria-busy="true">Saving…</button>
  <button type="button" class="button button-icon" aria-label="Delete">
    <svg aria-hidden="true">…</svg>
  </button>
</div>

.field

A label, a native control, help text and an error message. Controls are only styled inside .field.

Shown on the dashboard.

Enter a full email address.

Visibility
<div class="field">
  <label class="field-label" for="email">Email</label>
  <input id="email" type="email" aria-describedby="email-help">
  <p class="field-help" id="email-help">We never share it.</p>
</div>
<div class="field">
  <label class="field-label" for="name">Name</label>
  <input id="name" type="text" aria-invalid="true" aria-describedby="name-error">
  <p class="field-error" id="name-error">Enter your name.</p>
</div>
<div class="field">
  <label><input type="checkbox"> Remember me</label>
</div>

.switch

An on/off toggle: a native <input type="checkbox" role="switch"> inside its label, drawn as a track with a thumb. State comes from checked and disabled.

Workspace

New members wait until an admin approves them.

<label class="switch"><input type="checkbox" role="switch" checked> Require admin approval</label>
<label class="switch"><input type="checkbox" role="switch" disabled> Single sign-on</label>

.input-group

An input joined with buttons and/or selects in one row: shared borders, rounded outer corners, one height. The input grows; buttons and selects keep their size.

The budget is above your plan limit.

<div class="input-group">
  <input type="url" readonly value="https://example.com/invite/4f2a" aria-label="Invite link">
  <button type="button" class="button">Copy</button>
</div>

.card

A raised, self-contained block with optional media, header, body, footer and actions parts.

Atlas

Updated 2 hours ago

Customer-facing analytics dashboard.

3 members
<article class="card">
  <header class="card-header">
    <h3>Atlas</h3>
    <p>Updated 2 hours ago</p>
  </header>
  <div class="card-body"><p>Analytics dashboard.</p></div>
  <div class="card-actions">
    <a class="button button-primary" href="/atlas">Open</a>
    <button type="button" class="button">Share</button>
  </div>
  <footer class="card-footer">3 members</footer>
</article>

.badge

A short status label. The text carries the meaning; the color reinforces it.

  • Draft
  • Active
  • Trial ends soon
  • Failed
  • Beta
<span class="badge">Draft</span>
<span class="badge badge-success">Active</span>
<span class="badge badge-warning">Trial ends soon</span>
<span class="badge badge-danger">Failed</span>
<span class="badge badge-info">Beta</span>

.alert

A message box for status and errors. Headings, paragraphs and buttons inside are spaced automatically; an .alert-icon sits to their left.

A new version is available.

Settings saved.

Trial ends in 3 days

Add a payment method to keep your projects running.

A neutral note without a variant.

<div class="alert alert-success" role="status">
  <p>Settings saved.</p>
</div>
<div class="alert alert-danger" role="alert">
  <svg class="alert-icon" aria-hidden="true" viewBox="0 0 24 24">…</svg>
  <h2>Deployment failed</h2>
  <p>The build step exited with code 1.</p>
  <button type="button" class="button button-sm">View logs</button>
</div>

.panel

A flat, bordered group for secondary content. Lighter than a card: no shadow.

Usage this month

Pro plan

1,204 of 5,000 build minutes used.

<section class="panel">
  <header class="panel-header">
    <h2>Usage this month</h2>
  </header>
  <div class="panel-body">
    <p>1,204 of 5,000 build minutes used.</p>
  </div>
</section>

.table

A native table with header and body rows, borders, optional row hover and right-aligned .numeric cells. .table-wrap scrolls it sideways when narrow.

InvoiceCustomerStatusAmount
INV-1042Northwind TradersPaid1,250.00
INV-1043Contoso LtdDue89.90
INV-1044Fabrikam IncOverdue12,400.00
<div class="table-wrap" role="region" aria-label="Invoices" tabindex="0">
  <table class="table table-hover">
    <thead>
      <tr><th scope="col">Invoice</th><th scope="col" class="numeric">Amount</th></tr>
    </thead>
    <tbody>
      <tr><td>INV-1042</td><td class="numeric">1,250.00</td></tr>
      <tr><td>INV-1043</td><td class="numeric">89.90</td></tr>
    </tbody>
  </table>
</div>

.empty-state

A centered message for a list or page with nothing in it yet, with an optional icon and action.

No projects yet

Create a project to start tracking deployments.

<div class="empty-state">
  <svg aria-hidden="true">…</svg>
  <h2>No projects yet</h2>
  <p>Create a project to start tracking deployments.</p>
  <a class="button button-primary" href="/projects/new">New project</a>
</div>

.nav

Navigation links. .nav resets the list; .stack-sm or .cluster-sm sets the direction. The current page is aria-current="page".

<nav aria-label="Main">
  <ul class="nav cluster-sm" role="list">
    <li><a class="nav-link" href="/projects" aria-current="page">Projects</a></li>
    <li><a class="nav-link" href="/team">Team</a></li>
  </ul>
</nav>

.tabs

A tab list or segmented filter. The selected item is aria-selected="true" with role="tab"; for keyboard support and panel switching, see data-synth-tabs.

<div class="tabs" role="tablist" aria-label="Members">
  <button type="button" class="tabs-item" role="tab" aria-selected="true">All</button>
  <button type="button" class="tabs-item" role="tab" aria-selected="false">Admins</button>
  <button type="button" class="tabs-item" role="tab" aria-selected="false">Invited</button>
</div>

.avatar

A fixed square for initials, a photo or an icon on a 12% tint of its tone. Sizes follow --control-height.

Placeholder photo
<div class="cluster-sm">
  <span class="avatar avatar-round avatar-primary" aria-hidden="true">AL</span>
  <span>Ana Lima</span>
</div>
<img class="avatar avatar-round avatar-lg" src="/people/ben.jpg" alt="Ben Kim">
<span class="avatar avatar-accent"><svg aria-hidden="true" viewBox="0 0 24 24">…</svg></span>

Behaviors (SynthJS)

Optional and dependency-free: load dist/synth.js after the stylesheet and declare interactivity with one data-synth-* attribute per intent. SynthJS adds the events and keeps hidden, aria-expanded, aria-selected and tabindex in sync. Without it every component still renders. This page loads ../src/js/synth.js.

data-synth-open

Opens a native <dialog> as a modal. Escape or a data-synth-dismiss button closes it, and focus returns to the button that opened it.

Delete project?

Atlas and its 12 environments will be removed.

<button type="button" class="button button-danger" data-synth-open="confirm">Delete project</button>
<dialog id="confirm" aria-labelledby="confirm-title">
  <div class="stack">
    <h2 id="confirm-title">Delete project?</h2>
    <div class="cluster-sm">
      <button type="button" class="button button-danger">Delete</button>
      <button type="button" class="button" data-synth-dismiss>Cancel</button>
    </div>
  </div>
</dialog>

data-synth-toggle

Shows and hides the element with that id through its hidden attribute. The button's aria-expanded follows, from the initial markup on. Use it for any collapse or "show more".

<button type="button" class="button" data-synth-toggle="filters">Filters</button>
<div id="filters" class="panel" hidden>…</div>

data-synth-tabs

Turns .tabs into working tabs: click, ← → (wrapping), Home and End set aria-selected, a roving tabindex and hidden on the other panels.

This week: 18 deploys, 1 incident.

<div class="stack" data-synth-tabs>
  <div class="tabs" role="tablist" aria-label="Range">
    <button type="button" class="tabs-item" role="tab" id="tab-week" aria-controls="panel-week" aria-selected="true">Week</button>
    <button type="button" class="tabs-item" role="tab" id="tab-month" aria-controls="panel-month" aria-selected="false">Month</button>
  </div>
  <div role="tabpanel" id="panel-week" aria-labelledby="tab-week">…</div>
  <div role="tabpanel" id="panel-month" aria-labelledby="tab-month" hidden>…</div>
</div>

data-synth-dropdown

A trigger button and a .nav list of links. The trigger toggles the list and its aria-expanded; a click outside or Escape closes it, and Escape returns focus to the trigger.

<div data-synth-dropdown>
  <button type="button" class="button" data-synth-dropdown-trigger>Account</button>
  <ul class="nav stack-sm" role="list" data-synth-dropdown-menu hidden>
    <li><a class="nav-link" href="/profile">Profile</a></li>
    <li><a class="nav-link" href="/logout">Sign out</a></li>
  </ul>
</div>

data-synth-dismiss

Closes the <dialog> it is in, otherwise hides its closest data-synth-dismissible ancestor, such as an .alert, with hidden. The element stays in the page.

Settings saved.

<div class="alert alert-success" role="status" data-synth-dismissible>
  <p>Settings saved.</p>
  <button type="button" class="button button-sm" data-synth-dismiss>Dismiss</button>
</div>

Composed interface

A project settings screen built only from SynthCSS layout primitives and components, with no custom CSS. Drag the frame's corner or use the slider to see it adapt.

AI-friendly examples

A plain-English intent maps to one predictable class.

  • Intent

    "Show these tags in a row that wraps on small screens."

    SynthCSS

    <ul class="cluster" role="list">
      <li>Design</li>
      <li>AI</li>
      <li>CSS</li>
    </ul>
  • Intent

    "Show the products as responsive cards, as many per row as fit."

    SynthCSS

    <ul class="grid" role="list">
      <li class="stack-sm">…</li>
      <li class="stack-sm">…</li>
      <li class="stack-sm">…</li>
    </ul>
  • Intent

    "Put the settings navigation next to the form, stacked on phones."

    SynthCSS

    <div class="sidebar">
      <nav class="stack-sm">…</nav>
      <form class="stack">…</form>
    </div>
  • Intent

    "A header with the logo on the left and actions on the right."

    SynthCSS

    <header class="container split">
      <a href="/">Logo</a>
      <div class="cluster-sm">…</div>
    </header>
  • Intent

    "A full-screen sign-in page with the form in the middle."

    SynthCSS

    <main class="cover">
      <form class="cover-main center stack">…</form>
    </main>
  • Intent

    "Add a delete button and a status label to the project header."

    SynthCSS

    <header class="split">
      <h1>Atlas <span class="badge badge-success">Active</span></h1>
      <button type="button" class="button button-danger">Delete</button>
    </header>
  • Intent

    "Show an error under the email input."

    SynthCSS

    <div class="field">
      <label class="field-label" for="email">Email</label>
      <input id="email" type="email" aria-invalid="true"
        aria-describedby="email-error">
      <p class="field-error" id="email-error">Enter a full email.</p>
    </div>
  • Intent

    "Restyle the whole interface with our brand color and rounder corners."

    SynthCSS

    :root {
      --color-primary: #0b6e4f;
      --radius-md: 0.5rem;
    }

AI Contract

One compact file teaches a model the whole public vocabulary of SynthCSS: every token, layout primitive, component, part and variant, an intent table, composition rules, ten generation rules, the SynthJS behaviors, one extension rule for patterns the vocabulary lacks and valid and invalid examples. Paste synthcss.llm.md into a prompt, or read the same contract as structured data from synthcss.ai.json. Both are versioned with the framework and checked against the CSS on every change.

Size estimated as characters ÷ 4 (about 27,900 characters), small enough for one context window with room to spare.

SynthMCP

A stdio MCP server for coding agents. Instead of the whole contract in the prompt, an agent asks seven read-only tools: list_components, get_component, list_layouts, get_layout, resolve_intent, validate_markup and get_example. Every answer comes from synthcss.ai.json and carries synthVersion and contractVersion. Start it with npx synthmcp or npm run --silent mcp.

Intent to class: .cluster

The agent describes the need; resolve_intent scores it against the contract's intents, with no model involved.

Tool call

resolve_intent({ "intent": "a row of buttons that wraps" })

Response

{
  "class": ".cluster",
  "classes": "cluster",
  "reason": "Wrapping row of small items (buttons, tags, links) that keep their own width."
}

Rendered with SynthCSS

Validation: .button-danger

validate_markup parses the HTML and catches a variant used without its base class, with the fix as a suggestion.

Tool call

validate_markup({ "html": "<button class=\"button-danger\">Delete</button>" })

Response

{
  "valid": false,
  "issues": [{
    "type": "unsupported-variant",
    "severity": "error",
    "value": "button-danger",
    "message": ".button-danger is a variant of .button and needs class \"button\" on the same element.",
    "suggestion": "button button-danger"
  }]
}

Fixed, rendered with SynthCSS