docs: add concept pages, guides and entry-point narratives by pbroom · Pull Request #244 · pbroom/color-kit

pbroom · 2026-10-08T03:52:25Z

Summary

Docs overhaul slice S4: concept pages, guides and narratives for each entry point. A small commit on top finishes the integration with S2, S3 and #237–#241.

Content

Five concepts:
- OKLCH-canonical colors
- requested vs displayed
- planes and queries
- gamut and tolerance
- contrast
Five guides, each with one live example under src/examples/{guides,driver}:
- a headless picker with color-kit/driver
- color-kit/react
- contrast-aware palettes
- GPU and three.js interop
- performance
A narrative index.mdx for each of the core, plane, interop, compute, hct and driver entry points.
A polished /start quick start.
The mined legacy MDX is deleted.

Integration commit

Deletes the last legacy page, _legacy/api/plane-api.mdx, which had the stray "normalized" aside. Its quick start is now in S3's src/examples/plane/quick-start.tsx. No _legacy files remain.
Rewrites the content link test to check against the route registry built from the generated API data. Every /api link must name a generated page, which means the canonical entry only, so root re-exports fail. Member anchors stay with S2's drift test.
Brings the content in line with fix(driver): reject unknown gamuts and align validation error types #237–refactor(core)!: derive plane query budgets from step counts and drop PlaneWithSense #241:
- The headless picker guide notes that the driver rejects 'p3' with the same TypeError as core.
- A new "Typed input" section shows that a % in an expression is a position in the range, so 50% * 2 on [100, 200] gives 300.
- The core narrative says saturate/desaturate clamp chroma only at 0.
- The plane narrative says planeHue returns an OKLCH hue.
- No content references PlaneWithSense.

Verified

pnpm build and pnpm test pass. Docs tests pass: 792 tests, including the content link test and the API drift test.
A negative check confirms that /api/core/definePlane and /api/core/PlaneWithSense fail the link test.
The new snippet values were checked against the built facade.
These gates pass: lint, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict.
Docs chunk budget: the largest chunk is 194.8 kB against a 200 kB limit.
Docs home budget: home initial JS is 101.6 kB gzip against a 110 kB limit.
Browser checks on the built site:
- home hero drag
- /start
- /concepts/planes-and-queries
- /guides/headless-picker
- /api/plane/sense
- /api/core/Color
- ⌘K
- light and dark themes
- 375 px with no horizontal scroll
- no console errors or hydration warnings

Part of the color-kit assessment stack.

🤖 Generated with Claude Code

vercel · 2026-10-08T03:52:31Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
color-kit	Ready	Preview	Oct 10, 2026 2:51am UTC

chatgpt-codex-connector · 2026-10-08T03:52:35Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T03:56:09.712579Z	`0f9b3ac`	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

pbroom

Reviewed the full incremental PR and its corrections at 97ff2cd7a98856af5b5e069f5e451cec19c08f12. Concept/guide content reviewed; no remaining finding. No remaining actionable findings in the reviewed scope.

Independent correction re-reviews and stack preservation verification passed. At the integrated tip, lint, full build/DTS, 2,208 tests, formatting, strict agent checks and 14 built-site Chrome tests passed. All recorded actionable review threads are addressed. Hosted CI is being verified separately; this review does not authorize merge or release.

pbroom

Final re-review at 0b1fb88f5ae06b805adaf27dab741b2438c45b2f: Concept/guide content reviewed; no remaining finding. The hosted dependency-test follow-up is included; no remaining actionable findings in scope.

All 12 final stack heads now pass CI, including Node 20/22 and the plane benchmark. Final local lint, build/DTS, 2,209 tests, formatting and strict agent checks pass. The 14 built-site browser checks passed on unchanged application code; the follow-up changes only the regression test and archive lesson. Vercel previews are tracked separately while pending.

pbroom · 2026-10-10T18:47:23Z

Merge activity

Oct 10, 6:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
Oct 10, 8:26 PM UTC: Graphite rebased this pull request as part of a merge.
Oct 10, 8:27 PM UTC: @pbroom merged this pull request with Graphite.

