# 🤖 @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 |
| `/beam-update` | User-invoked | Detect version drift, surface the changelog, and update beam-react + the plugin in one step                       |

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

> **Note:** `/plugin` commands are Claude Code slash commands. Run them inside the Claude Code CLI, not in a raw terminal, the desktop app, or the VS Code Claude extension.

Before installing, make sure `@viasat/beam-react` is in your project and updated to the latest version. The plugin ships pinned to the same version as `@viasat/beam-react`, so installing it against an outdated `@viasat/beam-react` gives you an outdated plugin and MCP.

The plugin ships as a declared dependency of `@viasat/beam-react`, so no separate `npm install` is needed. Once `@viasat/beam-react` is in your project, run these two commands inside the Claude Code CLI:

```
/plugin marketplace add ./node_modules/@viasat/beam-react-claude-plugin
/plugin install beam-react-claude-plugin@beam
```

Then run `/reload-plugins`.

> **Migrating from the git marketplace path?** If you previously used
> `/plugin marketplace add git@git.viasat.com:vega/beam.git`, remove that
> marketplace entry and follow the steps above. The npm path is now the only
> supported path.

## 🔄 Updating

Run `/beam-update` inside the Claude Code CLI. Claude detects whether an update is
available, surfaces what changed, and handles the npm + plugin cache update. The
only step you take is `/reload-plugins` at the end to pick up the new version.

When the update crosses a version with a migration guide, Claude also surfaces the
relevant guides, scans your code for anything the migration affects, and offers to
apply the necessary changes for you before you reload, so you're not left to work
out the impact on your own.

To update manually without the skill:

```bash
npm update @viasat/beam-react          # updates beam-react + plugin as its dep
claude plugin marketplace update beam  # refreshes marketplace cache
claude plugin update beam-react-claude-plugin@beam  # updates plugin cache
```

Then run `/reload-plugins` in the Claude Code CLI.

### Automatic drift detection

Once per day, the plugin quietly checks the npm registry for a newer
`@viasat/beam-react`. If one is available, it surfaces a short notice at the top of
Claude's next response suggesting you run `/beam-update`. No prompt data leaves your
machine; the only outbound call is a version lookup to the public npm registry, and
the check is throttled to once per day even when it can't reach the network.

## 🖥️ 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.