@astryxdesign/core 0.6.0 → 0.6.1

package/dist/theme/localTokens.js

@@ -3,26 +3,19 @@
 /**
  * @file localTokens.ts
  * @input Root and adaptation theme-local token declarations and references
- * @output Validated enrollment metadata plus normalized conditional writes
- * @position Theme-local namespace owner; final adaptation-cycle validation is
+ * @output Validated exact-name ownership metadata plus normalized conditional writes
+ * @position Theme-local ownership boundary; final adaptation-cycle validation is
  *   performed after the reachable ordered cascade is assembled.
  */
 
-const LOCAL_TOKEN_PREFIX = '--astryx-theme-';
-const THEME_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const LOCAL_TOKEN_SUFFIX_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const CSS_VAR_PATTERN = /var\(\s*(--[^,\s)]+)/gi;
-
-/** Whether a custom-property name belongs to Astryx's reserved local namespace. */
-export function isReservedThemeLocalTokenName(name) {
-  return name.startsWith(LOCAL_TOKEN_PREFIX);
-}
+const CSS_NAME_CHARACTER = String.raw`(?:[-_a-zA-Z0-9]|\P{ASCII}|\\(?:[0-9a-fA-F]{1,6}[ \t\r\n\f]?|[^\r\n\f]))`;
+const CSS_CUSTOM_PROPERTY_NAME_PATTERN = new RegExp(`^--${CSS_NAME_CHARACTER}*$`, 'u');
+const CSS_VAR_PATTERN = new RegExp(`var\\(\\s*(--${CSS_NAME_CHARACTER}*)(?=\\s*(?:,|\\)))`, 'giu');
 function hasOwn(object, key) {
   return Object.prototype.hasOwnProperty.call(object, key);
 }
