@codecademy/gamut 68.5.2-alpha.f0a056.0 → 68.6.1-alpha.e6c390.0

package/agent-tools/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "gamut-design-system",
+  "owner": {
+    "name": "Codecademy"
+  },
+  "metadata": {
+    "description": "Local marketplace for @codecademy/gamut agent tools."
+  },
+  "plugins": [
+    {
+      "name": "gamut-design-system",
+      "source": "./",
+      "description": "Gamut design system agent tools: skills and rules for AI-assisted development."
+    }
+  ]
+}

package/agent-tools/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "gamut-design-system",
+  "version": "0.0.1",
+  "description": "Gamut design system agent tools: skills and rules for AI-assisted development.",
+  "license": "MIT",
+  "keywords": ["codecademy", "gamut", "design-system", "agent-skills"]
+}

package/agent-tools/.cursor-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "gamut-design-system",
+  "displayName": "Gamut Design System",
+  "version": "0.0.1",
+  "description": "Gamut design system agent tools: skills and rules for AI-assisted development.",
+  "keywords": ["codecademy", "gamut", "design-system", "agent-skills"]
+}

package/agent-tools/DESIGN.Codecademy.md

@@ -0,0 +1,648 @@
+---
+version: alpha
+name: Codecademy Design System
+description: Design tokens for codecademy.com
+colors:
+  # palette — reference hex for docs/tools; in product UI use semantic colors via Gamut theme (Emotion) / system props or Figma tokens—never paste these literals into code
+  hyper-500: '#3A10E5'
+  hyper-400: '#5533FF'
+  navy-900: '#0A0D1C'
+  navy-800: '#10162F'
+  navy-700: '#31374C'
+  navy-600: '#4C5063'
+  navy-500: '#686C7C'
+  navy-300: '#BCBEC5'
+  navy-200: '#E2E3E6'
+  navy-100: '#F5F6F7'
+  yellow-500: '#FFD300'
+  yellow-400: '#CCA900'
+  yellow-0: '#FFFAE5'
+  yellow-900: '#211B00'
+  green-700: '#008A27'
+  green-400: '#AEE938'
+  green-0: '#F5FFE3'
+  green-900: '#151C07'
+  red-600: '#BE1809'
+  red-500: '#E91C11'
+  red-400: '#DC5879'
+  red-300: '#E85D7F'
+  red-0: '#FBF1F0'
+  red-900: '#280503'
+  beige: '#FFF0E5'
+  white: '#ffffff'
+  black: '#000000'
+  # semantic aliases (light mode) — use these in code, not palette swatches or hex values
+  text: '{colors.navy-800}'
+  text-accent: '{colors.navy-900}'
+  text-secondary: '{colors.navy-600}'
+  text-disabled: '{colors.navy-500}'
+  background: '{colors.white}'
+  background-primary: '{colors.beige}'
+  background-contrast: '{colors.white}'
+  background-selected: '{colors.navy-100}'
+  background-hover: '{colors.navy-200}'
+  background-disabled: '{colors.navy-200}'
+  background-success: '{colors.green-0}'
+  background-warning: '{colors.yellow-0}'
+  background-error: '{colors.red-0}'
+  primary: '{colors.hyper-500}'
+  primary-hover: '{colors.hyper-400}'
+  primary-inverse: '{colors.yellow-500}'
+  secondary: '{colors.navy-800}'
+  secondary-hover: '{colors.navy-700}'
+  interface: '{colors.hyper-500}'
+  interface-hover: '{colors.hyper-400}'
+  danger: '{colors.red-500}'
+  danger-hover: '{colors.red-600}'
+  feedback-error: '{colors.red-600}'
+  feedback-success: '{colors.green-700}'
+  feedback-warning: '{colors.yellow-500}'
+  border-primary: '{colors.navy-800}'
+  border-secondary: '{colors.navy-600}'
+  border-tertiary: '{colors.navy-300}'
+  border-disabled: '{colors.navy-500}'
+  shadow-primary: '{colors.navy-800}'
+  shadow-secondary: '{colors.navy-600}'
+typography:
+  base:
+    fontFamily: '"Apercu", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif'
+    fontSize: '1rem'
+    fontWeight: '400'
+    lineHeight: '1.5'
+  accent:
+    fontFamily: '"Suisse", "Apercu", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif'
+    fontSize: '0.875rem'
+    fontWeight: '400'
+    lineHeight: '1.5'
+  title:
+    fontFamily: '"Apercu", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif'
+    fontSize: '2.125rem'
+    fontWeight: '700'
+    lineHeight: '1.2'
+  hankenGrotesk:
+    fontFamily: '"Hanken Grotesk", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif'
+  monospace:
+    fontFamily: 'Monaco, Menlo, "Ubuntu Mono", "Droid Sans Mono", Consolas, monospace'
+rounded:
+  none: '0px'
+  sm: '2px'
+  md: '4px'
+  lg: '8px'
+  xl: '16px'
+  full: '999px'
+spacing:
+  '0': '0'
+  '4': '0.25rem'
+  '8': '0.5rem'
+  '12': '0.75rem'
+  '16': '1rem'
+  '24': '1.5rem'
+  '32': '2rem'
+  '40': '2.5rem'
+  '48': '3rem'
+  '64': '4rem'
+  '96': '6rem'
+components:
+  FillButton:
+    backgroundColor: '{colors.primary}'
+    textColor: '{colors.white}'
+    rounded: '{rounded.md}'
+  FillButton-hover:
+    backgroundColor: '{colors.primary-hover}'
+    textColor: '{colors.white}'
+  FillButton-danger:
+    backgroundColor: '{colors.danger}'
+    textColor: '{colors.white}'
+    rounded: '{rounded.md}'
+  FillButton-danger-hover:
+    backgroundColor: '{colors.danger-hover}'
+    textColor: '{colors.white}'
+  StrokeButton:
+    backgroundColor: 'transparent'
+    textColor: '{colors.secondary}'
+    rounded: '{rounded.md}'
+  CTAButton:
+    backgroundColor: '{colors.primary}'
+    textColor: '{colors.white}'
+    rounded: '{rounded.md}'
+  CTAButton-inverse:
+    backgroundColor: '{colors.primary-inverse}'
+    textColor: '{colors.secondary}'
+    rounded: '{rounded.md}'
+  TextButton:
+    backgroundColor: 'transparent'
+    textColor: '{colors.primary}'
+  TextButton-hover:
+    textColor: '{colors.primary-hover}'
+  Card:
+    backgroundColor: '{colors.background}'
+    rounded: '{rounded.none}'
+  Card-interactive:
+    rounded: '{rounded.md}'
+  Card-elevated:
+    backgroundColor: '{colors.background-primary}'
+    rounded: '{rounded.lg}'
+  Card-beige:
+    backgroundColor: '{colors.beige}'
+    rounded: '{rounded.lg}'
+  Input:
+    backgroundColor: '{colors.background}'
+    textColor: '{colors.text}'
+    rounded: '{rounded.md}'
+  Checkbox:
+    backgroundColor: '{colors.interface}'
+    rounded: '{rounded.sm}'
+  Checkbox-hover:
+    backgroundColor: '{colors.interface-hover}'
+  Headline:
+    textColor: '{colors.text-accent}'
+    typography: '{typography.title}'
+  Tag-success:
+    backgroundColor: '{colors.feedback-success}'
+    textColor: '{colors.white}'
+    rounded: '{rounded.sm}'
+  Tag-warning:
+    backgroundColor: '{colors.feedback-warning}'
+    textColor: '{colors.text}'
+    rounded: '{rounded.sm}'
+  Alert-error:
+    backgroundColor: '{colors.background-error}'
+    textColor: '{colors.feedback-error}'
+  Alert-success:
+    backgroundColor: '{colors.background-success}'
+    textColor: '{colors.text}'
+  Alert-warning:
+    backgroundColor: '{colors.background-warning}'
+    textColor: '{colors.text}'
+---
+
+# Codecademy
+
+This file defines the visual design tokens for codecademy.com, implemented using the Gamut design system (`@codecademy/gamut`, `@codecademy/gamut-styles`). Gamut ships 52 components with Figma ↔ code mappings via Figma Code Connect.
+
+**Figma file**: https://www.figma.com/design/ReGfRNillGABAj5SlITalN/📐-Gamut
+**Storybook**: https://gamut.codecademy.com
+
+---
+
+## Visual Theme & Atmosphere
+
+Codecademy communicates **logic with personality** — structured and trustworthy enough for a learning platform, with creative moments that feel engaging and human. The design voice is: _"we are ruled by logic, but are creative and a bit unexpected as well."_
+
+**Density**: Medium. Information-dense layouts use careful whitespace and strong typographic hierarchy to stay readable. Avoid cramped or overly airy layouts.
+
+**Design philosophy**:
+
+- Components are color mode–aware by default — never hardcode hex values for adaptive UI
+- Every component works across all themes without modification
+- Mobile-first responsive design built on a 12-column grid
+- Accessibility is guaranteed by design: semantic color tokens meet contrast requirements per mode automatically
+
+---
+
+## Themes
+
+Codecademy products use one of four Gamut themes, all sharing the same core visual identity. Token aliases resolve to the right values per theme automatically — components require no modification.
+
+| Theme         | Use case                        | Base font      | Dark mode      |
+| ------------- | ------------------------------- | -------------- | -------------- |
+| **Core**      | Codecademy (default)            | Apercu         | ✓ light + dark |
+| **Admin**     | Codecademy admin tools          | Apercu         | ✓ light + dark |
+| **Platform**  | Codecademy learning environment | Apercu         | ✓ light + dark |
+| **LX Studio** | LX Studio application           | Hanken Grotesk | light only     |
+
+The active theme is set at the app root via `<GamutProvider>`. When designing, know which theme your screen targets — it affects primary colors, font families, and available color weights.
+
+**Font licensing**: Apercu is licensed for codecademy.com only. LX Studio uses Hanken Grotesk.
+
+For Percipio projects, use `DESIGN.Percipio.md` from the same package instead.
+
+### LX Studio theme overrides
+
+LX Studio extends Core with these differences:
+
+**Font**: All families → `"Hanken Grotesk"` (no Apercu, no Suisse).
+
+**Border radii** (all values shift up one step):
+
+| Token | Core | LX Studio |
+| ----- | ---- | --------- |
+| `sm`  | 2px  | 4px       |
+| `md`  | 4px  | 8px       |
+| `lg`  | 8px  | 12px      |
+
+**Semantic color overrides (light mode)**:
+
+| Token                | Core value          | LX Studio value                 |
+| -------------------- | ------------------- | ------------------------------- |
+| `primary`            | hyper-500 `#3A10E5` | `#5628FE` (lxStudioPurple)      |
+| `primary-hover`      | hyper-400 `#5533FF` | `#7955FC` (lxStudioPurpleHover) |
+| `interface`          | hyper-500           | hyper-500 (unchanged)           |
+| `feedback-success`   | green-700 `#008A27` | `#06844F` (lxStudioSuccess)     |
+| `background-primary` | beige `#FFF0E5`     | `#FAFBFC` (lxStudioBgPrimary)   |
+| `shadow-primary`     | navy-800            | navy-200                        |
+| `border-primary`     | navy-800            | navy-400                        |
+| `border-disabled`    | navy-500            | navy-300                        |
+
+---
+
+## Semantic Color Aliases
+
+Use these token names when specifying colors in designs. They resolve to the correct raw value for the active theme and color mode automatically. **Never hardcode hex values** for anything that needs to adapt across modes.
+
+### Text
+
+| Token            | Light                      | Dark            | Use for                     |
+| ---------------- | -------------------------- | --------------- | --------------------------- |
+| `text`           | navy-800 `#10162F` at 100% | white `#ffffff` | Default body and UI text    |
+| `text-accent`    | navy-900 `#0A0D1C`         | beige `#FFF0E5` | Stronger emphasis text      |
+| `text-secondary` | navy-800 at 75%            | white at 65%    | Supporting / secondary copy |
+| `text-disabled`  | navy-800 at 63%            | white at 50%    | Disabled state labels       |
+
+### Background
+
+| Token                 | Light              | Dark                 | Use for                           |
+| --------------------- | ------------------ | -------------------- | --------------------------------- |
+| `background`          | white `#ffffff`    | navy-800 `#10162F`   | Default page/component background |
+| `background-primary`  | beige `#FFF0E5`    | navy-900 `#0A0D1C`   | Slightly elevated surfaces        |
+| `background-contrast` | white              | black `#000000`      | Maximum contrast surface          |
+| `background-selected` | navy-800 at 4%     | white at 4%          | Selected row / item               |
+| `background-hover`    | navy-800 at 12%    | white at 9%          | Hover state overlay               |
+| `background-disabled` | navy-800 at 12%    | white at 9%          | Disabled surface                  |
+| `background-success`  | green-0 `#F5FFE3`  | green-900 `#151C07`  | Success state container           |
+| `background-warning`  | yellow-0 `#FFFAE5` | yellow-900 `#211B00` | Warning state container           |
+| `background-error`    | red-0 `#FBF1F0`    | red-900 `#280503`    | Error state container             |
+
+### Interactive
+
+| Token             | Light                | Dark                 | Use for                                       |
+| ----------------- | -------------------- | -------------------- | --------------------------------------------- |
+| `primary`         | hyper-500 `#3A10E5`  | yellow-500 `#FFD300` | Primary CTA, links, focus rings               |
+| `primary-hover`   | hyper-400 `#5533FF`  | yellow-400 `#CCA900` | Hover state of primary interactive            |
+| `primary-inverse` | yellow-500 `#FFD300` | hyper-500 `#3A10E5`  | Primary on a colored background               |
+| `secondary`       | navy-800 `#10162F`   | white `#ffffff`      | Secondary CTA, ghost buttons                  |
+| `secondary-hover` | navy-800 at 86%      | white at 80%         | Hover state of secondary interactive          |
+| `interface`       | hyper-500 `#3A10E5`  | yellow-500 `#FFD300` | UI affordances (checkboxes, toggles, sliders) |
+| `interface-hover` | hyper-400 `#5533FF`  | yellow-400 `#CCA900` | Hover on interface elements                   |
+| `danger`          | red-500 `#E91C11`    | red-300 `#E85D7F`    | Destructive actions, error states             |
+| `danger-hover`    | red-600 `#BE1809`    | red-400 `#DC5879`    | Hover on danger interactive                   |
+
+### Border
+
+| Token              | Light              | Dark            | Use for                    |
+| ------------------ | ------------------ | --------------- | -------------------------- |
+| `border-primary`   | navy-800 `#10162F` | white `#ffffff` | Strong borders, dividers   |
+| `border-secondary` | navy-800 at 75%    | white at 65%    | Medium-weight borders      |
+| `border-tertiary`  | navy-800 at 28%    | white at 20%    | Subtle borders, separators |
+| `border-disabled`  | navy-800 at 63%    | white at 50%    | Disabled input borders     |
+
+### Feedback
+
+| Token              | Light               | Dark                | Use for                          |
+| ------------------ | ------------------- | ------------------- | -------------------------------- |
+| `feedback-error`   | red-600 `#BE1809`   | red-300 `#E85D7F`   | Error messages, validation       |
+| `feedback-success` | green-700 `#008A27` | green-400 `#AEE938` | Success messages, confirmations  |
+| `feedback-warning` | yellow `#FFD300`    | yellow-0 `#FFFAE5`  | Warning messages, caution states |
+
+### Shadow
+
+| Token              | Light           | Dark         |
+| ------------------ | --------------- | ------------ |
+| `shadow-primary`   | navy-800        | white        |
+| `shadow-secondary` | navy-800 at 75% | white at 65% |
+
+---
+
+## Raw Color Palette
+
+All colors available as static tokens regardless of color mode. Use these only when a color should be **fixed** and not adapt to dark mode.
+
+### Core Palette
+
+| Name            | Weights available            | Notes                                                                             |
+| --------------- | ---------------------------- | --------------------------------------------------------------------------------- |
+| `navy`          | 100–900                      | 100–700 are rgba transparencies of `#10162F`; 800 = `#10162F`; 900 = `#0A0D1C`    |
+| `white`         | 100–700                      | rgba transparencies of `#ffffff` (no solid white weight — use `white` for `#fff`) |
+| `blue`          | 0, 100, 300, 400, 500, 800   | 500 = `#1557FF`                                                                   |
+| `hyper`         | 400, 500                     | 500 = `#3A10E5` (purple-blue), 400 = `#5533FF`                                    |
+| `green`         | 0, 100, 400, 700, 900        | 700 = `#008A27`                                                                   |
+| `yellow`        | 0, 400, 500, 900             | 500 = `#FFD300`                                                                   |
+| `red`           | 0, 300, 400, 500, 600, 900   | 500 = `#E91C11`                                                                   |
+| `gray`          | 100, 200, 300, 600, 800, 900 |                                                                                   |
+| `pink`          | 0, 400                       | 400 = `#F966FF`                                                                   |
+| `orange`        | 100, 500                     | 500 = `#FF8C00`                                                                   |
+| `beige`         | 100 (alias: `beige`)         | `#FFF0E5`                                                                         |
+| `black`         | —                            | `#000000`                                                                         |
+| `white` (solid) | —                            | `#ffffff`                                                                         |
+
+**Named aliases** (shorthand for common weights):
+`beige`, `blue`, `green`, `hyper`, `lightBlue`, `lightGreen`, `navy`, `orange`, `paleBlue`, `paleGreen`, `palePink`, `paleRed`, `paleYellow`, `pink`, `red`, `yellow`, `black`, `white`
+
+### Platform-only additions
+
+`lightBeige` (`#FFFBF8`), `gold` (`#8A7300`), `teal` (`#006D82`), `purple` (`#B3CCFF`)
+
+### LX Studio additions
+
+`lxStudioPurple` (`#5628FE`), `lxStudioPurpleHover` (`#7955FC`), `lxStudioSuccess` (`#06844F`)
+
+---
+
+## Typography
+
+### Typefaces
+
+| Token       | Core / Admin / Platform                                  | LX Studio                                             | Use for                                          |
+| ----------- | -------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------ |
+| `base`      | Apercu Pro (CSS: `Apercu`)                               | Hanken Grotesk                                        | All default UI text, headlines, body copy        |
+| `accent`    | Suisse Intl Mono (CSS: `Suisse`); falls back to `Apercu` | Hanken Grotesk                                        | Code, captions, labels, lists, technical context |
+| `monospace` | Monaco, Menlo, Ubuntu Mono, Droid Sans Mono, Consolas    | Monaco, Menlo, Ubuntu Mono, Droid Sans Mono, Consolas | Code editor contexts                             |
+| `system`    | System UI fonts                                          | System UI fonts                                       | Performance-critical surfaces                    |
+
+**Apercu is licensed for codecademy.com only.** LX Studio uses Hanken Grotesk for both `base` and `accent`.
+
+### Rules
+
+- **Apercu Bold** for headlines, sub-headlines, CTAs, and buttons.
+- **Apercu Regular** for body text, UI labels, and menu items.
+- **Apercu Italic** to emphasize text within a Regular paragraph — not Bold.
+- **Suisse** sparingly: code snippets, enumerated items, quotations, captions. Reads 10–15% large for its point size — size down relative to Apercu (14px Suisse ≈ 16px Apercu visually).
+- Text is **left-aligned** by default. Center-align only for short marketing headlines. Never right-align.
+- Do not adjust letter-spacing.
+
+### Font size scale
+
+| Token key | Size | Common use                   |
+| --------- | ---- | ---------------------------- |
+| `64`      | 64px | Hero / display               |
+| `44`      | 44px | Page titles                  |
+| `34`      | 34px | Section titles               |
+| `26`      | 26px | Sub-section titles           |
+| `22`      | 22px | Card titles, large UI labels |
+| `20`      | 20px | Secondary titles             |
+| `18`      | 18px | Large body, intro text       |
+| `16`      | 16px | Default body text            |
+| `14`      | 14px | Small body, captions, labels |
+
+### Font weight scale
+
+| Token   | Value | Use                      |
+| ------- | ----- | ------------------------ |
+| `base`  | 400   | Body text, UI labels     |
+| `title` | 700   | Headlines, CTAs, buttons |
+
+### Line height scale
+
+| Token         | Value | Use                                              |
+| ------------- | ----- | ------------------------------------------------ |
+| `base`        | 1.5   | Body text (150% — aim for 150–175% of font size) |
+| `spacedTitle` | 1.3   | Sub-headlines and medium titles                  |
+| `title`       | 1.2   | Large headlines (aim for 100–110% of font size)  |
+
+### Line length
+
+Target 45–85 characters per line; 66 characters is ideal for web body text. Max 50 characters for multi-column layouts.
+
+---
+
+## Spacing Scale
+
+All spacing is multiples of 4px, placed on an 8px grid.
+
+| Token | Value |
+| ----- | ----- |
+| `0`   | 0     |
+| `4`   | 4px   |
+| `8`   | 8px   |
+| `12`  | 12px  |
+| `16`  | 16px  |
+| `24`  | 24px  |
+| `32`  | 32px  |
+| `40`  | 40px  |
+| `48`  | 48px  |
+| `64`  | 64px  |
+| `96`  | 96px  |
+
+---
+
+## Depth & Elevation
+
+Gamut uses border-based and shadow-based depth cues rather than a rigid z-elevation tier system.
+
+### Shadow tokens
+
+Shadow props accept standard CSS `box-shadow` syntax. Always use `shadow-primary` / `shadow-secondary` color tokens so shadows remain visible in both light and dark modes.
+
+```
+box-shadow: 0 4px 0 <shadow-primary>   → Card "outline" shadow
+box-shadow: 0 0 4px rgba(0,0,0,.15)    → Subtle ambient shadow
+```
+
+### Card shadow variants
+
+| Variant          | Effect                                                 | Use for                        |
+| ---------------- | ------------------------------------------------------ | ------------------------------ |
+| `none` (default) | No shadow                                              | Static / non-interactive cards |
+| `outline`        | Solid shadow on bottom + left/right using border color | Standard clickable cards       |
+| `patternLeft`    | Decorative checker pattern on bottom + left            | Stylized content cards         |
+| `patternRight`   | Decorative checker pattern on bottom + right           | Stylized content cards         |
+
+Interactive cards (`isInteractive` prop) gain a shadow on hover and `borderRadius: md`. Cards with a pattern drop the pattern on hover.
+
+### Z-index
+
+| Token     | Value | Use                |
+| --------- | ----- | ------------------ |
+| `headerZ` | 15    | Global page header |
+
+---
+
+## Border Radius Scale
+
+| Token  | Value | Use                                        |
+| ------ | ----- | ------------------------------------------ |
+| `none` | 0px   | Square / non-interactive elements          |
+| `sm`   | 2px   | Subtle rounding, tags                      |
+| `md`   | 4px   | Default buttons, inputs, interactive cards |
+| `lg`   | 8px   | Cards, panels                              |
+| `xl`   | 16px  | Large cards, modals                        |
+| `full` | 999px | Pills, avatars, circular elements          |
+
+---
+
+## Responsive Behavior
+
+Mobile-first. Apply styles from the named breakpoint and up.
+
+### Breakpoints & screen sizes
+
+| Token    | Min-width | Screen dimensions | Max content | Fold height |
+| -------- | --------- | ----------------- | ----------- | ----------- |
+| _(base)_ | 0         | 320×480           | 288px       | 440px       |
+| `xs`     | 480px     | 480×900           | 448px       | 440px       |
+| `sm`     | 768px     | 768×1024          | 704px       | 680px       |
+| `md`     | 1024px    | 1024×768          | 896px       | 680px       |
+| `lg`     | 1200px    | 1200×900          | 1072px      | 680px       |
+| `xl`     | 1440px    | 1440×900          | 1248px      | 680px       |
+
+Container query variants (`c_xs` through `c_xl`) mirror these values but trigger on component container size, not viewport.
+
+### Grid
+
+12-column grid at all breakpoints. The designer specifies how many columns a section spans per breakpoint.
+
+| Usage                 | Recommended values                               |
+| --------------------- | ------------------------------------------------ |
+| Horizontal margins    | 64px (lg+), 48px (md), 32px (sm/xs), 16px (base) |
+| Column gaps (gutters) | 32px (lg+), 24px (md), 16px (sm/xs), 8px (base)  |
+| Row gaps              | 32px (lg+), 24px (md), 16px (sm/xs), 8px (base)  |
+
+### Touch targets
+
+Minimum interactive touch target: **44×44px** on mobile breakpoints.
+
+### Collapsing strategies
+
+- Begin design work at 1440px (XL), then adapt to smaller sizes.
+- Wider multi-column layouts collapse to fewer columns — do not simply stretch or squish.
+- Elements not in an explicit lockup (e.g., catalog cards) should align on one axis (usually left) rather than fill column widths.
+- Avoid dense or small components in the base (mobile) breakpoint.
+
+---
+
+## Component Library
+
+Components are organized into three tiers:
+
+### Atoms — foundational, single-purpose
+
+Badge, Button (FillButton, StrokeButton, CTAButton, TextButton, IconButton), ButtonBase, Card, Checkbox, CodeBlock, ColorMode, Drawer, FlexBox, FormGroup, GridBox, HiddenText, Icon, Input, Label, Loader, Radio, Select, Spinner, Tag, TextArea, Toggle, Tooltip
+
+### Molecules — composed of atoms, handle a discrete task
+
+Alert, Anchor, Breadcrumbs, Coachmark, Disclosure, GridForm, Markdown, Menu, Modal, Pagination, Popover, ProgressBar, Table, Tabs, Toast, Toaster, Video
+
+### Organisms — page-level compositions
+
+ContentContainer, GridContainer, Layout, LayoutGrid
+
+### Key component patterns
+
+#### Buttons
+
+| Variant           | Component      | Use for                             |
+| ----------------- | -------------- | ----------------------------------- |
+| Primary action    | `FillButton`   | Solid fill, high-emphasis CTA       |
+| Secondary action  | `StrokeButton` | Outlined, secondary CTA             |
+| Marketing CTA     | `CTAButton`    | High-visibility promotional actions |
+| Tertiary / inline | `TextButton`   | Low-emphasis, inline text actions   |
+| Icon-only         | `IconButton`   | Compact actions with icon only      |
+
+All button variants support sizes: `small`, `normal` (default), `large`. They accept an `icon` prop (leading or trailing) and a `disabled` prop. Passing `href` renders the button as an `<a>` tag.
+
+**States**: default → hover (`primary-hover` / `secondary-hover`) → active → disabled (`text-disabled` + `background-disabled`).
+
+#### Cards
+
+Cards support:
+
+- **Background variants**: `default` (ColorMode-responsive), `white`, `yellow`, `beige` (light contexts), `navy`, `hyper` (dark contexts)
+- **Shadow variants**: `none` (default), `outline`, `patternLeft`, `patternRight`
+- **Interaction**: wrap in `<Anchor>` and add `isInteractive` for hover shadow + `borderRadius: md`
+- **Border radius**: defaults to `none` (non-interactive); override with the `borderRadius` prop as needed
+
+#### Color-aware components
+
+- **`<ColorMode mode="light|dark|system">`** — wraps a subtree in an explicit color mode.
+- **`<Background bg="<color>">`** — applies a background color and automatically switches the color mode inside to maintain accessible contrast. Prefer this over setting a raw `bg` prop on any content-bearing surface.
+
+---
+
+## Global Elements
+
+| Token          | Value                                  | Use                             |
+| -------------- | -------------------------------------- | ------------------------------- |
+| `headerHeight` | 4rem (64px) base, 5rem (80px) at `md`+ | Global page header height       |
+| `headerZ`      | 15                                     | Z-index for global page headers |
+
+---
+
+## Do's and Don'ts
+
+### Colors
+
+- **Do** use semantic color aliases (`primary`, `text`, `background`, etc.) for any UI that must adapt to color mode or theme.
+- **Do** use `<Background bg="...">` when setting a section background — it adjusts the inner color mode for contrast automatically.
+- **Don't** hardcode hex values for anything adaptive.
+- **Don't** use navy or white semi-transparent swatches where they may overlap unpredictably.
+
+### Typography
+
+- **Do** use `title` weight (700) for headlines, CTAs, and buttons.
+- **Do** keep body text at 150–175% line height for readability.
+- **Do** use Suisse sparingly — as an accent for code, captions, and lists only.
+- **Don't** use Apercu Bold to emphasize text _within_ a paragraph — use Italic instead.
+- **Don't** adjust letter-spacing.
+- **Don't** right-align text in normal circumstances.
+- **Don't** center-align body paragraphs with long line lengths.
+
+### Layout & Spacing
+
+- **Do** use multiples of 8px for block-element spacing (4px only for inline / typographic relationships).
+- **Do** begin design work at 1440px (XL), then adapt down to each breakpoint.
+- **Do** align elements to the 12-column grid.
+- **Don't** stretch elements to fill wider space — maintain proper line lengths and component widths.
+
+### Components
+
+- **Do** use `FillButton` for primary actions and `StrokeButton` for secondary actions.
+- **Do** add `isInteractive` to any `Card` that is wrapped in an `<Anchor>`.
+- **Don't** use `CTAButton` for standard UI actions — reserve it for marketing/high-visibility promotions.
+- **Don't** use `<Background>` without an actual color value — it's not a neutral wrapper.
+
+---
+
+## Agent Prompt Guide
+
+Quick color/token reference for generating or specifying UI:
+
+| Scenario               | Tokens                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------------------- |
+| Primary button (light) | `bg: primary (#3A10E5)`, `color: white`, `hover: primary-hover (#5533FF)`                             |
+| Primary button (dark)  | `bg: primary (#FFD300)`, `color: navy-800`, `hover: primary-hover (#CCA900)`                          |
+| Body text              | `color: text`, `font: base (Apercu Pro)`, `size: 16px`, `weight: 400`, `lineHeight: base (1.5)`       |
+| Headline               | `color: text-accent`, `font: base`, `size: 34–64px`, `weight: title (700)`, `lineHeight: title (1.2)` |
+| Caption / label        | `color: text-secondary`, `font: accent (Suisse Int'l Mono)`, `size: 14px`                             |
+| Card default           | `bg: background`, `borderRadius: none` — add `isInteractive` for hover shadow + `borderRadius: md`    |
+| Error state            | `color: feedback-error`, `bg: background-error`, `border: danger`                                     |
+| Success state          | `color: feedback-success`, `bg: background-success`                                                   |
+| Disabled state         | `color: text-disabled`, `bg: background-disabled`, `border: border-disabled`                          |
+
+### Component token cheatsheet
+
+```
+FillButton      → bg: primary,      color: white,        hover: primary-hover
+StrokeButton    → bg: transparent,  border: secondary,   hover: secondary-hover
+CTAButton       → high-visibility; use primary-inverse on colored surfaces
+Card (light)    → variant: "default" | "white" | "yellow" | "beige"
+Card (dark)     → variant: "navy" | "hyper"
+Alert (error)   → uses feedback-error + background-error
+Alert (success) → uses feedback-success + background-success
+Alert (warning) → uses feedback-warning + background-warning
+ColorMode       → <ColorMode mode="light|dark|system">
+Background      → <Background bg="hyper"> — auto-flips color mode for contrast
+```
+
+---
+
+## Figma ↔ Code Mapping
+
+52 components have Code Connect entries in `packages/code-connect/`. These appear as live code snippets in Figma's inspect panel when you select a component.
+
+Figma layer names use emojis as visual shorthand (e.g. `✏️ label`, `👁 leading icon`, `↳ trailing icon`). These map to named props in the React components.
+
+To publish updated code snippets after changing a component:
+
+```
+npx figma connect publish --token <your-figma-token>
+```