# Beam tokens (procedure reference)

Taxonomy and lookup procedure for Beam tokens. Does NOT enumerate token values — fetch them at runtime from the MCP server's `Tokens/*` concept docs (primary) or the deployed `llms.txt` Tokens section (fallback).

For the full source-of-truth hierarchy, see `references/rules-preamble.md` and `references/data-sources.md`.

## Token taxonomy

Author UI with these three classes, chosen by intent.

### Semantic

Tokens that encode meaning, not appearance. Use these by default for any UI surface.

- Examples of intent (look up actual names): "background of the page," "color of a destructive action," "text on a primary action," "spacing between form fields."
- Rule of thumb: if you can describe the use in business or user-facing terms, it's semantic.
- Naming convention: `bm-sem-<type>-<role>-<variant>` (e.g., `bm-sem-color-surface-00`).

### Expressive

Tokens that encode brand/visual identity beyond pure semantics — accents, illustrative palettes, decorative gradients. Use these for marketing surfaces, branded sections, hero content.

- Rule of thumb: if you'd describe it as "looks Viasat-branded" rather than "indicates an error," it's expressive.

### Dataviz

Tokens for data visualization: chart series colors, axis lines, grid backgrounds. Distinct from semantic because viz palettes need perceptual distinguishability across many series.

- Rule of thumb: if it goes into a chart, table-heatmap, or similar, it's dataviz.

### Lower-level tiers (don't author against directly)

Beam also defines `primitive` (raw values), `theme` (theme-layer mappings), `comp` (component-internal), and `utility` tokens. These are valid `--bm-*` tokens — recognize them when auditing — but don't reach for `primitive`/`theme`/`comp` directly when writing UI. Author against the semantic/expressive/dataviz layer above, which resolves down to them.

## The "do not hard-code" rule

These are violations regardless of value:

- Hex literals: `#ABC123`, `#1a2`, `#abcd1234`
- `rgb()`, `rgba()`, `hsl()`, `hsla()`
- Named CSS colors except `transparent` and `currentColor` (e.g., `red`, `blue`, `aliceblue` — all forbidden)
- Raw `px` for spacing, typography, or radii — prefer a token; when no token fits, use `rem`
- Hard-coded `font-family`, `font-size`, `font-weight` when token alternatives exist

Resolution when no token fits: for **colors**, ask the user — never drop to a hex. For **dimensional values** (spacing, typography, radii), `rem` is the sanctioned fallback. Don't fabricate token names.

## Lookup procedure

### Primary (MCP)

The MCP server (auto-started with the plugin) is the source of truth for token values. There is **no dedicated token tool** — token data ships as MDX **concept docs**, one per category, served by the `getConcept` tool. Prefer this over llms.txt.

1. **Fetch by exact slug** — call `getConcept('<slug>')` with a slug from the table below (e.g. `getConcept('tokens-color')`), one call per category you need. It returns `{ title, slug, description, type, mdxContent }`; the token table lives in `mdxContent`. Each category is its own doc — there is no combined `tokens` doc, so `getConcept('tokens')` misses. Always pass a specific `tokens-<category>` slug.
2. **Discover only if unsure** — if you don't know which category fits, call `listConcepts` first, pick from the `Tokens/*` group, then fetch by that slug. Don't guess a slug that isn't in the table.

Token concept slugs by category:

| Category           | Slug                        |
| ------------------ | --------------------------- |
| Color              | `tokens-color`              |
| Space              | `tokens-space`              |
| Size               | `tokens-size`               |
| Typography         | `tokens-typography`         |
| Compact typography | `tokens-compact-typography` |
| Shadow             | `tokens-shadow`             |
| Opacity            | `tokens-opacity`            |
| Border width       | `tokens-border-width`       |
| Border radius      | `tokens-border-radius`      |

`mdxContent` carries a `| Token | Value | Description |` table for color, space, size, shadow, opacity, and both border categories; the two typography docs use `| Token | Size | Line Height |` (the token name and metrics are self-documenting).

### Fallback (llms.txt)

If MCP is unavailable, fetch the relevant token category page with `curl` (not WebFetch — see `references/data-sources.md`):

```bash
curl -fsSL https://react.beam.viasat.com/llms/tokens-color.txt
```

Each category page contains a markdown table of `| Token | Value | Description |`.

**Token categories** (from the deployed llms.txt index):

- `llms/tokens-border-radius.txt`
- `llms/tokens-border-width.txt`
- `llms/tokens-color.txt`
- `llms/tokens-compact-typography.txt`
- `llms/tokens-opacity.txt`
- `llms/tokens-shadow.txt`
- `llms/tokens-size.txt`
- `llms/tokens-space.txt`
- `llms/tokens-typography.txt`

If a category you expected isn't listed, verify against the live index (`curl -fsSL https://react.beam.viasat.com/llms.txt`) — the list above may evolve.

### Last resort (node_modules)

If both MCP and llms.txt are unreachable, the installed `@viasat/beam-tokens` package is the source. (Tokens are a separate package from `@viasat/beam-react`.)

```bash
# Type declarations
grep -E '^\s*(export )?(const|type|interface)' node_modules/@viasat/beam-tokens/types/lib/index.d.ts

# Actual values (CSS custom properties)
grep -E '^\s*--bm-' node_modules/@viasat/beam-tokens/tokens.css | head -50
```

Read JSDoc above each declaration for usage hints.

### If both fail

Stop and tell the user. Do not invent token names. See the honesty rule in `references/rules-preamble.md`.

## What NOT to do

- ❌ Invent token names from memory.
- ❌ Hard-code a hex because the closest color token isn't perfect — ask the user. (For dimensional values, `rem` is the sanctioned fallback; raw `px` is not.)
- ❌ Mix token systems (e.g., a semantic background with a hex border — pick one).
- ❌ Use `:root` CSS overrides to redefine tokens unless explicitly migrating.