@codecademy/gamut 68.6.0 → 68.6.1-alpha.e6c390.0

package/agent-tools/skills/gamut-testing/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: gamut-testing
+description: Use this skill when writing or fixing unit tests for React components that use Gamut — setupRtl, MockGamutProvider, ColorMode in tests, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
+---
+
+# Gamut Testing
+
+Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
+
+---
+
+## Core rule: never mock Gamut components
+
+Do not use `jest.mock('@codecademy/gamut')` or manually mock individual Gamut components in test files. This silently bypasses emotion's theme context, produces tests that can't catch real rendering failures, and requires every test file to maintain its own fragile mock list.
+
+Use `MockGamutProvider` or `setupRtl` — both are designed for exactly this purpose.
+
+---
+
+## What `MockGamutProvider` does
+
+`MockGamutProvider` wraps `GamutProvider` with test-safe settings:
+
+- `useCache={false}` — disables emotion's style injection cache so styles are predictable across tests
+- `useGlobals={false}` — disables global CSS (Reboot, Typography, CSS Variables) to avoid side effects between test files
+- `theme={coreTheme}` — provides the full Gamut token set so styled components resolve correctly
+
+You should never construct a `GamutProvider` manually in a test. Use `MockGamutProvider`.
+
+---
+
+## Decision guide
+
+| Scenario | Use |
+|---|---|
+| Standard component unit test | `setupRtl` from `@codecademy/gamut-tests` |
+| Test that needs to vary `useLogicalProperties` | `render` + `MockGamutProvider` directly |
+| Test that needs `ColorMode` context | `render` + `MockGamutProvider` + `<ColorMode>` |
+| Visual test mock / Storybook wrapper | `MockGamutProvider` directly |
+
+---
+
+## `setupRtl` — preferred pattern
+
+`setupRtl` from `@codecademy/gamut-tests` wraps `setupRtl` from `component-test-setup` with `MockGamutProvider` automatically. You do not need to add `MockGamutProvider` yourself.
+
+```tsx
+import { setupRtl } from '@codecademy/gamut-tests';
+
+import { MyComponent } from '../MyComponent';
+
+const renderView = setupRtl(MyComponent, {
+  label: 'Default label',
+  onClick: jest.fn(),
+});
+
+it('renders the label', () => {
+  const { view } = renderView();
+  expect(view.getByText('Default label')).toBeInTheDocument();
+});
+
+it('accepts prop overrides', () => {
+  const { view } = renderView({ label: 'Override' });
+  expect(view.getByText('Override')).toBeInTheDocument();
+});
+```
+
+`renderView` returns `{ view, props, update }`:
+- `view` — RTL `RenderResult` (getByRole, getByText, etc.)
+- `props` — the resolved props passed to the component (useful for asserting on jest.fn() mocks)
+- `update` — re-render with updated props without remounting
+
+### Accessing mock functions via `props`
+
+```tsx
+it('calls onClick when clicked', async () => {
+  const { view, props } = renderView();
+  await userEvent.click(view.getByRole('button'));
+  expect(props.onClick).toHaveBeenCalled();
+});
+```
+
+---
+
+## `MockGamutProvider` directly — when you need more control
+
+Use `render` + `MockGamutProvider` when `setupRtl` doesn't give enough control over the wrapper — for example, when testing both logical and physical CSS property modes, or when adding `ColorMode`.
+
+```tsx
+import { MockGamutProvider } from '@codecademy/gamut-tests';
+import { render } from '@testing-library/react';
+
+it('uses logical properties when enabled', () => {
+  const { container } = render(
+    <MockGamutProvider useLogicalProperties>
+      <MyComponent width="200px" />
+    </MockGamutProvider>
+  );
+  // assert on inlineSize rather than width
+});
+```
+
+### Testing both logical and physical property modes
+
+```tsx
+describe.each([
+  { useLogicalProperties: true, widthProp: 'inlineSize' },
+  { useLogicalProperties: false, widthProp: 'width' },
+])(
+  'useLogicalProperties=$useLogicalProperties',
+  ({ useLogicalProperties, widthProp }) => {
+    it(`uses ${widthProp}`, () => {
+      const { container } = render(
+        <MockGamutProvider useLogicalProperties={useLogicalProperties}>
+          <MyComponent width="200px" />
+        </MockGamutProvider>
+      );
+      expect(container.firstChild).toHaveStyle({ [widthProp]: '200px' });
+    });
+  }
+);
+```
+
+---
+
+## Emotion style assertions
+
+Install `@emotion/jest` matchers once per test file to enable CSS-in-JS assertions:
+
+```tsx
+import { matchers } from '@emotion/jest';
+
+expect.extend(matchers);
+```
+
+Then assert on styles:
+
+```tsx
+expect(element).toHaveStyle({ borderRadius: '2px' });
+expect(element).toHaveStyleRule('padding', '1rem');
+```
+
+Use `theme` from `@codecademy/gamut-styles` to avoid hardcoding token values:
+
+```tsx
+import { theme } from '@codecademy/gamut-styles';
+
+expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
+```
+
+---
+
+## Visual test wrappers
+
+When creating mock components for visual tests or Storybook, wrap with `MockGamutProvider` and `ColorMode`:
+
+```tsx
+import { MockGamutProvider } from '@codecademy/gamut-tests';
+import { ColorMode } from '@codecademy/gamut-styles';
+
+export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (props) => (
+  <MockGamutProvider>
+    <ColorMode mode="light">
+      <MyComponent {...props} />
+    </ColorMode>
+  </MockGamutProvider>
+);
+```
+
+---
+
+## Common anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `jest.mock('@codecademy/gamut', () => ({ ... }))` | Remove mock; use `setupRtl` or `MockGamutProvider` |
+| `jest.mock('@codecademy/gamut-styles', ...)` | Remove mock; `MockGamutProvider` handles theme context |
+| Wrapping with `GamutProvider` directly in tests | Use `MockGamutProvider` — it sets `useCache={false}` and `useGlobals={false}` |
+| Repeating `render(<MockGamutProvider>...</MockGamutProvider>)` in every test | Extract with `setupRtl`; define `renderView` once above the `describe` block |
+| One `setupRtl` call per `it` block | Define `renderView` once outside `describe`, call it inside each `it` |
+| Asserting on raw CSS token strings | Import `theme` from `@codecademy/gamut-styles` and use `theme.spacing[n]`, `theme.fontSize`, etc. |

