[dreamwasp]

Overview

Moves every gamut component onto the color system's roles, following design's component map (gamut-sandbox PR #34, Migration → Components, head ef1272a). Stacked on #52. Draft, for showing the team what the components look like on the new colors.

Screenshots: today's core next to this branch on skillsoft and originalCodecademy, light and dark, 37 stories: https://claude.ai/artifact/QJ836yQVQ6ghKHwawDqE5m (private; ask for access).

How it was made

• Ran the color-roles preset from feat(gamut-codemods): add a color-roles preset #53 on packages/gamut/src: 60 files, 273 lines. A second run changes nothing.
• Resolved the ~170 places it leaves for a person (splits, retired names, pending names, old palette colors, runtime-built names) using design's component map.

Buttons (Button/shared/variants.ts)

• variant values don't change. primary, secondary and danger map to action-primary, action-neutral and action-danger, each with its own hover and pressed step; interface merges into primary (TextButton's interface label is text-default).
• Labels on fills are text-inverse; every variant gets one action-primary focus ring; disabled fill labels are a knockout.
• StrokeButton and TextButton hover and press with state-hover / state-pressed veils instead of a gray fill and a full inversion.
• CTAButton follows primary FillButton; its offset shadow is action-neutral until there's a shadow role.

Components, by design's map

