History / API Conventions

Revert "docs: define adaptive overlay ownership" This reverts commit be5bd275cb15a8d7359545ad29df674e1f992273.

docs: define adaptive overlay ownership

Clarify button loading and contrast rubric

Architecture: publish component cheat sheet and refresh references

Theming/API: record <component-kebab>-<part> as the theme target naming convention, and how to rename one

Rubric v1.2.1 + API Conventions: correct T28 (composition-layer theme targets) and P33 (html prefix) Both from the AlertDialog audit review, PR #4887. T28 read as a blanket ban on themeProps anywhere a composition wrapper wraps themed components. That is not what #672 and #749 established: #672 deliberately ADDED a target to MoreMenu over DropdownMenu so themes could reach it, and #749 skipped Tokenizer, an outer node wrapping several independently themed components. T28 now says that: a layer may name its own concept on the painting element; the ban is on the multi-component wrapper node. P33 led with the html prefix. The prefix is for props that ARE the native attribute (htmlName, htmlFor); a prop that merely reuses the name with a different meaning keeps the semantic name. BaseProps already omits title, so a component's own title prop is not a collision at all. API Conventions §HTML Attribute Collisions rewritten to match, since it owns the rule.

Reroute links from the collapsed auditor sections to the rubric Design Conventions, API Conventions, the Accessibility Checklist, Component Lifecycle and the Night Watch role summary all pointed at auditor sections that no longer exist. Each now points at the rubric section that carries the check, with the convention pages still owning what the rule is.

Fix remaining stale token names across the wiki --size-sm/md/lg, spacingTokens.space3, --shadow-menu, --radius-rounded and the --text-* raw scale do not exist on main; the token objects are *Vars maps keyed by CSS custom property name.

Teach ref as a prop instead of forwardRef Main is React 19 ref-as-prop: 149 core components declare ref on their props interface, @eslint-react/no-forward-ref is enabled, and exactly one forwardRef call site remains (lab's RichTextEditor).

Replace the ComponentStyles module-augmentation example with the VariantMap pattern There is no ComponentStyles interface in packages/core/src/theme/types.ts. Extensible props are backed by a *VariantMap interface declared in the component's public subpath barrel.

Correct the input size union and heights to sm/md/lg at 28/32/36px TextInput, Selector and Button all derive size from the same sizeStyles keyed sm/md/lg, backed by --size-element-sm/md/lg (28/32/36px). There is no inputs-only sm|md union, and --size-sm/md/lg do not exist.

State the busy-vs-disabled rule once and flag Button's deviation The page said both that isBusy disables the button and that busy never uses native disabled. Busy is aria-busy plus a guarded handler, never the attribute; Button's current native disable is called out as a tracked deviation (#4871).

Async actions: the shipped prop is changeAction, not on{Verb}Action Every async-capable core component ships changeAction / clickAction; there are zero on*Action props in packages/core/src. Async actions drop the on prefix.

Hook naming: replace useControllableState with a hook that exists useControllableState is not in packages/core/src/hooks — components hand-roll the controlled/uncontrolled merge. Use useInputContainer as the internal-hook example instead.

Correct export conventions: exports map is generated, not tsup The core exports map is generated by scripts/sync-exports.js and guarded by sync:exports:check and verify-exports.mjs. Hand-editing it is a review reject. vega is the only package still built with tsup.

Refine rest-forwarding guidance: per-category precedence (combine/compose/clobber) + composeEventHandlers Correct the earlier oversimplified 'spread ...rest' rule. Document that prop collisions resolve per category: className/style combine (mergeProps), contract props let the component win (set after {...rest}), owned handlers compose (composeEventHandlers, #3863), neutral pass-throughs forward. Update the Component Auditor check to match — it's a judgment check on collision handling, not just 'does ...rest exist'.

Component Auditor: catch components that extend BaseProps but never forward ...rest Add a check (and the underlying API convention) for the silent-drop bug fixed in #3738 and #3852: a component extends BaseProps so data-testid/aria-* type-check, but never captures/spreads ...rest, so those pass-through attributes never reach the DOM. Documents the placement rule (after mergeProps, before component-owned role/aria) and distinguishes it from the composed-component overwrite check.

API Conventions: document disabledMessage as a common input prop Add disabledMessage to the Optional Common Props table, a new "Explaining a disabled input" section (Tooltip-wrapper trap vs. the disabledMessage fix, including combine-with-tooltip behavior), and reconcile the Accessibility disabled-state guidance with the focusable aria-disabled mechanism used when a disabled reason is shown.

Update wiki for XDS → Astryx rename Refresh outdated references across all wiki articles to match the current codebase after the XDS → Astryx rebrand: - Package scope @xds/* → @astryxdesign/* (theme-default/theme-daily → theme-neutral; ESLint rule → @astryx/*) - CLI command xds → astryx; fix stale commands (build-theme → theme build, agent-docs folded into init) - CSS/layers: xds.css → astryx.css, @layer xds → @layer astryx-base, @layer xds.theme → @layer astryx-theme - Config key "xds" → "astryx"; env var XDS_THEME → ASTRYX_THEME - Repo facebookexperimental/xds → facebook/astryx; versions 0.0.15 → 0.1.1 - Swizzle output dir components/xds/ → components/astryx/ - API rename xdsThemeProps → themeProps (verified against source) - Asset set xds_oss → astryx (browse via internalfb.com/assets/set/astryx) - Correct component-purity docs: components are unprefixed (no "Astryx" prefix) Co-authored-by: Cursor <cursoragent@cursor.com>

Astryx design system wiki Documentation for the Astryx design system: API conventions, component authoring, theming, RSC utilities, Night Watch automation, and contribution guides.