Concepts
The handful of ideas behind Stoaken, and how they relate.
Workspaces and roles
A workspace holds your Brands and the people who work on them. Each person has a role on the whole workspace or on chosen Brands:
| Role | Can |
|---|---|
| Viewer | See tokens, releases and comments. |
| Reviewer | Everything a Viewer can, plus approve or reject releases and comment. Free on every plan. |
| Editor | Edit tokens, themes and components, and propose releases. |
| Admin | Everything, plus members, webhooks and breaking-change approvals. |
| Owner | Everything, plus billing, handing the workspace over and deleting it. |
Brands
A Brand is one design system or product. A Brand can extend another in the same workspace: it inherits the parent's tokens and overrides what it sets itself, which suits sub-brands and white-label products.
Token sets
A token set is one JSON document in the W3C design tokens format (2025.10): groups, tokens with $type and $value, and aliases like {color.brand.primary}. Stoaken checks every save against the format.
Themes
A theme stacks some of a Brand's token sets in order; later sets override earlier ones where they set the same token. Every release belongs to a theme.
Modes
A theme can have axes (for example color-scheme) with modes (light, dark), one of them the default. Each mode can turn token sets on or off, so a dark mode is usually one extra set that overrides colours. A release stores the resolved tokens for every combination of modes, and exports can write one mode or all of them.
Releases and review
A release is a versioned, resolved snapshot of a theme. It moves through draft, pending approval and published (or rejected). Reviewers see what changed, what depends on it, and visual checks of your components in every mode. Breaking changes need an Admin. Only published releases reach exports, the API and agents.
Deprecation
Mark a token $deprecated (in the editor: Deprecated, with an optional replacement). It keeps working, but the Token Graph, exports and agents flag it and point at the replacement, so you can retire it safely.