The swift-web Design Language
Whether you work in Figma or Claude Design, you are using the same design language. This page explains its three parts: semantic tokens (the naming system for colors / radii / shadows / typography), component forms (which ready-made components the framework provides and what they look like), and the right workflow for building a color scheme for a new site.
Semantic tokens: a naming system for design decisions
Every visual decision in swift-web converges into a set of semantically named variables (known in the industry as design tokens). "Semantic" means the name describes the purpose, not the color value — --primary means "the brand's primary color," not "blue." When the brand changes, you change the variable's value, and everything that uses it follows automatically.
The core tokens a designer should know (full list in Styling & Tokens):
| Category | Tokens | Meaning |
|---|---|---|
| Base | --background / --foreground | Page background / body text |
| Text hierarchy | --foreground-soft / --muted-foreground | Softened body text / auxiliary caption text (a three-level text hierarchy) |
| Brand | --primary / --primary-foreground | Primary color / text color on top of it |
| Brand gradient | --gradient-brand | Brand gradient (CTA buttons etc.; degrades to the solid primary color by default) |
| Cards | --card / --card-foreground | Card background / text on cards |
| Subdued fills | --muted / --secondary / --accent | Backgrounds for secondary blocks |
| Semantic colors | --destructive / --success / --warning / --info | Danger / success / warning / info |
| Lines & focus | --border / --input / --ring | Borders / input borders / focus ring |
| Shape | --radius / --shadow-sm·md·lg | Radius baseline / three shadow levels |
| Layout | --nav-height / --container-padding / --content-max-width | Nav height / container padding / max content width |
Three things to keep in mind when reading them:
*-foregroundpairing. Every "background" token has a paired "text color" token (--primary↔--primary-foreground). If your design keeps each pair's contrast up to standard, the code side can never produce "dark text on a dark background."- Two value sets, light and dark. Every color token has one value for the light theme and one for the dark theme; switching themes just swaps the whole set — if a design needs a dark version, what changes is, again, only token values.
- Naming follows industry convention (Shadcn style). Designers and AI tools familiar with mainstream design systems can read it at zero cost.
Component forms: the 20-card catalog
The design resources are currently consolidated into 20 preview cards (they constitute the design system on the Claude Design side; the Figma component library is being built from the same catalog). Each card's CSS is taken directly from the framework component source — what the card looks like is exactly what the live component looks like:
| Group | Cards | Contents |
|---|---|---|
| Tokens (3 cards) | Colors / Typography / Shape & Layout | Semantic palette (with both light and dark values) / font stack, links and focus / radius · shadows · layout variables |
| Base components (9 cards) | Button / Segmented / Select / Modal / Toast / Pagination / Breadcrumb / FormField / Table | Buttons / option groups / dropdown select / modals / toasts / pagination / breadcrumbs / form fields / data tables |
| Content components (8 cards) | Image / Rail / Carousel / Gallery / Ads / Player / Upload / Editor | Images / horizontal rails / carousels / grid galleries / the ad slot family / players / upload / rich-text editor |
One important note: some cards carry the label "reference implementation (not built into the framework)" — for example, colored button variants or the visual styling of form field inputs. This means the framework deliberately does not build in those styles (they are left for the business layer to customize), and the card shows the recommended way to draw them with semantic tokens. Designers can use them as-is or redesign them — as long as the result stays within the token vocabulary.
Full-width live previews of all 20 cards, with per-card notes (what each card shows, how to use it while designing, how to call it by name when drafting with AI) live on their own page: Design Cards Reference — browse it as a form dictionary before designing; it is far more tangible than the table above. The downloadable bundles (Claude Design / Open Design flavors) are on that page too.
For the full capabilities of framework components (props, events, interaction details), see the component overview; designers usually only need to recognize the forms and never have to read the API.
Building a color scheme for a new site: the right workflow
This is the question designers ask most: "The design system ships with default colors / some existing brand's colors — I'm designing a brand-new site, so how do I switch to my own palette?"
The answer is where this system shines the most: changing the color scheme = overriding the values of a dozen-odd semantic tokens. Components hard-code no colors; they only reference tokens — redefine --primary, --background, and the rest of the set, and every component re-dresses itself automatically. No element-by-element edits.
Recommended workflow (using Claude Design as the example; editing the Variables collection in Figma works the same way):
- Start your draft from the base design system (neutral defaults) and focus on structure and layout first.
- Adjust colors at the token layer. Tell the AI your intent — "switch the primary to a dark-red-and-gold scheme, luxurious dark mood overall" — or give concrete values. The key constraint: adjustments happen on semantic tokens, not as scattered color picks inside the draft. One token change propagates through the entire draft — that's both efficiency and the precondition for landing in code later.
- Iterate until satisfied and produce the final draft.
- Deliver a "brand token list": collect the finalized token values (
--primary: #xxx,--background: #xxx… usually 15–25 entries) into a list and hand it to the frontend team / framework maintainers. - The maintainers land it in one step: from that list they generate two things — a dedicated design system for that brand (for future design reuse) and the project's brand override stylesheet (the rebrand on the code side). Design resources and code update from the same source: deliver once, both sides take effect.
An intuitive way to think about it: the brand token list is the contract between design and code. Freedom within the list (any values you like) belongs entirely to the designer; scattered colors outside the list never enter the contract, and will be lost or normalized at implementation time. Brand-specific colors that semantic tokens can't cover (a VIP gold family, badge colors) are simply listed as supplementary entries — the code side has a matching extension mechanism (the
--brand-*namespace).
The brand variant mechanism
Design systems are layered by brand: a base (the framework's neutral defaults, for new projects and exploration) plus brand variants (one per business brand, generated by injecting that brand's tokens into the base cards). When designing a new page for an existing brand, pick its brand variant — colors and component forms match production exactly. When designing a brand-new site, start from the base and follow the color workflow above.
Brand variants are generated by the maintainers' automated pipeline (they are not hand-maintained copies). When you need a new brand variant, contact the framework maintainers and provide the brand token list — that's all it takes.
Related links
- Styling & Tokens — the complete token list and how it's consumed on the code side
- Component overview — capability docs for all framework components
- Theme system — how light/dark themes relate to tokens
- Standards and governance — token-layer color discipline and the brand onboarding process