## Summary Docs overhaul slice S2: a generated API reference built into the site. It replaces the TypeDoc HTML output that used to live in `/reference`. - **Generator** (`apps/docs/scripts/api`). It runs TypeDoc JSON for every entry point in `packages/color-kit/package.json#exports`. - The JSON is normalized into `src/generated/api.json`, plus page files per entry and per symbol, typed by `src/api/model.ts`. All of these are gitignored and built by `pnpm docs:api`. - Each declaration gets one page, in its most specific entry. Other entries list it as a re-export. - Links resolve at generation time. - **Routes**, all prerendered: - `/api`. - `/api/:entry`: domains, kind glyphs, a narrative MDX slot and re-exports. - `/api/:entry/:Symbol`: declaration, params, returns, throws, build-time highlighted examples, a notes MDX slot, see also, "also exported from" and a source link at the commit. - **`<Signature>`** implements the S1 contract. It comes with `<Params>`, `<TypeLink>` and a responsive layout with one parameter per line. - **⌘K**: symbol hits come from the API routes, ranked by name, word and initials. - **Drift test** checks three things: - every export in the facade `.d.ts` has a page - every exports subpath is documented - every `/api` link resolves Rebased onto #241 with no conflicts. The generated reference reflects the #237–#241 surface; for example, `PlaneWithSense` has no page. ## Verified - On this branch: `pnpm build` and `pnpm test`. - Builds 523 prerendered routes. - Bundle check passes: the largest chunk is 194.8 kB against a 200 kB limit, and home initial JS is 91.0 kB gzip against a 110 kB limit. - Docs tests pass: 584 tests. - At the stack top (#244): lint, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict all pass. - Browser checks at the stack top: - `/api/plane/sense` and `/api/core/Color` render. - ⌘K returns symbol hits and opens the selected page. - No horizontal scroll at 375 px. - No console errors or hydration warnings. Part of the color-kit assessment stack. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary Docs overhaul slice S3: the live plane hero on the home page, plus the example system. **Home page** - Headline: "A queryable OKLCH color engine.", set over a live hue slice of OKLCH (chroma × lightness). - `sense(plane)` answers three queries: - the sRGB region - the Display P3 boundary - the WCAG AA region on white or black, chosen by the theme - Underneath, a 160×160 `toP3Into` loop paints a display-p3 canvas. - The first frame (hue 264) is computed in Node at build time via `?build`. The SVG prerenders and hydrates from the same JSON, and `color-kit/plane` loads lazily after hydration. - Hue is set with a native range input that has `aria-valuetext`, or by dragging horizontally on the plane. Updates are rAF-throttled. - Below the hero: its own source, the install line and three "what you can ask" links. - Follow-up commit: the hero axes get every tick and separate axis titles. **Examples** - `<Example>` renders the live component above its source, which is highlighted at build time. It collapses long sources and isolates failures. - `plugins/eval-example.ts` fills in `// →` results by running each snippet against the color-kit source. This is documented in `src/examples/README.md`. - The graphics demos get `*Example` wrappers. - The old Sandpack plane quick start is now a real example in `src/examples/plane/quick-start.tsx`. **Contract changes** (backwards compatible) - `<Example>`'s `source` also accepts the `?highlighted` module. - New `collapseAfter` prop. - New `?build` imports. - Prerender links route-chunk CSS. - ESLint allows bare expressions in example snippets. Rebased onto #242 with no conflicts. The `eslint.config.js` and styles changes merged cleanly with S2's; the `api.css` import and the example-snippet rule are both kept. ## Verified - On this branch: `pnpm build` and `pnpm test`. - Bundle check passes: the largest chunk is 194.8 kB against a 200 kB limit, and home initial JS is 100.2 kB gzip against a 110 kB limit. - Docs tests pass: 601 tests. - At the stack top (#244): lint, format:check, typecheck, size, check:artifacts, check:preprod and agents:check:strict all pass. - Browser checks at the stack top: - Dragging the hero hue slider from 264° to 65° recomputes the geometry (about 3.8 ms of queries plus paint). - In light theme the contrast reference flips to white. - At 375 px the hero fits with no horizontal scroll. - No console errors or hydration warnings. Part of the color-kit assessment stack. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Five concepts (OKLCH-canonical colors, requested vs displayed, planes and queries, gamut and tolerance, contrast) and five guides (headless picker with color-kit/driver, color-kit/react, contrast-aware palettes, GPU and three.js interop, performance), each with one live example under src/examples/{guides,driver}. Narrative index.mdx for the core, plane, interop, compute, hct and driver entry points, a polished /start quick start, and a test that internal links resolve to real pages, anchors and canonical API symbols. Mined legacy MDX is deleted; plane-api.mdx stays for the plane quick start. Co-Authored-By: Claude Opus 5.5 <[email protected]>

Delete the last legacy page (_legacy/api/plane-api.mdx); its quick start now lives in src/examples/plane and its prose in the plane narrative and concepts. The content link test now resolves internal links against the route registry built from the generated API data, so /api links must name a generated page (canonical entry only) instead of a barrel export parsed from source. Member anchors stay with the API drift test. Reflect the #237-#241 behaviour fixes: the headless picker guide notes that the driver rejects 'p3' and adds a typed-input section showing that percentages in an expression are positions in the range; the core narrative notes saturate/desaturate are uncapped above 0.4; the plane narrative notes planeHue returns an OKLCH hue. Co-Authored-By: Claude Opus 5.5 <[email protected]>

Only ColorArea, ColorSlider and ColorStringInput accept requested and onChangeRequested on their own; ColorPlane, Thumb and the layers read the surrounding ColorArea context and throw outside one. Co-Authored-By: Claude Opus 5.5 <[email protected]>

…in the headless picker Track the pointerId that starts a drag and ignore other pointers until it lifts, cancels or loses capture. Give the area thumb aria-valuenow, min and max from the x axis, matching the React Thumb. Co-Authored-By: Claude Opus 5.5 <[email protected]>

