Caster — Getting started

The 60-second mental model

Caster is built on three ideas. Once these click, everything else falls into place.

1 · Three-tier tokens

Every token belongs to one of three tiers. Components only ever reference semantic tokens — never primitives directly. This is what makes a re-theme a single-file change.

Tier	Example	Who edits this
Primitive	color.blue.700 = #0021a6	Brand owners, rarely
Semantic	color.brand.default → {color.blue.700}	Designers — when meaning shifts
Component	button.brand.bg → {color.brand.default}	Component authors

2 · One source, many outputs

Source-of-truth lives in tokens/{primitives,semantic,components}.json. Style Dictionary compiles those into five platform-specific outputs, all in tokens/:

Output	Best for
tokens.css	Vanilla web, modern Stencil, any HTML/JS project
tokens.scss	Legacy Stencil partials, Sass-based codebases
tokens.tailwind.css	Catalyst (Tailwind v4) — drop-in `@theme` block
tokens.tailwind.js	Older Tailwind v3 setups (theme config object)
tokens.figma.json	Figma via Tokens Studio plugin

3 · CSS variables are the contract

Every output ultimately resolves to --caster-* CSS custom properties on :root. Components read those variables. To override at any scope, redefine the variable on a parent element:

<!-- Override the brand color inside this section only -->
<section style="--caster-color-brand-default: #1a8a3f">
  <button class="btn btn-brand">Now green</button>
</section>

Pick your integration path

Three documented paths, all consuming the same compiled tokens. Pick the one that matches your project.

Path 1

Vanilla / HTML

Plain HTML/JS pages, prototypes, Webflow exports. Two stylesheets, use class names, done.

Path 2

BigCommerce Stencil

The shop.usaclean.com production target. Cornerstone + Caster tokens via SCSS partials.

Path 3

Catalyst (future)

Next.js + React + Tailwind v4. Future-state replatform path. @theme import + utilities.

Quick start (vanilla, 30 seconds)

If you just want to render a Caster button right now in any HTML file:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet"
        href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;500;600;700;800&display=swap">
  <link rel="stylesheet" href="https://demo.thecxlabs.com/design-system/tokens/tokens.css?v=0.16.3">
  <link rel="stylesheet" href="https://demo.thecxlabs.com/design-system/components/components.css?v=0.16.3">
</head>
<body>
  <button class="btn btn-primary">Add to cart</button>
</body>
</html>

Loading from the deployed showcase is fine for prototypes and internal demos but should not be the strategy for production. Self-host the files (or vendor them into your project) for production. See the integration guides for that.

Where things live

Project layout, top-down.

design-system/
├── tokens/
│   ├── primitives.json    Source: raw values (color.blue.700, spacing.4)
│   ├── semantic.json      Source: meaning aliases (brand.default, surface.subtle)
│   ├── components.json    Source: button.brand.bg, product-card.badge-oem-bg
│   ├── tokens.css         BUILT — drop-in CSS custom properties
│   ├── tokens.scss        BUILT — SCSS variables for Stencil partials
│   ├── tokens.tailwind.css BUILT — Tailwind v4 @theme block
│   ├── tokens.tailwind.js BUILT — Tailwind v3 theme config
│   └── tokens.figma.json  BUILT — Tokens Studio import
├── components/
│   ├── components.css     The canonical Caster CSS implementation
│   ├── _showcase.css      Showcase chrome (NOT part of DS)
│   ├── _showcase.js       Sidebar nav, copy-to-clipboard, syntax hl
│   ├── index.html         Component browser
│   ├── foundations/       Color, typography, spacing showcase pages
│   ├── primitives/        Button, pill, stock-badge, ...
│   └── composites/        Product card, machine card, ...
├── docs/                  You are here
├── build/                 Style Dictionary build pipeline
│   └── style-dictionary.config.mjs
├── decisions.md           Reconciliation log — every judgment call
├── README.md              Top-level overview
└── index.html             Landing page

What to actually consume

Each file's role at a glance.

If you want to…	Consume	How
Use Caster components in HTML	tokens.css + components.css	`<link rel="stylesheet">` both
Use Caster tokens only (no components)	tokens.css	`<link rel="stylesheet">` + write your own CSS using `var(--caster-*)`
Use Caster in Stencil partials	tokens.scss	`@import "caster/tokens";` in your theme.scss
Use Caster in Catalyst (Tailwind v4)	tokens.tailwind.css	`@import` at top of `app/globals.css`
Use Caster in Tailwind v3	tokens.tailwind.js	Spread into `theme.extend` in `tailwind.config.js`
Use Caster tokens in Figma	tokens.figma.json	Tokens Studio plugin → Import

Quick FAQ

Do I need to run any build to use Caster?

No. The built outputs (tokens.css, etc.) are committed to the repo. You only run the build if you're changing tokens — see the build README.

Why is btn-primary gold and btn-brand blue? That's backwards.

It is — most systems use "primary" for the brand color. Caster preserves the existing prototype convention where primary = highest-emphasis CTA (the gold "Add to cart" button) and brand = brand-blue solid. See D19 in the decisions log.

Where's dark mode?

Out of scope for v1. The token structure supports adding it later (semantic aliases would gain dark variants), but B2B distributor sites typically don't need it. Revisit if a use case emerges.

Can I use Caster in something other than USA Clean?

Yes — the token + build architecture is reusable. The brand colors and component compositions are USA-Clean-specific, but the tier system, build pipeline, and component patterns translate to any B2B site. To rebrand, replace primitives, then run the build.