@viasat/beam-react-claude-plugin 2.39.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "beam",
+  "description": "Beam Design System plugins for Claude Code.",
+  "owner": {
+    "name": "Viasat",
+    "url": "https://git.viasat.com/vega/beam"
+  },
+  "plugins": [
+    {
+      "name": "beam-react-claude-plugin",
+      "description": "Reduce AI hallucinations on Beam Design System usage. Ships skills for build/audit/Q&A workflows plus reference docs, and launches the Beam MCP server via npx.",
+      "source": {
+        "source": "npm",
+        "package": "@viasat/beam-react-claude-plugin"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "beam-react-claude-plugin",
+  "displayName": "Beam React Claude Plugin",
+  "description": "Equips AI tools with Beam Design System context for building, auditing, and answering implementation questions across tokens, components and data sources in React.",
+  "version": "2.39.0",
+  "author": {
+    "name": "Viasat",
+    "url": "https://git.viasat.com/vega/beam"
+  },
+  "homepage": "https://git.viasat.com/vega/beam/tree/master/libs/react-claude-plugin",
+  "license": "MIT",
+  "mcpServers": {
+    "beam": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@viasat/beam-react-mcp@2.39.0"
+      ]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,78 @@
+# 🤖 @viasat/beam-react-claude-plugin
+
+A Claude Code plugin that keeps Claude honest about the Beam Design System. Instead
+of guessing component names, props, and tokens, Claude pulls them from Beam's own
+sources.
+
+## ✨ What it does
+
+Inside any project that depends on `@viasat/beam-react`, the plugin adds:
+
+| Skill     | Type         | Purpose                                                                                                              |
+| --------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `beam-ui` | Auto-invoked | Build, modify, refactor, or debug UI using Beam components — and answer questions or give recommendations about Beam |
+
+Each skill carries a short critical-rules block (the source-of-truth hierarchy,
+token rules, and composition rules) and defers to
+`references/rules-preamble.md` for the full procedure. The plugin also runs the
+Beam MCP server via `npx`, which gives Claude structured tool access to component
+props, stories, and concept docs.
+
+## ⬇️ Installing it
+
+### 🏢 Via Beam internal Claude plugin marketplace
+
+On VPN, add the Beam repo as a marketplace:
+
+```bash
+/plugin marketplace add git.viasat.com/vega/beam
+/plugin install beam-react-claude-plugin
+```
+
+### 📦 Via npm
+
+Off VPN, install from npm and add the bundled marketplace:
+
+```bash
+npm install --save-dev @viasat/beam-react-claude-plugin
+/plugin marketplace add ./node_modules/@viasat/beam-react-claude-plugin
+/plugin install beam-react-claude-plugin@beam
+```
+
+## 🔄 Updating
+
+### 🏢 Via Beam internal Claude plugin marketplace
+
+To update on VPN use:
+
+```bash
+/plugin update beam-react-claude-plugin
+```
+
+Restart Claude Code
+
+### 📦 Via npm
+
+Off VPN, update the npm package and then the marketplace:
+
+```bash
+npm i @viasat/beam-react-claude-plugin@latest
+/plugin marketplace update beam
+```
+
+Restart Claude Code
+
+## 🖥️ Non Claude Code users
+
+On a different editor? The MCP runs on its own, no plugin required — see
+[`@viasat/beam-react-mcp`](https://www.npmjs.com/package/@viasat/beam-react-mcp).
+
+## ✅ Requirements
+
+- A project with `@viasat/beam-react` in `package.json` dependencies (skills check this before activating).
+- Node.js and npm/npx available to run the `@viasat/beam-react-mcp` server (primary).
+- Network access to `https://react.beam.viasat.com/llms.txt` (fallback when the MCP server is unavailable).
+
+## 📄 License
+
+MIT. © Viasat.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@viasat/beam-react-claude-plugin",
+  "version": "2.39.0",
+  "description": "Claude Code plugin that reduces AI hallucinations on Beam usage. Ships skills, reference docs, and a user-invocable token audit command.",
+  "license": "MIT",
+  "author": "Viasat",
+  "homepage": "https://react.beam.viasat.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://git.viasat.com/vega/beam",
+    "directory": "libs/react-claude-plugin"
+  },
+  "bugs": {
+    "url": "https://git.viasat.com/vega/beam/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "design-system",
+    "beam",
+    "viasat"
+  ],
+  "files": [
+    ".claude-plugin/",
+    "skills/",
+    "references/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/data-sources.md

@@ -0,0 +1,120 @@
+# Data sources for the Beam Claude Plugin
+
+How the plugin's skills fetch authoritative Beam information at runtime.
+
+## Source-of-truth hierarchy
+
+Use these in order. Never skip upward.
+
+1. **MCP server (beam)** — PRIMARY. Structured JSON, offline-capable, auto-started by plugin.
+2. **Deployed `llms.txt`** at `https://react.beam.viasat.com/llms.txt` — fallback when MCP server unavailable.
+3. **Local `node_modules/@viasat/beam-react`** (and `@viasat/beam-tokens` for tokens) TypeScript definitions — fallback when llms.txt is unreachable.
+4. **Model knowledge** — forbidden.
+
+## MCP server
+
+The `@viasat/beam-react-mcp` server provides structured, offline access to Beam component APIs, props, usage examples, and concept docs. It is auto-started by the plugin via the `mcpServers` config in `plugin.json`.
+
+Data comes from `beam-manifest.json`, bundled in the npm package. Zero network calls at runtime.
+
+## Fetching llms.txt (fallback) — use curl, not WebFetch
+
+When MCP is unavailable, fall back to llms.txt. **Use `curl` via Bash. Do NOT use the WebFetch tool.** WebFetch refuses to reproduce content verbatim and returns a summarized/categorized rewrite, which destroys the exact URLs, prop names, and descriptions you need. `curl` returns the raw markdown intact.
+
+```bash
+curl -fsSL https://react.beam.viasat.com/llms.txt
+```
+
+The `-f` flag makes curl exit non-zero on HTTP errors (4xx/5xx) so failures are detectable.
+
+### Index structure
+
+The index page is a flat list of links per section. Each entry has a URL and a one-line description. Always fetch the index first to discover what exists, then fetch only the specific pages you need.
+
+URL patterns:
+
+| Section    | URL pattern                  | Example                                          |
+| ---------- | ---------------------------- | ------------------------------------------------ |
+| Components | `llms/components-<name>.txt` | `llms/components-button.txt`                     |
+| Forms      | `llms/forms-<name>.txt`      | `llms/forms-autocomplete.txt`                    |
+| Layout     | `llms/layout-<name>.txt`     | `llms/layout-pagelayout.txt`                     |
+| Concepts   | `llms/concepts-<name>.txt`   | `llms/concepts-theming.txt`                      |
+| Tokens     | `llms/tokens-<category>.txt` | `llms/tokens-color.txt`, `llms/tokens-space.txt` |
+
+Sub-components use a flattened slug: `Avatar.Group` → `components-avatar-avatar-group.txt`, `Menu.Trigger` → `components-menu-menu-trigger.txt`. Confirm the exact slug from the index.
+
+**Examples pages:** some — not all — components have a companion examples page at `llms/components-<name>-examples.txt` (e.g. `components-actionlist-examples.txt`, `components-menu-examples.txt`). Don't assume it exists for a given component — check the index entry first. If no entry, there is no examples page; rely on the main component page.
+
+Particularly relevant: **`llms/concepts-using-beam-with-ai.txt`** — the official Beam guide on AI consumption of llms.txt. Read it once to ground all AI-driven work in Beam.
+
+If a section or page is missing from the index, do not assume it exists. Be defensive about parsing.
+
+## node_modules fallback
+
+When both MCP and llms.txt are unavailable, read the installed packages' TypeScript definitions.
+
+### Locating the packages
+
+| Layout             | Path                                                                       |
+| ------------------ | -------------------------------------------------------------------------- |
+| npm / yarn classic | `node_modules/@viasat/beam-react/`                                         |
+| pnpm               | `node_modules/.pnpm/@viasat+beam-react@*/node_modules/@viasat/beam-react/` |
+| yarn berry (PnP)   | No flat layout — ask the user                                              |
+
+Same patterns for `@viasat/beam-tokens`.
+
+### Which files matter
+
+**`@viasat/beam-react`:**
+
+- `index.d.ts` — top-level barrel exports. Discover what components exist.
+- `lib/<Component>/<Component>.d.ts` — actual prop types with JSDoc descriptions on each prop (mirrors the prop descriptions in llms.txt).
+- `lib/<Component>/index.d.ts` — sub-barrel for the component.
+- `lib/<Component>/<Component>.figma.d.ts` — Code Connect metadata (rarely needed).
+
+**`@viasat/beam-tokens`** (separate package):
+
+- `types/lib/index.d.ts` — token type declarations (entry point).
+- `tokens.css`, `tokens.scss` — the actual token values as CSS custom properties / SCSS variables.
+- `themes/` — per-theme overrides.
+
+### What's extractable vs missing
+
+| Available from node_modules                            | Missing                                |
+| ------------------------------------------------------ | -------------------------------------- |
+| Component names and types                              | Story / usage examples                 |
+| Prop names, types, defaults, JSDoc descriptions        | Visual screenshots                     |
+| Token declarations and raw values (from `beam-tokens`) | MDX concept docs (theming, a11y, etc.) |
+
+## Fidelity caveats
+
+When using a fallback source, tell the user which tier you're on:
+
+**Tier 1 (MCP):** Full fidelity — structured props, stories, concept docs.
+
+**Tier 2 (llms.txt):** Full fidelity — same content as MCP, raw markdown format.
+> "The Beam MCP server is unavailable — falling back to llms.txt. If you weren't expecting this, please report it in **#beam-help** so the team can investigate."
+
+**Tier 3 (node_modules):** Degraded — no stories, no concept docs.
+> "MCP and llms.txt unreachable — used node_modules. Story examples and concept docs unavailable; verify visually."
+
+The user must know when data quality drops below the primary tier.
+
+## Error handling
+
+If ALL data sources fail:
+
+1. Do not proceed.
+2. Tell the user explicitly what was attempted and what failed.
+3. Ask the user how to proceed: install the dep, check network, switch repos, etc.
+4. Do not generate code from memory.
+
+Example user-facing message:
+
+> I couldn't fetch Beam component data. I tried:
+>
+> 1. MCP server (beam) — server not running or not configured.
+> 2. `https://react.beam.viasat.com/llms.txt` — fetch failed: ENETUNREACH.
+> 3. Local `node_modules/@viasat/beam-react` — package not installed.
+>
+> Beam isn't in my training data, so I can't safely generate code. Want to install the package, check the network, or work on something else?

package/references/rules-preamble.md

@@ -0,0 +1,38 @@
+# 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.

package/references/tokens.md

@@ -0,0 +1,100 @@
+# Beam tokens (procedure reference)
+
+Taxonomy and lookup procedure for Beam tokens. Does NOT enumerate token values — fetch them at runtime from the MCP server (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)
+
+Use the MCP server's token tools — available automatically when the plugin is loaded. Prefer this over llms.txt.
+
+### 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.

package/skills/beam-ui/SKILL.md

@@ -0,0 +1,53 @@
+---
+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)
+
+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. 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).** 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. If MCP and llms.txt were both unreachable, apply the honesty rule.
+6. **Report.** BUILD: components/tokens/files touched + suggest `/beam-audit-tokens`. 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. |
+
+## Not in scope
+
+Filesystem audit (use `/beam-audit-tokens`), test generation, Storybook authoring, visual design judgment, screenshot or Figma input, Figma write-back.