feat(theme): add appearance nesting tokens by cixzhang · Pull Request #5963 · facebook/astryx

cixzhang · 2026-09-03T08:59:32Z

Why

Themes need shared stacking bands so nested component chrome and ordinary floating surfaces do not each maintain unrelated z-index numbers.

What

Add typed integer appearance tokens for container nesting (10) and layer nesting (50).
Migrate all 47 positive or dynamic z-index assignments in Core, Lab, Charts, and RichText to the shared bands.
Preserve local ordering with band-relative offsets for nested surfaces, overlapping schedule events, and sibling drawers.\n- Keep ChartTooltip beside its owning chart and promote it with a native manual popover; the layer token remains its reduced-browser fallback.
Keep native top-layer-only roots, zero-valued isolation roots, negative underlays, and consumer-authored values unchanged.
Export and document the token family, and add a source guard against new component-local stacking numbers.

Current main already contains no z-index override in Neutral, and the former Rose theme package is no longer present, so there are no obsolete theme overrides to remove.

Risk

Stacking ownership moves from component-local numbers to theme tokens. Native popovers and modal dialogs continue to rely on the browser top layer. A theme can now adjust the two shared bands while component-local ties and relative ordering remain stable.

Testing

718 focused tests on the exact integrated head
Core, Lab, Charts, and RichText builds and typechecks
Typed-token contract and source-guard tests
Generated token documentation drift check
pnpm check:repo

No Changeset is included because this API is not intended to trigger a package version bump yet.

vercel · 2026-09-03T08:59:33Z

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 4, 2026 3:08pm UTC

github-actions · 2026-09-03T09:33:42Z

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

AppShell _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	575	-
Complexity	N/A	Very High (96)	-

BottomSheet _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	3207	-
Complexity	N/A	Very High (258)	-

Calendar _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1477	-
Complexity	N/A	Very High (138)	-

Chat _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	5546	-
Complexity	N/A	Very High (455)	-

CheckboxInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	315	-
Complexity	N/A	Very High (38)	-

CodeBlock _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1570	-
Complexity	N/A	Very High (83)	-

Field _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	789	-
Complexity	N/A	Very High (49)	-

FileInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	660	-
Complexity	N/A	Very High (102)	-

InputGroup _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	270	-
Complexity	N/A	Medium (12)	-

Lightbox _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	663	-
Complexity	N/A	Very High (84)	-

NumberInput _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1070	-
Complexity	N/A	Very High (151)	-

Outline _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	674	-
Complexity	N/A	High (28)	-

Popover _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	810	-
Complexity	N/A	Very High (90)	-

RadioList _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	434	-
Complexity	N/A	Very High (45)	-

Resizable _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1328	-
Complexity	N/A	Very High (106)	-

SideNav _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	2049	-
Complexity	N/A	Very High (213)	-

Slider _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	856	-
Complexity	N/A	Very High (115)	-

Switch _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	491	-
Complexity	N/A	Very High (46)	-

Table _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1960	-
Complexity	N/A	Very High (112)	-

TextArea _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	435	-
Complexity	N/A	Very High (65)	-

Thumbnail _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	308	-
Complexity	N/A	Very High (37)	-

Toast _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1287	-
Complexity	N/A	Very High (129)	-

