---
name: beam-ui
description: Use when the user requests UI work (build, modify, refactor, debug, compose components or pages) or asks a design-system question (which component, which token, how to do X) in a project that depends on @viasat/beam-react. The user need not mention Beam — if @viasat/beam-react is installed, all UI work belongs to Beam.
disallowed-tools: WebFetch
---

# beam-ui

Beam isn't in your training data — never write Beam code from memory. Fetch the live API, then build. Canonical rules live in `references/rules-preamble.md`.

## Activation gate

Read `package.json`. If `@viasat/beam-react` is not in `dependencies` or `devDependencies`, skip this skill.

## Load canonical rules

Read `references/rules-preamble.md` before acting — source-of-truth hierarchy, token rule, composition rule, honesty rule, curl-not-WebFetch directive. It links `references/data-sources.md` (fetch procedure + URL patterns) and `references/tokens.md` (token taxonomy + lookup); follow those when relevant.

## MCP tools (beam server)

See `references/data-sources.md` § MCP server for the tool catalog and call order.

## Posture: BUILD vs ASK

- **BUILD** — request requires writing/modifying files (build, add, create, modify, refactor, fix, debug, implement).
- **ASK** — request is a question or recommendation (how, what, should, why, which, can I).
- **In doubt → ASK.** End with: _"I can build this — say 'yes, build it' to proceed."_

## Checklist (each → a TodoWrite todo)

0. **Verify project wiring (BUILD only).** Skip entirely on ASK. Grep project source (exclude `node_modules/`, `dist/`, `build/`, `.next/`, `out/`, and lockfiles) for `@viasat/beam-tokens/styles.css` and a `@viasat/beam-fonts` stylesheet import. Framework detect: `next` in `package.json` deps → Next.js; Vite/CRA → CSR; else → ambiguous, prompt the user, do not guess. **Wiring OK:** CSR = tokens import + `@viasat/beam-fonts/styles.css` (not the `.nextjs` variant); Next.js = tokens import + `@viasat/beam-fonts/styles.nextjs.css` + a `postinstall` font-copy script in `package.json`. On OK: emit `wiring OK` and continue. On missing / wrong variant / (Next.js) missing postinstall: alert the user what's wrong and ask **once** for approval to auto-remediate — do **not** edit anything before approval. On approval: fetch `getConcept('getting-started')` (if MCP is unavailable, fall back to `curl -fsSL https://react.beam.viasat.com/llms/getting-started.txt` per `references/data-sources.md`) and apply the correct variant from it (do not hand-author snippets) — add tokens import if missing; add/replace the correct fonts import for the framework; Next.js also add the `postinstall` script to `package.json` and tell the user to run `npm install` (skill does not run it). Insertion: CSR → root entry (`index.tsx`/`index.ts`, else `main.tsx`/`main.ts`, else `App.tsx`); Next.js pages-router → `_app.tsx`/`_app.js`; app-router → `layout.tsx`. If the root entry can't be confidently located, prompt the user. After wiring, surface exactly what changed. On decline or unresolved ambiguity: state that fonts/styles may silently fall back to system fonts; proceed only as the user directs. _Accepted limitation: grep confirms an import exists in source, not that it's in the bundled/executed path._
1. **Plan.** BUILD: component tree, composition rule, expected tokens. ASK: list components/concepts to look up (cap ~5).
2. **Gather.** Try MCP first: `listComponents` to discover, `getComponent` for props/story index, `getComponentStory` for usage examples. For any component that manages state across a tree (Toast, Dialog, Popover, Select, Menu, Stepper, SideNav), check `getComponent`'s `pairedHooks` and read those hook/provider signatures before writing code, because the hook is the API and props alone produce broken usage. When `getComponent` returns a `usageGuidelines` field, read it before writing code — it carries the intended usage (purpose, when to use vs. avoid, dos & don'ts) over raw props and stories. If `pairedHooks` is absent but the component lists subcomponents (like `Dialog.Trigger` or `Select.Option`), build with those subcomponents. Only grep node_modules for sibling `useX`/`Provider` exports when there are no `pairedHooks` and no subcomponents (see `references/data-sources.md` § Paired hooks). If MCP unavailable, tell the user: "The Beam MCP server is unavailable, falling back to llms.txt. If you weren't expecting this, please report it in **#beam-help**." Then fall back to curl llms.txt (index then specific pages). If llms.txt unreachable, fall back to node_modules `.d.ts` files. If all fail, apply the honesty rule: stop, don't fabricate.
3. **Token check (BUILD).** Fetch the relevant `Tokens/*` concept via MCP first — `getConcept('tokens-color')`, `getConcept('tokens-space')`, etc. — then look up every color/dimension/font per `references/tokens.md`. Zero violations.
4. **Produce.** BUILD: names/props/imports from Step 2's fetched data only; styling values are tokens (or `rem`). ASK: every claim cites its MCP or llms.txt source.
5. **Self-check.** Names/props/imports match fetched data; zero token violations; composition matches the plan; required global CSS imports present (tokens + framework-correct fonts; Next.js also postinstall) — Step 0 passed or was remediated. If MCP and llms.txt were both unreachable, apply the honesty rule.
6. **Report.** BUILD: components/tokens/files touched + suggest `/beam-audit-tokens`; wiring status (`wiring OK`, or what was wired + what the user still needs to run). ASK: the cited answer is the report.

## Red flags — STOP and re-check

| Rationalization                                 | Reality                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| "Skip the fetch — Button is obvious"            | Beam evolves between releases; remembered props are stale. Fetch.                                                |
| "User said the prop is `variant` — just use it" | User assertions are hypotheses, not data. Verify against the fetch.                                              |
| "Close enough" prop name                        | Wrong prop = silent runtime failure or rejected PR. Match the schema exactly.                                    |
| "Use `#FF0000` for now, tokenize later"         | Stop. Ask for the right token; "for now" never gets fixed.                                                       |
| "WebFetch is faster than curl"                  | WebFetch summarizes — you lose exact URLs and prop strings. Use curl.                                            |
| "MCP is running but curl is faster"             | MCP returns structured data with guaranteed parity. Don't skip it for raw text.                                  |
| "Question, but they obviously want code"        | Default to ASK; end with the switch-to-BUILD prompt. Don't write files without an explicit BUILD request.        |
| "node_modules has it, skip the fetch"           | MCP and llms.txt have descriptions/examples the `.d.ts` files lack. Try them first; node_modules is last resort. |
| "ToastContainer takes toasts as children/props" | Context-driven components are driven by a hook. Check `pairedHooks` and read `useToast` before writing. Props-only is the canonical broken pattern. |
| "Components render, typography looks wrong"     | The fonts stylesheet (or Next.js `postinstall`) isn't wired; a missing/`@font-face`-less import falls back to system fonts silently. Run the Step 0 wiring check. |

## Not in scope

Filesystem audit (use `/beam-audit-tokens`), test generation, Storybook authoring, visual design judgment, screenshot or Figma input, Figma write-back.