docs(gamut-docs): add the color system concept page by dreamwasp · Pull Request #59 · Codecademy/skillsoft-gamut

dreamwasp · 2026-10-29T14:40:23Z

Overview

Adds a gamut-docs concept page on the generated color system: how it works, how to use it, and what's better and worse than the old color names.

Docs

concepts/color-system.md: covers:
- brand inputs, the OKLCH palette, the 43 roles, and the build-time checks
- the three outputs, how GamutProvider puts tokens.css on the page, and mode and brand attributes
- intended use, with a job-to-role table, text-inverse, status tint plus ink, Background, viz-* and app setup
- an honest comparison with the old system
concepts/index.md: links the page. The Concepts sidebar is generated, so astro.config.mjs doesn't change.

Every role name, CSS variable, prop and import path on the page is checked against the code on this branch. Stacked on #58, so it lists all six brands. It's kept in step with design's changes from 2026-10-29: status alerts carry their ink on the message and on a floating border, and Original Codecademy no longer pins navy and beige. Status separation is described as reported, not enforced, because that's what probe.ts does.

Not in this PR

concepts/color-modes.md, foundations/design-tokens.md, foundations/themes.md and guides/supporting-dark-mode.md still describe the old aliases here. #67 moves them, and the rest of the site, onto roles. The codemod (#53) isn't named until it lands.

PR Checklist

Related to designs: gamut-sandbox PR fix: update spinner to match cc gamut #34
Related to JIRA ticket: GMT-1825
Version plan added/updated (docs only)
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

cd packages/gamut-docs && npx astro build: the build completes.
npx astro dev and open /concepts/color-system/: the page renders, it's in the Concepts sidebar, and its links work.
Check the code samples against packages/gamut-styles/src/colorSystem/roles.ts.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…udio brands Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…olor-docs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dreamwasp

Kept in step with today's design fixes in #52.

dreamwasp · 2026-10-29T16:11:18Z

+
+### Pair a status tint with a status ink
+
+A status message is a tint behind and an ink on top. An error box uses `surface-error` for the background and `text-error` for the icon and the message; each status ink clears text contrast on its own tint. A floating `Alert` takes the same ink on its border. Show warnings with an icon, not color alone.


Updated for design's Alert change (sandbox 15c2195): the status ink now carries the message as well as the icon, and a floating Alert's border. Line 50 also reflects that Original Codecademy no longer pins navy and beige.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…s' into cass-gmt-1825-color-docs

- 45 roles: the shadow-* group (key, ambient, scrim) replaces backdrop. - surface-raised is the lighter surface step, not a depth; navs and headers are surface-default, fields surface-raised. - New guidance: raised surfaces take a border-subtle hairline, floating ones add a shadow, Card is default or brand. - Brand role overrides need both attributes on one element. - Elevation: old Core's hard offset for Original Codecademy, soft shadows elsewhere. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dreamwasp

Kept in step with design's sandbox update, 2026-11-03 (df33b47), as ported in #52, #58 and #54.

dreamwasp · 2026-11-04T14:43:17Z

+| `action-*`  | `primary`, `danger` and `neutral`, each with `-hover` and `-pressed`; `disabled`      | Interactive fills and inks: buttons, links, toggles              |
+| `state-*`   | `hover`, `pressed`, `selected`                                                        | Translucent layers over elements that have no fill of their own  |
+| `viz-*`     | `1` to `8` (categorical), `seq-1` to `seq-4` (sequential)                             | Charts                                                           |
+| `shadow-*`  | `key`, `ambient`, `scrim`                                                             | Shadow colors and the dimmed layer behind a modal                |


Design's sandbox update, 2026-11-03: backdrop becomes shadow-scrim, and shadow-key / shadow-ambient are the two layers every elevation shadow draws.

dreamwasp · 2026-11-04T14:43:17Z

