Wayfinder: Astryx dependency form, theme and tokens in ui-common

[yomybaby]

Question

Is Astryx a dependency or peerDependency of ui-common, and how is its version pinned/ranged? Does the Lablup brand palette become an Astryx theme shipped by ui-common, and what happens to @astryxdesign/theme-neutral? What replaces ui-common's 119-token [data-theme] contract?

Inputs

• From FR-4049 (shipping): Astryx is an exact-pinned dependency (never bundled); @stylexjs/stylex ^0.19 is a peer. Also decide (a) where ui-common's own CSS layer sits relative to astryx-base / astryx-theme (whether wrapper styles beat theme overrides), (b) ui-common's own StyleX class-name prefix (not x, not webui), (c) any exported vars must be ---prefixed.
• From FR-4051 (CLI): astryx component/search/build/upgrade need @astryxdesign/core resolvable in the app's node_modules — "no direct Astryx dependency" may still need core as a devDependency (or hoisting) for tooling. Keep exact pinning: CLI 0.x has real breaking changes.
• From FR-4052 (consumer survey): consumer-defined --color-border / --color-text-primary / --color-error collide with Astryx's own variable names; @lablup/ui-ai and ui-charts cap peer at <0.2.0 so the Astryx release needs a coordinated library release. Contract is 122 tokens (README's 119 is stale), 47 already mapped in BUI theme-shim.
• From FR-4047 (export surface): ui-common's own component CSS ships as ui-common.css in @layer ui-common; theme packages (@astryxdesign/theme-neutral) were explicitly left to this ticket; lab is an optional exact-pinned peer.

Map

Wayfinder map: FR-4046 / lablup/backend.ai-webui#9890. Moved here from Jira FR-4048 (ui-common-scoped tickets live in this repo).

Blocking

• Blocked by: (none — FR-4049 resolved)
• Blocks: (none)

[yomybaby]

Input from FR-4059 (research, https://github.com/lablup/backend.ai-webui/blob/research/fr-4059-pnpm-patches-transitive/docs/research/fr-4059-pnpm-patches-transitive.md): pnpm patchedDependencies apply by name@version across the whole graph, so webui's Astryx patches survive a transitive reach through ui-common as long as core is a dependency of ui-common — if this ticket makes core a peer instead, that answer must be re-verified (scenarios B/C). Also: lab's non-optional canary core peer makes autoInstallPeers silently install a second, unpatched core when core is not in the consumer's importer; --frozen-lockfile and pnpm peers check stay green. Consumers keep core as a pinned devDependency (the CLI needs it anyway) and use bare-name patch keys as a tripwire. Optional peer for lab (FR-4047) is the right call — a non-optional one reproduces the duplicate.

[yomybaby]

Resolved (2026-09-25, decided in the driving session under the map owner's standing delegation; reversible before landing).

1. Dependency form. @astryxdesign/core and @astryxdesign/theme-neutral are exact-pinned dependencies, moved as one set. @astryxdesign/cli is an exact-pinned dependency too, because the ui-common bin wraps it (Wayfinder: shape of the ui-common CLI over astryx #42). @astryxdesign/lab is an optional exact-pinned peer (FR-4047). @stylexjs/stylex ^0.19 is a peer (FR-4049). Core is not a peer: that keeps FR-4059's verified answer (patches apply graph-wide, one copy) without re-verification.
2. Brand theme. ui-common ships the Lablup brand as an Astryx theme: @lablup/ui-common/theme/lablup (source defineTheme, extends neutral, color.accent: ['#FF7A00', '#DC6B03'], status seeds from today's base.css), plus /theme/lablup/built and /theme/lablup/theme.css produced by astryx theme build and committed behind a --check drift gate. Neutral is mirrored as /theme/neutral, /theme/neutral/built, /theme/neutral/theme.css. Product palettes (bliss, glass, reverie, stained, mlxcel, webui's operator-seeded theme.json families) stay in the products as their own defineTheme over lablup or neutral. The package still ships "the mechanism and one default".
3. Token contract. The 122-name --token-* contract is retired. Astryx's token set is the contract, versioned with the Astryx pin. A deprecated compat sheet @lablup/ui-common/legacy-tokens.css declares every old --token-* name as the matching Astryx var() (or the old literal where Astryx has no counterpart) inside @layer ui-common. Libraries that only read tokens (ui-ai, ui-charts) keep resolving, and a product's own unlayered definitions still win. It is removed in 0.3.
4. Cascade layers. The canonical order becomes @layer reset, theme, base, astryx-base, astryx-theme, ui-common, components, utilities;. ui-common's composite styles beat Astryx base and theme overrides of the primitives they wrap; the app's components layer beats ui-common.
5. ui-common's own styling. Co-located plain CSS in @layer ui-common, reading Astryx var(--…) tokens only, with uic--prefixed BEM class names. No StyleX compile step in ui-common for now; if one is added later it uses classNamePrefix: 'uic' and ---prefixed defineVars keys (FR-4049).
6. Name collisions. Consumer-defined --color-* properties that collide with Astryx names (backend.ai-go, continuum-hub, mlxcel — FR-4052) are reported by the upgrade tool for manual review, not rewritten.