> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Understand how Humic organizes design tokens — token types, color scales, primitives, and visibility.

## 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:

| Type                 | Example key               | Example value                   |
| -------------------- | ------------------------- | ------------------------------- |
| `color`              | `color.brand.primary`     | References a color scale + step |
| `spacing`            | `spacing.page.gutter`     | `16px`, `1.5rem`                |
| `radius`             | `radius.card`             | `8px`                           |
| `font.size`          | `font.size.body`          | `16px`, `1rem`                  |
| `font.weight`        | `font.weight.bold`        | `700`                           |
| `font.family`        | `font.family.sans`        | `"Inter"`                       |
| `font.lineHeight`    | `font.lineHeight.tight`   | `1.25`                          |
| `font.letterSpacing` | `font.letterSpacing.wide` | `0.025em`                       |
| `shadow`             | `shadow.card`             | `0 1px 3px rgba(...)`           |
| `opacity`            | `opacity.disabled`        | `0.5`                           |
| `duration`           | `duration.fast`           | `150ms`                         |
| `easing`             | `easing.ease-out`         | `cubic-bezier(0.16, 1, 0.3, 1)` |
| `z-index`            | `z-index.modal`           | `100`                           |
| `boolean`            | `boolean.dark-mode`       | `true` / `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**:

| Type          | Example keys                  | Values                        |
| ------------- | ----------------------------- | ----------------------------- |
| `spacing`     | `xs`, `sm`, `md`, `lg`        | `4`, `8`, `16`, `24`          |
| `radius`      | `sm`, `md`, `lg`, `full`      | `4`, `8`, `16`, `9999`        |
| `font.size`   | `xs`, `sm`, `base`, `lg`      | `12`, `14`, `16`, `18`        |
| `font.weight` | `normal`, `medium`, `bold`    | `400`, `500`, `700`           |
| `font.family` | `sans`, `mono`                | `"Inter"`, `"JetBrains Mono"` |
| `opacity`     | `subtle`, `muted`, `disabled` | `0.8`, `0.6`, `0.4`           |
| `duration`    | `fast`, `normal`, `slow`      | `100`, `200`, `400`           |
| `z-index`     | `dropdown`, `modal`, `toast`  | `10`, `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:

| Visibility         | Who can see it                            | Use case                                  |
| ------------------ | ----------------------------------------- | ----------------------------------------- |
| **Private**        | Explicit members only                     | Internal systems, work in progress        |
| **Request access** | Anyone with the link can request access   | Cross-team systems, open to collaboration |
| **Public read**    | Everyone, including unauthenticated users | Open-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**](/export-formats/css) — Custom properties with light/dark mode support
* [**JSON**](/export-formats/json) — W3C Design Tokens Community Group format
* [**Tailwind**](/export-formats/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.