@astryxdesign/cli 0.1.3 → 0.1.4-canary.01e5b29

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
@@ -9,7 +36,7 @@
 - Strict config + integration v1 schema (integrations, issuesUrl, hooks.postCodemod) and new @astryxdesign/cli/integration export.
 - File-based codemod API (createCodemod/createConfigCodemod) with the @astryxdesign/cli/codemod export and integration codemod discovery in upgrade.
 - component, template, and upgrade now print a one-line non-blocking warning when a configured integration has validation issues, pointing to validate-integration.
-- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar.
+- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar. Based on a design by @cg-hub18.
 - Add frame-first layout guidance: new `astryx docs layout` topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in `docs principles`.
 - Add a v0.1.3 config codemod that migrates astryx.config layout.components to experimental.xle.components.
 - Add v0.1.0 codemods for migrating `declare module "@xds/core/..."` type augmentations and `.xds-*` / `[data-xds-theme]` / `@layer xds-theme` CSS surfaces to their `@astryxdesign`/`astryx-*` equivalents.
@@ -53,6 +80,7 @@
 Thanks to everyone who contributed to this release:
 
 - @AKnassa
+- @cg-hub18
 - @ejhammond
 - @ernestt
 - @harshavardhan194

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/getting-started.doc.mjs

@@ -69,6 +69,10 @@ export const docs = {
           type: 'prose',
           text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
         },
