[vjeux]

Proposed; pending owner review (cixzhang, owner of architecture:theme-tokens).

Exact decision needed

Should INV10's surface roles include backdrop (the dim behind a modal) and glass (the surface behind bar buttons), making --color-background-backdrop and --color-background-glass shape-1 names?

Existing authority searched

• architecture:theme-tokens INV10 (current): shape 1 is --color-<property>-<role>; surface roles are surface, body, card, popover, muted, inverted. The role-less utility names form a closed list.
• No current record names a modal dim or a glass surface. --color-overlay is the media scrim (Overlay, Thumbnail), not a modal dim.
• Open work needing the names: feat(core): modals drop the backdrop blur #8120 (iOS modal dim) and feat(TopNav): under a finger, the phone bar's end items sit on an iOS 26 capsule #8188 (iOS bar-button capsule), which fail the INV10 guard test until this is decided.

Decision

INV10 shape 1 accepts two more surface roles: backdrop, the dim behind a modal presentation, and glass, the surface behind bar buttons. The guard test's surface list gains both; the rest of the grammar is unchanged.

Rejected alternatives

• New utility names (--color-dim): they grow the closed utility list.
• Reusing --color-overlay: it is the media scrim.
• Hard-coded colours: themes could not retune them.

Claim scope and non-goals

Only the two role names. No tokens, values, components or platform behaviour; #8120 and #8188 carry those.

Evidence and implementation relationship

#8120 and #8188 depend on this. The guard test (tokens.test.ts › colour token name grammar) checks every Astryx colour token against the grammar.

Writing rubric results

• R1 narration: none. The amended sentence states the surface roles in the present tense.
• R2 research in the record: none.
• R3 evidence naming a change: none.
• R4 rejected alternatives over one line or outside a decision: none in the record.
• R5 pull request or issue references remaining: none in the record.
• R6 ruled open questions still listing options: none.

Scope

• This PR contains specification records only. The guard test's role list is the record's own verification and moves with it.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Validation

• pnpm check:knowledge: records aligned.
• pnpm exec vitest run packages/core/src/theme/tokens.test.ts: 30 pass, including the grammar's guard and the two new role names.
• Prettier on the record and the test; git diff --check is clean.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 24, 2026 6:20pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
❓ Needs maintainer input (for maintainers only)	Oct 24, 2026, 6:41 PM UTC

[astracat-bot]

Approval is on hold for an owner decision: this pull request intentionally changes the current architecture:theme-tokens INV10 by adding backdrop and glass to its surface roles, and that update to the existing spec needs an engineering owner's approval. An engineering owner records the decision by commenting /approve-spec <full head SHA> on this pull request; you are listed in .github/ENGOWNERS, so you may record it yourself. The record sentence and the guard test are consistent, so nothing else blocks.

• Please correct the rejected alternative about --color-overlay before the decision: on main it also paints the ::backdrop of Dialog, Drawer, BottomSheet, MobileNav and Lightbox, so backdrop splits that token's job.
• The decision should also settle whether glass, a material name, fits INV3's purpose-led naming or the role should be named for the place it serves.

[Automated review]

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR

🧪 Sandbox Preview

View Sandbox for this PR

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.9KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

46 of 502 shot(s) changed.

A change here is a question, not a failure: check whether the after is the
picture you intended. Record that review on the PR. Baseline maintenance is an
explicit dispatch of CI; this report never rewrites the baseline or adds a release gate.

component	story	theme	mode	pixels
Selector	Indicator Space Bottom Sheet Narrow End RTL	neutral	light	753,933
Selector	Indicator Space Bottom Sheet Wide Start	neutral	light	740,072
Chat	Full AI Chat	probe	light	230,823
Chat	Full AI Chat	probe	dark	229,805
RichTextEditor	Markdown parity: side by side	probe	dark	94,866
RichTextEditor	Markdown parity: side by side	probe	light	89,762
Collapsible	Dividers	probe	dark	66,445
Collapsible	Dividers	probe	light	66,445
Chat	Default	neutral	dark	36,304
Chat	Default	neutral	light	35,767
Chat	Empty State	probe	light	23,531
Chat	Empty State	probe	dark	22,622
ChatAutoScroll	Scroll Behavior Comparison	neutral	dark	15,378
ChatAutoScroll	Scroll Behavior Comparison	neutral	light	14,107
Chat	With Attachments	probe	light	13,406
Chat	With Attachments	probe	dark	11,232
ProgressBar	With Target Mark	probe	dark	7,895
ProgressBar	With Target Mark	probe	light	7,895
Markdown	Default	neutral	dark	7,573
Markdown	Default	neutral	light	7,566

and 26 more.

---

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

[cixzhang]

Posted by Cindy's agent on her behalf.

Following the decision on #8120 (the overlay stays theme-controlled through --color-overlay, with no new token), the backdrop role isn't needed: please drop it. glass already waits on the look-and-feel decision. With both out, this PR may not be needed.

[cixzhang]

Posted by Cindy's agent on her behalf.

With #8120 narrowed to a blur-only performance fix, this PR isn't needed: there's no backdrop role, and glass waits on the look-and-feel decision. Recommend closing it.

[vjeux]

Closing, as recommended in the 03:43 review: with #8120 narrowed to a blur-only performance fix there is no backdrop role, and glass waits on the look-and-feel decision.