• Alert, Toast, Popover, Menu, Tip, Modals, Flyout, Overlay — floating surfaces are surface-raised with a border-default edge; the scrim is backdrop. Tooltips are no longer black.
• Form, GridForm, ConnectedForm, Toggle — fields on surface-raised, hover darkens the outline (border-strong) so blue only means focus; a checked Radio is action-primary; Toggle disabled is action-disabled instead of 50% opacity.
• Card — yellow and hyper become a featured card on the brand gradient (Alert's gradient layer moved to utils/gradientLayer.ts so both use it); navy is a dark-mode scope; every card gets a border-subtle hairline.
• Badge, Tag — filled badges are text-default / text-subtle behind text-inverse; accent is surface-brand with a border-default edge.
• Tabs, Disclosure, Pagination, Anchor — block Tabs follow the page's mode instead of forcing dark; Disclosure focus is a ring, not a fill.
• ProgressBar, DataList, List, BarChart, Markdown, Video, Loading, Typography and the rest — mapped by the closest documented rule; see "Choices" below.

Choices where design has no exact mapping (each has a /* */ comment at the spot)

• background-current stays in List, Drawer, DataList empty rows, Card's offset shadow, RadialProgress and Text fade. Design describes a surface-current alias that every surface sets; that rename belongs in gamut-styles, as a follow-up.
• Badge accent gets the flat surface-brand, not the gradient: the gradient is sized in cqw, and a content-sized badge can't be its own container.
• DatePicker (no map): weekday headers text-subtle, today action-primary, selected day a dark chip with text-inverse, range state-selected, disabled action-disabled.
• SelectDropdown multi-value chip follows the selection Tag (text-subtle / text-inverse). Design's slot says surface-sunken but its note says "follows the selection Tag", so this needs design to pick.
• Retired primary-inverse (Text highlight) → action-primary, flagged for design.
• Video controls are always dark, so they use the mode-independent white and black.
• BarChart defaults take the plain renames; moving them onto viz-* is a follow-up.

Added 2026-10-29

• Old themes: feat(gamut-styles)!: rebuild admin, platform and lxStudio as brands; skillsoftTheme replaces percipioTheme #58 rebuilds admin, platform, percipio and lxStudio as brands and is merged in here, so every theme in the toolbar defines every role. Merge feat(gamut-styles)!: rebuild admin, platform and lxStudio as brands; skillsoftTheme replaces percipioTheme #58 first. Old coreTheme still has no roles; Original Codecademy is its rebuild.
• styleguide: its stories and docs are on roles (52 files). The type check has no color errors left; the 23 remaining errors exist on the base branch too (argTypes alias, InfoTip, BarChart, Tabs types).
• Card: an interactive card gets design's hover. The border goes to border-strong, and a state-hover veil sits under the content, on the same trigger as the existing lift. 4 new tests.
• Storybook defaults to Skillsoft and drops the old Core option.
• Tag (design feedback, 2026-10-29): navigation and suggestion tags have no fill of their own, so they sit on the surface they're on. Disabled tags drop the action-disabled fill, take action-disabled ink, and keep their edge. The selection chip at rest stays a dark chip, per design's map. Adds Tag's first tests.
• Merged in feat(gamut-styles)!: brands, overrides and Original Codecademy on the color system #52's design fixes: Alert's status inks and mode-following CTA, and navy and beige unpinned. Screenshots retaken with all seven themes.
• Judgement calls in the styleguide, for design:
  • background-selected as a resting panel → surface-sunken
  • text-disabled as muted helper text → text-subtle
  • background-contrast as a label on a fill → text-inverse
  • danger as red text → text-error
  • Tabs yellow → flat surface-brand
  • The PreviewTip avatar loses its yellow accent

Known gaps

• No shadow role yet, so elevation still renders undefined.
• BarChart onto viz-* is a follow-up.

---

PR Checklist

• Related to designs: gamut-sandbox PR #34, Migration → Components
• Related to JIRA ticket: GMT-1825
• Version plan added/updated (.changeset/color-roles-components.md)
• I have run this code to verify it works
• This PR includes unit tests for the code change
• This PR includes testing instructions for the code change

Testing Instructions

1. npx jest -c packages/gamut/jest.config.ts → 1208 of 1208 pass. On feat(gamut-styles)!: brands, overrides and Original Codecademy on the color system #52, 48 BarChart and Modal tests fail because they expect old names.
2. npx jest -c packages/gamut-styles/jest.config.ts → 280 of 280; yarn workspace @skillsoft/gamut-styles validate:tokens → every check passes for both brands.
3. Type-check gamut's library: 0 errors (145 after the codemod alone).
4. Storybook: pick Skillsoft or Original Codecademy in the theme toolbar, both modes. Check Actions → Buttons → Button Examples, Molecules → Alert, Atoms → FormInputs, Containers → Card, Overlays → Dialog. Compare with the screenshots page.
5. Switch to Core: components lose their colors. That's expected on this branch (see Known gaps).

🤖 Generated with Claude Code

[dreamwasp]

Fix from design feedback on the components comparison page (2026-10-29).

[dreamwasp]

Design feedback (2026-10-29): selection and navigation tags shouldn't have a fill. Navigation and suggestion tags were surface-raised, which shows as a white box on beige or paper pages. They're transparent now, so they sit on whatever surface they're on; hover and press stay state-hover / state-pressed veils. The selection chip at rest stays text-subtle behind text-inverse, per design's map.

[dreamwasp]

Disabled tags lose the action-disabled fill too. A knockout label (surface-raised) needs a fill under it, so the label becomes the action-disabled ink instead. This is contrast-exempt as an inactive control. The chip keeps a border-default edge as an inset shadow, so disabling it doesn't change its size. Navigation, suggestion and the dismiss button get the same treatment below.

[dreamwasp]

Port of design's sandbox update, 2026-11-03 (gamut-sandbox df33b47). Notes on the lines below.

[dreamwasp]

Design's sandbox update, 2026-11-03: Card's variants collapse to default (old default, white, beige, navy) and brand (old yellow, hyper). Navy was a dark card and now renders light; the color-roles codemod will rename the variants and comment every navy.

[dreamwasp]

Design's sandbox update, 2026-11-03: an interactive card has the raised shadow at rest and the raised-hover shadow (plus the veil) on hover, and the border no longer switches to border-strong. A card that isn't interactive has no shadow.

[dreamwasp]

Design's sandbox update, 2026-11-03: menus, popovers, tips, toasts and the SelectDropdown menu drop to a border-subtle hairline because "the shadow separates them". Most of them had no shadow, so they take the theme's raised shadow as a placeholder until design defines an overlay depth. Internal, not exported.

[dreamwasp]

Design's sandbox update, 2026-11-03: CTAButton's shadow comes from the elevation system, soft by default and the hard offset in the Codecademy theme only. Judgement call, flagged for design: the sandbox doesn't give the hard offset's geometry, so Original Codecademy's raised depth is old core's CTAButton offset (-4px at rest, -8px on hover), set in #52.

[dreamwasp]

Design's sandbox update, 2026-11-03: the Flyout panel gets a border-subtle inner edge.

[dreamwasp]

Design's sandbox update, 2026-11-03: backdrop is renamed shadow-scrim.

[dreamwasp]

Design feedback (Stacey, 2026-11-04): inputs use surface-raised. Input, TextArea, Select, SelectDropdown, Radio and the DatePicker field already did; an unchecked Checkbox had no fill, so it showed whatever it sat on. Fixed here, and Form/__tests__/fieldColors.test.tsx checks the fills.

Same commit: the other mismatches from an audit against design's component map (sandbox df33b47) and the elevation proposal (sandbox #50). They're listed in the commit message, including the DatePicker error ring that never drew and the checker pattern now drawn only on Original Codecademy.