USA Clean Design System

The foundation under USA Clean's web surfaces — tokens, components, and patterns. One source, many platforms.

v0.15 · Mobile chrome (hamburger nav drawer)

Developer docs

Start here

Getting started

5-minute orientation: 3-tier tokens, integration paths, the file map, quick-start example, FAQ.

v0.4
Brand

Logo & brand

Three Caster variants, color values, when-to-use, lockup rules, minimum sizes, don'ts, file reference.

v0.11
Integration

Vanilla / HTML

Plain HTML pages, prototypes, internal tools. Two stylesheets, use class names.
Integration

BigCommerce Stencil

The production target. SCSS partials, variable bridging, phased migration.
Future-state

Catalyst migration

Next.js + React + Tailwind v4. @theme import, React component patterns.
Reference

Tokens reference

Searchable, filterable list of every --caster-* token. Click to copy.
Designers

Figma setup

Step-by-step Tokens Studio plugin install + import of tokens.figma.json. Three sync patterns, troubleshooting, file hygiene.

v0.5

Component showcase

Live reference

Component browser

Foundations, primitives, composites — every component with its states, variants, and reference markup. Storybook-style, self-contained.

v0.3 ready
Foundation

Color

Brand, accent, text, surface, feedback, border tokens with WCAG contrast notes.
Primitive

Button

7 styles × 5 sizes × icon-only modifier.

Foundations

Tokens · primitives

Primitive tokens

Raw values: color scales, spacing, radii, shadows, typography primitives, motion, breakpoints. DTCG JSON.

v0.1 ready
Tokens · semantic

Semantic tokens

Meaning aliases mapping primitives to brand intent: brand.default, surface.subtle, feedback.success, etc.

v0.1 ready
Tokens · components

Component tokens

Component-specific values referencing semantic tokens. button.brand.bg, product-card.badge-oem-bg, etc.

v0.1 ready

Built outputs

CSS

tokens.css

CSS custom properties on :root, prefixed --caster-*. Drop-in for any web project.

Built
SCSS

tokens.scss

SCSS variables prefixed $caster-*. For BigCommerce Stencil and other Sass-based codebases.

Built
Tailwind v4

tokens.tailwind.css

@theme block for Tailwind v4 (Catalyst). Imports tokens directly as Tailwind theme vars.

Built
Tailwind v3

tokens.tailwind.js

Structured theme object for older Tailwind v3 setups. Bucketed into colors / spacing / fontSize / etc.

Built
Figma

tokens.figma.json

DTCG nested JSON for the Tokens Studio Figma plugin. Two-way sync between code and design.

Built
Build

How the build works

Style Dictionary config + custom formats. npm run build compiles all 5 outputs from one source.

Coming next

Phase 5

Component showcase

One page per component with all states and variants. Buttons, badges, product cards, machine cards, etc.

Up next
Phase 6

Developer docs

Stencil integration guide, Catalyst migration notes, Figma variable import workflow.

Pending
Phase 7

Figma import workflow

Step-by-step instructions for importing tokens.figma.json into Figma via Tokens Studio.

Pending

Project

Doc

README

Overview, structure, three-tier rationale, deploy targets.
Doc

Reconciliation log

Open judgment calls awaiting your sign-off before v0.2.

Awaiting review
Repo

Back to prototype

Live USA Clean prototype using the current pre-Caster CSS.

Naming

Caster

Every USA Clean machine rolls on them. Mechanical, grounded, ownable.

Use as a noun: a Caster button, the Caster tokens, the Caster theme. CSS custom properties are namespaced --caster-* to avoid collisions on BigCommerce pages with theme code or third-party widgets.