Core Concepts
A quick rundown of the main ideas in Bezel before you dig in.
Design tokens
A design token is just a named value for a design decision. Instead of hardcoding #16A34A in fifty places across your codebase, you define one token called color.success.500 and use that name everywhere. When the color needs to change, you change it once.
Tokens can represent colors, sizes, spacing, font families, font weights, animation durations, and more.
Token types
Every token has a type that tells the app (and any downstream tools) what kind of value it is.
| Type | What it's for |
|---|---|
| Color | Hex, RGB, or other color values |
| Dimension | Sizes, spacing, radii, anything measured in px or rem |
| Font Family | Font stack names |
| Font Weight | Numeric or named weights like 400, 700, or Semi |
| Duration | Animation and transition times |
| Number | Plain numbers with no unit |
Groups
Tokens live inside groups, which work like folders. They show up as a collapsible tree in the side nav under the Tokens tab, and can be nested as deep as you need.
Most projects split tokens into two layers:
- Base tokens — the raw palette, like every shade of a color from 50 to 900
- Semantic tokens — tokens that point to base tokens and describe their role, like
color.successreferencingcolor.green.500
Contexts and themes
A context is a named variant of your token values. Every project starts with one called $root, shown in the app as $root (default). You can add more (like light and dark) and then override specific tokens per context without touching the base values.
When you switch to a non-root context, the token table shows a Default Value column next to a Value column. Leave the value blank and the token inherits from $root. Set one and it overrides. That's the whole system.
Design mode
The Design tab holds nine guided workflows for setting up the common parts of your token system, grouped into Color, Typography, Border, and Spacing. Rather than typing raw values yourself, you get sliders, presets, and pickers that generate the tokens for you.
Design mode needs a plan that includes AI credits.
Publishing and exporting
Three ways to get your tokens out:
- Download — grabs the current project state as a
design-tokens.jsonfile, right now, no version attached - Publish a release — creates a versioned snapshot like
v0.1.0with release notes, which anyone can come back to and download later - The MCP server — hands your tokens straight to a coding agent, always current
See Versions & Releases and MCP Server for more.