Chart _{(@astryxdesign/lab)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	3469	-
Complexity	N/A	Very High (374)	-

Drawer _{(@astryxdesign/lab)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	464	-
Complexity	N/A	High (30)	-

Schedule _{(@astryxdesign/lab)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	3387	-
Complexity	N/A	Very High (187)	-

ChartTooltip _{(@astryxdesign/charts)}

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	341	-
Complexity	N/A	Very High (54)	-

RichTextEditor _{(@astryxdesign/richtext)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	603	-
Complexity	N/A	Very High (57)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB
@astryxdesign/lab	N/A	3.5KB	1.5KB
@astryxdesign/charts	N/A	922B	436B
@astryxdesign/richtext	N/A	N/A	N/A

Accessibility Audit

Status: 5 accessibility violation(s) found — 1 critical, 4 serious.

FileInput - 1 issue(s)

🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
- Rule: color-contrast · Affects 3/15 stories · Learn more
- WCAG: 1.4.3 (Level AA)

RadioList - 1 issue(s)

🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
- Rule: color-contrast · Affects 3/13 stories · Learn more
- WCAG: 1.4.3 (Level AA)

RichTextEditor - 2 issue(s)

🟠 serious: Ensure every ARIA input field has an accessible name
- Rule: aria-input-field-name · Affects 2/18 stories · Learn more
- WCAG: 4.1.2 (Level A)
🔴 critical: Ensure every form element has a label
- Rule: label · Affects 1/18 stories · Learn more
- WCAG: 4.1.2 (Level A)

Thumbnail - 1 issue(s)

🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
- Rule: color-contrast · Affects 1/12 stories · Learn more
- WCAG: 1.4.3 (Level AA)

Visual Regression

Status: Skipped — Broad stable scope is deferred to the daily release gate. It covers 380 trusted baseline shots instead of recapturing them for this PR. View the report

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

cixzhang

Semantic verdict: approve

The 10/50 defaults, public exports, override path, generated docs, and built CSS all match the settled layering contract.

[Reviewed by Robohands]

cixzhang

Semantic verdict: request changes

The earlier approval covers 3855819; this head removes the only Changeset. These are public Core and CLI additions, so this PR no longer requests a package bump or changelog entry and can only ship incidentally with another release. Please restore the patch Changeset for both packages. The 10/50 defaults, typed variables, override path, generated docs, and built CSS are otherwise preserved.

[Reviewed by Robohands]

cixzhang

Semantic verdict: approve

My earlier Changeset request covered 4014d9d. This head follows the settled no-bump direction; its 10/50 defaults, typed exports, overrides, docs, and built CSS are correct.

[Reviewed by Robohands]

# Conflicts: # packages/core/src/CheckboxInput/CheckboxInput.tsx # packages/core/src/RadioList/RadioListItem.tsx # packages/core/src/Switch/Switch.tsx

cixzhang

Semantic verdict: approve

The 10/50 migration keeps local ordering intact, and ChartTooltip now stays with its owning chart while the new native-popover path works in Chromium.

[Reviewed by Robohands]

cixzhang

Semantic verdict: approve

The exact head preserves 10/50 and tooltip mechanics. Resizable now passes RTL; the remaining failure is unverified N/A coverage, not a behavior defect.

[Reviewed by Robohands]

cixzhang

APPROVED at exact head 2314d2934cc13c4451f82481a963aeb0c3c8ae6a.

Verified the complete Appearance nesting migration after landing #5994 and updating from main:

all 47 positive/dynamic component stacking assignments map to 41 container and 6 layer usages with offsets and exclusions preserved;
ChartTooltip remains owner-local with native popover geometry reset;
144 focused migration tests, all four affected package builds/typechecks, and repository checks pass;
stable visual, accessibility, and RTL gates pass; RTL coverage is complete at 23 measured / 4 verified N/A / 0 gaps.

No actionable findings.

…d value PR #5909 seeded `options`/`label` playground defaults for Selector so its Properties preview stops showing the "missing required props" placeholder, but did not seed `value` (correctly: Selector's own contract requires "closed with no value" to be a valid representative state, FR1 in Selector.spec.md). That exposed a latent bug in `buildRuntimePreviewState`: it only bridges a controlled callback back into playground state when its target prop already has a value in `state`, so Selector's `onChange` was never wired up and the live preview stayed frozen on the placeholder no matter what option a person clicked. Fix generalizes the bridge instead of papering over Selector specifically: the literal `value`/`onChange` pair — a component's one primary controlled value — now bridges whenever `target` names a real prop, even an optional one with no seeded default. Secondary paired callbacks (onIndexChange, onPageSizeChange, onOpenChange, ...) keep the original opt-in behavior, preserving each preview's chosen representative starting state (verified by the existing Lightbox gallery-index and overlay tests, unchanged and still passing). Added a focused regression test reproducing the exact reported scenario: Selector with options seeded but no value, selecting Orange must update preview state. Testing: - New test: bridges Selector onChange even though its optional value prop is not seeded (red before the fix, green after) - Full docsite suite: 34 files, 475 tests passing - tsc --noEmit: no new errors (pre-existing theme-package /built errors are unrelated to this worktree's unbuilt theme packages) - eslint on both changed files: clean - check:package-boundaries: clean Excludes all work from #5963 (unrelated theme appearance-nesting tokens); touches only docsite preview infrastructure and its test.

…d value (#6035) PR #5909 seeded `options`/`label` playground defaults for Selector so its Properties preview stops showing the "missing required props" placeholder, but did not seed `value` (correctly: Selector's own contract requires "closed with no value" to be a valid representative state, FR1 in Selector.spec.md). That exposed a latent bug in `buildRuntimePreviewState`: it only bridges a controlled callback back into playground state when its target prop already has a value in `state`, so Selector's `onChange` was never wired up and the live preview stayed frozen on the placeholder no matter what option a person clicked. Fix generalizes the bridge instead of papering over Selector specifically: the literal `value`/`onChange` pair — a component's one primary controlled value — now bridges whenever `target` names a real prop, even an optional one with no seeded default. Secondary paired callbacks (onIndexChange, onPageSizeChange, onOpenChange, ...) keep the original opt-in behavior, preserving each preview's chosen representative starting state (verified by the existing Lightbox gallery-index and overlay tests, unchanged and still passing). Added a focused regression test reproducing the exact reported scenario: Selector with options seeded but no value, selecting Orange must update preview state. Testing: - New test: bridges Selector onChange even though its optional value prop is not seeded (red before the fix, green after) - Full docsite suite: 34 files, 475 tests passing - tsc --noEmit: no new errors (pre-existing theme-package /built errors are unrelated to this worktree's unbuilt theme packages) - eslint on both changed files: clean - check:package-boundaries: clean Excludes all work from #5963 (unrelated theme appearance-nesting tokens); touches only docsite preview infrastructure and its test.

feat(theme): add appearance nesting tokens

3855819

cixzhang requested review from imdreamrunner and josephfarina as code owners September 3, 2026 08:59

meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Sep 3, 2026

github-actions Bot added the needs:design-review Affects visuals — Design should review label Sep 3, 2026

github-actions Bot requested review from cvkxx, ernestt, kentonquatman and rubyycheung September 3, 2026 08:59

vercel Bot deployed to Preview September 3, 2026 09:02 View deployment

github-actions Bot added a commit that referenced this pull request Sep 3, 2026

Deploy PR #5963 preview

30ea0a5

cixzhang commented Sep 3, 2026

View reviewed changes

chore: remove appearance token changeset

4014d9d

vercel Bot deployed to Preview September 3, 2026 11:57 View deployment

cixzhang commented Sep 3, 2026

View reviewed changes

github-actions Bot added a commit that referenced this pull request Sep 3, 2026

Deploy PR #5963 preview

aecd41e

Merge remote-tracking branch 'origin/main' into ac-maint-20260903-pr5963

f5323bf

vercel Bot deployed to Preview September 3, 2026 17:13 View deployment

github-actions Bot added a commit that referenced this pull request Sep 3, 2026

Deploy PR #5963 preview

8f645af

cixzhang commented Sep 3, 2026

View reviewed changes

refactor(theme): adopt appearance nesting tokens

8ad3671

cixzhang requested review from humbertovirtudes and potatowagon as code owners September 3, 2026 22:43

Merge remote-tracking branch 'origin/main' into ariakit-z-index-cleanup

6804d1d

# Conflicts: # packages/core/src/CheckboxInput/CheckboxInput.tsx # packages/core/src/RadioList/RadioListItem.tsx # packages/core/src/Switch/Switch.tsx

vercel Bot deployed to Preview September 3, 2026 22:47 View deployment

test(theme): harden nesting token guard

a669024

vercel Bot had a problem deploying to Preview September 3, 2026 22:54 Failure

fix(charts): keep tooltip in owner layer

364f08a

github-actions Bot added a commit that referenced this pull request Sep 3, 2026

Deploy PR #5963 preview

4f58020

vercel Bot had a problem deploying to Preview September 3, 2026 23:10 Failure

fix(charts): reset tooltip popover geometry

5e2a617

vercel Bot had a problem deploying to Preview September 3, 2026 23:22 Failure

github-actions Bot added a commit that referenced this pull request Sep 3, 2026

Deploy PR #5963 preview

f6c2893

cixzhang commented Sep 3, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into ariakit-z-index-cleanup

dbed817

vercel Bot deployed to Preview September 4, 2026 14:11 View deployment

test(storybook): register Resizable as Core

4f2b9fe

cixzhang force-pushed the ariakit-z-index-cleanup branch from fb3933f to 4f2b9fe Compare September 4, 2026 14:21

vercel Bot deployed to Preview September 4, 2026 14:25 View deployment

cixzhang commented Sep 4, 2026

View reviewed changes

github-actions Bot added a commit that referenced this pull request Sep 4, 2026

Deploy PR #5963 preview

206e059

test: cover migrated stacking surfaces

2314d29

vercel Bot deployed to Preview September 4, 2026 15:08 View deployment

github-actions Bot added a commit that referenced this pull request Sep 4, 2026

Deploy PR #5963 preview

6298086

cixzhang commented Sep 4, 2026

View reviewed changes

cixzhang merged commit ea04834 into main Sep 4, 2026
28 checks passed

This was referenced Sep 4, 2026

fix(cli): align search test with internal coverage #6023

Merged

chore(changesets): cover appearance nesting tokens #6030

Closed

fix(docsite): bridge Selector's onChange preview even without a seeded value #6035

Merged

github-actions Bot deleted the ariakit-z-index-cleanup branch September 5, 2026 06:19

Navigation Menu

Uh oh!

feat(theme): add appearance nesting tokens - #5963

feat(theme): add appearance nesting tokens#5963
cixzhang merged 11 commits into
mainfrom
ariakit-z-index-cleanup

cixzhang commented Sep 3, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

cixzhang left a comment

Uh oh!

cixzhang left a comment

Uh oh!

cixzhang left a comment

Uh oh!

cixzhang left a comment

Uh oh!

cixzhang left a comment

Uh oh!

cixzhang left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

cixzhang commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Risk

Testing

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Analysis Report

📚 Storybook Preview

🧪 Sandbox Preview

Modified Components

Bundle Size Summary

Accessibility Audit

Visual Regression

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cixzhang commented Sep 3, 2026 •

edited

Loading

vercel Bot commented Sep 3, 2026 •

edited

Loading

github-actions Bot commented Sep 3, 2026 •

edited

Loading