…previews, list mix spaces The quick start blends a translucent color over each background before measuring and measures the hex it paints with precision '8bit', as do the palette's AA labels. Unrounded readings on the contrast page are labelled as measured before rounding. The core overview lists the six supported mix spaces and describes lightnessScale separately. Co-Authored-By: Claude Opus 5.5 <[email protected]>

vercel · 2026-10-10T20:25:46Z

Deployment failed for project color-kit with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/pbrooms-projects?upgradeToPro=build-rate-limit

Slice S5, the final slice of the docs overhaul. ## Commits - **feat(docs): native API map at `/api/map`.** A d3-hierarchy tidy tree rendered as React SVG and fed by the generated API data. There are no CDN scripts. It has its own pan/zoom (drag, pinch, ⌘/Ctrl-wheel), arrow/Home/End keyboard navigation, entry/kind/name filters and a ledger per entry point. The first view is prerendered. The chunk is 16.2 kB gzip. - **docs(react): entry narrative, live examples and symbol notes.** `/api/react` covers the provider and hooks, requested vs displayed, controlled vs uncontrolled, accessibility and performance. It has five live examples (ColorArea + ColorPlane, ColorSlider, ColorStringInput, a controlled provider, a contrast region layer) and edge-case notes for the main components. Every claim was checked against `packages/react/src`. - **feat(docs): polish the search dialog.** Symbols come first with kind and entry, then pages, then prose with highlighted excerpts. Recent searches are kept, and the dialog goes full-screen below 640 px. - **fix(docs): truncate long sidebar names and collapse API domains.** The symbol tree is lazy-loaded. - **chore(docs): point the ColorArea Playwright tools at `/api/react`.** The profile shows about 0.3 ms from pointer to thumb and no dropped frames. - **fix(docs): keep the map ledger from widening phone pages.** - **fix(docs): wrap long export names in symbol page headings.** The 60 longest names were checked at 375 px. ## Verified - Gates: lint, build, test (docs 830), format:check, typecheck, size, check:artifacts and agents:check:strict all pass. - Budgets: home initial JS is 101.7 kB gzip (limit 110), unchanged from #244. The largest chunk is 194.8 kB (limit 200). - Browser: checked light and dark at 1440 and 375 px. No hydration warnings or console errors. Part of the color-kit assessment stack (#204 → #245). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

pbroom force-pushed the docs/s4-content branch from b22a94a to c0501d3 Compare October 8, 2026 17:04

pbroom force-pushed the docs/s3-home-and-examples branch from 89c7f6e to 00d4967 Compare October 8, 2026 17:04

vercel Bot deployed to Preview October 8, 2026 17:12

View deployment

pbroom force-pushed the docs/s3-home-and-examples branch from 00d4967 to dbb1238 Compare October 8, 2026 18:45

pbroom force-pushed the docs/s4-content branch from c0501d3 to 97ff2cd Compare October 8, 2026 18:45

pbroom commented Oct 8, 2026

View reviewed changes

pbroom force-pushed the docs/s4-content branch from 97ff2cd to 0b1fb88 Compare October 8, 2026 18:54

pbroom commented Oct 8, 2026

View reviewed changes

vercel Bot deployed to Preview October 8, 2026 19:04

View deployment

This was referenced Oct 9, 2026

feat(react): add plane renderer, geometry and adaptive-quality hooks #247

Merged

docs(react): rebuild the React docs around the plane hooks #248

Merged

refactor(react)!: remove UI components; ship state and plane hooks only #249

Merged

pbroom force-pushed the docs/s4-content branch from 0b1fb88 to 9cc3717 Compare October 10, 2026 02:39

pbroom force-pushed the docs/s3-home-and-examples branch from b3eb623 to 3394969 Compare October 10, 2026 02:39

vercel Bot deployed to Preview October 10, 2026 02:51

View deployment

pbroom changed the base branch from docs/s3-home-and-examples to graphite-base/244 October 10, 2026 20:22

pbroom changed the base branch from graphite-base/244 to main October 10, 2026 20:24

pbroom and others added 5 commits October 10, 2026 20:25

pbroom force-pushed the docs/s4-content branch from 9cc3717 to 0b9c337 Compare October 10, 2026 20:25

pbroom merged commit c889f85 into main Oct 10, 2026
5 of 6 checks passed

pbroom deleted the docs/s4-content branch October 10, 2026 20:27

Navigation Menu

Repository navigation

docs: add concept pages, guides and entry-point narratives - #244

docs: add concept pages, guides and entry-point narratives#244
pbroom merged 5 commits into
mainfrom
docs/s4-content

pbroom commented Oct 8, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

pbroom left a comment

Uh oh!

pbroom left a comment

Uh oh!

pbroom commented Oct 10, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

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

Uh oh!

Summary

Verified

Uh oh!

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

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

pbroom left a comment

Choose a reason for hiding this comment

Uh oh!

pbroom left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Merge activity

Uh oh!

vercel Bot commented Oct 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pbroom commented Oct 8, 2026 •

edited

Loading

vercel Bot commented Oct 8, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

pbroom commented Oct 10, 2026 •

edited

Loading