Documentation

Key Concepts

ReframeUI is built around a small set of concepts that work together. Whether you're a brand guardian keeping a design system consistent, an engineer shipping to multiple platforms, or a team managing multiple design systems, these are the building blocks.

Design tokens vs components

Design tokens are the raw, named values that make up your visual language: colors, spacing, radii, shadows, typography. In ReframeUI, tokens are stored in the W3C DTCG JSON format, which means they're compatible with any tooling that understands that standard.

Components are reusable UI elements that consume those tokens. You build them in Studio from scratch, configuring layout (icons, labels, slots), behavior (event handlers, state), and all visual properties. Every component you create works across all supported platforms, so you define it once and use it everywhere.

Both matter. Tokens alone give you variables; components alone hard-code values. Together, they give you a full, living design system: change a token and every component that references it updates immediately.

Token modes

A mode is a named variant of your full token set. You create modes yourself, for example light, dark, or high-contrast. Each token has a value per mode.

To add a custom mode (e.g. high-contrast), go to Token Settings → Modes → Add Mode. You then set a value for every token in that mode.

The CDN endpoint returns a CSS @layer for each mode, activated with a data-theme attribute on any ancestor element:

index.htmlhtml
<!-- Light mode (default) -->
<html data-theme="light">

<!-- Dark mode -->
<html data-theme="dark">

<!-- Custom high-contrast mode -->
<div data-theme="high-contrast">
  <!-- All children use high-contrast token values -->
</div>

Token aliases

Tokens can reference other tokens by name. This is how you build a semantic layer on top of raw base values: instead of scattering hex codes across your components, you define meaning once and let every component reference that meaning.

A base token like color.blue.500 holds a raw hex value. A semantic token like color.interactive.default aliases it using double-brace syntax. Every component that references color.interactive.default updates automatically the moment you change what it aliases. No find-and-replace, no manual propagation.

Token alias exampletext
// Base
color.blue.500 = #2563eb

// Semantic: aliases the base token
color.interactive.default → {{color.blue.500}}

// Result: changing color.blue.500 ripples to every component using color.interactive.default

Branching

main is your production branch. It hosts the live CDN endpoint (…/latest/tokens.css) and the current npm package version. Every app consuming your design system is always on main.

Creating a branch gives you an isolated preview endpoint and a preview npm tag (@org/design-system@branch-name). Share the preview URL with stakeholders, or point a staging environment at the preview tag. Test fully before anything goes live.

Merging to main publishes a new production version. Deleting a branch is safe. Preview endpoints are cleaned up automatically.

For brand guardians (Stewards): Branches let you test a full rebrand (new primary color, new type scale) without touching the live system. Only promote when you're confident.
Free plan: No branching. Changes go directly to main and are live immediately. Upgrade to Team or Agency for preview branches.

Versioning

ReframeUI follows semantic versioning. The type of change you make determines the version bump:

  • patch1.0.0 → 1.0.1: Token value tweaks, no breaking changes.
  • minor1.0.0 → 1.1.0: New tokens or components added. Fully backwards-compatible.
  • major1.0.0 → 2.0.0: Token renamed or removed, component API breaking change.

ReframeUI detects breaking changes automatically and warns you before you publish, so you never accidentally ship a major as a patch.

Component customization

Every component in your design system has configurable slots, variants, and properties, all set in Studio's component editor. Slots control structure: does the button include a leading icon? A trailing chevron? Variants control visual style: primary, secondary, ghost. Properties control behavior: disabled state, loading state, size.

The choices you make in the component editor are reflected directly in the typed props exported from the npm package. The TypeScript interface always matches exactly what you configured. If a variant doesn't exist in Studio, it won't exist in the type, and your editor will catch any mismatch at compile time.

CDN endpoint vs npm package

There are two ways to consume your design system:

CDN endpoint

A <link> tag pointing to your live token endpoint. Zero install, great for prototypes, static sites, CMS-embedded HTML, or any context where you only need CSS variables. Updates automatically on every publish.

npm package

Install @org/design-system and import typed React, Vue, or Angular components. Auto-published on every merge to main. Best for production apps with TypeScript, build pipelines, and tree-shaking.

CDN usagehtml
<!-- Drop into any HTML, no build step needed -->
<link rel="stylesheet" href="https://cdn.reframeui.io/acme/design-system/latest/tokens.css" />
<script type="module" src="https://cdn.reframeui.io/acme/design-system/latest/design-system.js"></script>

<ds-button variant="primary">Deploy now</ds-button>

Next steps

Ready to integrate your design system into a framework? Start with React.

React Integration →