@viasat/beam-react-claude-plugin 2.59.0 → 2.61.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.59.0",
+  "version": "2.61.0",
   "author": {
     "name": "Viasat",
     "url": "https://git.viasat.com/vega/beam"
@@ -15,7 +15,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@viasat/beam-react-mcp@2.59.0"
+        "@viasat/beam-react-mcp@2.61.0"
       ]
     }
   },

package/package.json

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

@@ -37,6 +37,11 @@ This is a backstop for one narrow case: a hook-driven component that shipped bef
 
 Before using anything the grep finds, confirm it is public API — i.e. it resolves through the package barrel. The root `node_modules/@viasat/beam-react/index.d.ts` only re-exports wildcards (`export * from './lib'`), so a name won't appear there literally; instead confirm it is re-exported from its own component barrel, e.g. `grep -rn "useToast" node_modules/@viasat/beam-react/lib/Toasts/index.d.ts`. If a name is only in an implementation file and not re-exported from any `index.d.ts`, it is an internal detail (for example `useDialogContext`, `usePopoverContext`, `useSelectDropdown`), not public API. Do not use it.
 
+### Usage guidelines
+
+Some components carry designer-authored usage guidance that can't be inferred from props or JSDoc — purpose, when to use versus avoid, anatomy, and dos & don'ts. When it exists, `getComponent` returns it inline as a `usageGuidelines` field (freeform markdown). Read it before using the component — it captures intent the API surface alone doesn't.
+
+
 ## 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.
@@ -112,7 +117,7 @@ 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.
+**Tier 2 (llms.txt):** Near-full fidelity — has most of the core component knowledge (props, stories, concept docs) as raw markdown, but does NOT contain design usage guidelines. When you need a component's `usageGuidelines`, use MCP (Tier 1).
 > "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.

package/skills/beam-ui/SKILL.md

@@ -30,7 +30,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. 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.
+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.
 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.