+);
+```
+
+### Give raised surfaces a hairline


Design's sandbox update, 2026-11-03: every card and floating surface takes a border-subtle hairline and the shadow does the separating; Card collapses to default and brand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…t pairings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…olor-docs

…s' into cass-gmt-1825-color-docs

Each brand theme now carries and injects only its own brand's CSS (about 21 KB, down from 56 KB for every brand at once). The CSS puts the brand's palette and initial mode on :root, and folds its role overrides into its mode blocks. Every brand resolves to the same values as before in both modes. The generator, role table, checks, sandbox fixture and gamut's brand inputs move from gamut-styles' src/colorSystem to a new build-time package, @skillsoft/gamut-brand. Its `gamut-brand build` CLI writes a brand's values.ts, tokens.css and DTCG JSON (--watch, --check), and refuses a brand that fails a check, including on its own tokens.css read back. gamut-styles' build:tokens uses the same writeBrand on gamut's five brands. - createBrandTheme, BrandBase and BrandValues are exported. A team's theme has the same type as gamut's, so system props stay typed. - BREAKING: generated files move to one folder per brand (tokens/<brand>.css, tokens/<brand>/*.tokens.json; tokens.css stays the default brand). initialMode moves from the theme onto the brand. - DTCG mode files include each brand's role overrides. - Role names in brand overrides are typed (ROLE_TOKENS). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…or-docs

… your own brand Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Sandbox parity only matters while the port is in development. The generator is now held to its own rules for any hue (fixed lightness per grade, chroma inside sRGB, the separation guarantee, one role mapping for every brand, every check passing) instead of a saved copy of the sandbox's output. The checked-in generated files still catch value drift. Drops the sandbox fixture, dump script and comments that pointed at sandbox commits and files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…or-docs

Covers the variance createTheme and gamut-styles ColorMode prefixes, the gamut-brand Style Dictionary prefix, the docs and the regenerated tokens. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

…s' into cass-gmt-1825-color-docs # Conflicts: # .changeset/color-system-brands.md # packages/gamut-brand/src/__tests__/system.test.ts # packages/gamut-styles/scripts/build-tokens.ts # packages/gamut-styles/scripts/validate-tokens.ts # packages/gamut-styles/src/colorSystem/README.md # packages/gamut-styles/src/themes/__tests__/__snapshots__/theme.test.ts.snap # packages/gamut-styles/src/themes/__tests__/brandElevation.test.ts # packages/gamut-styles/src/themes/__tests__/theme.test.ts # packages/gamut-styles/src/themes/platform.ts # packages/gamut-styles/src/tokens/generated/tokens.css # packages/gamut-styles/src/tokens/generated/tokensCss.ts

dreamwasp and others added 4 commits October 29, 2026 10:39

docs(gamut-docs): add the color system concept page

399c188

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(gamut-docs): list the rebuilt admin, platform, percipio and lxSt…

ed1f8a6

…udio brands Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge branch 'cass-gmt-1825-color-legacy-brands' into cass-gmt-1825-c…

e5165c3

…olor-docs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(gamut-docs): navy and beige unpinned; status alerts carry their ink

41c22f7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dreamwasp commented Oct 29, 2026

View reviewed changes

dreamwasp and others added 3 commits November 4, 2026 09:42

docs(gamut-docs): percipioTheme is removed; five brands ship

fcd29d1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/cass-gmt-1825-color-legacy-brand…

f11a9dd

…s' into cass-gmt-1825-color-docs

dreamwasp commented Nov 4, 2026

View reviewed changes

dreamwasp and others added 2 commits November 4, 2026 10:17

Merge cass-gmt-1825-color-legacy-brands into cass-gmt-1825-color-docs

0c54a72

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(gamut-docs): skillsoftTheme replaces percipioTheme; 204 componen…

bdab784

…t pairings Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dreamwasp mentioned this pull request Nov 4, 2026

chore: color stack preview (do not merge) #60

Closed

dreamwasp and others added 8 commits November 4, 2026 11:19

Merge branch 'cass-gmt-1825-color-legacy-brands' into cass-gmt-1825-c…

1f4d7fa

…olor-docs

Merge remote-tracking branch 'origin/cass-gmt-1825-color-legacy-brand…

2d9af71

…s' into cass-gmt-1825-color-docs

fix(gamut-brand): dump:sandbox writes the fixture where it moved

5a2390c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge branch 'cass-gmt-1825-color-white-label' into cass-gmt-1825-col…

75a06be

…or-docs

docs(gamut-docs): color system page covers per-brand CSS and building…

ed87041

… your own brand Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge branch 'cass-gmt-1825-color-white-label' into cass-gmt-1825-col…

ab01baf

…or-docs

This was referenced Nov 5, 2026

feat(gamut-brand)!: one tokens.css per brand, and white-label tooling #66

Draft

docs(gamut-docs): move the docs site onto the color system #67

Draft

refactor: use the singular --color- prefix for color variables

3e08400

Covers the variance createTheme and gamut-styles ColorMode prefixes, the gamut-brand Style Dictionary prefix, the docs and the regenerated tokens. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

dreamwasp mentioned this pull request Nov 10, 2026

Color stack preview: rebuilt with the --color- prefix (do not merge) #73

Draft

Navigation Menu

Repository navigation

docs(gamut-docs): add the color system concept page - #59

docs(gamut-docs): add the color system concept page#59
dreamwasp wants to merge 19 commits into
cass-gmt-1825-color-legacy-brandsfrom
cass-gmt-1825-color-docs

dreamwasp commented Oct 29, 2026 •

edited

Loading

Uh oh!

dreamwasp left a comment

Uh oh!

dreamwasp Oct 29, 2026

Uh oh!

dreamwasp left a comment

Uh oh!

dreamwasp Nov 4, 2026

Uh oh!

dreamwasp Nov 4, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		### Pair a status tint with a status ink

		A status message is a tint behind and an ink on top. An error box uses `surface-error` for the background and `text-error` for the icon and the message; each status ink clears text contrast on its own tint. A floating `Alert` takes the same ink on its border. Show warnings with an icon, not color alone.

Conversation

dreamwasp commented Oct 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR Checklist

Testing Instructions

Uh oh!

dreamwasp left a comment

Choose a reason for hiding this comment

Uh oh!

dreamwasp Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

dreamwasp left a comment

Choose a reason for hiding this comment

Uh oh!

dreamwasp Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

dreamwasp Nov 4, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dreamwasp commented Oct 29, 2026 •

edited

Loading