+        {
+          type: 'prose',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `npx astryx docs migration` before building screens.',
+        },
       ],
     },
     {

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/migration.doc.mjs

@@ -33,6 +33,7 @@ export const docs = {
             'Install the design system and run init so the project has package scripts, theme CSS, and agent docs.',
             'Wrap the app root with Theme and choose the initial light, dark, or system mode behavior.',
             'Make Tailwind and design system CSS layer order explicit before replacing components.',
+            'Render the foundation smoke test page and confirm primitives keep their padding before migrating any surface.',
             'Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation.',
             'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, Tabs, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
             'Replace global workflows: command palette, settings popover, theme toggle, search, filters, create flows, and destructive confirmation dialogs.',
@@ -125,6 +126,139 @@ export function AppRoot({children}: {children: React.ReactNode}) {
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
+        {
+          type: 'prose',
+          text: 'On Tailwind v3 there is no preflight.css to import, so wrap the @tailwind base directive in a named layer instead. Keep utilities unlayered so existing app utility classes still win everywhere.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Tailwind v3 coexistence',
+          code: `@layer reset, tw-preflight, astryx-base, astryx-theme;
+
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+@layer tw-preflight {
+  @tailwind base; /* layered: astryx-theme now wins over preflight */
+}
+@tailwind components;
+@tailwind utilities; /* unlayered: legacy utility classes keep winning */`,
+        },
+      ],
+    },
+    {
+      title: 'Cascade Layer Safety',
+      content: [
+        {
+          type: 'prose',
+          text: 'In a stylesheet with no layers at all, a zero-specificity reset like `* { padding: 0 }` loses to any class selector, so most developers treat resets as harmless. Layers change the rules twice: unlayered styles beat every named layer, and a later layer beats an earlier one, both regardless of specificity. The same reset therefore wins against every component style either by staying unlayered or by landing in a layer declared after astryx-base. Same CSS, opposite outcome, and no error or warning when it happens.',
+        },
+        {
+          type: 'prose',
+          text: 'This is the most common way an adoption breaks, through one of two @import mechanisms. A top-level @import without the layer() keyword keeps the legacy reset unlayered, where it overrides every design system layer. And an @import nested inside a file that was itself imported into a layer inherits that surrounding layer, so a reset can silently land in a consumer layer above astryx-base. Either way the fix is the same: import the legacy reset into the lowest layer explicitly.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Legacy reset, explicitly layered',
+          code: `/* was: @import "./legacy-reset.css";  (unlayered: beats every layer) */
+@import "./legacy-reset.css" layer(reset);`,
+        },
+        {
+          type: 'prose',
+          text: 'Audit the layers around the design system with this checklist before building screens.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Declare the canonical @layer order once, before any @import. With webpack-based bundlers (including Next.js) the order declaration must live in its own CSS file imported first, such as layers.css, because webpack hoists @import content above the inline CSS that follows it.',
+            'Audit every pre-existing global or reset stylesheet and assign each one to a layer deliberately. Top-level imports without layer() stay unlayered and beat every layer; imports nested inside a layered file inherit that layer.',
+            'Remove or demote the app legacy reset. The design system ships its own :where() reset in the lowest layer, so any app reset belongs in that same reset layer and never in a layer above astryx-base.',
+            'Layer Tailwind preflight. On Tailwind v4, import preflight.css with layer(base). On Tailwind v3, wrap the @tailwind base directive in a named layer (see the snippet in Theme and CSS Setup). Unlayered preflight overrides theme CSS silently.',
+            'Set moduleResolution to bundler or node16 and newer so subpath imports like @astryxdesign/core/reset.css resolve.',
+            'Theme with defineTheme and the accent family API instead of hand-writing individual color tokens. Derived tokens like --color-on-accent are generated from the accent scale automatically; hand-writing only --color-accent leaves --color-on-accent at its stale white default with no contrast guarantee against the new accent.',
+            'Run the foundation smoke test below and view a few components in both light and dark mode before migrating any route.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'One more mental model shift: a className or utility class you write on a component still reaches the DOM either way, but whether it overrides the component is a layer question, not a source order question. Keep app utilities in the utilities layer so they keep winning.',
+        },
+      ],
+    },
+    {
+      title: 'Foundation Smoke Test',
+      content: [
+        {
+          type: 'prose',
+          text: 'A broken layer order fails silently and identically on every page, so catch it before feature work instead of after N migrated screens. Render one throwaway page with a few primitives as the first migration step.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Foundation check page',
+          code: `import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {Table} from '@astryxdesign/core/Table';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {VStack} from '@astryxdesign/core/VStack';
+
+export default function FoundationCheck() {
+  const [email, setEmail] = useState('');
+
+  return (
+    <div data-foundation-check>
+      <VStack gap={4}>
+        <Button label="Primary action" variant="primary" />
+        <TextInput
+          label="Email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={setEmail}
+        />
+        <Card>One card with default padding</Card>
+        <Table
+          data={[{name: 'Foundation', status: 'ok'}]}
+          columns={[
+            {key: 'name', header: 'Name'},
+            {key: 'status', header: 'Status'},
+          ]}
+        />
+      </VStack>
+    </div>
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'If the button renders with visible padding, a filled primary background, and the input and card have borders and internal spacing, the foundation is sound. For an assertion that can run in any test runner or a dev-only effect, check that a primitive keeps non-zero padding:',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          label: 'Foundation assertion',
+          code: `const button = document.querySelector<HTMLButtonElement>(
+  '[data-foundation-check] button',
+);
+if (!button) {
+  throw new Error('Foundation check page did not render a button.');
+}
+if (getComputedStyle(button).paddingInline === '0px') {
+  throw new Error(
+    'Foundation broken: an unlayered reset or a later cascade layer is ' +
+      'overriding component styles. Check that no app reset sits outside ' +
+      'the reset layer.',
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'When this fails, the fix is almost always in the layer order: find the stylesheet that zeroes padding, and move it into the reset layer or delete it.',
+        },
       ],
     },
     {

package/docs/styling.doc.mjs

@@ -338,6 +338,59 @@ const styles = stylex.create({
         },
       ],
     },
+    {
+      title: 'StyleX Build Setup (required for swizzled components)',
+  category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
+        },
+        {
+          type: 'table',
+          headers: ['Bundler', 'StyleX plugin'],
+          rows: [
+            ['Webpack', '@stylexjs/webpack-plugin'],
+            ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],
+            ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
+            ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.',
+        },
+        {
+          type: 'prose',
+          text: 'The working path on Next.js is an SWC-based StyleX transform (e.g. the community `@stylexswc/nextjs-plugin`) wired into `next.config`, which keeps SWC and `next/font` intact. See the example app `apps/example-nextjs-stylex` in the repo for a complete, working Next.js + StyleX + SWC configuration.',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
+          code: `import stylexPlugin from '@stylexswc/nextjs-plugin';
+
+export default stylexPlugin({
+  rsOptions: {
+    // Resolve @astryxdesign/core's StyleX so swizzled component source compiles.
+    aliases: {'@/*': ['./src/*']},
+    unstable_moduleResolution: {type: 'commonJS'},
+  },
+})({
+  // your existing Next.js config
+});`,
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
+            'Do NOT add @stylexjs/babel-plugin to a Next.js App Router app; it disables SWC and breaks next/font.',
+            'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
+          ],
+        },
+      ],
+    },
     {
       title: 'What NOT to Do',
   category: 'guide',

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/docs/working-with-ai.doc.mjs

@@ -125,7 +125,7 @@ If you don't know all three, run \`npx astryx init --features agents\` to genera
           lang: 'json',
           label: 'package.json',
           code: `"scripts": {
-  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
 }`,
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.3",
+  "version": "0.1.4-canary.01e5b29",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -68,19 +68,23 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.5.1",
+    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.01e5b29",
+    "@astryxdesign/core": "0.1.4-canary.01e5b29",
+    "@astryxdesign/lab": "0.1.4-canary.01e5b29",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.01e5b29",
+    "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
+    "@astryxdesign/charts": {
+      "optional": true
+    },
     "@astryxdesign/core": {
       "optional": true
     },
@@ -92,10 +96,11 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.01e5b29",
+    "@astryxdesign/core": "0.1.4-canary.01e5b29",
+    "@astryxdesign/lab": "0.1.4-canary.01e5b29",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.01e5b29",
+    "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

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/doctor.mjs

@@ -115,10 +115,21 @@ function findThemePackages(cwd) {
     return found;
   }
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
     if (!entry.name.startsWith('theme-')) continue;
+    const dir = path.join(scopeDir, entry.name);
+    // pnpm installs packages as symlinks into node_modules/.pnpm, and a
+    // symlink dirent reports isDirectory() as false — stat the target instead.
+    let isDir = entry.isDirectory();
+    if (!isDir && entry.isSymbolicLink()) {
+      try {
+        isDir = fs.statSync(dir).isDirectory();
+      } catch {
+        isDir = false;
+      }
+    }
+    if (!isDir) continue;
     const name = `@astryxdesign/${entry.name}`;
-    found.push({name, version: pkgVersion(path.join(scopeDir, entry.name))});
+    found.push({name, version: pkgVersion(dir)});
   }
   return found;
 }

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);