Design Tokens

Design tokens are the named, reusable primitives the whole system is built from — spacing, radius, elevation, motion, typography, z-index, and breakpoints (colours have their own richer system; see Custom Color System).

Single source of truth

The tokens are declared once, as CSS custom properties, in app/assets/stylesheets/midwest/tokens.css under the @layer midwest.tokens cascade layer. That CSS is the canonical definition. Everything else reads from it rather than re-declaring values:

• Components consume them directly in CSS via var(--space-md), var(--radius-md), etc.
• Ruby reads them through Midwest::Tokens, which parses tokens.css at runtime — so the Ruby values can never drift from what components render. This mirrors the contract Midwest::Theme has with color-system.css.
• The MCP server exposes them through the get_design_tokens tool.
• The CLI exports them with midwest_mcp tokens:export.

All length tokens are expressed in rem, so they scale with the responsive root font-size. Steps use a t-shirt scale (xs … 3xl) that lines up with the component option vocabulary (size:, padding:).

Using tokens in CSS

Reference a token anywhere you would otherwise hard-code a value:

@layer midwest.my-component {
  .midwest-my-component {
    padding: var(--space-md);
    border-radius: var(--radius-md);
    box-shadow: var(--shadow-lg);
    transition: transform var(--duration-base) var(--ease-standard);
  }
}

For example, CardComponent drives its padding, radius, sticky-header stacking, and flip animation entirely from tokens:

.midwest-card {
  --border-radius: var(--radius-md);
  --padding: var(--space-md);
}
.midwest-card.padding-lg { --padding: var(--space-lg); }

Token reference

The tables below are generated live from Midwest::Tokens, so they always match the shipped tokens.css.

Spacing

Border radius

Elevation (shadow)

Motion

Durations:

Easings:

Typography

Font families:

Font sizes:

Font weights:

Line heights:

Letter spacing:

Z-index

Named stacking order. --z-max matches the legacy 999999 sentinel used by sticky/overlay surfaces.

Breakpoints

These mirror the responsive root-font-size steps. They are exposed for JavaScript and container queries; CSS media queries still use the literal pixel values.

Ruby API

Midwest::Tokens gives read access to every token. Colours are folded in by delegating to Midwest::Theme, so the API covers the whole system.

Midwest::Tokens.categories            # => [:font_size, :spacing, :radius, ...]
Midwest::Tokens.spacing               # => { "none" => "0", "md" => "1rem", ... }
Midwest::Tokens.get(:radius, "md")    # => "0.5rem"
Midwest::Tokens.z_index               # => { "modal" => "1300", "max" => "999999", ... }
Midwest::Tokens.colors["gray"]["0"]   # => "#f6f6f7" (delegated to Midwest::Theme)
Midwest::Tokens.get(:colors, "gray")  # => the full shade hash
Midwest::Tokens.all                   # => the full token tree, colours included

Exporting tokens

The same tree can be exported in three formats, for handing tokens to other tools (design tools, non-Rails apps, a Sass pipeline):

Midwest::Tokens.to_json   # => JSON string of the full tree
Midwest::Tokens.to_css    # => ":root { --space-md: 1rem; ... }"  (scalars + colour hex)
Midwest::Tokens.to_scss   # => "$space-md: 1rem;\n$radius-md: 0.5rem;\n..."

From the command line

The midwest_mcp executable exposes the same exporters:

midwest_mcp tokens:export --format json   # default
midwest_mcp tokens:export --format css
midwest_mcp tokens:export --format scss

AI assistance (MCP)

The Midwest MCP server exposes the token tree to AI tools through get_design_tokens. Call it with no arguments for the full tree, or pass a category (spacing, radius, shadow, duration, easing, font_size, font_weight, font_family, line_height, letter_spacing, z_index, breakpoint, or colors) to scope the result. Because the tool reads from Midwest::Tokens, the values it returns are exactly what the components render.