Skip to content

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

Draft
dreamwasp wants to merge 61 commits into
cass-gmt-1825-color-legacy-brandsfrom
cass-gmt-1825-color-docs
Draft

dreamwasp wants to merge 61 commits into
cass-gmt-1825-color-legacy-brandsfrom
cass-gmt-1825-color-docs

Conversation

@dreamwasp

@dreamwasp dreamwasp commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

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

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

🤖 Generated with Claude Code

dreamwasp and others added 4 commits October 29, 2026 10:39
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 dreamwasp left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

dreamwasp and others added 3 commits November 4, 2026 09:42
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- 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 dreamwasp left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

| `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 |

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

);
```

### Give raised surfaces a hairline

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

dreamwasp and others added 2 commits November 4, 2026 10:17
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t pairings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dreamwasp and others added 8 commits November 4, 2026 11:19
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>
… 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>
dreamwasp and others added 2 commits November 10, 2026 09:09
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>
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
…s' into cass-gmt-1825-color-white-label

# 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 2 commits November 13, 2026 10:54
Roboto 500 and 700 share one bold file, so the preload list had two links
with the same key (the file URL), and React warned about duplicate keys.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Roboto 500 and 700 share one bold file, so the preload list had two links
with the same key (the file URL), and React warned about duplicate keys.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
dreamwasp and others added 15 commits November 19, 2026 14:58
…gration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit bb684b9)
…gration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit bb684b9)
…igration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit b35dc09)
…igration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit b35dc09)
… skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 552d148)
… skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 552d148)
…ser in the gamut-migration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 7d92c95)
…ser in the gamut-migration skill

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 7d92c95)
…ate-stylis symptom

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 0dc47cf)
…ate-stylis symptom

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 0dc47cf)
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 53cce61)
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
(cherry picked from commit 53cce61)
# Conflicts:
#	packages/gamut-brand/src/__tests__/system.test.ts
#	packages/gamut-styles/src/colorSystem/__tests__/sandboxParity.test.ts
#	packages/gamut-styles/src/stylingContract.test.tsx
#	packages/gamut-styles/src/themes/brandElevation.test.ts
#	packages/gamut-styles/src/themes/theme.test.ts
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
# Conflicts:
#	.changeset/color-system-brands.md
#	packages/gamut-brand/README.md
#	packages/gamut-styles/src/themes/__tests__/__snapshots__/theme.test.ts.snap
#	packages/gamut-styles/src/themes/__tests__/theme.test.ts
dreamwasp added a commit that referenced this pull request Nov 20, 2026
Replaces this branch's tree with the color stack as it now stands: the
site branch (#67, which includes #63, #59, #54, #66, #58, #52 and #50,
each merged with main through 45586df), plus the codemod branch (#53).
Static styles (#69) is still out, as before.

The preview's earlier head is the parent. This commit only moves the
tree forward, so nothing is rewritten.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
dreamwasp and others added 5 commits November 20, 2026 11:34
* build: remove unused macros package and test deps

title.macro hasn't been imported since the Storybook 8 move, which
relies on auto-titles. Also drop babel-plugin-macros and the unused
@testing-library/react-hooks and react-test-renderer.

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

* test: drop the Date pin from the Storybook setup

Story tests pass unpinned and pinned to month-, year-, and leap-day
edges. Unpinned, a11y checks also cover the "today" cell.

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

* test: colocate unit tests next to their source

Move every test out of __tests__/tests folders and split codemods'
lib.test.ts per module. Still runs on Jest; keep tests out of builds,
coverage, and npm.

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

* test: run unit tests on Vitest

Add jsdom and node Vitest projects alongside storybook, port every
non-story test from Jest (and agent-tools from node:test), and run them
all from one vitest:test Nx target. Jest stays installed until the next PR.

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

* build: remove Jest

Delete the Jest configs, preset, script/jest, and the nx target
default. Drop the Jest packages; add jsdom directly for Vitest.

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

* build: remove unused Babel configs

babel-jest was their last reader; tsdown, Storybook (SWC), and SVGR
(configFile: false) never load them. Build output is unchanged.

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

* Drop vitest Nx project left over from main merge

Use main's per-package test targets.

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

* changeset

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

❌ 3 Tests Failed:

Tests completed Failed Passed Skipped
1287 3 1284 0
View the top 3 failed test(s) by shortest run time
packages/gamut/src/Alert/__tests__/Alert.test.tsx > packages/gamut/src/Alert/__tests__/Alert.test.tsx
Stack Traces | 0s run time
Error: [vitest] There was an error when mocking a module. If you are using "vi.mock" factory, make sure there are no top level variables inside, since this call is hoisted to top of the file. Read more: https://vitest.dev/api/vi.html#vi-mock
 ❯ .../src/Alert/Alert.tsx:5:1

Caused by: Caused by: ReferenceError: jest is not defined
 ❯ .../Alert/__tests__/Alert.test.tsx:18:29
 ❯ .../src/Alert/Alert.tsx:5:1
packages/gamut/src/Card/Card.test.tsx > useCardElevation > resolves borderRadius from percipioTheme
Stack Traces | 0.00184s run time
TypeError: Cannot read properties of undefined (reading 'borderRadii')
 ❯ forEach .../src/Card/Card.test.tsx:78:21
 ❯ .../src/Card/Card.test.tsx:64:35
packages/gamut/src/Card/Card.test.tsx > useCardElevation > resolves borderRadius from coreTheme
Stack Traces | 0.00739s run time
TypeError: Cannot read properties of undefined (reading 'borderRadii')
 ❯ forEach .../src/Card/Card.test.tsx:78:21
 ❯ .../src/Card/Card.test.tsx:64:35

To view more test analytics, go to the Test Analytics Dashboard
📋 Got 3 mins? Take this short survey to help us improve Test Analytics.

dreamwasp and others added 8 commits November 20, 2026 11:50
main removed Jest and Babel (#81). gamut-brand's test target still pointed at
the Jest base config, which is gone. The package now runs under the Vitest node
project like the other packages, and its test files import Vitest.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants