@codecademy/gamut 68.6.1-alpha.edab62.0 → 68.6.1

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

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

@@ -1,123 +0,0 @@
----
-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

@@ -1,173 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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();
-}

package/bin/commands/plugin/remove.mjs

@@ -1,116 +0,0 @@
-import { rm, stat } from 'node:fs/promises';
-
-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';
-import { TARGETS } from './install.mjs';
-
-export function help() {
-  console.log(`
-Usage:
-  gamut plugin remove [target] [options]
-
-Remove the installed Gamut plugin from an AI or design tool.
-
-Arguments:
-  target               Tool to remove from (default: cursor)
-                       cursor | claude | figma
-
-Options:
-  --output <path>      [figma] Path to the DESIGN.md that was installed.
-                       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 remove
-  gamut plugin remove claude
-  gamut plugin remove figma
-  gamut plugin remove figma --output ./docs/DESIGN.md
-`);
-}
-
-// ---------------------------------------------------------------------------
-
-/** @param {string} sourceRoot */
-async function removeCursor(sourceRoot) {
-  const dest = await cursorDestPath(sourceRoot);
-  const st = await stat(dest).catch(() => null);
-
-  if (!st) {
-    console.log(`Cursor: nothing to remove — ${dest} does not exist.`);
-    return;
-  }
-
-  await rm(dest, { recursive: true, force: true });
-  console.log(`Cursor: removed ${dest}`);
-}
-
-/** @param {string} sourceRoot */
-async function removeClaude(sourceRoot) {
-  const spec = await claudePluginSpec(sourceRoot);
-  const mpName = marketplaceName(spec);
-  const pluginName = spec.split('@')[0];
-
-  let code = await runCommand('claude', ['plugin', 'remove', pluginName, '--scope', 'user']);
-  if (code !== 0) {
-    console.warn(
-      `warning: "claude plugin remove" exited ${code} — the plugin may not have been installed.`,
-    );
-  } else {
-    console.log(`Claude Code: removed plugin "${pluginName}"`);
-  }
-
-  code = await runCommand('claude', ['plugin', 'marketplace', 'remove', mpName]);
-  if (code !== 0) {
-    console.warn(
-      `warning: "claude plugin marketplace remove" exited ${code} — ` +
-        `the marketplace entry may not exist or the command syntax may differ. ` +
-        `Run "claude plugin marketplace list" to check.`,
-    );
-  } else {
-    console.log(`Claude Code: removed marketplace "${mpName}"`);
-  }
-}
-
-/** @param {string | undefined} outputArg */
-async function removeFigma(outputArg) {
-  const { path: dest } = await resolveFigmaOutput(outputArg);
-  const st = await stat(dest).catch(() => null);
-
-  if (!st) {
-    console.log(`Figma: nothing to remove — ${dest} does not exist.`);
-    return;
-  }
-
-  await rm(dest, { force: true });
-  console.log(`Figma: removed ${dest}`);
-}
-
-// ---------------------------------------------------------------------------
-
-/**
- * gamut plugin remove [cursor|claude|figma] [--plugin-dir <path>]
- *
- * @param {string[]} args
- */
-export default async function remove(args) {
-  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
-
-  if (!TARGETS.includes(target)) {
-    throw new Error(`Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`);
-  }
-
-  const pluginDir = await resolvePluginDir(args);
-
-  if (target === 'cursor') {
-    await removeCursor(pluginDir);
-  } else if (target === 'claude') {
-    await removeClaude(pluginDir);
-  } else if (target === 'figma') {
-    const output = getFlag(args, '--output', undefined);
-    await removeFigma(output);
-  }
-}

package/bin/commands/plugin/update.mjs

@@ -1,49 +0,0 @@
-import { getFlag } from '../../lib/resolve-plugin-dir.mjs';
-import install, { TARGETS } from './install.mjs';
-
-export function help() {
-  console.log(`
-Usage:
-  gamut plugin update [target] [options]
-
-Update the Gamut plugin in an AI or design tool.
-Equivalent to re-running install — replaces the existing installation in place.
-
-Arguments:
-  target               Tool to update (default: cursor)
-                       cursor | claude | figma
-
-Options:
-  --scope <scope>      Content to update (default: all)
-                       all | skills | rules | commands | agents
-  --plugin-dir <path>  Override the bundled agent-tools directory
-  -h, --help           Show this help message
-
-Examples:
-  gamut plugin update
-  gamut plugin update claude
-  gamut plugin update cursor --scope skills
-`);
-}
-
-/**
- * gamut plugin update [cursor|claude|figma] [--scope all|skills|rules|commands|agents]
- *                                           [--plugin-dir <path>]
- *
- * Re-runs install with the same arguments. For Cursor this does an in-place
- * copy replacing any existing installation. For Claude Code it updates the
- * marketplace entry and re-installs.
- *
- * @param {string[]} args
- */
-export default async function update(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(', ')}`);
-  }
-
-  console.log(`Updating Gamut plugin for ${target}${scope !== 'all' ? ` (scope: ${scope})` : ''}…`);
-  await install(args);
-}