@astryxdesign/core 0.5.0 → 0.5.1-canary.70169cd

package/src/Spinner/Spinner.tsx

@@ -34,6 +34,16 @@ import {themeProps} from '../utils/themeProps';
  */
 const ARC_FRACTION = 0.375;
 
+/**
+ * The dash pattern, per unit of diameter: one arc, then the gap that closes
+ * the circle. The circumference is `pi x diameter`, so multiplying the
+ * resolved diameter by these two constants gives exactly the lengths the
+ * default render has always used, and scales them with a themed diameter.
+ */
+const PI = 3.141592653589793;
+const ARC_DASH = PI * ARC_FRACTION;
+const ARC_GAP = PI * (1 - ARC_FRACTION);
+
 const SIZES = {
   sm: {diameter: 10, border: 2},
   md: {diameter: 14, border: 3},
@@ -41,14 +51,103 @@ const SIZES = {
   xl: {diameter: 28, border: 4},
 };
 
-/** `onMedia` keeps the 77/255 its token's `4D` hex suffix used to encode. */
-const TRACK_OPACITY = {
+/**
+ * Opacity the track is drawn at, per shade. `77 / 255` is the `4D` the onMedia
+ * track used to append to the token's hex — the same composite, but applied as
+ * `stroke-opacity` to a color off the cascade, so it no longer depends on the
+ * token being hex notation and it applies to a themed color too.
+ */
+const TRACK_OPACITY: Record<SpinnerShade, number> = {
   default: 1,
   subtle: 1,
   onMedia: 77 / 255,
   inherit: 0.3,
 };
 
+/**
+ * Where the resolved geometry lands: the public var, resolved into a registered
+ * `<length>` the `calc()`s below can do arithmetic on. The box and the ring
+ * read these; the public vars are declared once, on the element carrying the
+ * theme target, by `sizeStyles`.
+ */
+const RESOLVED_DIAMETER = '--_spinner-ring-diameter';
+const RESOLVED_STROKE = '--_spinner-ring-stroke';
+const RESOLVED_GEOMETRY_VARS = [RESOLVED_DIAMETER, RESOLVED_STROKE];
+
+/**
+ * The composed box size: diameter plus a stroke width on each side.
+ *
+ * It is deliberately NOT registered, unlike the pair above. The element reads
+ * it through an inline `width`/`height` with the size's own default as the
+ * `var()` fallback, so a render with no stylesheet — where nothing declares
+ * it — still sizes the box the way it always did. A registered property always
+ * has a value (its `initial-value`), which would swallow that fallback and
+ * collapse the box to zero.
+ */
+const BOX_SIZE = '--_spinner-box-size';
+
+/**
+ * Register the resolved geometry vars as `<length>`.
+ *
+ * Both are consumed inside `calc()` — the box adds two stroke widths to a diameter,
+ * the circle halves one. Unregistered, a custom property substitutes as text,
+ * so whatever a theme wrote lands in the expression verbatim and a bare `0`
+ * (a valid length on its own, a `<number>` inside `calc()`) poisons the sum:
+ * `calc(28px + 0 * 2)` is invalid at computed-value time and the box loses its
+ * size. Registered, the value is already an absolute length by the time the
+ * `calc()` sees it, so `0` means `0px` — a zero-width stroke that paints
+ * nothing — rather than a bare `0` that invalidates the sum and leaves the box
+ * with no size at all. One `stroke-width` drives both circles, so a themed
+ * stroke width of `0` hides the arc along with the track; an arc with no track behind
+ * it is `--spinner-track-color: transparent`.
+ *
+ * Only these private vars are registered. The four public ones deliberately
+ * are not: a registered property has an `initial-value`, so every element in
+ * the document would report a value for it — and
+ * `.github/scripts/theme-var-reachability.js` finds a var's declaring element
+ * by exactly that test, so registering them would point the guard at `<html>`
+ * and report a var no theme can select.
+ */
+function registerSpinnerVars(): void {
+  if (
+    typeof CSS === 'undefined' ||
+    typeof CSS.registerProperty !== 'function'
+  ) {
+    return;
+  }
+  for (const name of RESOLVED_GEOMETRY_VARS) {
+    try {
+      CSS.registerProperty({
+        name,
+        syntax: '<length>',
+        inherits: true,
+        initialValue: '0px',
+      });
+    } catch {
+      // Already registered — a second copy of the package on the page, or a
+      // fast-refresh re-evaluation. registerProperty throws rather than
+      // replacing, and the existing registration is this same one.
+    }
+  }
+}
+
+// Registering an inherited property with an `initial-value` invalidates style
+// for the whole document, so this runs when the module is evaluated rather
+// than when a spinner mounts. A spinner is the loading indicator: it mounts
+// onto a page that is already rendered, with someone already waiting, and the
+// recalc it triggers there is paid on the full tree. At import the tree is
+// whatever has rendered so far, which for a bundle loaded in the head is
+// nothing.
+//
+// It is safe at module scope in both directions. The `typeof CSS` guard above
+// keeps it out of the server render, and tree-shaking cannot strip it from a
+// build that renders a spinner: core's `sideEffects` allowlist does not name
+// this file, so a bundle that never imports `Spinner` drops the module whole —
+// registration and all, which is the outcome you want — while one that does
+// import it keeps the module, and a bare call is not something a bundler may
+// elide.
+registerSpinnerVars();
+
 /**
  * Pin every ring's rotation to the document timeline's origin instead of its
  * own start time, so spinners mounted seconds apart turn in phase.
@@ -78,12 +177,20 @@ function pinRingsToTimelineOrigin(): void {
   }
 }
 
+/**
+ * Ref callback for the ring: the one place a mounted ring touches the DOM.
+ *
+ * It reads nothing back — the geometry is resolved by the cascade, not in JS.
+ */
 function syncRotationPhase(
   svg: SVGSVGElement | null,
 ): (() => void) | undefined {
+  if (svg == null) {
+    return undefined;
+  }
   // jsdom implements no Web Animations, and this runs in every consumer's
   // component tests.
-  if (svg == null || typeof svg.getAnimations !== 'function') {
+  if (typeof svg.getAnimations !== 'function') {
     return undefined;
   }
   pendingRings.add(svg);
@@ -121,11 +228,31 @@ const styles = stylex.create({
     placeItems: 'center',
     overflow: 'hidden',
     verticalAlign: 'middle',
+    // The public geometry vars, resolved into the registered `<length>` pair
+    // the arithmetic below needs. Reading them here rather than in each
+    // `calc()` keeps one place where a themed value enters the component, and
+    // it is the span that reads them whether the theme target is the span or
+    // the wrapper — a custom property inherits either way.
+    [RESOLVED_DIAMETER]: 'var(--spinner-diameter)',
+    [RESOLVED_STROKE]: 'var(--spinner-stroke-width)',
+    // The size of the box, composed here and applied as an inline style at the
+    // element, so that the box and the drawn ring come from the same two vars
+    // and a themed size moves both together — without the sizing moving from
+    // an inline style to a rule, which would hand a caller's `style={{width}}`
+    // a precedence over the box that it has never had.
+    [BOX_SIZE]: `calc(var(${RESOLVED_DIAMETER}) + var(${RESOLVED_STROKE}) * 2)`,
   },
   ring: {
     backfaceVisibility: 'hidden',
     display: 'block',
     willChange: 'transform',
+    // The svg keeps the size its `viewBox` describes, so one user unit is one
+    // CSS pixel and the lengths below mean what they say. A themed diameter
+    // therefore draws a ring wider than the svg's own box — which is fine, and
+    // stays centered, because the box it is centered in is the span, sized
+    // from the same two vars. Clipping it to the default frame is the one
+    // thing that would break that, hence `visible`.
+    overflow: 'visible',
     // Slow the rotation dramatically under reduced-motion rather than freezing
     // it (a frozen spinner reads as broken), matching ProgressBar's approach.
     // The role="status" + "Loading" label still convey busy state (obs-6).
@@ -140,30 +267,98 @@ const styles = stylex.create({
   circle: {
     fill: 'none',
     strokeLinecap: 'round',
+    // The geometry the ring is actually drawn at. `r` and `stroke-width` are
+    // CSS properties on an SVG shape, and a CSS declaration outranks the
+    // presentation attribute of the same name — so the attributes below stay
+    // as the size's default (and as what a server render and a no-CSS render
+    // draw), and these take over the moment the cascade has a themed value.
+    r: `calc(var(${RESOLVED_DIAMETER}) / 2)`,
+    strokeWidth: `var(${RESOLVED_STROKE})`,
   },
+  // The two ring colors ride `stroke` directly, read off the public vars the
+  // shade declares. The paint comes from the cascade, so every notation a
+  // theme can write — `var()`, `color-mix()`, and the `currentColor` the
+  // inherit shade is built on — resolves where it is used, and a color changed
+  // after mount repaints instead of going stale.
+  //
+  // The dash pattern is composed from the resolved diameter the same way, so a
+  // themed ring keeps the same fraction of arc rather than the same absolute
+  // dash. `pathLength` would be the shorter route to that, but it rescales the
+  // pattern against the path length the UA measures on its own approximation
+  // of the circle — 87.398 against the 87.965 of pi x 28 — which shortens the
+  // default arc by 0.64% and moves the cap by half a pixel. Composing the
+  // lengths keeps the default byte-identical to what it drew before.
+  arc: {
+    stroke: 'var(--spinner-color)',
+    strokeDasharray: `calc(var(${RESOLVED_DIAMETER}) * ${ARC_DASH}) calc(var(${RESOLVED_DIAMETER}) * ${ARC_GAP})`,
+  },
+  track: {stroke: 'var(--spinner-track-color)'},
 });
 
-const arcStyles = stylex.create({
-  default: {stroke: colorVars['--color-accent']},
-  subtle: {stroke: colorVars['--color-text-secondary']},
-  onMedia: {stroke: colorVars['--color-on-dark']},
-  inherit: {stroke: 'currentColor'},
+// What each named `size` and `shade` resolve to. Both groups DECLARE the four
+// public vars, on the element that carries the `spinner` theme target, and
+// everything downstream reads them — so a theme's `@layer astryx-theme` rule
+// against `.astryx-spinner.xl` overrides the default the same way it does for
+// `--tree-list-indent` or `--button-focus-offset`, e.g.
+// spinner: { 'size:xl': { '--spinner-diameter': '40px' } }.
+//
+// Declaring is only safe because #5410 moved the compiled StyleX CSS inside
+// `@layer astryx-base`. Before it, StyleX emitted custom-property
+// declarations at priority 0 and therefore OUTSIDE its layers, and an
+// unlayered declaration beats every layer — so a StyleX-declared
+// `--spinner-diameter: 10px` shadowed the theme's own rule no matter how
+// specific the theme got. An earlier revision of this component worked around
+// that by never declaring the public var and reading it with the default as a
+// `var()` fallback; that is no longer necessary, and the fallback shape has a
+// cost of its own — with nothing declaring the var,
+// `theme-var-reachability.js` cannot find an element to check, so a documented
+// var reads as unreachable.
+const sizeStyles = stylex.create({
+  sm: {
+    '--spinner-diameter': `${SIZES.sm.diameter}px`,
+    '--spinner-stroke-width': `${SIZES.sm.border}px`,
+  },
+  md: {
+    '--spinner-diameter': `${SIZES.md.diameter}px`,
+    '--spinner-stroke-width': `${SIZES.md.border}px`,
+  },
+  lg: {
+    '--spinner-diameter': `${SIZES.lg.diameter}px`,
+    '--spinner-stroke-width': `${SIZES.lg.border}px`,
+  },
+  xl: {
+    '--spinner-diameter': `${SIZES.xl.diameter}px`,
+    '--spinner-stroke-width': `${SIZES.xl.border}px`,
+  },
 });
 
-const trackStyles = stylex.create({
+const shadeStyles = stylex.create({
   default: {
-    stroke: colorVars['--color-track'],
-    strokeOpacity: TRACK_OPACITY.default,
+    '--spinner-color': colorVars['--color-accent'],
+    '--spinner-track-color': colorVars['--color-track'],
   },
   subtle: {
-    stroke: colorVars['--color-track'],
-    strokeOpacity: TRACK_OPACITY.subtle,
+    '--spinner-color': colorVars['--color-text-secondary'],
+    '--spinner-track-color': colorVars['--color-track'],
   },
   onMedia: {
-    stroke: colorVars['--color-on-dark'],
-    strokeOpacity: TRACK_OPACITY.onMedia,
+    '--spinner-color': colorVars['--color-on-dark'],
+    '--spinner-track-color': colorVars['--color-on-dark'],
+  },
+  inherit: {
+    '--spinner-color': 'currentColor',
+    '--spinner-track-color': 'currentColor',
   },
-  inherit: {stroke: 'currentColor', strokeOpacity: TRACK_OPACITY.inherit},
+});
+
+// The track's alpha is a property, not a color: it composites over whatever
+// color the shade or the theme supplies. `77 / 255` is the `4D` the onMedia
+// token's hex used to carry.
+const trackOpacityStyles = stylex.create({
+  default: {strokeOpacity: TRACK_OPACITY.default},
+  subtle: {strokeOpacity: TRACK_OPACITY.subtle},
+  onMedia: {strokeOpacity: TRACK_OPACITY.onMedia},
+  inherit: {strokeOpacity: TRACK_OPACITY.inherit},
 });
 
 // =============================================================================
@@ -178,7 +373,9 @@ export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLSpanElement>;
   /**
-   * Spinner size.
+   * Spinner size. The diameter is the ring itself; the rendered box adds the
+   * stroke width on each side (xl draws a 28px ring in a 36px box). A theme can
+   * redefine what each named size resolves to — see `--spinner-diameter`.
    * - 'sm': 10px diameter
    * - 'md': 14px diameter
    * - 'lg': 18px diameter
@@ -275,9 +472,30 @@ export function Spinner({
       {...(hasLabel ? {} : restProps)}
       {...mergeProps(
         hasLabel ? '' : themeProps('spinner', {size, shade}),
-        stylex.props(styles.spinner, !hasLabel && xstyle),
+        stylex.props(
+          styles.spinner,
+          // The defaults are declared on whichever element carries the theme
+          // target, and only there: when a label moves the target to the
+          // wrapper, this span must inherit the wrapper's value rather than
+          // declare its own, which would shadow a theme's override with the
+          // default it is trying to replace.
+          !hasLabel && sizeStyles[size],
+          !hasLabel && shadeStyles[shade],
+          !hasLabel && xstyle,
+        ),
         hasLabel ? undefined : className,
-        {...(hasLabel ? {} : style), width: frameSize, height: frameSize},
+        // The box is sized here, after the caller's `style`, exactly as it was
+        // before the geometry became themeable: the component's own size wins
+        // over a `style={{width}}` a caller passes, and the precedence between
+        // the two is unchanged by this PR. What the value is made of has
+        // changed — it is the composed var rather than a number — so a themed
+        // diameter moves the box with the ring. The fallback is the size's own
+        // frame, for the render where no stylesheet has declared the var.
+        {
+          ...(hasLabel ? {} : style),
+          width: `var(${BOX_SIZE}, ${frameSize}px)`,
+          height: `var(${BOX_SIZE}, ${frameSize}px)`,
+        },
       )}>
       <svg
         ref={syncRotationPhase}
@@ -291,16 +509,23 @@ export function Spinner({
           cy={center}
           r={diameter / 2}
           strokeWidth={border}
-          {...stylex.props(styles.circle, trackStyles[shade])}
+          {...stylex.props(
+            styles.circle,
+            styles.track,
+            trackOpacityStyles[shade],
+          )}
         />
         <circle
           cx={center}
           cy={center}
           r={diameter / 2}
           strokeWidth={border}
+          // The size's own dash, for the render with no stylesheet. The rule
+          // above composes the same lengths from the resolved diameter, so a
+          // themed ring keeps this fraction of arc rather than this length.
           strokeDasharray={`${arcLength} ${circumference - arcLength}`}
           transform={`rotate(-90 ${center} ${center})`}
-          {...stylex.props(styles.circle, arcStyles[shade])}
+          {...stylex.props(styles.circle, styles.arc)}
         />
       </svg>
     </span>
@@ -317,7 +542,12 @@ export function Spinner({
       {...restProps}
       {...mergeProps(
         themeProps('spinner', {size, shade}),
-        stylex.props(styles.wrapper, xstyle),
+        stylex.props(
+          styles.wrapper,
+          sizeStyles[size],
+          shadeStyles[shade],
+          xstyle,
+        ),
         className,
         style,
       )}>

package/src/StatusDot/StatusDot.doc.mjs

@@ -48,7 +48,10 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-statusdot', visualProps: ['variant']},
+      {className: 'astryx-status-dot', visualProps: ['variant']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},
     ],
   },
   usage: {
@@ -105,7 +108,10 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-statusdot', visualProps: ['variant']},
+      {className: 'astryx-status-dot', visualProps: ['variant']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},
     ],
   },
   usage: {

package/src/StatusDot/StatusDot.test.tsx

@@ -189,3 +189,12 @@ describe('StatusDot', () => {
     });
   });
 });
+
+describe('StatusDot theme target names', () => {
+  it('renders the deprecated class beside the current one', () => {
+    render(<StatusDot variant="success" label="Online" />);
+    const dot = screen.getByRole('img', {name: 'Online'});
+    expect(dot).toHaveClass('astryx-status-dot');
+    expect(dot).toHaveClass('astryx-statusdot');
+  });
+});

package/src/StatusDot/StatusDot.tsx

@@ -200,7 +200,13 @@ export function StatusDot({
       role="img"
       aria-label={label}
       {...mergeProps(
-        themeProps('statusdot', {variant}),
+        themeProps(
+          'status-dot',
+          {variant},
+          // `statusdot` ran the compound name together; themes styling it keep
+          // working until the next major.
+          {legacyNames: ['statusdot']},
+        ),
         stylex.props(
           styles.base,
           variants[variant],

package/src/Stepper/Step.doc.mjs

@@ -10,7 +10,7 @@ export const docs = {
   category: 'Navigation',
   isHiddenFromOverview: true,
   description:
-    'Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper\u2019s activeStep and this step\u2019s step index.',
+    'Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper\'s activeStep and this step\'s step index.',
   props: [
     {
       name: 'step',

package/src/Stepper/Step.tsx

@@ -51,6 +51,7 @@ import {
   isRenderable,
   themeProps,
 } from '../utils';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Icon} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -655,13 +656,7 @@ const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
-    backgroundColor: {
-      default: 'transparent',
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': colorVars['--color-overlay-hover'],
-      },
-      ':active': colorVars['--color-overlay-pressed'],
-    },
+    backgroundColor: 'transparent',
   },
 
   // ===================== ON-TRACK LAYOUT =====================
@@ -702,13 +697,7 @@ const styles = stylex.create({
       '@media (prefers-reduced-motion: reduce)': '0s',
     },
     transitionTimingFunction: easeVars['--ease-standard'],
-    backgroundColor: {
-      default: 'transparent',
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': colorVars['--color-overlay-hover'],
-      },
-      ':active': colorVars['--color-overlay-pressed'],
-    },
+    backgroundColor: 'transparent',
   },
 
   otRowWrap: {
@@ -1411,6 +1400,7 @@ export function Step({
               aria-label={stepAriaLabel}
               {...stylex.props(
                 styles.otInteractive,
+                interactionOverlayStyles.backgroundColor,
                 styles.otRowWrap,
                 styles.otRowPadV(densitySpace),
                 focusOutlineStyles.focusVisible,
@@ -1493,6 +1483,7 @@ export function Step({
             aria-label={stepAriaLabel}
             {...stylex.props(
               styles.otInteractive,
+              interactionOverlayStyles.backgroundColor,
               styles.otColWrap,
               styles.otPadBlock(densitySpace),
               focusOutlineStyles.focusVisible,
@@ -1549,6 +1540,7 @@ export function Step({
               aria-label={stepAriaLabel}
               {...stylex.props(
                 styles.buttonReset,
+                interactionOverlayStyles.backgroundColor,
                 focusOutlineStyles.focusVisible,
                 density === 'compact' && styles.densityCompact,
                 density === 'balanced' && styles.densityBalanced,
@@ -1609,6 +1601,7 @@ export function Step({
           aria-label={stepAriaLabel}
           {...stylex.props(
             styles.buttonReset,
+            interactionOverlayStyles.backgroundColor,
             focusOutlineStyles.focusVisible,
             density === 'compact' && styles.densityCompact,
             density === 'balanced' && styles.densityBalanced,

package/src/Switch/Switch.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'Switch',
   displayName: 'Switch',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'switch',
     'toggle',
@@ -167,6 +167,7 @@ export const docs = {
         className: 'astryx-switch-field',
         visualProps: ['labelPosition', 'labelSpacing'],
       },
+      {className: 'astryx-switch-label'},
     ],
   },
   usage: {
@@ -338,6 +339,7 @@ export const docsZh = {
         className: 'astryx-switch-field',
         visualProps: ['labelPosition', 'labelSpacing'],
       },
+      {className: 'astryx-switch-label'},
     ],
   },
   usage: {

package/src/Switch/Switch.test.tsx

@@ -823,3 +823,13 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getForcedColorsRules()).not.toContain('color-mix');
   });
 });
+
+describe('label theme target', () => {
+  it('names its own label so a theme can style it apart from a field label', () => {
+    // See CheckboxInput: the control names the label it owns.
+    render(<Switch label="Wi-Fi" value={false} onChange={() => {}} />);
+    const label = screen.getByText('Wi-Fi').closest('label');
+    expect(label).toHaveClass('astryx-field-label');
+    expect(label).toHaveClass('astryx-switch-label');
+  });
+});

package/src/Switch/Switch.tsx

@@ -633,6 +633,9 @@ export function Switch({
   const labelElement = (
     <div {...stylex.props(styles.labelWrapper, labelWrapperSizeStyles[size])}>
       <FieldLabel
+        // See CheckboxInput: the control names its own label target rather
+        // than the label guessing at its placement.
+        {...themeProps('switch-label')}
         label={label}
         inputID={id}
         isLabelHidden={isLabelHidden}

package/src/Table/BaseTable.tsx

@@ -528,7 +528,12 @@ function BaseTableInner<T extends Record<string, unknown>>({
       {...(ariaRowCount != null ? {'aria-rowcount': ariaRowCount} : null)}
       {...tableRenderProps.htmlProps}
       {...mergeProps(
-        themeProps('base-table'),
+        themeProps('table', undefined, {
+          // `base-table` was a second root on the same <table> element that
+          // `table` names; themes styling it keep working until the next
+          // major.
+          legacyNames: ['base-table'],
+        }),
         stylex.props(...tableRenderProps.xstyle, xstyle),
         [tableRenderProps.htmlProps.className, className]
           .filter(Boolean)

package/src/Table/Table.doc.mjs

@@ -24,7 +24,6 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-base-table'},
       {className: 'astryx-table'},
       {className: 'astryx-table-scroll-wrapper'},
       {className: 'astryx-table-header'},
@@ -33,6 +32,9 @@ export const docs = {
       {className: 'astryx-table-row'},
       {className: 'astryx-table-cell', visualProps: ['density']},
       {className: 'astryx-table-header-cell', visualProps: ['density']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-base-table', deprecatedFor: 'table'},
     ],
   },
   description: 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support. T must extend Record<string, unknown>.',
@@ -107,7 +109,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Children mode: compose the table yourself from TableHeader / TableBody / TableFooter, each holding TableRow and TableCell, instead of using data-driven rendering. The children are passed straight to the <table>, so the section is yours to supply — a TableRow placed directly in Table emits <table><tr>, which is invalid HTML and mismatches on hydration (the parser inserts an implied <tbody> for server-rendered markup; React does not on the client). Data-driven mode renders the sections for you.',
+      description: 'Children mode: compose the table yourself from TableHeader / TableBody / TableFooter, each holding TableRow and TableCell, instead of using data-driven rendering. The children are passed straight to the <table>, so the section is yours to supply. A TableRow placed directly in Table emits <table><tr>, which is invalid HTML and mismatches on hydration (the parser inserts an implied <tbody> for server-rendered markup; React does not on the client). Data-driven mode renders the sections for you.',
     },
     {
       name: 'xstyle',
@@ -187,7 +189,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
       { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
-      { guidance: true, description: 'Children mode: wrap rows in TableHeader/TableBody/TableFooter. <table> cannot hold a <tr> directly — parser adds an implied <tbody> for SSR markup, React does not on the client, so unwrapped rows mismatch on hydration.' },
+      { guidance: true, description: 'Children mode: wrap rows in TableHeader/TableBody/TableFooter. <table> cannot hold a <tr> directly; the parser adds an implied <tbody> for SSR markup, React does not on the client, so unwrapped rows mismatch on hydration.' },
       { guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
       { guidance: true, description: 'Data-driven API is RSC-safe: proportional(), pixel(), column defs w/o function props work in Server Components. renderCell (any function prop) requires a "use client" wrapper.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },

package/src/Table/Table.tsx

@@ -186,16 +186,11 @@ function buildTableStylePlugin<
 >(): TablePlugin<T> {
   return {
     transformTable(props: TableRenderProps): TableRenderProps {
-      const existingClass = props.htmlProps.className ?? '';
-      const tableClass = themeProps('table').className;
+      // The `astryx-table` class itself comes from BaseTable, which renders
+      // the <table> element and now names it `table` (with `base-table` as its
+      // legacy name). Adding it here too would put the token on twice.
       return {
         ...props,
-        htmlProps: {
-          ...props.htmlProps,
-          className: existingClass
-            ? `${existingClass} ${tableClass}`
-            : tableClass,
-        },
         xstyle: [...props.xstyle, tableStyles.base],
       };
     },

package/src/Table/TableBody.doc.mjs

@@ -8,7 +8,7 @@ export const docs = {
   displayName: 'Table Body',
   isHiddenFromOverview: true,
   description:
-    '<tbody> wrapper for children mode. Holds the data rows. A row must sit inside a section — <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so rows written straight into Table mismatch on hydration. The data-driven data={...} mode renders this element itself; in children mode it is yours to supply.',
+    '<tbody> wrapper for children mode. Holds the data rows. A row must sit inside a section: <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so rows written straight into Table mismatch on hydration. The data-driven data={...} mode renders this element itself; in children mode it is yours to supply.',
   props: [
     {
       name: 'children',
@@ -32,7 +32,7 @@ export const docsDense = {
   name: 'TableBody',
   isHiddenFromOverview: true,
   displayName: 'Table Body',
-  description: '<tbody> wrapper for children mode; holds the data rows — children mode does not add one for you',
+  description: '<tbody> wrapper for children mode; holds the data rows; children mode does not add one for you',
   propDescriptions: {
     children: 'The <tbody> rows.',
     xstyle: 'StyleX styles for layout customization',

package/src/Table/TableFooter.doc.mjs

@@ -8,7 +8,7 @@ export const docs = {
   displayName: 'Table Footer',
   isHiddenFromOverview: true,
   description:
-    '<tfoot> wrapper for children mode. Holds summary or total rows beneath the body. A row must sit inside a section — <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so the two trees mismatch on hydration. Children mode only: the data-driven data={...} path renders a header and a body, never a footer.',
+    '<tfoot> wrapper for children mode. Holds summary or total rows beneath the body. A row must sit inside a section: <table> cannot contain a <tr> directly, because the HTML parser inserts an implied <tbody> when it parses server-rendered markup and React does not when it renders on the client, so the two trees mismatch on hydration. Children mode only: the data-driven data={...} path renders a header and a body, never a footer.',
   props: [
     {
       name: 'children',