@viasat/beam-react-claude-plugin 2.62.0 → 2.63.0

package/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "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.62.0",
+  "version": "2.63.0",
   "author": {
     "name": "Viasat",
     "url": "https://git.viasat.com/vega/beam"
@@ -15,7 +15,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@viasat/beam-react-mcp@2.62.0"
+        "@viasat/beam-react-mcp@2.63.0"
       ]
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viasat/beam-react-claude-plugin",
-  "version": "2.62.0",
+  "version": "2.63.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",

package/references/data-sources.md

@@ -17,6 +17,23 @@ The `@viasat/beam-react-mcp` server provides structured, offline access to Beam
 
 Data comes from `beam-manifest.json`, bundled in the npm package. Zero network calls at runtime.
 
+### Tool catalog
+
+| Tool                | Purpose                                                                 |
+| ------------------- | ----------------------------------------------------------------------- |
+| `listComponents`    | Discover components (optional `query`/`category` filter).               |
+| `getComponent`      | Full API for one component: props, story index, `pairedHooks`.          |
+| `getComponentStory` | Source of a specific usage example/story.                               |
+| `listIcons`         | Available icon names.                                                   |
+| `listConcepts`      | Discover concept docs (theming, styling, tokens, getting started, …).   |
+| `getConcept`        | Full MDX content for one concept doc, by slug or title.                 |
+
+### Concept docs (and tokens)
+
+Concept docs are MDX guides bundled in the manifest — theming, styling, getting started, and the token reference tables. Discover them with `listConcepts`, then fetch full content with `getConcept('<slug-or-title>')` (case-insensitive; returns `{ title, slug, description, type, mdxContent }`).
+
+**Token data is delivered as concept docs, not a dedicated tool.** The nine `Tokens/*` concepts (e.g. `tokens-color`, `tokens-space`) each carry a token table inside `mdxContent`. See `references/tokens.md` for the full slug list, table shapes, and lookup procedure.
+
 ### Paired hooks and context-driven components
 
 Some components are driven by an imperative hook or context provider, not by props and children alone. `ToastContainer` is controlled by `useToast()`, not by passing toasts as JSX. For these, `getComponent` returns a `pairedHooks` array. Each entry has the hook or provider `name`, `kind`, full `signature` (params plus resolved return type), and `importPath`.

package/references/tokens.md

@@ -1,6 +1,6 @@
 # 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).
+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`.
 
@@ -48,7 +48,26 @@ Resolution when no token fits: for **colors**, ask the user — never drop to a
 
 ### Primary (MCP)
 
-Use the MCP server's token tools — available automatically when the plugin is loaded. Prefer this over llms.txt.
+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)
 

package/skills/beam-ui/SKILL.md

@@ -31,7 +31,7 @@ See `references/data-sources.md` § MCP server for the tool catalog and call ord
 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).** Look up every color/dimension/font per `references/tokens.md`. Zero violations.
+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.