-function isExactLocalTokenName(name, owner) {
-  const prefix = `${LOCAL_TOKEN_PREFIX}${owner}-`;
-  return name.startsWith(prefix) && LOCAL_TOKEN_SUFFIX_PATTERN.test(name.slice(prefix.length));
+function isValidCSSCustomPropertyName(name) {
+  return !name.includes('\0') && CSS_CUSTOM_PROPERTY_NAME_PATTERN.test(name);
 }
 function resolveTokenValue(value, path) {
   if (typeof value === 'string') {
@@ -53,15 +46,6 @@ function collectCustomPropertyReferences(value, refs) {
     }
   }
 }
-function collectLocalReferences(value, refs) {
-  const customProperties = new Set();
-  collectCustomPropertyReferences(value, customProperties);
-  for (const name of customProperties) {
-    if (isReservedThemeLocalTokenName(name)) {
-      refs.add(name);
-    }
-  }
-}
 export function assertNoTokenCycles(tokenValues, context, relevantNames) {
   const dependencies = new Map();
   for (const [name, value] of Object.entries(tokenValues)) {
@@ -140,18 +124,6 @@ export function assertNoTokenCycles(tokenValues, context, relevantNames) {
     }
   }
 }
-function assertDeclaredReferences(localTokens, components, onDark, onLight) {
-  const refs = new Set();
-  collectLocalReferences(localTokens, refs);
-  collectLocalReferences(components, refs);
-  collectLocalReferences(onDark?.components, refs);
-  collectLocalReferences(onLight?.components, refs);
-  for (const reference of refs) {
-    if (!hasOwn(localTokens, reference)) {
-      throw new Error(`Theme-local token reference "${reference}" has no declaration in the enrolled theme lineage.`);
-    }
-  }
-}
 function assertInheritedContract(themeName, base) {
   const lineage = base.__localTokenLineage;
   if (!Array.isArray(lineage) || lineage.length === 0 || lineage[lineage.length - 1] !== base.name || lineage.some(name => typeof name !== 'string' || name.length === 0)) {
@@ -162,7 +134,7 @@ function assertInheritedContract(themeName, base) {
   }
   for (const [name, value] of Object.entries(base.localTokens)) {
     const owner = base.__localTokenOwners[name];
-    if (typeof value !== 'string' || !owner || !lineage.includes(owner) || !isExactLocalTokenName(name, owner)) {
+    if (typeof value !== 'string' || !owner || !lineage.includes(owner) || !isValidCSSCustomPropertyName(name)) {
       throw new Error(`defineTheme("${themeName}"): inherited local token "${name}" does not match its exact lineage metadata.`);
     }
   }
@@ -177,17 +149,14 @@ function assertInheritedContract(themeName, base) {
  * Resolve and validate the opt-in theme-local token contract.
  *
  * Themes that omit `localTokens` and do not extend an enrolled base bypass this
- * function's reserved-namespace checks so legacy token behavior stays intact.
+ * function's exact owner and lineage checks so legacy token behavior stays intact.
  */
-export function resolveLocalTokenContract(input, base, tokens, components, onDark, onLight) {
+export function resolveLocalTokenContract(input, base, tokens, portableTokens) {
   const directlyEnrolled = hasOwn(input, 'localTokens');
   const inherited = base?.__localTokenLineage !== undefined;
   if (!directlyEnrolled && !inherited) {
     return undefined;
   }
-  if (directlyEnrolled && !THEME_NAME_PATTERN.test(input.name)) {
-    throw new Error(`defineTheme("${input.name}"): themes using localTokens require a stable lower-kebab name.`);
-  }
   if (inherited && base) {
     assertInheritedContract(input.name, base);
   }
@@ -203,11 +172,10 @@ export function resolveLocalTokenContract(input, base, tokens, components, onDar
   }
   for (const [name, value] of Object.entries(declarations ?? {})) {
     const inheritedOwner = owners[name];
+    if (!isValidCSSCustomPropertyName(name)) {
+      throw new Error(`defineTheme("${input.name}"): local token "${name}" must be a valid CSS custom-property name.`);
+    }
     if (!inheritedOwner) {
-      const expectedPrefix = `${LOCAL_TOKEN_PREFIX}${input.name}-`;
-      if (!isExactLocalTokenName(name, input.name)) {
-        throw new Error(`defineTheme("${input.name}"): local token "${name}" must use the exact namespace "${expectedPrefix}" followed by a lowercase kebab-case purpose.`);
-      }
       owners[name] = input.name;
     }
     localTokens[name] = resolveTokenValue(value, `defineTheme("${input.name}").localTokens["${name}"]`);
@@ -216,11 +184,10 @@ export function resolveLocalTokenContract(input, base, tokens, components, onDar
     if (!owners[name]) {
       throw new Error(`defineTheme("${input.name}"): inherited local token "${name}" has no owner metadata.`);
     }
-    if (hasOwn(tokens, name)) {
+    if (hasOwn(tokens, name) || hasOwn(portableTokens, name)) {
       throw new Error(`defineTheme("${input.name}"): token "${name}" cannot be declared in both tokens and localTokens.`);
     }
   }
-  assertDeclaredReferences(localTokens, components, onDark, onLight);
   assertNoTokenCycles(localTokens, `defineTheme("${input.name}").localTokens`);
   return {
     localTokens,
@@ -233,20 +200,12 @@ export function resolveLocalTokenContract(input, base, tokens, components, onDar
  * Resolve theme-local values written by one adaptation rule.
  *
  * Adaptations may replace names already enrolled by the root theme lineage, but
- * they never enroll names of their own. This validates one rule's references;
- * cycle validation waits until all co-matching writes have cascaded in order.
+ * they never enroll names of their own. Cycle validation waits until all
+ * co-matching writes have cascaded in order.
  */
-export function resolveAdaptationLocalTokens(themeName, ruleIndex, declarations, rootLocalTokens, tokens, components) {
+export function resolveAdaptationLocalTokens(themeName, ruleIndex, declarations, rootLocalTokens) {
   const path = `defineTheme("${themeName}").adaptations.rules[${ruleIndex}].value.localTokens`;
   if (declarations === undefined) {
-    const refs = new Set();
-    collectLocalReferences(tokens, refs);
-    collectLocalReferences(components, refs);
-    for (const reference of refs) {
-      if (!rootLocalTokens || !hasOwn(rootLocalTokens, reference)) {
-        throw new Error(`${path}: theme-local token reference "${reference}" has no declaration in the enrolled root theme lineage.`);
-      }
-    }
     return undefined;
   }
   if (declarations === null || typeof declarations !== 'object' || Array.isArray(declarations)) {
@@ -259,18 +218,5 @@ export function resolveAdaptationLocalTokens(themeName, ruleIndex, declarations,
     }
     resolved[name] = resolveTokenValue(value, `${path}["${name}"]`);
   }
-  const effective = {
-    ...rootLocalTokens,
-    ...resolved
-  };
-  const refs = new Set();
-  collectLocalReferences(resolved, refs);
-  collectLocalReferences(tokens, refs);
-  collectLocalReferences(components, refs);
-  for (const reference of refs) {
-    if (!hasOwn(effective, reference)) {
-      throw new Error(`${path}: theme-local token reference "${reference}" has no declaration in the enrolled root theme lineage.`);
-    }
-  }
   return Object.keys(resolved).length > 0 ? resolved : undefined;
 }

package/dist/theme/themeAdaptations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themeAdaptations.d.ts","sourceRoot":"","sources":["../../src/theme/themeAdaptations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"themeAdaptations.d.ts","sourceRoot":"","sources":["../../src/theme/themeAdaptations.ts"],"names":[],"mappings":"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"}

package/dist/theme/themeAdaptations.js

@@ -22,7 +22,7 @@
  */
 
 import { resolveThemeValues } from "./resolveThemeValues.js";
-import { assertNoTokenCycles, isReservedThemeLocalTokenName, resolveAdaptationLocalTokens } from "./localTokens.js";
+import { assertNoTokenCycles, resolveAdaptationLocalTokens } from "./localTokens.js";
 
 // =============================================================================
 // Public authoring vocabulary
@@ -593,11 +593,11 @@ export function resolveThemeAdaptationRules(themeName, adaptations, axes, rootTo
       assertConcreteLeaf(resolved.components, `defineTheme("${themeName}").adaptations.rules[${index}].value.components`);
     }
     for (const name of Object.keys(rule.value.tokens ?? {})) {
-      if (isReservedThemeLocalTokenName(name)) {
-        throw new Error(`defineTheme("${themeName}").adaptations.rules[${index}].value.tokens["${name}"] uses the reserved --astryx-theme-* namespace; write it through value.localTokens instead.`);
+      if (rootLocalTokens && Object.prototype.hasOwnProperty.call(rootLocalTokens, name)) {
+        throw new Error(`defineTheme("${themeName}").adaptations.rules[${index}].value.tokens["${name}"] matches an enrolled theme-local declaration; write it through value.localTokens instead.`);
       }
     }
-    const localTokens = resolveAdaptationLocalTokens(themeName, index, rule.value.localTokens, rootLocalTokens, resolved.tokens, resolved.components);
+    const localTokens = resolveAdaptationLocalTokens(themeName, index, rule.value.localTokens, rootLocalTokens);
     return {
       when: rule.when,
       query: mediaQueryForCondition(themeName, index, rule.when, adaptations.widthBreakpoints),

package/dist/utils/themeProps.d.ts

@@ -17,12 +17,13 @@ export declare function themeDataAttributes(props?: ClassProps): ThemeDataAttrib
  * Build the props object components should spread onto the same element that
  * receives the stable Astryx class name.
  *
- * This emits one stable astryx target class plus data-attribute reflection for
- * visual props and runtime states. For example:
+ * This emits one stable Astryx target, deprecated bare compatibility classes,
+ * and canonical data-attribute reflection for visual props and runtime states.
+ * For example:
  *
  * ```ts
  * themeProps('button', { variant: 'primary', size: 'sm' })
- * // → { className: 'astryx-button', data-variant: 'primary', data-size: 'sm' }
+ * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
 /**
@@ -30,17 +31,16 @@ export declare function themeDataAttributes(props?: ClassProps): ThemeDataAttrib
  */
 export type ThemePropsOptions = {
     /**
-     * Stable class names to emit ALONGSIDE the component's own, for targets that
-     * have been renamed.
+     * Stable target names to emit alongside the canonical target for backwards
+     * compatibility.
      *
      * A theme target is public API: renaming one silently breaks every theme
-     * that styles it. Emitting the old name beside the new one keeps those
-     * themes working through a deprecation window, at the cost of one extra
-     * class on the element until the old name is dropped in a major.
+     * that styles it. Keep aliases emitted unless a separate compatibility
+     * decision explicitly retires them.
      *
      * Pass plain string literals — the theming guards scan for them statically.
-     * Document the old name with `deprecated` in the component's
-     * `theming.targets` so the docsite says which to use.
+     * Document each old name with `deprecatedFor` in the component's
+     * `theming.targets` so discovery and diagnostics name the replacement.
      */
     legacyNames?: ReadonlyArray<string>;
 };

package/dist/utils/themeProps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"themeProps.d.ts","sourceRoot":"","sources":["../../src/utils/themeProps.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,mBAAmB,CAAC;AAEnE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,MAAM,EAAE,CAErE;AAuBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAa3E;AAED;;;;;;;;;;;GAWG;AACH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU,CAQZ"}
+{"version":3,"file":"themeProps.d.ts","sourceRoot":"","sources":["../../src/utils/themeProps.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,mBAAmB,CAAC;AAEnE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,MAAM,EAAE,CAErE;AA0CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAa3E;AAED;;;;;;;;;;;;GAYG;AACH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU,CAQZ"}

package/dist/utils/themeProps.js

@@ -4,14 +4,20 @@ import { stableClassName } from "../naming.js";
 export function themeDataAttributeName(prop) {
   return `data-${prop.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;
 }
+function legacyClassTokenForPropValue(prop, value) {
+  // CSS classes cannot start with a digit, so preserve the released prop prefix.
+  return /^\d/.test(value) ? `${prop}-${value}` : value;
+}
 
 /**
  * Build the stable astryx-* class name string for a component.
  *
  * Every component renders one stable target class (`astryx-button`,
- * `astryx-card`, etc.). Visual props and runtime states are reflected only as
- * data attributes (`data-variant`, `data-size`, `data-selected`, etc.), which
- * preserve the axis name and cannot collide when two axes share a value.
+ * `astryx-card`, etc.). Visual props and runtime states use explicit data
+ * attributes (`data-variant`, `data-size`, `data-selected`, etc.) as their
+ * canonical selector surface. Released bare value/state classes remain on the
+ * same element as deprecated compatibility aliases until their 0.7.0 removal
+ * window.
  *
  * The `astryx-` prefix comes from the centralized naming module
  * (`packages/core/src/naming.ts`) so the namespace lives in one place.
@@ -20,10 +26,20 @@ export function themeDataAttributeName(prop) {
  * <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->
  *
  * @param component - Component name in lowercase (e.g. 'button', 'card')
- * @returns Stable class name (e.g. "astryx-button")
+ * @param props - Visual prop values whose released bare classes remain aliases
+ * @returns Stable target and deprecated compatibility classes
  */
-function buildClassName(component) {
-  return stableClassName(component);
+function buildClassName(component, props) {
+  const classes = [stableClassName(component)];
+  if (props) {
+    for (const [prop, value] of Object.entries(props)) {
+      if (value == null) {
+        continue;
+      }
+      classes.push(legacyClassTokenForPropValue(prop, String(value)));
+    }
+  }
+  return classes.join(' ');
 }
 
 /**
@@ -50,12 +66,13 @@ export function themeDataAttributes(props) {
  * Build the props object components should spread onto the same element that
  * receives the stable Astryx class name.
  *
- * This emits one stable astryx target class plus data-attribute reflection for
- * visual props and runtime states. For example:
+ * This emits one stable Astryx target, deprecated bare compatibility classes,
+ * and canonical data-attribute reflection for visual props and runtime states.
+ * For example:
  *
  * ```ts
  * themeProps('button', { variant: 'primary', size: 'sm' })
- * // → { className: 'astryx-button', data-variant: 'primary', data-size: 'sm' }
+ * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
 /**
@@ -63,7 +80,7 @@ export function themeDataAttributes(props) {
  */
 
 export function themeProps(component, props, options) {
-  const className = buildClassName(component);
+  const className = buildClassName(component, props);
   const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];
   return {
     className: legacy.length > 0 ? [className, ...legacy].join(' ') : className,

package/locales/en.json

@@ -347,6 +347,22 @@
     "defaultMessage": "Slide {current, number} of {total, number}",
     "description": "Screen-reader accessible name for one slide in a Carousel, giving its position. `current` is the 1-based slide number; `total` is the slide count."
   },
+  "@astryx.chart.label": {
+    "defaultMessage": "Chart",
+    "description": "Generic screen-reader name for a Chart with no primary series and no consumer-supplied title. Noun (a data visualization), not a verb."
+  },
+  "@astryx.chart.labelWithSeries": {
+    "defaultMessage": "Chart of {series} by {xKey}",
+    "description": "Generated screen-reader name for a Chart without a consumer-supplied title. `{series}` is a locale-formatted list of series labels; `{xKey}` is the consumer's horizontal data-field name."
+  },
+  "@astryx.chart.dataTableCaption": {
+    "defaultMessage": "{label} data",
+    "description": "Screen-reader-only caption for the small-data table that mirrors a Chart. `{label}` is the Chart's resolved accessible name."
+  },
+  "@astryx.chartLegend.label": {
+    "defaultMessage": "Chart legend",
+    "description": "Screen-reader-only accessible name for the list of series labels and swatches rendered by ChartLegend."
+  },
   "@astryx.chat.status.sending": {
     "defaultMessage": "Sending",
     "description": "Chat send-status caption under an outgoing message while it is being transmitted. Part of the set sending → sent → delivered → read (or failed) — keep tense/aspect consistent."

package/locales/pseudo.json

@@ -260,6 +260,18 @@
   "@astryx.carousel.slideLabel": {
     "defaultMessage": "⟦Šłíðé {current, number} óƒ {total, number}⟧"
   },
+  "@astryx.chart.label": {
+    "defaultMessage": "⟦Çĥàřţ⟧"
+  },
+  "@astryx.chart.labelWithSeries": {
+    "defaultMessage": "⟦Çĥàřţ óƒ {series} ƀý {xKey}⟧"
+  },
+  "@astryx.chart.dataTableCaption": {
+    "defaultMessage": "⟦{label} ðàţà⟧"
+  },
+  "@astryx.chartLegend.label": {
+    "defaultMessage": "⟦Çĥàřţ łéĝéñð⟧"
+  },
   "@astryx.chat.status.sending": {
     "defaultMessage": "⟦Šéñðíñĝ⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -434,6 +434,11 @@
       "types": "./dist/Resizable/index.d.ts",
       "default": "./dist/Resizable/index.js"
     },
+    "./ScrollableArea": {
+      "source": "./src/ScrollableArea/index.ts",
+      "types": "./dist/ScrollableArea/index.d.ts",
+      "default": "./dist/ScrollableArea/index.js"
+    },
     "./Section": {
       "source": "./src/Section/index.ts",
       "types": "./dist/Section/index.d.ts",
@@ -676,7 +681,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.6.0"
+    "@astryxdesign/cli": "0.6.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/AppShell.test.tsx

@@ -26,6 +26,7 @@ import {InternationalizationProvider} from '../i18n';
 import {MobileNav} from '../MobileNav';
 import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
 import {TopNav, TopNavHeading, TopNavItem} from '../TopNav';
+import {TextInput} from '../TextInput';
 import {useAppShellMobile} from './AppShellMobileContext';
 import {Theme, defineTheme} from '../theme';
 
@@ -706,6 +707,41 @@ describe('AppShell', () => {
   // Sticky navigation in auto mode
   // ===========================================================================
 
+  // A Field input wrapper carries a local z-index (it paints above the
+  // attached status message box via a negative-margin overlap), so without a
+  // component-owned isolation boundary it competes with page-level stacking —
+  // a field scrolled underneath the sticky header then paints over it (#5689).
+  // The fix is local containment: the Field root isolates the wrapper's local
+  // layer, so the header needs no escalated z-index to stay above it. This
+  // asserts that ownership boundary — the field's painted surface is an
+  // isolated stacking context — not a comparison between two page-level
+  // z-index values.
+  it('contains Field input stacking locally so the sticky header needs no escalated z-index in auto mode', () => {
+    render(
+      <AppShell height="auto" topNav={<div>Nav</div>}>
+        <TextInput
+          label="Name"
+          statusVariant="detached"
+          value=""
+          onChange={() => {}}
+        />
+      </AppShell>,
+    );
+    const header = screen.getByRole('banner');
+    const inputWrapper = screen.getByRole('textbox').parentElement!;
+    // The detached variant renders the input wrapper outside Field's isolated
+    // attached-status wrapper, so the Field root must own the boundary.
+    const fieldRoot = inputWrapper.parentElement!;
+    expect(inputWrapper).toBeTruthy();
+    expect(getComputedStyle(header).position).toBe('sticky');
+    // The header stays at its normal local stacking level — no escalation.
+    expect(Number(getComputedStyle(header).zIndex)).toBe(1);
+    expect(getComputedStyle(inputWrapper).position).toBe('relative');
+    // Field's local layers cannot escape into page-level stacking: the root
+    // establishes an isolation boundary around the input wrapper's z-index.
+    expect(getComputedStyle(fieldRoot).isolation).toBe('isolate');
+  });
+
   it('wraps header in sticky container in auto mode', () => {
     render(
       <AppShell

package/src/AppShell/AppShell.tsx

@@ -395,7 +395,10 @@ const styles = stylex.create({
     height: spacingVars['--spacing-12'],
     paddingInline: spacingVars['--spacing-2'],
   },
-  // Sticky header for auto height mode
+  // Sticky header for auto height mode. The header stays at its local
+  // stacking level — Field-owned input surfaces contain their own local
+  // z-index layers (AST-027), so no escalated page-level value is needed
+  // for the header to paint above scrolled content.
   headerSticky: {
     position: 'sticky',
     top: 0,

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -11,7 +11,7 @@ export const docs = {
     description:
       'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
-      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Express the ratio as a fraction for readability — `ratio={16 / 9}` rather than `ratio={1.78}`. It is a number, so the string form `ratio="16/9"` is a type error.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
@@ -79,7 +79,7 @@ export const docsZh = {
     description:
       'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
-      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Express the ratio as a fraction for readability — `ratio={16 / 9}` rather than `ratio={1.78}`. It is a number, so the string form `ratio="16/9"` is a type error.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
@@ -130,7 +130,7 @@ export const docsDense = {
     description:
       'Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.',
     bestPractices: [
-      {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
+      {guidance: true, description: 'Express the ratio as a fraction for readability — `ratio={16 / 9}` rather than `ratio={1.78}`. It is a number, so the string form `ratio="16/9"` is a type error.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},

package/src/Banner/Banner.test.tsx

@@ -531,7 +531,9 @@ describe('Banner', () => {
           );
           const frame = container.firstElementChild;
           expect(frame).toHaveClass('astryx-banner-frame');
-          expect(frame).not.toHaveClass(containerType, elevation);
+          // The data attributes are canonical; the released bare values remain
+          // same-element compatibility classes through the 0.7.0 window.
+          expect(frame).toHaveClass(containerType, elevation);
           expect(frame).toHaveAttribute('data-container', containerType);
           expect(frame).toHaveAttribute('data-elevation', elevation);
           expect(frame?.firstElementChild).toHaveClass('astryx-banner');

package/src/BottomSheet/BottomSheetSwitcher.doc.mjs

@@ -1,6 +1,28 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+
+const anatomy = [
+  {
+    name: 'Shared dialog',
+    required: true,
+    description:
+      'One native dialog that owns modality, focus, dismissal, and lifecycle for the complete flow.',
+  },
+  {
+    name: 'Sheet panels',
+    required: true,
+    description:
+      'Direct BottomSheet children; exactly one is interactive while a previous panel may remain visible and inert during a handoff.',
+  },
+  {
+    name: 'Scrim',
+    required: false,
+    description:
+      'Native dialog backdrop shown by the default scrim-backed modal presentation.',
+  },
+];
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'BottomSheetSwitcher',
   displayName: 'Bottom Sheet Switcher',
@@ -122,6 +144,17 @@ export const docs = {
   description:
     'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. The switcher owns one shared native <dialog>: modal flows call showModal() once for one top-layer boundary and one ::backdrop across the whole flow, while no-scrim flows use a non-modal show() shell. Its ref and shared DOM props target that dialog.',
   props: [
+    {
+      name: 'ref',
+      type: 'Ref<HTMLDialogElement>',
+      description: 'Ref forwarded to the one shared native dialog.',
+    },
+    {
+      name: 'onCancel',
+      type: '(event: SyntheticEvent<HTMLDialogElement>) => void',
+      description:
+        'Called before the switcher handles a native dialog cancel request. Calling preventDefault() keeps the controlled flow open.',
+    },
     {
       name: 'activeSheet',
       type: 'string | null',
@@ -151,6 +184,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
     bestPractices: [
@@ -159,11 +193,21 @@ export const docs = {
         description:
           'Use when each step depends on the previous one and only one step needs attention at a time.',
       },
+      {
+        guidance: true,
+        description:
+          'Give every child a unique sheetId and non-empty label, choose its purpose to match dismissal requirements, and follow the WAI-ARIA Dialog (Modal) pattern for scrim-backed flows: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/.',
+      },
       {
         guidance: false,
         description:
           "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
       },
+      {
+        guidance: false,
+        description:
+          "Don't use the switcher when multiple panels must stay interactive or visible together; activeSheet intentionally selects one interactive step.",
+      },
     ],
   },
   examples: [
@@ -201,6 +245,7 @@ export const docsDense = {
   description:
     'controller with one shared native dialog for mutually exclusive multi-step BottomSheets',
   usage: {
+    anatomy,
     description:
       "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
     bestPractices: [
@@ -209,11 +254,21 @@ export const docsDense = {
         description:
           'Use when each step depends on the previous one and only one step needs attention at a time.',
       },
+      {
+        guidance: true,
+        description:
+          'Give every child a unique sheetId and non-empty label, choose its purpose to match dismissal requirements, and follow the WAI-ARIA Dialog (Modal) pattern for scrim-backed flows: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/.',
+      },
       {
         guidance: false,
         description:
           "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
       },
+      {
+        guidance: false,
+        description:
+          "Don't use the switcher when multiple panels must stay interactive or visible together; activeSheet intentionally selects one interactive step.",
+      },
     ],
   },
 };