package/agent-tools/skills/gamut-theming/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: gamut-theming
+description: Use this skill when working with GamutProvider themes, Emotion theme tokens, or behavior that differs across Core, Admin, Platform, LX Studio, and Percipio — including new themes, token access in styled components, or debugging theme-specific styles.
+---
+
+# Gamut Theming
+
+Source: `@codecademy/gamut-styles`
+
+## Overview
+
+Gamut uses Emotion's theme system. All styled components have access to a typed theme object containing every design token. Themes are org-specific collections of tokens; components work across all themes without modification as long as they use token aliases rather than hardcoded values.
+
+**See also:** [`gamut-color-mode`](../gamut-color-mode/SKILL.md) for `<ColorMode>`, `<Background>`, `useColorModes`, and contrast-safe surfaces — read that before wiring light/dark or colored sections. Storybook: [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page), [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
+
+## Available themes
+
+| Theme     | Used for                                                   |
+| --------- | ---------------------------------------------------------- |
+| Core      | Codecademy default (public-facing products)                |
+| Admin     | Codecademy admin tools                                     |
+| Platform  | Codecademy learning environment / shared platform surfaces |
+| LX Studio | Learning Experience Studio                                 |
+| Percipio  | Skillsoft Percipio platform                                |
+
+The active theme is set at the app level via `<GamutProvider>`. Components inside receive the current theme via Emotion's context.
+
+## Accessing tokens in styled components
+
+### Via `css()` utility (recommended for static styles)
+
+```tsx
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+// Static color token
+const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
+
+// Semantic color alias (adapts to color mode and theme)
+const Text = styled.div(css({ color: 'primary', p: 4 }));
+```
+
+### Via `theme` prop (for dynamic styles)
+
+Every Emotion styled component receives `theme` as a prop:
+
+```tsx
+import styled from '@emotion/styled';
+
+const DynamicBox = styled.div`
+  color: ${({ theme }) => theme.colors.blue};
+  font-size: ${({ theme }) => theme.fontSize[16]};
+`;
+```
+
+### Via imported `theme` object (outside styled components)
+
+```tsx
+import { css as emotionCss } from '@emotion/react';
+import { theme } from '@codecademy/gamut-styles';
+
+// For use in plain CSS-in-JS outside of styled components
+const myStyles = emotionCss`
+  font-size: ${theme.fontSize[14]};
+  color: ${theme.colors['navy-400']};
+`;
+```
+
+### Via `useTheme()` hook
+
+```tsx
+import { useTheme } from '@emotion/react';
+
+const MyComponent = () => {
+  const theme = useTheme();
+  return <div style={{ color: theme.colors.primary }} />;
+};
+```
+
+## System props as the primary token API
+
+For most styling needs, use **system props** (see the `gamut-system-props` skill) rather than accessing the theme directly. System props are the idiomatic way to use design tokens in Gamut components:
+
+```tsx
+import { variance } from '@codecademy/variance';
+import { system } from '@codecademy/gamut-styles';
+
+const Card = styled.div(
+  variance.compose(system.layout, system.space, system.color)
+);
+
+// token scale values are validated at the type level
+<Card bg="navy-400" p={16} width="100%" />;
+```
+
+## Theme-aware vs. color-mode-aware
+
+| Concern                                        | Tool                                       |
+| ---------------------------------------------- | ------------------------------------------ |
+| Tokens change per theme (colors, sizes, fonts) | Access via `theme.*` or system props       |
+| Colors change per light/dark mode              | Use semantic color aliases + `<ColorMode>` |
+| Background contrast                            | Use `<Background>` from ColorMode          |
+
+Semantic aliases like `primary`, `secondary`, `text`, `background` serve double duty: they resolve to theme-specific values **and** switch between light/dark variants automatically.
+
+## Creating a new theme
+
+See `CreatingThemes.mdx` in the styleguide (`packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx`) for the full guide. Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
+
+## Key principles
+
+- Prefer semantic token aliases over raw token values when the style needs to respond to color mode changes.
+- Use raw tokens (e.g. `navy-400`) only for styles that should be fixed regardless of mode.
+- Never hardcode hex values in styled components — always go through the theme/system props.
+- The `GamutProvider` at the app root wires up the theme, color mode, and logical properties settings; components should not need to know which theme is active.

package/agent-tools/skills/gamut-typography/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: gamut-typography
+description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts — even if the user does not name fonts or tokens. Covers Apercu Pro, Suisse Intl Mono, scale, line heights, line length, and alignment.
+---
+
+# Gamut Typography
+
+> **Scope**: This skill covers typography for **Codecademy products** using the Core, Admin, or Platform themes (Apercu + Suisse). Percipio uses Roboto for all type — see `DESIGN.md` for Percipio-specific guidance. LX Studio uses Hanken Grotesk in place of both Apercu and Suisse.
+
+## Typefaces
+
+Codecademy products use two typefaces:
+
+### Apercu Pro (`fontFamily: "base"`)
+
+The primary typeface. Geometric-ish, humanist sans-serif. Use for:
+- Headlines (Bold weight)
+- Body / paragraph text (Regular weight)
+- UI labels, menu items (Regular weight)
+- Emphasis within body copy (Italic — **not** Bold)
+
+**Rules:**
+- Do not use Bold to emphasize text within a Regular-weight paragraph. Use Italic instead.
+- Set with generous line-height for body text: **150–175%** of the type size (e.g. 16px type → 24–28px line-height).
+- Headlines should use **100–110%** line-height to appear intentional and grouped.
+- Text should be **left-aligned** by default.
+
+### Suisse Intl Mono (`fontFamily: "accent"`)
+
+Monospace accent typeface. Use sparingly for:
+- Code snippets and inline code
+- Numbers, figures, and statistics
+- Captions and labels that reference technical/engineering context
+- Enumerated lists
+- Quotations in a technical voice
+
+**Rules:**
+- Every character is the same width — avoid long paragraph-length prose in Suisse.
+- It reads large for its point size: **reduce the size by ~10–15%** relative to Apercu text at the same visual scale (e.g. 14px Suisse ≈ 16px Apercu visually).
+- Requires extra line-height to remain readable.
+
+## Font size scale (`fontSize`)
+
+Sizes are accessed via the theme's `fontSize` scale. Common keys:
+
+```tsx
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+// Via system props
+import { system } from '@codecademy/gamut-styles';
+const Text = styled.p(system.typography);
+<Text fontSize={16} />;
+
+// Via css() utility
+const Box = styled.div(css({ fontSize: 14 }));
+
+// Via theme directly (outside styled components)
+import { theme } from '@codecademy/gamut-styles';
+const size = theme.fontSize[16];
+```
+
+## Line heights (`lineHeight`)
+
+Line heights are limited to **multiples of 4px**. Type boxes are placed on an **8px placement grid**.
+
+Guidelines:
+- Body text: 150–175% of font size
+- Headlines: 100–110% of font size
+
+## Line length
+
+Controlling line length is essential for readability:
+
+| Context | Target |
+|---|---|
+| Single-column body text | ~66 characters (max 85) |
+| Multi-column layouts | ≤50 characters per line |
+| Minimum | 45 characters |
+
+**How to control line length**: Start with the right text style for the design, then adjust the width or column count of the text container.
+
+## Alignment
+
+- **Left-align** paragraphs by default — this is easiest to read and supports grid alignment.
+- **Center-align** only for short marketing headlines or specific interface components with brief text.
+- **Never right-align** text in normal circumstances (exceptions: numbers, equations).
+- Do not adjust letter-spacing.
+
+## Accessing typography tokens
+
+```tsx
+// System props (recommended for styled components)
+import { system } from '@codecademy/gamut-styles';
+import { variance } from '@codecademy/variance';
+
+const Heading = styled.h2(
+  variance.compose(system.typography, system.space)
+);
+
+<Heading fontSize={24} fontFamily="base" fontWeight="bold" lineHeight={1.1} mb={8} />;
+
+// css() utility (recommended for static styles)
+import { css } from '@codecademy/gamut-styles';
+
+const Caption = styled.span(
+  css({ fontFamily: 'accent', fontSize: 12, color: 'secondary' })
+);
+
+// Theme object (outside styled components)
+import { theme } from '@codecademy/gamut-styles';
+import { css as emotionCss } from '@emotion/react';
+
+const myStyles = emotionCss`
+  font-size: ${theme.fontSize[14]};
+`;
+```
+
+## Semantic vs. visual sizing
+
+- The term **"Title"** distinguishes visual size from semantic HTML hierarchy (H1–H6).
+- A visually large title may use `<h2>` or `<p>` semantically — visual scale and semantic meaning are independent in Gamut.
+- Choose HTML heading levels for document structure, choose font size for visual hierarchy.

package/bin/commands/plugin/install.mjs

@@ -0,0 +1,173 @@
+import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
+import { cursorDestPath } from '../../lib/cursor.mjs';
+import { resolveFigmaOutput } from '../../lib/figma.mjs';
+import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+import { runCommand } from '../../lib/run-command.mjs';
+
+export const TARGETS = ['cursor', 'claude', 'figma'];
+export const SCOPES = ['all', 'skills', 'rules', 'commands', 'agents'];
+
+export function help() {
+  console.log(`
+Usage:
+  gamut plugin install [target] [options]
+
+Install the Gamut plugin into an AI or design tool.
+
+Arguments:
+  target               Tool to install into (default: cursor)
+                       cursor | claude | figma
+
+Options:
+  --scope <scope>      Content to install (default: all)
+                       all | skills | rules | commands | agents
+  --output <path>      [figma] Explicit destination directory for guidelines/.
+                       If omitted, walks up from cwd to find figma.config.json.
+  --plugin-dir <path>  Override the bundled agent-tools directory
+  -h, --help           Show this help message
+
+Examples:
+  gamut plugin install
+  gamut plugin install claude
+  gamut plugin install figma
+  gamut plugin install figma --output /path/to/project/guidelines
+  gamut plugin install cursor --scope skills
+  gamut plugin install cursor --plugin-dir ./my-agent-tools
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** Directories in the plugin source that should not be installed to Cursor. */
+const CURSOR_IGNORE = new Set([
+  '.claude-plugin', // Claude Code manifest — not a Cursor concept
+  'guidelines',     // Figma Make only
+]);
+
+/** @param {string} sourceRoot @param {string} scope */
+async function installCursor(sourceRoot, scope) {
+  const dest = await cursorDestPath(sourceRoot);
+
+  if ((process.env.CURSOR_INSTALL_METHOD ?? 'copy') !== 'copy') {
+    // Symlink the whole plugin dir (dev convenience)
+    await rm(dest, { recursive: true, force: true });
+    await symlink(resolve(sourceRoot), dest, 'dir');
+    console.log(`Cursor: symlinked to ${dest}`);
+    return;
+  }
+
+  // Selective copy: always include the cursor manifest, then scoped content dirs
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+
+  await cp(`${sourceRoot}/.cursor-plugin`, `${dest}/.cursor-plugin`, { recursive: true });
+
+  let dirs;
+  if (scope === 'all') {
+    const entries = await readdir(sourceRoot, { withFileTypes: true });
+    dirs = entries
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !CURSOR_IGNORE.has(e.name))
+      .map((e) => e.name);
+  } else {
+    dirs = [scope];
+  }
+
+  for (const dir of dirs) {
+    await cp(`${sourceRoot}/${dir}`, `${dest}/${dir}`, { recursive: true }).catch(() => {
+      // directory may be empty/missing — not an error
+    });
+  }
+
+  const scopeLabel = scope === 'all' ? 'all content' : scope;
+  console.log(`Cursor: installed (${scopeLabel}) → ${dest}`);
+}
+
+// Claude Code only loads from recognized plugin directories: skills/, commands/, agents/.
+// rules/ is Cursor-specific (.mdc format); .cursor-plugin/ and guidelines/ are also
+// present in sourceRoot but ignored by Claude Code.
+
+/** @param {string} sourceRoot */
+async function installClaude(sourceRoot) {
+  const spec = await claudePluginSpec(sourceRoot);
+  const mpName = marketplaceName(spec);
+  const root = resolve(sourceRoot);
+
+  let code = await runCommand('claude', ['plugin', 'marketplace', 'add', root, '--scope', 'user']);
+  if (code !== 0) {
+    console.warn(
+      `warning: "claude plugin marketplace add" exited ${code} — ` +
+        `if it's already registered this is safe to ignore.`,
+    );
+    code = await runCommand('claude', ['plugin', 'marketplace', 'update', mpName]);
+    if (code !== 0) {
+      throw new Error(
+        `claude plugin marketplace add/update failed (exit ${code}).\n` +
+          `Try manually: claude plugin marketplace add ${root}`,
+      );
+    }
+  }
+
+  code = await runCommand('claude', ['plugin', 'install', spec, '--scope', 'user']);
+  if (code !== 0) {
+    throw new Error(
+      `claude plugin install failed (exit ${code}).\n` +
+        `Try manually: claude plugin install ${spec} --scope user`,
+    );
+  }
+
+  console.log(`Claude Code: installed ${spec} (user scope)`);
+  console.log(`  Tip: run /reload-plugins in Claude Code if skills don't appear immediately.`);
+  console.log(`  One-off without install: claude --plugin-dir ${root}`);
+}
+
+/**
+ * @param {string} sourceRoot
+ * @param {string | undefined} outputArg
+ */
+async function installFigma(sourceRoot, outputArg) {
+  const src = join(sourceRoot, 'guidelines');
+  const { path: dest, discovered } = await resolveFigmaOutput(outputArg);
+
+  if (discovered) {
+    console.log(`Figma: found figma.config.json — installing to ${dest}`);
+  }
+
+  await rm(dest, { recursive: true, force: true });
+  await cp(src, dest, { recursive: true });
+  console.log(`Figma: installed guidelines/ → ${dest}`);
+  console.log(`  In Figma Make, point your kit at this guidelines/ directory for design system context.`);
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin install [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
+ *                                            [--plugin-dir <path>]
+ *
+ * @param {string[]} args
+ */
+export default async function install(args) {
+  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
+  const scope = getFlag(args, '--scope', 'all') ?? 'all';
+
+  if (!TARGETS.includes(target)) {
+    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
+  }
+  if (!SCOPES.includes(scope)) {
+    throw new Error(`Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`);
+  }
+
+  const pluginDir = await resolvePluginDir(args);
+
+  if (target === 'cursor') {
+    await installCursor(pluginDir, scope);
+  } else if (target === 'claude') {
+    await installClaude(pluginDir);
+  } else if (target === 'figma') {
+    const output = getFlag(args, '--output', undefined);
+    await installFigma(pluginDir, output);
+  }
+}

package/bin/commands/plugin/list.mjs

@@ -0,0 +1,105 @@
+import { stat } from 'node:fs/promises';
+
+import { cursorDestPath } from '../../lib/cursor.mjs';
+import { findFigmaConfigDir } from '../../lib/figma.mjs';
+import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
+
+export function help() {
+  console.log(`
+Usage:
+  gamut plugin list [options]
+
+Show installation status for all supported targets.
+
+Options:
+  --output <path>      [figma] Explicit path to DESIGN.md.
+                       If omitted, walks up from cwd to find figma.config.json.
+  --plugin-dir <path>  Override the bundled agent-tools directory
+  -h, --help           Show this help message
+
+Examples:
+  gamut plugin list
+  gamut plugin list --output ./docs/DESIGN.md
+`);
+}
+
+// ---------------------------------------------------------------------------
+
+/** @param {string} sourceRoot */
+async function cursorStatus(sourceRoot) {
+  const dest = await cursorDestPath(sourceRoot);
+  const installed = !!(await stat(dest).catch(() => null));
+  return {
+    target: 'cursor',
+    status: installed ? '✓ installed' : '✗ not installed',
+    notes: installed ? dest : 'run: gamut plugin install cursor',
+  };
+}
+
+async function claudeStatus() {
+  // Claude Code doesn't expose a stable filesystem path we can check.
+  return {
+    target: 'claude',
+    status: '? unknown',
+    notes: 'run: claude plugin list',
+  };
+}
+
+/** @param {string | undefined} outputArg */
+async function figmaStatus(outputArg) {
+  let dest;
+  if (outputArg) {
+    dest = outputArg;
+  } else {
+    const dir = await findFigmaConfigDir(process.cwd());
+    dest = dir ? `${dir}/DESIGN.md` : null;
+  }
+
+  if (!dest) {
+    return {
+      target: 'figma',
+      status: '? unknown',
+      notes: 'figma.config.json not found — run from your project root or use --output',
+    };
+  }
+
+  const installed = !!(await stat(dest).catch(() => null));
+  return {
+    target: 'figma',
+    status: installed ? '✓ installed' : '✗ not installed',
+    notes: installed ? dest : `run: gamut plugin install figma`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * gamut plugin list
+ *
+ * Shows installation status for each supported target.
+ *
+ * @param {string[]} args
+ */
+export default async function list(args) {
+  const pluginDir = await resolvePluginDir(args);
+  const output = getFlag(args, '--output', undefined);
+
+  const rows = await Promise.all([
+    cursorStatus(pluginDir),
+    claudeStatus(),
+    figmaStatus(output),
+  ]);
+
+  const col0 = Math.max(...rows.map((r) => r.target.length));
+  const col1 = Math.max(...rows.map((r) => r.status.length));
+
+  const header = `${'Target'.padEnd(col0)}  ${'Status'.padEnd(col1)}  Path / Notes`;
+  const rule = '─'.repeat(header.length);
+
+  console.log(`\n${header}`);
+  console.log(rule);
+  for (const row of rows) {
+    console.log(`${row.target.padEnd(col0)}  ${row.status.padEnd(col1)}  ${row.notes}`);
+  }
+  console.log();
+}