# Beam rules (canonical preamble)

## What Beam is

Beam is Viasat's production multi-framework design system: React components (`@viasat/beam-react`), tokens (`@viasat/beam-tokens`), icons, fonts, and styles. It is opinionated about composition and tokens. It is not a CSS framework and not a wrapper around any third-party UI library. Beam's component API surface is large and evolves between releases — your training data does not include it.

## Source-of-truth hierarchy

Use these data sources in order; never skip a tier upward:

1. **MCP server (beam)** — PRIMARY. Structured JSON, offline-capable, auto-started by plugin.
2. **Deployed `llms.txt`** (`https://react.beam.viasat.com/llms.txt`) — fallback when MCP unavailable. Fetch with `curl`, never the WebFetch tool (it summarizes and drops the exact URLs and prop strings you need).
3. **Local `node_modules/@viasat/beam-react`** (+ `@viasat/beam-tokens` for tokens) TypeScript definitions — fallback when llms.txt is also unreachable.
4. **Model knowledge** — forbidden. Beam is not in your training data. Never fabricate component names, prop names, or token values from memory.

See `references/data-sources.md` for the full procedure (MCP tools, curl usage, index structure, node_modules paths across npm/yarn/pnpm, fidelity caveats).

## Core rules

### Token rule

Never hard-code design values:

- No hex colors (`#ABC123`)
- No `rgb()` / `rgba()` / `hsl()` / `hsla()` literals
- No named CSS colors (except `transparent` and `currentColor`)
- For spacing, typography, or radii: use a token; if none fits, fall back to `rem` — never raw `px`
- No hard-coded `font-family`, `font-size`, or `font-weight` literals when token alternatives exist

See `references/tokens.md` for the taxonomy and lookup procedure.

### Composition rule

Prefer composing existing Beam components over creating new ones or "doing your own thing." When composition can't reach what you need, build custom from Beam primitives + tokens — never from scratch. If the gap is library-shaped (multiple consumers would benefit, pattern is stable), flag it as a candidate for a new Beam component and ask the user before writing custom code.

### Honesty / uncertainty rule

If llms.txt is unreachable AND `node_modules/@viasat/beam-react` does not contain the answer, stop and tell the user. Do not invent component names, prop names, import paths, or token values. Saying "I don't know" is better than fabricating.