@astryxdesign/cli 0.1.3 → 0.1.4-canary.02643db

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @xds/cli
 
+# 0.1.4
+
+#### Fixes
+
+- `astryx component <Name>` now prints the correct `defineTheme` component-override key. The theming example stripped a stale `xds-` prefix (left over from the astryx rename) instead of `astryx-`, so it advertised keys like `astryx-base-table` / `astryx-button`. Those double-prefix to `.astryx-astryx-*` selectors at runtime and silently match nothing. Keys are now the stable class name minus `astryx-` (e.g. `base-table`, `button`), which is what `generateThemeRules` expects (#3458).
+- Harden the v0.1.0 upgrade codemods against three cases surfaced while migrating consumer apps:
+
+#### Documentation
+
+- Add a browser-support guide (`astryx docs browser-support`) documenting the support tiers, the modern platform features Astryx depends on (Popover API, CSS anchor positioning, `light-dark()`), which components are affected, and how consumers can support older browsers for their own audience.
+
+#### Other Changes
+
+- **drop-xds-prefix-imports**: when un-prefixing an `@xds/core` import (e.g. `XDSCodeBlock` → `CodeBlock`) would collide with a same-named local binding in the file (such as a local `export function CodeBlock` wrapper), alias the import to `Astryx<Name>` and rewrite its usages instead of producing a duplicate declaration that breaks the build.
+- **migrate-xds-css-surfaces**: rewrite CSS `@import` of `@xds/*` package stylesheets (both `'…'`/`"…"` and `url(…)` forms), including the `@xds/core/xds.css` → `@astryxdesign/core/astryx.css` file rename and the `theme-default`/`theme-daily` → `theme-neutral` collapse.
+- **migrate-xds-module-specifiers**: when collapsing `@xds/theme-default`/`@xds/theme-daily` to `@astryxdesign/theme-neutral`, remap the `defaultTheme` export to `neutralTheme`, aliasing back to the original local name (`neutralTheme as defaultTheme`) so downstream usages keep working.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @ejhammond
+- @ryanda9910
+
+---
+
 # 0.1.3
 
 #### New Features

package/docs/browser-support.doc.mjs

@@ -0,0 +1,200 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'browser-support',
+  title: 'Browser Support',
+  category: 'guide',
+  description:
+    'What browsers Astryx targets, which modern platform features it depends on, and how to support older browsers for your own audience.',
+
+  sections: [
+    {
+      title: 'Overview',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx is built on modern web platform features: the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+        },
+        {
+          type: 'prose',
+          text: 'A design system does not own its traffic; the products built on it do. Their audiences range from evergreen-Chrome-only internal tools to public sites with meaningful older-Safari share. So Astryx does not declare a single hard browser floor the way an app would. Instead it defines tiers that describe what works at each level, and hands the final decision to you. Pick the tier that matches your audience.',
+        },
+      ],
+    },
+    {
+      title: 'Support Tiers',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx officially supports Tier 1 and Tier 2. Tier 3 is best-effort: components will not crash, but positioning and theming may degrade.',
+        },
+        {
+          type: 'table',
+          headers: ['Tier', 'Baseline', 'Representative versions', 'What your users experience'],
+          rows: [
+            [
+              'Tier 1: Full fidelity',
+              'Current Baseline (2026)',
+              'Chrome 125+, Edge 125+, Safari 26+, Firefox 147+',
+              'Everything works, including CSS anchor positioning. This is the reference target.',
+            ],
+            [
+              'Tier 2: Functional',
+              'Baseline − 2 years (2024)',
+              'Chrome 114+, Edge 114+, Safari 17+, Firefox 125+',
+              'Components open, dismiss, and are fully usable. Only anchor positioning is missing, so layered surfaces (tooltips, menus, popovers) may not be positioned next to their trigger.',
+            ],
+            [
+              'Tier 3: Below Tier 2',
+              'Older than Baseline − 2',
+              'Anything older',
+              'Best-effort. The only guarantee is "does not crash." `light-dark()` is unavailable, so theme colors may fall back to defaults.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Which Features Set the Floor',
+      content: [
+        {
+          type: 'prose',
+          text: 'Only three modern features carry a browser requirement. Everything else Astryx uses (`:has()`, `color-mix()`, container queries, the `<dialog>` element) has been widely available since 2023 or earlier and needs no special handling.',
+        },
+        {
+          type: 'table',
+          headers: ['Feature', 'Role in Astryx', 'Widely available'],
+          rows: [
+            [
+              'CSS Anchor Positioning',
+              'Positions layered surfaces relative to their trigger (tooltips, menus, popovers, dropdowns).',
+              'Baseline 2026: the tightest requirement.',
+            ],
+            [
+              'Popover API',
+              'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
+              'Baseline 2025.',
+            ],
+            [
+              'CSS light-dark()',
+              'Compiles every theme color tuple into a single value that responds to color scheme. Underpins the whole theming system.',
+              'Widely available since mid-2024.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+        },
+      ],
+    },
+    {
+      title: 'Which Components Are Affected',
+      content: [
+        {
+          type: 'prose',
+          text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tooltip',
+            'HoverCard',
+            'Popover',
+            'ContextMenu',
+            'Selector and MultiSelector (dropdown surfaces)',
+            'Tokenizer (suggestion menu)',
+            'Carousel (anchored controls)',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+        },
+      ],
+    },
+    {
+      title: 'What Astryx Guarantees',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Tier 1 and Tier 2 are officially supported and tested.',
+            'Non-layered components render correctly down to Tier 2.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Astryx does not guarantee correct layer positioning below Tier 1 (anchor positioning). Closing that gap for a Tier 2 audience is a consumer choice; see below.',
+            'Astryx does not ship a `light-dark()` fallback, so theme colors are not guaranteed below Tier 2.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Supporting Older Browsers',
+      content: [
+        {
+          type: 'prose',
+          text: 'If your audience includes Tier 2 browsers and you need correct layer positioning, you have three options, cheapest first. All of them are decisions you make for your audience; Astryx does not impose one.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; note that polyfills may not cover every position-fallback feature.',
+            'Provide a JS positioning fallback. Detect missing support with `CSS.supports("anchor-name", "--x")` and position layers with a measurement-based library (e.g. a floating-element positioner) when it returns false. More code, full control.',
+            'Accept degraded positioning. Document for your users that on Tier 2 browsers, layered surfaces open correctly but may not sit next to their trigger. Cheapest, and often fine for internal tools on evergreen browsers.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Feature-detect at runtime rather than sniffing user agents:',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'Feature detection',
+          code: `// Popover API (Tier 2 and up)
+const hasPopover = typeof HTMLElement !== 'undefined'
+  && typeof HTMLElement.prototype.showPopover === 'function';
+
+// CSS anchor positioning (Tier 1)
+const hasAnchorPositioning = CSS.supports('anchor-name', '--x');
+
+// CSS light-dark() (Tier 2 and up)
+const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
+        },
+      ],
+    },
+    {
+      title: 'How These Tiers Move Over Time',
+      content: [
+        {
+          type: 'prose',
+          text: 'The tiers are rolling, not frozen to specific versions. They track the Web Baseline year:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tier 1 tracks the current Baseline year.',
+            'Tier 2 tracks Baseline minus two years.',
+            'Tier 3 is everything older, and remains best-effort.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+        },
+      ],
+    },
+  ],
+};

package/docs/layout.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data — anything the user scans, filters, or selects — belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
+          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data (anything the user scans, filters, or selects) belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
         },
         {
           type: 'list',
@@ -111,7 +111,7 @@ export const docs = {
             'Wrapping each list item in a Card (card soup)',
             'Stacking full-width Cards as a substitute for page structure',
             'Nesting Cards inside Cards',
-            'Using Badge as decoration — reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
+            'Using Badge as decoration: reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
           ],
         },
       ],

package/docs/theme.doc.mjs

@@ -124,14 +124,14 @@ function App() {
           type: 'table',
           headers: ['Prop', 'Type', 'Default', 'Description'],
           rows: [
-            ['theme', 'DefinedTheme', '—', 'Theme object (required)'],
+            ['theme', 'DefinedTheme', '-', 'Theme object (required)'],
             [
               'mode',
               "'system' | 'light' | 'dark'",
               "'system'",
               'Color mode. system follows OS preference.',
             ],
-            ['children', 'ReactNode', '—', 'App content'],
+            ['children', 'ReactNode', '-', 'App content'],
           ],
         },
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.3",
+  "version": "0.1.4-canary.02643db",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/core": "0.1.4-canary.02643db",
+    "@astryxdesign/lab": "0.1.4-canary.02643db",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.02643db",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/core": "0.1.4-canary.02643db",
+    "@astryxdesign/lab": "0.1.4-canary.02643db",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.02643db",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/component.mjs

@@ -8,6 +8,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
 import {
@@ -560,7 +561,7 @@ export async function component(name, options = {}) {
 
     // Examples: blocks in the component's own directory, or
     // componentsUsed match for sub-components without a directory.
-    const ownDir = allBlocks.filter(b => b.category.split('/').pop() === dirName);
+    const ownDir = allBlocks.filter(b => path.basename(b.category) === dirName);
     const examples = ownDir.length > 0
       ? ownDir
       : allBlocks.filter(b => b.componentsUsed?.some(c => c === dirName));

package/src/api/template.mjs

@@ -63,6 +63,17 @@ const DEMO_IMAGE_PATTERNS = [
   /https?:\/\/(?:[\w-]+\.)*lookaside\.facebook\.com\/[^\s'"`)]+/g,
 ];
 
+/**
+ * Normalize path into Unix path (using forward slashes) for consistent comparison
+ * across Windows, macOS, and Linux.
+ *
+ * @param {string} p - The file path to normalize.
+ * @returns {string} The normalized Unix path.
+ */
+function toPosixPath(p) {
+  return p.replace(/\\/g, '/');
+}
+
 /**
  * Replace demo image references with a self-contained placeholder data URI so
  * scaffolded pages render with zero setup. Builders drop in their own images.
@@ -144,7 +155,7 @@ async function discoverBlocks() {
     const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
     if (!fs.existsSync(tsxPath)) continue;
     const doc = await loadDocModule(docPath);
-    const relPath = path.relative(BLOCKS_DIR, path.dirname(docPath));
+    const relPath = toPosixPath(path.relative(BLOCKS_DIR, path.dirname(docPath)));
     blocks.push({
       type: 'block',
       dirName: basename,
@@ -180,7 +191,7 @@ async function discoverExternalBlocks(cwd = process.cwd()) {
       const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
       if (!fs.existsSync(tsxPath)) continue;
       const doc = await loadDocModule(docPath);
-      const relPath = path.relative(ext.blocksDir, path.dirname(docPath));
+      const relPath = toPosixPath(path.relative(ext.blocksDir, path.dirname(docPath)));
       blocks.push({
         type: 'block',
         dirName: basename,
@@ -428,7 +439,7 @@ export async function findShowcase(componentName, cwd, options) {
 
   // Priority 1: own directory (components/Badge/ for "Badge")
   const dirMatch = showcases.find(b => {
-    const catDir = b.category.split('/').pop()?.toLowerCase();
+    const catDir = path.basename(b.category).toLowerCase();
     return catDir === lc;
   });
   if (dirMatch) return toResult(dirMatch);

package/src/codemods/transforms/v0.1.0/__tests__/drop-xds-prefix-imports.test.mjs

@@ -134,4 +134,47 @@ describe('drop-xds-prefix-imports', () => {
     expect(output).toContain(`import {useState} from 'react';`);
     expect(output).toContain('const x = 1;');
   });
+
+  it('aliases to Astryx<Name> when the bare name collides with a local export function', async () => {
+    const input = [
+      `import {XDSCodeBlock} from '@xds/core/CodeBlock';`,
+      `export function CodeBlock({code}: {code: string}) {`,
+      `  return <XDSCodeBlock code={code} />;`,
+      `}`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    // Import aliased to AstryxCodeBlock; local declaration untouched.
+    expect(output).toContain('CodeBlock as AstryxCodeBlock');
+    expect(output).toContain('@xds/core/CodeBlock');
+    expect(output).toContain('export function CodeBlock({code}');
+    expect(output).toContain('<AstryxCodeBlock code={code} />');
+    // No duplicate CodeBlock binding (not imported bare).
+    expect(output).not.toMatch(/import \{CodeBlock\}/);
+  });
+
+  it('aliases on collision with a local const/class binding', async () => {
+    const input = [
+      `import {XDSCard} from '@xds/core';`,
+      `const Card = 42;`,
+      `export const value = <XDSCard />;`,
+      `export const other = Card;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('import {Card as AstryxCard}');
+    expect(output).toContain('const Card = 42;');
+    expect(output).toContain('<AstryxCard />');
+    expect(output).toContain('export const other = Card;');
+  });
+
+  it('un-prefixes normally when there is NO local collision', async () => {
+    const input = [
+      `import {XDSCodeBlock} from '@xds/core/CodeBlock';`,
+      `export const App = () => <XDSCodeBlock code="x" />;`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain('{CodeBlock}');
+    expect(output).toContain('@xds/core/CodeBlock');
+    expect(output).toContain('<CodeBlock code="x" />');
+    expect(output).not.toContain('AstryxCodeBlock');
+  });
 });

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-css-surfaces.test.mjs

@@ -64,4 +64,40 @@ describe('migrate-xds-css-surfaces', () => {
     const output = await applyTransform(input);
     expect(output).toBe(input);
   });
+
+  it('rewrites @import of @xds/* package stylesheets', async () => {
+    const input = [
+      `@import '@xds/core/reset.css';`,
+      `@import '@xds/core/xds.css';`,
+      `@import '@xds/theme-default/theme.css';`,
+    ].join('\n');
+    const output = await applyTransform(input);
+    expect(output).toContain(`@import '@astryxdesign/core/reset.css';`);
+    // xds.css is renamed to astryx.css (file rename, not just scope swap).
+    expect(output).toContain(`@import '@astryxdesign/core/astryx.css';`);
+    // theme-default collapses to theme-neutral.
+    expect(output).toContain(
+      `@import '@astryxdesign/theme-neutral/theme.css';`,
+    );
+    expect(output).not.toContain('@xds/');
+  });
+
+  it('collapses theme-daily @import to theme-neutral and preserves quote style', async () => {
+    const input = `@import "@xds/theme-daily/theme.css";`;
+    const output = await applyTransform(input);
+    expect(output).toBe(`@import "@astryxdesign/theme-neutral/theme.css";`);
+  });
+
+  it('rewrites @import url() form', async () => {
+    const input = `@import url('@xds/core/reset.css');`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`@astryxdesign/core/reset.css`);
+    expect(output).not.toContain('@xds/');
+  });
+
+  it('does not touch @import of non-xds packages', async () => {
+    const input = `@import '@acme/widgets/styles.css';`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
 });

package/src/codemods/transforms/v0.1.0/__tests__/migrate-xds-module-specifiers.test.mjs

@@ -48,4 +48,45 @@ describe('migrate-xds-module-specifiers', () => {
     const output = await applyTransform(input, 'test.ts');
     expect(output).toBe(input);
   });
+
+  it('remaps defaultTheme -> neutralTheme when collapsing theme-default', async () => {
+    const output = await applyTransform(
+      `import {defaultTheme} from '@xds/theme-default';`,
+      'test.ts',
+    );
+    // Package collapses to theme-neutral; binding aliased so local usage works.
+    expect(output).toContain('neutralTheme as defaultTheme');
+    expect(output).toContain('@astryxdesign/theme-neutral');
+    expect(output).not.toContain('@xds/');
+    expect(output).not.toContain('theme-default');
+  });
+
+  it('remaps defaultTheme -> neutralTheme for theme-daily and /built subpath', async () => {
+    const output = await applyTransform(
+      `import {defaultTheme} from '@xds/theme-daily/built';`,
+      'test.ts',
+    );
+    expect(output).toContain('neutralTheme as defaultTheme');
+    expect(output).toContain('@astryxdesign/theme-neutral/built');
+  });
+
+  it('preserves an existing alias when remapping defaultTheme', async () => {
+    const output = await applyTransform(
+      `import {defaultTheme as dt} from '@xds/theme-default';`,
+      'test.ts',
+    );
+    expect(output).toContain('neutralTheme as dt');
+    expect(output).toContain('@astryxdesign/theme-neutral');
+  });
+
+  it('does NOT remap neutralTheme import from theme-neutral (no rename needed)', async () => {
+    const output = await applyTransform(
+      `import {neutralTheme} from '@xds/theme-neutral';`,
+      'test.ts',
+    );
+    expect(output).toContain('neutralTheme');
+    expect(output).toContain('@astryxdesign/theme-neutral');
+    expect(output).not.toContain('defaultTheme');
+    expect(output).not.toContain('neutralTheme as');
+  });
 });

package/src/codemods/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -85,35 +85,87 @@ export default function transformer(file, api) {
   // local alias and only the imported name is rewritten.
   const localRenames = new Map();
 
+  // Collision detection: un-prefixing `XDSCodeBlock` -> `CodeBlock` breaks if
+  // the file already has a top-level binding named `CodeBlock` (e.g. its own
+  // `export function CodeBlock`). Collect every existing top-level binding name
+  // up front so we can alias to `Astryx<Name>` instead of producing a duplicate
+  // declaration. We gather: import locals, and top-level function/class/var
+  // declaration names (the realistic collision sources for component wrappers).
+  const existingBindings = new Set();
+  root.find(j.ImportDeclaration).forEach(path => {
+    for (const spec of path.node.specifiers || []) {
+      if (spec.local && spec.local.name) existingBindings.add(spec.local.name);
+    }
+  });
+  const collectDeclName = node => {
+    if (!node) return;
+    if (
+      (node.type === 'FunctionDeclaration' ||
+        node.type === 'ClassDeclaration') &&
+      node.id
+    ) {
+      existingBindings.add(node.id.name);
+    } else if (node.type === 'VariableDeclaration') {
+      for (const d of node.declarations) {
+        if (d.id && d.id.type === 'Identifier') existingBindings.add(d.id.name);
+      }
+    }
+  };
+  root.find(j.Program).forEach(path => {
+    for (const stmt of path.node.body) {
+      collectDeclName(stmt);
+      // Unwrap `export function X` / `export const X`.
+      if (stmt.type === 'ExportNamedDeclaration' && stmt.declaration) {
+        collectDeclName(stmt.declaration);
+      }
+      if (stmt.type === 'ExportDefaultDeclaration' && stmt.declaration) {
+        collectDeclName(stmt.declaration);
+      }
+    }
+  });
+
   // 1. Rewrite import specifiers from @xds/core
   root.find(j.ImportDeclaration).forEach(path => {
     const source = path.node.source.value;
     if (typeof source !== 'string' || !XDS_CORE_SOURCE.test(source)) return;
 
-    for (const spec of path.node.specifiers || []) {
-      if (spec.type !== 'ImportSpecifier') continue; // skip default/namespace
+    path.node.specifiers = (path.node.specifiers || []).map(spec => {
+      if (spec.type !== 'ImportSpecifier') return spec; // default/namespace
       const importedName = spec.imported.name;
       const bare = bareName(importedName);
-      if (!bare) continue;
+      if (!bare) return spec;
 
       const localName = spec.local.name;
       const wasAliased = localName !== importedName;
 
-      // Rewrite the imported name to the bare alias.
-      spec.imported.name = bare;
-
+      // We REPLACE the specifier node (rather than mutating .imported/.local)
+      // because recast preserves the original printed form of a mutated
+      // ImportSpecifier and will drop a newly-introduced `as local` alias.
+      // Building a fresh node makes recast print the full `imported as local`.
       if (wasAliased) {
         // `import {XDSButton as Btn}` -> `import {Button as Btn}`.
-        // Local binding unchanged, so no usage rewrites needed.
         hasChanges = true;
-      } else {
-        // `import {XDSButton}` -> `import {Button}`. The local binding is the
-        // prefixed name; rename it and all its references.
-        spec.local.name = bare;
-        localRenames.set(importedName, bare);
+        return j.importSpecifier(j.identifier(bare), j.identifier(localName));
+      }
+      if (bare !== importedName && existingBindings.has(bare)) {
+        // COLLISION: the bare name is already a top-level binding in this file
+        // (e.g. a local `export function CodeBlock` alongside imported
+        // `XDSCodeBlock`). Un-prefixing directly would create a duplicate
+        // declaration, so alias the import to `Astryx<Name>` and rename the
+        // import's references to that alias, leaving the local binding intact.
+        const alias = `Astryx${bare}`;
+        localRenames.set(importedName, alias);
+        existingBindings.add(alias);
         hasChanges = true;
+        return j.importSpecifier(j.identifier(bare), j.identifier(alias));
       }
-    }
+      // `import {XDSButton}` -> `import {Button}`. The local binding is the
+      // prefixed name; rename it and all its references.
+      localRenames.set(importedName, bare);
+      existingBindings.add(bare);
+      hasChanges = true;
+      return j.importSpecifier(j.identifier(bare), j.identifier(bare));
+    });
   });
 
   // 2. Rewrite re-exports from @xds/core

package/src/codemods/transforms/v0.1.0/migrate-xds-css-surfaces.mjs

@@ -18,6 +18,10 @@
  *   [data-xds-media         (media attribute selector)
  *   @layer xds-theme        (cascade layer name — incl. comma-separated
  *   @layer xds-base          `@layer a, b;` statement lists and nested blocks)
+ *   @import '@xds/...'      (package stylesheet imports — scope rewrite, plus
+ *                            the @xds/core/xds.css -> @astryxdesign/core/
+ *                            astryx.css file rename and the theme-default /
+ *                            theme-daily -> theme-neutral collapse)
  *
  * It deliberately does NOT blindly replace every `xds` substring: a bare
  * `xds` in a comment, a custom-property value, or an unrelated identifier is
@@ -30,9 +34,10 @@ export const meta = {
   description:
     'Rewrites the documented XDS CSS surfaces to their Astryx equivalents: ' +
     'the `.xds-*` class-selector prefix, `[data-xds-theme]` / ' +
-    '`[data-xds-theme-prose]` / `[data-xds-media]` attribute selectors, and ' +
-    '`@layer xds-theme` / `@layer xds-base` cascade-layer names all become ' +
-    'their `astryx-*` / `data-astryx-*` forms.',
+    '`[data-xds-theme-prose]` / `[data-xds-media]` attribute selectors, ' +
+    '`@layer xds-theme` / `@layer xds-base` cascade-layer names, and ' +
+    '`@import` of @xds/* package stylesheets (scope rewrite, xds.css->astryx.css, ' +
+    'theme-default/theme-daily->theme-neutral) all become their Astryx forms.',
   pr: '#3092',
   fileExtensions: ['.css', '.scss'],
 };
@@ -52,6 +57,32 @@ function rewriteLayerPrelude(prelude) {
   );
 }
 
+// Rewrite a single @import package-stylesheet specifier value (without quotes)
+// from an @xds/* path to its @astryxdesign/* equivalent. Handles the two
+// non-mechanical cases beyond the scope swap:
+//   @xds/core/xds.css            -> @astryxdesign/core/astryx.css   (file rename)
+//   @xds/theme-default/*         -> @astryxdesign/theme-neutral/*   (collapse)
+//   @xds/theme-daily/*           -> @astryxdesign/theme-neutral/*   (collapse)
+// Returns the original value unchanged if it is not an @xds/* specifier.
+function rewriteImportSpecifier(spec) {
+  if (!spec.startsWith('@xds/')) return spec;
+  // Theme package collapse (default/daily -> neutral).
+  let next = spec
+    .replace(/^@xds\/theme-default(\/|$)/, '@astryxdesign/theme-neutral$1')
+    .replace(/^@xds\/theme-daily(\/|$)/, '@astryxdesign/theme-neutral$1');
+  if (next === spec) {
+    // Not a collapsed theme — plain scope swap.
+    next = spec.replace(/^@xds\//, '@astryxdesign/');
+  }
+  // Core stylesheet file rename: xds.css -> astryx.css (only the core bundle;
+  // reset.css and others keep their names).
+  next = next.replace(
+    /^@astryxdesign\/core\/xds\.css$/,
+    '@astryxdesign/core/astryx.css',
+  );
+  return next;
+}
+
 // Ordered, non-overlapping replacements. Each pattern is intentionally narrow
 // so we never touch a bare `xds` substring outside these surfaces.
 const REPLACEMENTS = [
@@ -62,6 +93,15 @@ const REPLACEMENTS = [
   // Cascade-layer preludes: `@layer <names>` up to the block `{` or `;`.
   // Rewrite only the recognized xds-* layer tokens inside the prelude.
   {re: /@layer\b[^{;]*/g, to: match => rewriteLayerPrelude(match)},
+  // Package stylesheet imports: `@import '@xds/...'` or `@import url('@xds/...')`.
+  // Rewrite only the quoted @xds/* specifier, preserving the quote style.
+  {
+    re: /@import\s+(?:url\(\s*)?(['"])(@xds\/[^'"]+)\1/g,
+    to: (match, quote, spec) => {
+      const next = rewriteImportSpecifier(spec);
+      return next === spec ? match : match.replace(spec, next);
+    },
+  },
 ];
 
 export default function transformer(file /*, api */) {

package/src/codemods/transforms/v0.1.0/migrate-xds-module-specifiers.mjs

@@ -51,12 +51,57 @@ function rewriteLiteral(node) {
   return true;
 }
 
+// @xds/theme-default and @xds/theme-daily both collapse to
+// @astryxdesign/theme-neutral, whose exported theme binding is `neutralTheme`
+// (not `defaultTheme`). When we rewrite an import from one of those packages,
+// remap a `defaultTheme` named import to `neutralTheme`, aliasing back to the
+// original local name so downstream usages keep working unchanged:
+//   import {defaultTheme} from '@xds/theme-default'
+//     -> import {neutralTheme as defaultTheme} from '@astryxdesign/theme-neutral'
+// An already-aliased `{defaultTheme as x}` just has its imported name remapped.
+const THEME_EXPORT_RENAMES = new Map([['defaultTheme', 'neutralTheme']]);
+const COLLAPSED_THEME_SOURCES = new Set([
+  '@xds/theme-default',
+  '@xds/theme-daily',
+]);
+
+function isCollapsedThemeSource(value) {
+  if (typeof value !== 'string') return false;
+  for (const src of COLLAPSED_THEME_SOURCES) {
+    if (value === src || value.startsWith(src + '/')) return true;
+  }
+  return false;
+}
+
+function remapThemeExportNames(importPath, j) {
+  let changed = false;
+  importPath.node.specifiers = (importPath.node.specifiers || []).map(spec => {
+    if (spec.type !== 'ImportSpecifier') return spec;
+    const importedName = spec.imported.name;
+    const renamed = THEME_EXPORT_RENAMES.get(importedName);
+    if (!renamed) return spec;
+    // Preserve the original local binding (so downstream usages keep working),
+    // remapping only the imported name. Build a FRESH specifier node: recast
+    // preserves the printed form of a mutated ImportSpecifier and would drop a
+    // newly-introduced `as local` alias, so mutating in place loses it.
+    const localName = spec.local.name;
+    changed = true;
+    return j.importSpecifier(j.identifier(renamed), j.identifier(localName));
+  });
+  return changed;
+}
+
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   root.find(j.ImportDeclaration).forEach(path => {
+    // Remap collapsed-theme export names BEFORE rewriting the source specifier
+    // (the check keys off the original @xds/theme-default|daily path).
+    if (isCollapsedThemeSource(path.node.source.value)) {
+      hasChanges = remapThemeExportNames(path, j) || hasChanges;
+    }
     hasChanges = rewriteLiteral(path.node.source) || hasChanges;
   });
 

package/src/commands/agent-docs.mjs

@@ -29,7 +29,8 @@ import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 const AGENTS_MD = 'AGENTS.md';
 const CLAUDE_MD = 'CLAUDE.md';
-const CLAUDE_DIR_MD = path.join('.claude', 'CLAUDE.md');
+const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+
 
 const MARKER_START = '<!-- ASTRYX:START -->';
 const MARKER_END = '<!-- ASTRYX:END -->';

package/src/commands/component-resolution.test.mjs

@@ -78,13 +78,13 @@ describe('findShowcase() priority', () => {
   it('Badge resolves to Badge dir, not a sibling that uses Badge', async () => {
     const result = await findShowcase('Badge');
     expect(result).not.toBeNull();
-    expect(result.filePath).toMatch(/\/Badge\//);
+    expect(result.filePath).toMatch(/[/\\]Badge[/\\]/);
   });
 
   it('Avatar resolves to Avatar dir, not AvatarStatusDot', async () => {
     const result = await findShowcase('Avatar');
     expect(result).not.toBeNull();
-    expect(result.filePath).toMatch(/\/Avatar\//);
+    expect(result.filePath).toMatch(/[/\\]Avatar[/\\]/);
     expect(result.filePath).not.toMatch(/AvatarStatusDot/);
   });
 
@@ -92,7 +92,7 @@ describe('findShowcase() priority', () => {
     const result = await findShowcase('ClickableCard');
     expect(result).not.toBeNull();
     expect(result.name).toBe('ClickableCard');
-    expect(result.filePath).toMatch(/\/Card\//);
+    expect(result.filePath).toMatch(/[/\\]Card[/\\]/);
   });
 
   it('SelectableCard resolves via componentsUsed in Card/', async () => {
@@ -104,7 +104,7 @@ describe('findShowcase() priority', () => {
   it('Stack resolves to Stack dir despite componentsUsed elsewhere', async () => {
     const result = await findShowcase('Stack');
     expect(result).not.toBeNull();
-    expect(result.filePath).toMatch(/\/Stack\//);
+    expect(result.filePath).toMatch(/[/\\]Stack[/\\]/);
   });
 
   it('returns null for nonexistent component', async () => {

package/src/commands/doctor.test.mjs

@@ -4,6 +4,7 @@ import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
 import {Command} from 'commander';
 
 import {registerDoctor} from './doctor.mjs';
@@ -128,7 +129,7 @@ describe('doctor — individual checks', () => {
     // serve a file written to an arbitrary tmp path at runtime. Write the
     // fixture inside the package tree so Vite can resolve it, then clean up.
     const fixtureDir = fs.mkdtempSync(
-      path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
+      path.join(path.dirname(fileURLToPath(import.meta.url)), '__doctor_cfg_'),
     );
     const configPath = path.join(fixtureDir, 'astryx.config.mjs');
     try {
@@ -145,7 +146,7 @@ describe('doctor — individual checks', () => {
 
   it('config: FAIL when astryx.config.mjs throws on import', async () => {
     const fixtureDir = fs.mkdtempSync(
-      path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
+      path.join(path.dirname(fileURLToPath(import.meta.url)), '__doctor_cfg_'),
     );
     const configPath = path.join(fixtureDir, 'astryx.config.mjs');
     try {
@@ -160,7 +161,7 @@ describe('doctor — individual checks', () => {
 
   it('config: FAIL when default export is not an object', async () => {
     const fixtureDir = fs.mkdtempSync(
-      path.join(path.dirname(new URL(import.meta.url).pathname), '__doctor_cfg_'),
+      path.join(path.dirname(fileURLToPath(import.meta.url)), '__doctor_cfg_'),
     );
     const configPath = path.join(fixtureDir, 'astryx.config.mjs');
     try {

package/src/lib/component-discovery.mjs

@@ -335,10 +335,13 @@ export function resolveImportPath(coreDir, componentName) {
     ? JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
     : null;
 
+  const exportKeys = Object.keys(pkg?.exports || {});
+
   // Priority 1: exact subpath export matching the component name (e.g. ./Heading)
   // This allows convenience re-export directories to win over the source directory.
-  if (pkg?.exports?.[`./${componentName}`]) {
-    return `@astryxdesign/core/${componentName}`;
+  const exactMatch = exportKeys.find(k => k.toLowerCase() === `./${componentName}`.toLowerCase());
+  if (exactMatch) {
+    return `@astryxdesign/core/${exactMatch.slice(2)}`;
   }
 
   const sourcePath = findComponentSource(coreDir, componentName);
@@ -348,8 +351,9 @@ export function resolveImportPath(coreDir, componentName) {
   const relToSrc = path.relative(srcDir, sourcePath);
   const topDir = relToSrc.split(path.sep)[0];
 
-  if (pkg?.exports?.[`./${topDir}`]) {
-    return `@astryxdesign/core/${topDir}`;
+  const topMatch = exportKeys.find(k => k.toLowerCase() === `./${topDir}`.toLowerCase());
+  if (topMatch) {
+    return `@astryxdesign/core/${topMatch.slice(2)}`;
   }
 
   return '@astryxdesign/core';

package/src/lib/component-format.mjs

@@ -7,9 +7,20 @@
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
 
-/** Derive the theme component key from a theming target (strips 'xds-' prefix). */
+/**
+ * Derive the `defineTheme` component-override key from a theming target.
+ *
+ * Override keys are the component's stable class name with the `astryx-`
+ * namespace prefix stripped — `generateThemeRules` re-adds the prefix when it
+ * builds the `.astryx-*` selector. So `astryx-base-table` → key `base-table`
+ * (→ `.astryx-base-table`), and `astryx-button` → key `button`.
+ *
+ * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
+ * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.
+ * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
+ */
 function targetKey(target) {
-  return target.className.replace(/^xds-/, '');
+  return target.className.replace(/^astryx-/, '');
 }
 
 function dataAttrForName(name) {

package/src/lib/component-format.test.mjs

@@ -51,3 +51,45 @@ describe('formatFull sub-component rendering', () => {
     expect(out).not.toContain('astryx component XDSButtonGroup');
   });
 });
+
+describe('formatFull theming override keys', () => {
+  // Regression guard: the `defineTheme` component-override key is the stable
+  // class name with the `astryx-` prefix stripped — `generateThemeRules`
+  // re-adds the prefix to build the `.astryx-*` selector. targetKey() used to
+  // strip a dead `xds-` prefix (from before the astryx rename), so the printed
+  // example advertised `astryx-*` keys. Those double-prefix to
+  // `.astryx-astryx-*` at runtime and silently match nothing. See issue #3458.
+  it('prints override keys without the astryx- prefix (single-word component)', () => {
+    const docs = {
+      name: 'Button',
+      description: 'A button.',
+      theming: {targets: [{className: 'astryx-button', visualProps: ['variant']}]},
+    };
+    const out = formatFull(docs);
+
+    expect(out).toContain("'button': {");
+    // The full DOM class must not appear as an override key.
+    expect(out).not.toContain("'astryx-button': {");
+  });
+
+  it('prints override keys without the astryx- prefix (compound Table classes)', () => {
+    const docs = {
+      name: 'Table',
+      description: 'A table.',
+      theming: {
+        targets: [
+          {className: 'astryx-base-table'},
+          {className: 'astryx-table-cell'},
+        ],
+      },
+    };
+    const out = formatFull(docs);
+
+    // Correct keys: class name minus the astryx- prefix.
+    expect(out).toContain("'base-table': {");
+    expect(out).toContain("'table-cell': {");
+    // The verbatim DOM class names must not be advertised as override keys.
+    expect(out).not.toContain("'astryx-base-table': {");
+    expect(out).not.toContain("'astryx-table-cell': {");
+  });
+});

package/src/utils/paths.test.mjs

@@ -97,7 +97,7 @@ describe('discoverExternalPackages', () => {
     fs.writeFileSync(
       path.join(scopedDir, 'package.json'),
       JSON.stringify({
-        name: '@acme/xds-widgets',
+        name: '@acme/astryx-widgets',
         astryx: {docs: './lib', category: 'Widgets'},
       }),
     );
@@ -105,7 +105,7 @@ describe('discoverExternalPackages', () => {
     const result = discoverExternalPackages(tmpDir);
     expect(result).toEqual([
       {
-        name: '@acme/xds-widgets',
+        name: '@acme/astryx-widgets',
         category: 'Widgets',
         docsDir: path.join(scopedDir, 'lib'),
         blocksDir: null,

package/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BaseTypeahead',
+  name: 'BaseTypeahead — Custom Search Bar',
+  displayName: 'BaseTypeahead — Custom Search Bar',
+  description:
+    'BaseTypeahead embedded inside a custom-styled wrapper. The wrapper provides its own border and icon chrome; anchorRef positions the dropdown relative to it. Use this pattern when Typeahead\'s built-in field layout does not fit your composition.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['BaseTypeahead', 'Icon', 'Layout', 'Text'],
+};

package/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.tsx

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef, useState} from 'react';
+import {BaseTypeahead, createStaticSource} from '@astryxdesign/core/Typeahead';
+import type {SearchableItem} from '@astryxdesign/core/Typeahead';
+import {Icon} from '@astryxdesign/core/Icon';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+
+const frameworks: SearchableItem[] = [
+  {id: 'react', label: 'React'},
+  {id: 'vue', label: 'Vue'},
+  {id: 'angular', label: 'Angular'},
+  {id: 'svelte', label: 'Svelte'},
+  {id: 'solid', label: 'SolidJS'},
+  {id: 'remix', label: 'Remix'},
+  {id: 'next', label: 'Next.js'},
+  {id: 'nuxt', label: 'Nuxt'},
+];
+
+const source = createStaticSource(frameworks);
+
+export default function BaseTypeaheadCustomSearch() {
+  const [value, setValue] = useState<SearchableItem | null>(null);
+  const wrapperRef = useRef<HTMLElement>(null);
+
+  return (
+    <VStack gap={3} style={{width: 320}}>
+      <HStack
+        ref={wrapperRef}
+        gap={2}
+        vAlign="center"
+        style={{
+          border: '1px solid var(--color-border)',
+          borderRadius: 'var(--radius-control)',
+          padding: '6px 10px',
+          background: 'var(--color-surface)',
+        }}>
+        <Icon icon={MagnifyingGlassIcon} size="sm" color="secondary" />
+        <BaseTypeahead
+          searchSource={source}
+          value={value}
+          onChange={setValue}
+          anchorRef={wrapperRef}
+          placeholder="Search frameworks…"
+          hasEntriesOnFocus
+          debounceMs={0}
+        />
+      </HStack>
+      <Text type="supporting" color="secondary">
+        {value != null ? `Selected: ${value.label}` : 'No selection'}
+      </Text>
+    </VStack>
+  );
+}

package/templates/blocks/components/CodeBlock/CodeBlockTerminal.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CodeBlock',
+  name: 'Code — Terminal',
+  displayName: 'Code — Terminal',
+  description:
+    'A dark terminal-style command block: a bash CodeBlock wrapped in SyntaxTheme with the GitHub Dark preset, copy button on, and no line numbers. Use for shell sessions or CLI output that should read as a terminal even on light pages — reach for a dark syntax preset instead of hand-rolling a dark box with custom CSS.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CodeBlock', 'SyntaxTheme'],
+};

package/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {SyntaxTheme} from '@astryxdesign/core/theme';
+import {githubDark} from '@astryxdesign/core/theme/syntax';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+
+const commands = `$ astryx init --features agents
+✓ AI agent docs installed → .claude/CLAUDE.md
+$ pnpm astryx component CodeBlock --dense`;
+
+export default function CodeBlockTerminal() {
+  return (
+    <SyntaxTheme theme={githubDark}>
+      <CodeBlock
+        code={commands}
+        language="bash"
+        hasCopyButton
+        style={{width: '100%', maxWidth: 480}}
+      />
+    </SyntaxTheme>
+  );
+}

package/templates/blocks/components/MetadataListItem/MetadataListItemBasic.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'MetadataListItem — Basic',
   displayName: 'MetadataListItem — Basic',
   description:
-    'Labeled key–value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
+    'Labeled key-value rows inside a MetadataList. Values accept any content, from plain text to components like Badge.',
   isReady: true,
   aspectRatio: 16 / 9,
   componentsUsed: ['MetadataList', 'MetadataListItem', 'Badge'],

package/templates/blocks/components/TabList/TabListTabsWithActions.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'TabList — With Actions',
   displayName: 'TabList — With Actions',
   description:
-    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, pair with a smaller button size (sm) so actions don\u2019t overpower the tab row.',
+    'Page header pattern with tabs on the left and action buttons pushed to the right. When hasDivider is true, pair with a smaller button size (sm) so actions don\'t overpower the tab row.',
   isReady: true,
   aspectRatio: 4 / 3,
   componentsUsed: ['TabList', 'Tab', 'Button'],

package/templates/blocks/components/Table/TableRowExpansionTable.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableRowExpansion',
+  name: 'useTableRowExpansion — Tree Table',
+  displayName: 'useTableRowExpansion — Tree Table',
+  description:
+    'A tree table using useTableRowExpansion with inherited columns. Child rows use the same columns as parents, indented by depth. Click the chevron or right-click to expand/collapse.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/templates/blocks/components/Table/TableRowExpansionTable.tsx

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  Table,
+  useTableRowExpansion,
+  useTableRowExpansionState,
+  proportional,
+  pixel,
+} from '@astryxdesign/core/Table';
+
+interface FileNode extends Record<string, unknown> {
+  id: string;
+  name: string;
+  type: 'folder' | 'file';
+  size: string;
+  children?: FileNode[];
+}
+
+const fileTree: FileNode[] = [
+  {
+    id: 'src',
+    name: 'src',
+    type: 'folder',
+    size: '—',
+    children: [
+      {
+        id: 'src/components',
+        name: 'components',
+        type: 'folder',
+        size: '—',
+        children: [
+          {
+            id: 'src/components/Button.tsx',
+            name: 'Button.tsx',
+            type: 'file',
+            size: '4.2 KB',
+            children: [],
+          },
+          {
+            id: 'src/components/Table.tsx',
+            name: 'Table.tsx',
+            type: 'file',
+            size: '12.8 KB',
+            children: [],
+          },
+        ],
+      },
+      {
+        id: 'src/index.ts',
+        name: 'index.ts',
+        type: 'file',
+        size: '0.4 KB',
+        children: [],
+      },
+    ],
+  },
+  {
+    id: 'package.json',
+    name: 'package.json',
+    type: 'file',
+    size: '1.8 KB',
+    children: [],
+  },
+];
+
+const columns = [
+  {key: 'name', header: 'Name', width: proportional(2)},
+  {key: 'type', header: 'Type', width: pixel(80)},
+  {key: 'size', header: 'Size', width: pixel(90)},
+];
+
+export default function TableRowExpansionTable() {
+  const [expandedKeys, setExpandedKeys] = useState<Set<string>>(
+    new Set(['src']),
+  );
+
+  const {data, expansionConfig} = useTableRowExpansionState<FileNode>({
+    baseData: fileTree,
+    getChildren: item => item.children ?? [],
+    getRowKey: item => item.id,
+    expandedKeys,
+    setExpandedKeys,
+  });
+
+  const expansion = useTableRowExpansion(expansionConfig);
+
+  return (
+    <Table
+      data={data}
+      columns={columns}
+      idKey="id"
+      hasHover
+      plugins={{expansion}}
+    />
+  );
+}

package/templates/blocks/components/ToggleButtonGroup/ToggleButtonGroupVertical.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   name: 'ToggleButtonGroup — Vertical',
   displayName: 'ToggleButtonGroup — Vertical',
   description:
-    'A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior — ideal for sidebar-style option lists and vertical toolbars.',
+    'A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior, ideal for sidebar-style option lists and vertical toolbars.',
   isReady: true,
   aspectRatio: 3 / 4,
   componentsUsed: ['ToggleButton', 'ToggleButtonGroup', 'Layout', 'Text'],

package/templates/themes/stone/stoneTheme.ts

@@ -94,13 +94,13 @@ export const stoneTheme = defineTheme({
     // Core semantic — all neutrals H=291
     // Stone 900 T=16 C=1.4, Stone 500 T=55 C=4, Stone 300 T=86 C=1.6, Stone 100 T=96 C=1
     '--color-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
-    '--color-accent-muted': ['#25252a14', '#f3f3f5'], // light: Stone Neutral T15 · 8%
+    '--color-accent-muted': ['#25252a14', '#f3f3f520'], // light: Stone Neutral T15 · 8% / dark: T96 · 12.5%
     '--color-neutral': ['#25252a0f', '#f3f3f51a'], // light: Stone Neutral T15 · 6% / dark: T96 · 10%
     '--color-background-surface': ['#ffffff', '#1b1b1f'], // dark: Stone Neutral T10
     '--color-background-body': ['#f3f3f5', '#111015'], // dark: Stone Neutral T5
-    '--color-overlay': ['#25252a80', '#28282a'], // light: Stone Neutral T15 · 50%
-    '--color-overlay-hover': ['#25252a0d', '#f3f3f5'], // light: Stone Neutral T15 · 5%
-    '--color-overlay-pressed': ['#25252a1a', '#f3f3f5'], // light: Stone Neutral T15 · 10%
+    '--color-overlay': ['#25252a80', '#28282acc'], // light: Stone Neutral T15 · 50% / dark: 80%
+    '--color-overlay-hover': ['#25252a0d', '#f3f3f50d'], // light: Stone Neutral T15 · 5% / dark: T96 · 5%
+    '--color-overlay-pressed': ['#25252a1a', '#f3f3f51a'], // light: Stone Neutral T15 · 10% / dark: T96 · 10%
     '--color-background-muted': ['#e2e2e8', '#3b3b3f'], // light: Stone Neutral T90
 
     // Text — H=291
@@ -136,12 +136,12 @@ export const stoneTheme = defineTheme({
     '--color-warning-muted': ['#f4e1b7', '#d7c59c'], // Yellow T90 / T80
 
     // Border — H=291
-    '--color-border': ['#e2e2e8', '#f3f3f5'], // light: Stone Neutral T90
+    '--color-border': ['#e2e2e8', '#f3f3f51a'], // light: Stone Neutral T90 / dark: T96 · 10%
     '--color-border-emphasized': ['#83838a', '#5e5e61'], // T55 C=4 / T40 C=2
 
     // Effects — H=291
     '--color-skeleton': ['#d4d4da', '#5e5e64'], // T85 / T40 from H=291 C=3
-    '--color-shadow': ['#25252a1a', '#000000'], // light: Stone Neutral T15 · 10%
+    '--color-shadow': ['#25252a1a', '#0000004d'], // light: Stone Neutral T15 · 10% / dark: 30%
     '--color-tint-hover': ['black', 'white'],
 
     // Typography override