refactor(useScheme): name the concept scheme, not schema - #1372
Merged
Conversation
`schema` was the wrong word. The platform calls this a color *scheme* — `prefers-color-scheme`, the `color-scheme` property, `<meta name="color-scheme">` — and in Cube's own vocabulary "schema" means the data model, so a `useSchema()` returning `'light' | 'dark'` lands next to Cloud's SQL Runner `useSchema()` as a pure homonym. This reverts the API rename shipped in 0.170.0 (#1362) and also renames the `<html>` attribute it was built to agree with: `data-schema` becomes `data-scheme`, so `@root(scheme=…)` and `@dark` compile to `:root[data-scheme="dark"]`. The attribute was the older half of the mistake; #1362 propagated it into the API rather than fixing it. No aliases. An alias for the attribute was measured and rejected: teaching `@dark` to accept both spellings expands every arm against both attributes, taking a four-variant palette style map from 21 rules / 3.6 KB to 52 rules / 10.3 KB — a permanent 2.9x on the kit's most-used state to save a one-line edit in the one app that sets it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: 9f02b7f The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
📦 NPM canary releaseDeployed canary version 0.0.0-canary-eb9133b. |
Contributor
🏋️ Size limit report
Compared against main at ae2b2d1 — run 33067377179, 2026-08-27T11:26:30Z.To see which modules changed, download the size-limit-statoscope-report artifact from this run and open report.html. |
Contributor
🧪 Storybook is successfully deployed!
|
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reverts the
scheme→schemarename shipped in 0.170.0 (#1362), and renames the<html>attribute it was built to agree with.Why
schemais the wrong word for this concept, on two counts:prefers-color-scheme, thecolor-schemeCSS property,<meta name="color-scheme">. "Schema" means a structure definition.useSchema()(SQL Runner), plususeSchemaPath(),useSchemaGenerationContext()andresolveSchemaLanguageExtensions(). A ui-kituseSchema()that returns'light' | 'dark'is a pure homonym sitting in the middle of the product's core vocabulary — and Cloud's own name for the color concept isuseResolvedScheme.data-schemais the older half of the mistake — it predates #1362 (back toc12660be). #1362 propagated it into the API instead of fixing it; this PR fixes both halves at once.Timing
Cheapest it will ever be.
@cube-dev/ui-kitis at 0.171.0 and every Cloud package is pinned to 0.165.0, so nothing downstream has consumed the rename. Today this costs one PR here and nothing there. Once Cloud upgrades past 0.170, the same fix costs two migrations instead of zero.The four new hooks are free:
useSchema()has existed for two days anduseScheme()never shipped, so renaming them back is invisible to everyone.What changed
API, back to
scheme:renderColorTokens()/renderPaletteTokens()/RenderPaletteOptions:schemaoption →scheme<CubeLogo>/<CubeFullLogo>:schemaprop →schemeuseSchema()→useScheme(),resolveSchema()→resolveScheme(),subscribeSchema()→subscribeScheme(),ColorSchema→ColorScheme(useHighContrast()/resolveHighContrast()unchanged)tokenOptions.schema→.scheme; CLI--schema→--scheme(--scheme hcstill means light + high contrast)DOM opt-in, renamed for the first time:
<html data-schema="dark">→<html data-scheme="dark">; the tasty state is@root(scheme=…), so@darkcompiles to:root[data-scheme="dark"].data-contrastunchanged.No aliases — and why the attribute doesn't get one
An alias for the attribute looked obviously worth it, so I measured it. Teaching
@darkto accept both spellings works (the DSL handles the full precedence: canonical wins, then legacy, then the media query), but it expands every arm against both attributes. On a four-variant palette style map — the shape the palette actually emits:@darkdefinition2.5× the rules and 2.9× the bytes on the kit's most-used state, permanently, to save a one-line edit in the one app that sets the attribute — and right after #1344 went to the trouble of batching stylesheet writes. The other shape, mirroring the legacy attribute onto the canonical one at runtime from
Root, is free in CSS but puts permanent attribute-writing machinery in the library and has an SSR flash caveat.Neither is worth it. An app that wants a transition window can write both attributes itself, for as long as it needs, at no cost to anyone else.
Migration for Cloud
Whenever it takes the upgrade, in
packages/console-ui:src/styles/theme.tsx— the threedata-schemareads/writes →data-schemesrc/contexts/CubeSystemContext.tsx—scopeToWarmUpentrysrc/styles/adaptive-color.ts,src/codemirror/core/theme.ts— selector + comment referencestests/probe/harness.browser.probe.tsx— the twosetAttributecalls[data-schema]Cloud's own
schemenaming (useResolvedScheme,adaptive-color.ts) already matches the reverted API, so nothing there has to be renamed — only the attribute.Verification
vitest run— 102 files, 2202 passed, 1 skippedtsc --noEmit— 18 errors, byte-identical to the count onmain; none scheme-relatedoxlint/prettier --check— clean (warnings onmainunchanged)Mechanical apart from the attribute decision: 64 files, 494 insertions / 494 deletions.
$schemakeys in JSON configs, the ESLint ruleschema:field, and the genuine data-schema references inTreedocs/tests were excluded;prefers-color-schemeis untouched.src/icons/SchemeIcon.tsxis misnamed in the other direction (it's a sitemap glyph — really a data schema) and is left alone as a separate cleanup.Chromatic
Four story exports are renamed, which changes their story IDs —
PinnedScheme(CubeLogo),DarkScheme(NoDataIcon,LoadingAnimation) andColorScheme(AdvancedStates). Chromatic will report four additions and four deletions rather than four unchanged stories, so expect approval prompts on snapshots that are identical to the baselines they replace.🤖 Generated with Claude Code
Note
Medium Risk
Breaking rename of public hooks, token render options, logo props, probe flags, and the global
data-schemeattribute affects every app that adopted 0.170.0’sschemaspelling ordata-schema; styling breaks if attributes are not migrated together.Overview
Breaking rename that undoes the 0.170.0
schematerminology and aligns with platform vocabulary (prefers-color-scheme,color-scheme) and Cube’s data-model meaning of “schema.”Public API goes back to
scheme:renderColorTokens/renderPaletteTokensoptions,<CubeLogo>/<CubeFullLogo>props, and the hooks/types from 0.170.0 (useScheme,resolveScheme,subscribeScheme,ColorScheme; high-contrast helpers unchanged). Thepnpm probeCLI and harness use--schemeandtokenOptions.schemeinstead of--schema.The document opt-in moves from
<html data-schema>todata-scheme, with Glaze’s@darkstate compiled against@root(scheme=…). Storybook bridges/decorators (colorSchemeBridge,withColorScheme,withDarkScheme) and docs/tests are updated to match; no backward-compat aliases on API or attributes.Consumers must rename call sites,
setAttribute('data-scheme', …), and any[data-schema]CSS.Reviewed by Cursor Bugbot for commit 9f02b7f. Bugbot is set up for automated code reviews on this repo. Configure here.