Skip to main content

​
Design tokens

A design token is a named value that represents a design decision. Instead of hardcoding #36AA08 in your components, you use a token like color.brand.primary that resolves to the right value for each platform and theme. Humic stores tokens with a dot-notation key (e.g., spacing.page.gutter) and a type that determines how the value is structured and exported.

​
Token types

Humic supports 14 token types:
TypeExample keyExample value
colorcolor.brand.primaryReferences a color scale + step
spacingspacing.page.gutter16px, 1.5rem
radiusradius.card8px
font.sizefont.size.body16px, 1rem
font.weightfont.weight.bold700
font.familyfont.family.sans"Inter"
font.lineHeightfont.lineHeight.tight1.25
font.letterSpacingfont.letterSpacing.wide0.025em
shadowshadow.card0 1px 3px rgba(...)
opacityopacity.disabled0.5
durationduration.fast150ms
easingeasing.ease-outcubic-bezier(0.16, 1, 0.3, 1)
z-indexz-index.modal100
booleanboolean.dark-modetrue / false

​
How color tokens work

Color tokens don’t store raw hex values. Instead, they reference a color scale and a step within that scale. This means changing a scale automatically updates every token that references it. A color token stores:
  • Scale — which color scale (e.g., brand, neutral)
  • Step — which step in the light scale (e.g., 500)
  • Dark step — optionally, a different step for dark mode

​
Color scales

A color scale is a named palette with numbered steps. Each step has a light and dark hex value, giving you automatic dark mode support. 
brand
  ├── 50   → light: #F0FDE8  dark: #0A1F04
  ├── 100  → light: #DCFACC  dark: #153B0A
  ├── 200  → light: #BAF59B  dark: #1E5B0F
  ├── ...
  ├── 800  → light: #1E5B0F  dark: #BAF59B
  └── 900  → light: #0A1F04  dark: #F0FDE8
When you export tokens, the export layer resolves the scale reference to the actual hex value for each theme.

​
Primitives

Primitives are the raw foundation values of your design system — the base spacing scale, font sizes, border radii, and other numeric values that tokens can reference. Think of primitives as your system’s building blocks:
TypeExample keysValues
spacingxs, sm, md, lg4, 8, 16, 24
radiussm, md, lg, full4, 8, 16, 9999
font.sizexs, sm, base, lg12, 14, 16, 18
font.weightnormal, medium, bold400, 500, 700
font.familysans, mono"Inter", "JetBrains Mono"
opacitysubtle, muted, disabled0.8, 0.6, 0.4
durationfast, normal, slow100, 200, 400
z-indexdropdown, modal, toast10, 50, 100
Tokens can reference primitives instead of storing literal values. When you update a primitive, every token that references it updates automatically.

​
Design systems

A design system is a collection of tokens, color scales, and primitives. One organization can have multiple design systems — for example, a brand system for the marketing site and a product system for the app.

​
Visibility

Each design system has a visibility setting that controls who can access it:
VisibilityWho can see itUse case
PrivateExplicit members onlyInternal systems, work in progress
Request accessAnyone with the link can request accessCross-team systems, open to collaboration
Public readEveryone, including unauthenticated usersOpen-source design systems, documentation

​
Roles

Access is controlled at two levels: Organization level:
  • Admin — full access, manages members and billing
  • Member — sees public and request-access design systems
Design system level:
  • Editor — create and edit tokens, manage API keys (paid seat)
  • Viewer — read and export only (free)
  • Guest — same as viewer, but without org-level visibility

​
Export

Humic stores token values in a platform-agnostic format. The export layer transforms them into the format you need:
  • CSS — Custom properties with light/dark mode support
  • JSON — W3C Design Tokens Community Group format
  • Tailwind — Theme configuration for tailwind.config.ts
  • Figma — Variables API format with collections and modes
  • TypeScript — Typed constant with autocomplete support
The same export logic runs everywhere — whether you pull via the CLI, call the API, or sync from the UI. The output is always identical.