@astryxdesign/cli 0.1.0-canary.6fc892b → 0.1.0-canary.7517fdf

package/docs/icons.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Icons reference doc: semantic icon names available in XDS
+ * @file Icons reference doc: semantic icon names available in Astryx
  */
 
 /** @type {import('../../core/src/docs-types').ReferenceDoc} */

package/docs/migration.doc.mjs

@@ -234,7 +234,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+          code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
 - npx astryx docs migration --dense
@@ -242,7 +242,7 @@ First run:
 - npx astryx docs styling --dense
 - npx astryx template AppShellTopNavWithSideNav --skeleton
 
-Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with XDS components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
         },
       ],
     },

package/docs/shape.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
           type: 'code',
           lang: 'css',
           label: 'Concentric radius formula',
-          code: `/* Automatic in XDS Card */
+          code: `/* Automatic in Astryx Card */
 --card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
         },
       ],

package/docs/styling.doc.mjs

@@ -231,7 +231,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
+          text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
         },
         {
           type: 'code',
@@ -273,7 +273,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'XDS still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
+          text: 'Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
         },
         {
           type: 'code',

package/docs/theme.doc.dense.mjs

@@ -5,8 +5,8 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { title: 'Props', content: [null] },
     { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },

package/docs/theme.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       title: 'Quick Start',
   category: 'guide',
       content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Install a theme package',
+          code: 'npm install @astryxdesign/theme-neutral',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -45,6 +51,10 @@ function App() {
   );
 }`,
         },
+        {
+          type: 'prose',
+          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>` — the same pattern works for every theme; just swap the package and import name.',
+        },
         {
           type: 'prose',
           text: 'The default import uses runtime style injection, which works everywhere with no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',
@@ -55,6 +65,10 @@ function App() {
       title: 'Available Themes',
   category: 'guide',
       content: [
+        {
+          type: 'prose',
+          text: 'Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its theme object as shown below.',
+        },
         {
           type: 'table',
           headers: ['Theme', 'Import', 'Description'],

package/docs/theme.doc.zh.mjs

@@ -5,8 +5,8 @@
 export const docsZh = {
   description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
   sections: [
-    { title: '快速开始', content: [null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
-    { title: '可用主题', content: [null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
+    { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
     { title: 'Theme 属性', content: [null] },
     { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
     { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },

package/docs/working-with-ai.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your XDS context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -103,7 +103,7 @@ npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `Before writing any XDS code, check your knowledge:
+          code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
 2. How do you make an Dialog non-dismissible?
@@ -165,7 +165,7 @@ npx astryx docs tokens --dense`,
       content: [
         {
           type: 'prose',
-          text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
+          text: 'Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
         },
         {
           type: 'prose',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.0-canary.6fc892b",
+  "version": "0.1.0-canary.7517fdf",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -15,7 +15,7 @@
     "url": "https://github.com/facebook/astryx/issues"
   },
   "keywords": [
-    "xds",
+    "astryx",
     "cli",
     "design-system",
     "init",
@@ -54,9 +54,9 @@
     "jscodeshift": "^17.3.0"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.6fc892b",
-    "@astryxdesign/lab": "0.1.0-canary.6fc892b",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.6fc892b"
+    "@astryxdesign/core": "0.1.0-canary.7517fdf",
+    "@astryxdesign/lab": "0.1.0-canary.7517fdf",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.7517fdf"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -70,9 +70,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.6fc892b",
-    "@astryxdesign/lab": "0.1.0-canary.6fc892b",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.6fc892b"
+    "@astryxdesign/core": "0.1.0-canary.7517fdf",
+    "@astryxdesign/lab": "0.1.0-canary.7517fdf",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.7517fdf"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/commands/agent-docs.mjs

@@ -93,14 +93,55 @@ export function resolveAgentPaths(targetDir, agent) {
   return {inject: [], create: [searchPaths[searchPaths.length - 1]]};
 }
 
+/**
+ * Detect which styling system the consumer project has wired up, so the agent
+ * docs recommend a path that actually compiles in THIS project.
+ *
+ * `xstyle`/StyleX needs the StyleX compiler (the `@stylexjs/stylex` runtime
+ * alone throws at runtime → blank page); Tailwind utilities need Tailwind.
+ * Recommending either when it isn't configured yields unstyled or blank output.
+ * Plain CSS variables (via `style`/`className`) always work, so they're the
+ * safe default. Precedence: stylex (compiler wired) → tailwind → css.
+ *
+ * @param {string} targetDir
+ * @returns {'stylex' | 'tailwind' | 'css'}
+ */
+export function detectStylingSystem(targetDir) {
+  try {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath)) return 'css';
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const deps = {...pkg.dependencies, ...pkg.devDependencies};
+    // Key off a StyleX *compiler* plugin — the runtime alone won't render.
+    const stylexCompilers = [
+      '@stylexjs/babel-plugin',
+      'vite-plugin-stylex',
+      'unplugin-stylex',
+      '@stylexswc/unplugin',
+      '@stylexswc/nextjs-plugin',
+      'stylex-webpack',
+    ];
+    if (stylexCompilers.some(d => d in deps)) return 'stylex';
+    if ('tailwindcss' in deps) return 'tailwind';
+    return 'css';
+  } catch {
+    // Best-effort: default to the universally-safe CSS-variable path.
+    return 'css';
+  }
+}
+
 /**
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
  * Templates are positioned first in the workflow to teach agents the
  * "look at reference code" reflex before writing any UI.
+ *
+ * `stylingSystem` tailors the custom-styling guidance to what the project has
+ * configured (see {@link detectStylingSystem}) so the agent never reaches for a
+ * styling path that isn't compiled here.
  */
-export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix()} = {}) {
+export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix(), stylingSystem = 'css'} = {}) {
   const run = `${runPrefix} astryx`;
   const lines = [MARKER_START];
 
@@ -117,86 +158,57 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
     }
   }
 
-  // Header
-  lines.push(`Astryx v${version} — ${componentCount} components`);
+  // Header — state the CLI prefix once; commands below are shown as `astryx <cmd>`.
+  lines.push(`Astryx v${version} · ${componentCount} components`);
+  lines.push(`CLI: run every command as \`${run} <cmd>\` (shown below as \`astryx ...\`).`);
   lines.push('');
 
-  // One-time project setup — components ship precompiled CSS that MUST be
-  // imported, or everything renders unstyled. Stated as text (the CLI does not
-  // edit your files). The Theme provider is OPTIONAL (a default theme ships in
-  // astryx.css); only the CSS imports are required.
-  lines.push('SETUP (required, once) — in your app entry (e.g. main.tsx):');
+  // Required setup — components ship precompiled CSS; without these imports
+  // everything renders unstyled. Theme is optional (a default ships in astryx.css).
+  lines.push('SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled:');
   lines.push('  import "@astryxdesign/core/reset.css";');
   lines.push('  import "@astryxdesign/core/astryx.css";');
-  lines.push('Without these CSS imports, components render completely unstyled.');
-  lines.push(`Optional: apply a specific theme with <Theme> — see \`${run} docs theme\`.`);
   lines.push('');
 
-  // Behavioral workflow — `build` is the front door for making pages: it returns
-  // a composition kit, and `build` with no args prints the full how-to playbook.
-  lines.push('Before writing any UI code:');
-  lines.push(
-    `1. \`${run} build "<what you're building>"\` — START HERE. Returns a composition kit: the closest [page] recipe (scaffold it, or use as a layout reference), the [block]s that cover parts, and the [component]s to fill gaps. (Run \`${run} build\` with no args for the full how-to-build playbook.)`,
-  );
-  lines.push(`2. \`${run} template <name> --skeleton\` — scaffold a matched [page], or study its layout (gap, padding, nesting)`);
-  lines.push(`3. \`${run} template <BlockName>\` — drop in each [block] the kit surfaced (ready-made multi-component patterns) instead of hand-building`);
-  lines.push(`4. \`${run} component <Name>\` — read props + examples for EVERY component you use`);
-  lines.push('');
-  lines.push('Templates and blocks are reference code — read them for composition patterns, not just scaffolding.');
-  lines.push(`(\`${run} search <query>\` is a neutral find across components/hooks/docs/templates when you just need to look something up.)`);
+  // Workflow — `build` is the front door; discover before writing UI.
+  lines.push("WORKFLOW — discover, don't guess. Before writing UI:");
+  lines.push('1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.');
+  lines.push('2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.');
+  lines.push('3. `astryx component <Name>` — props + examples for every component you use.');
   lines.push('');
 
-  // Rules — inline, compact, prevents the top error categories
-  lines.push('No <div> anywhere — not for layout, not for wrappers, not for spacing. Use components.');
-  lines.push('Full-page shells → AppShell (not Layout). Sidebar nav → SideNav (not List).');
-  lines.push('No style={{}} — use the xstyle prop on components for custom styling.');
-  lines.push('If a component prop does what you need, use it — never replicate with CSS/stylex.');
-  lines.push(`No magic values — run \`${run} docs tokens\` for spacing/color/radius.`);
-  lines.push(`To change accent/brand colors: \`${run} theme\` — never override --astryx-color-* in :root.`);
+  // Rules — the top error-preventers.
+  lines.push('RULES:');
+  lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+  // Styling guidance tailored to the project's configured system — never
+  // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
+  // utilities need Tailwind). Tokens are always the source of truth.
+  if (stylingSystem === 'stylex') {
+    lines.push('- Custom styling: component props first; else the xstyle prop / StyleX tokens (@astryxdesign/core/theme/tokens.stylex). No raw hex/px.');
+  } else if (stylingSystem === 'tailwind') {
+    lines.push('- Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.');
+  } else {
+    lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
+  }
+  lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
   lines.push('');
 
-  // CLI quick reference
-  lines.push(`${run} build "<idea>"            START HERE for pages — kit: closest page + blocks + components (\`build\` = how-to playbook)`);
-  lines.push(`${run} search "<query>"          find anything: components, hooks, docs, templates, blocks`);
-  lines.push(`${run} component --list         ${componentCount} components by category`);
-  lines.push(`${run} component <Name>         props, types, examples`);
-
-  // Doc topics from live discovery
+  // Command reference — build/template/component are covered in WORKFLOW above.
+  lines.push('MORE CLI:');
+  lines.push('  search "<query>"   find any component / hook / doc / template / block');
+  lines.push(`  component --list   ${componentCount} components by category`);
+  lines.push('  template --list    page + block recipes');
   const docsDir = path.join(CLI_ROOT, 'docs');
   if (fs.existsSync(docsDir)) {
-    for (const file of fs.readdirSync(docsDir).sort()) {
-      const match = file.match(/^(\w+)\.doc\.mjs$/);
-      if (!match) continue;
-      const topic = match[1];
-      let desc = topic;
-      try {
-        const fileContent = fs.readFileSync(path.join(docsDir, file), 'utf-8');
-        const descMatch = fileContent.match(/description:\s*['"](.+?)['"]/);
-        if (descMatch) desc = descMatch[1];
-      } catch {
-        // Best-effort: fall back to the topic name if the file is unreadable.
-      }
-      if (desc.length > 50) desc = desc.slice(0, 47) + '...';
-      lines.push(`${run} docs ${topic.padEnd(20)} ${desc}`);
-    }
-  }
-
-  // Templates
-  const templatesDir = path.join(CLI_ROOT, 'templates');
-  if (fs.existsSync(templatesDir)) {
-    const templates = fs.readdirSync(templatesDir, {withFileTypes: true})
-      .filter(e => e.isDirectory())
-      .map(e => e.name)
+    const topics = fs.readdirSync(docsDir)
+      .map(f => f.match(/^(\w+)\.doc\.mjs$/))
+      .filter(Boolean)
+      .map(m => m[1])
       .sort();
-    if (templates.length > 0) {
-      lines.push(`${run} template --list           page recipes with component lists`);
-      lines.push(`${run} template <name> [path]     scaffold from template`);
-    }
+    if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
   }
-
-  lines.push(`${run} swizzle <Name>            eject source (--gap to report why)`);
-  lines.push(`${run} upgrade --apply            codemods after version bump`);
-  lines.push(`after @astryxdesign/core bump, always run ${run} upgrade --apply`);
+  lines.push('  swizzle <Name>     eject component source (--gap reports why)');
+  lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
   lines.push(MARKER_END);
 
   return lines.join('\n');
@@ -275,7 +287,10 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal
  */
 export function injectAgentsMd(targetDir, version) {
   const agentsPath = path.join(targetDir, AGENTS_MD);
-  const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});
+  const compressedIndex = generateCompressedIndex(version, {
+    coreDir: findCoreDir(targetDir),
+    stylingSystem: detectStylingSystem(targetDir),
+  });
   injectXdsBlock(agentsPath, compressedIndex, {
     createIfMissing: true,
     header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
@@ -290,7 +305,10 @@ export function injectAgentsMd(targetDir, version) {
  */
 export function injectClaudeMd(targetDir, version) {
   const claudePath = path.join(targetDir, CLAUDE_MD);
-  const compressedIndex = generateCompressedIndex(version, {coreDir: findCoreDir(targetDir)});
+  const compressedIndex = generateCompressedIndex(version, {
+    coreDir: findCoreDir(targetDir),
+    stylingSystem: detectStylingSystem(targetDir),
+  });
   return injectXdsBlock(claudePath, compressedIndex);
 }
 
@@ -373,7 +391,8 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
   const coreDir = findCoreDir(targetDir);
   const version = getXdsVersion(coreDir);
   const runPrefix = getRunPrefix(targetDir);
-  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix});
+  const stylingSystem = detectStylingSystem(targetDir);
+  const compressedIndex = generateCompressedIndex(version, {coreDir, zh, lang, runPrefix, stylingSystem});
   const written = [];
 
   // Explicit paths override everything

package/src/commands/agent-docs.path-safety.test.mjs

@@ -20,7 +20,7 @@ import {PathSafetyError} from '../utils/path-safety.mjs';
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-agent-docs-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/agent-docs.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import {
   generateCompressedIndex,
+  detectStylingSystem,
   getXdsVersion,
   installAgentDocs,
   injectAgentsMd,
@@ -20,7 +21,7 @@ import {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-agent-docs-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));
 });
 
 afterEach(() => {
@@ -39,31 +40,86 @@ describe('generateCompressedIndex', () => {
   it('includes theme nudge rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toMatch(/astryx theme/);
-    expect(result).toMatch(/never override --astryx-color/);
+    expect(result).toMatch(/never override --color-/);
+  });
+
+  it('defaults to the CSS-variable styling path (no compiler)', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toMatch(/style\/className with tokens/);
+    expect(result).toMatch(/var\(--color-\*/);
+    // Must NOT push xstyle when no StyleX compiler is present.
+    expect(result).not.toMatch(/xstyle prop/);
+  });
+
+  it('recommends xstyle when StyleX is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    expect(result).toMatch(/xstyle prop \/ StyleX tokens/);
+  });
+
+  it('recommends Tailwind utilities when Tailwind is configured', () => {
+    const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    expect(result).toMatch(/Tailwind utilities backed by tokens/);
+    expect(result).toMatch(/tailwind-theme\.css/);
   });
 
   it('includes upgrade command and migration rule', () => {
     const result = generateCompressedIndex('1.0.0');
-    expect(result).toContain('astryx upgrade');
-    expect(result).toContain('astryx upgrade --apply');
-    expect(result).toMatch(/always run .+ astryx upgrade --apply/);
+    expect(result).toContain('upgrade --apply');
+    expect(result).toMatch(/after any @astryxdesign\/core bump/);
   });
 
-  it('uses custom runPrefix when provided', () => {
+  it('states the runPrefix once in the CLI header', () => {
     const result = generateCompressedIndex('1.0.0', {runPrefix: 'yarn'});
-    expect(result).toContain('yarn astryx component <Name>');
-    expect(result).toContain('yarn astryx upgrade --apply');
-    expect(result).toContain('after @astryxdesign/core bump, always run yarn astryx upgrade --apply');
+    expect(result).toContain('yarn astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 
   it('uses pnpm exec prefix', () => {
     const result = generateCompressedIndex('1.0.0', {runPrefix: 'pnpm exec'});
-    expect(result).toContain('pnpm exec astryx component <Name>');
+    expect(result).toContain('pnpm exec astryx <cmd>');
     expect(result).not.toContain('npx astryx');
   });
 });
 
+describe('detectStylingSystem', () => {
+  function writePkg(deps) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'x', devDependencies: deps}),
+    );
+  }
+
+  it('defaults to css when no package.json', () => {
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('returns css for a plain project', () => {
+    writePkg({react: '19.0.0', vite: '6.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('detects stylex when the compiler plugin is present', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+
+  it('detects tailwind when tailwindcss is present', () => {
+    writePkg({tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('tailwind');
+  });
+
+  it('does NOT treat the StyleX runtime alone as a compiler', () => {
+    // Only the runtime, no compiler plugin → must stay on the safe css path.
+    writePkg({'@stylexjs/stylex': '0.0.1'});
+    expect(detectStylingSystem(tmpDir)).toBe('css');
+  });
+
+  it('prefers stylex over tailwind when both are configured', () => {
+    writePkg({'@stylexjs/babel-plugin': '0.0.1', tailwindcss: '4.0.0'});
+    expect(detectStylingSystem(tmpDir)).toBe('stylex');
+  });
+});
+
 describe('getXdsVersion', () => {
   it('reads version from core package.json', () => {
     const coreDir = path.join(tmpDir, 'core');

package/src/commands/build-theme.import-path.test.mjs

@@ -70,7 +70,7 @@ beforeAll(() => {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-import-path-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-import-path-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/build-theme.path-safety.test.mjs

@@ -54,7 +54,7 @@ function writeTheme(dir, name) {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/build-theme.prose.test.mjs

@@ -82,7 +82,7 @@ beforeAll(() => {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-build-theme-prose-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-prose-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

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

@@ -65,7 +65,7 @@ export const docs = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-pkg-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-pkg-test-'));
   createFixture();
 });
 

package/src/commands/component.test.mjs

@@ -18,7 +18,7 @@ import {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-component-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-component-test-'));
 });
 
 afterEach(() => {

package/src/commands/docs.test.mjs

@@ -10,7 +10,7 @@ import {registerDocs} from './docs.mjs';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-docs-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));
   vi.spyOn(console, 'log').mockImplementation(() => {});
   vi.spyOn(console, 'error').mockImplementation(() => {});
 });

package/src/commands/doctor.test.mjs

@@ -26,7 +26,7 @@ let logCalls;
 let exitCode;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-doctor-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doctor-test-'));
   logCalls = [];
   exitCode = undefined;
   vi.spyOn(console, 'log').mockImplementation((...args) => {

package/src/commands/external-showcase.test.mjs

@@ -78,7 +78,7 @@ export const doc = {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-showcase-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-showcase-test-'));
   createFixture();
 });
 

package/src/commands/interactive-guard.test.mjs

@@ -35,7 +35,7 @@ function runCli(args) {
 }
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-interactive-guard-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
 });
 
 afterEach(() => {

package/src/commands/json-contract.test.mjs

@@ -53,7 +53,7 @@ function parseJson(stdout) {
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-json-contract-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
 });
 
 afterEach(() => {

package/src/commands/swizzle-gap-safety.test.mjs

@@ -36,7 +36,7 @@ let markerFile;
 let baseEnv;
 
 beforeAll(() => {
-  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-gh-shim-'));
+  shimDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gh-shim-'));
   markerFile = path.join(shimDir, 'gh-issue-create-was-called.marker');
 
   // Sabotaged `gh` shim. Records ONLY `gh issue create` invocations to the

package/src/commands/swizzle.path-safety.test.mjs

@@ -58,7 +58,7 @@ function runCli(args, cwd) {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-swizzle-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-swizzle-paths-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/commands/template.path-safety.test.mjs

@@ -17,7 +17,7 @@ let tmpDir;
 let templateApi;
 
 beforeEach(async () => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-paths-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-paths-'));
   templateApi = (await import('../api/template.mjs')).template;
 });
 afterEach(() => {

package/src/commands/template.test.mjs

@@ -12,7 +12,7 @@ import * as os from 'node:os';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-template-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-test-'));
 });
 
 afterEach(() => {

package/src/commands/upgrade.test.mjs

@@ -14,7 +14,7 @@ let stdoutCalls;
 let exitCode;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-upgrade-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-test-'));
   originalCwd = process.cwd();
   process.chdir(tmpDir);
   logCalls = [];

package/src/utils/package-manager.test.mjs

@@ -18,7 +18,7 @@ afterEach(() => {
 });
 
 function makeTmpDir() {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-pm-test-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-pm-test-'));
   return tmpDir;
 }
 

package/src/utils/path-safety.test.mjs

@@ -13,7 +13,7 @@ import {
 
 let tmpDir;
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-path-safety-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-path-safety-'));
 });
 afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});

package/src/utils/paths.test.mjs

@@ -9,7 +9,7 @@ import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages}
 let tmpDir;
 
 function makeTmpDir() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'xds-paths-test-'));
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-paths-test-'));
 }
 
 beforeEach(() => {
@@ -69,12 +69,12 @@ describe('findProjectRoot', () => {
 describe('discoverExternalPackages', () => {
   it('finds packages with an "astryx" field in package.json', () => {
     const nm = path.join(tmpDir, 'node_modules');
-    const extDir = path.join(nm, 'xds-charts');
+    const extDir = path.join(nm, 'astryx-charts');
     fs.mkdirSync(extDir, {recursive: true});
     fs.writeFileSync(
       path.join(extDir, 'package.json'),
       JSON.stringify({
-        name: 'xds-charts',
+        name: 'astryx-charts',
         astryx: {docs: './src', category: 'Data Viz'},
       }),
     );
@@ -82,7 +82,7 @@ describe('discoverExternalPackages', () => {
     const result = discoverExternalPackages(tmpDir);
     expect(result).toEqual([
       {
-        name: 'xds-charts',
+        name: 'astryx-charts',
         category: 'Data Viz',
         docsDir: path.join(extDir, 'src'),
         blocksDir: null,
@@ -92,7 +92,7 @@ describe('discoverExternalPackages', () => {
 
   it('handles scoped packages (@org/pkg)', () => {
     const nm = path.join(tmpDir, 'node_modules');
-    const scopedDir = path.join(nm, '@acme', 'xds-widgets');
+    const scopedDir = path.join(nm, '@acme', 'astryx-widgets');
     fs.mkdirSync(scopedDir, {recursive: true});
     fs.writeFileSync(
       path.join(scopedDir, 'package.json'),
@@ -165,12 +165,12 @@ describe('discoverExternalPackages', () => {
 
   it('walks up directories to find node_modules', () => {
     const nm = path.join(tmpDir, 'node_modules');
-    const extDir = path.join(nm, 'xds-ext');
+    const extDir = path.join(nm, 'astryx-ext');
     fs.mkdirSync(extDir, {recursive: true});
     fs.writeFileSync(
       path.join(extDir, 'package.json'),
       JSON.stringify({
-        name: 'xds-ext',
+        name: 'astryx-ext',
         astryx: {docs: './src'},
       }),
     );
@@ -180,7 +180,7 @@ describe('discoverExternalPackages', () => {
 
     const result = discoverExternalPackages(nested);
     expect(result).toHaveLength(1);
-    expect(result[0].name).toBe('xds-ext');
+    expect(result[0].name).toBe('astryx-ext');
   });
 
   it('handles invalid JSON in package.json gracefully', () => {

package/src/utils/update-check.test.mjs

@@ -14,7 +14,7 @@ let tmpDir;
 const originalEnv = {};
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-update-check-'));
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-update-check-'));
   // Save and clear env
   originalEnv.ASTRYX_LATEST_VERSION = process.env.ASTRYX_LATEST_VERSION;
   delete process.env.ASTRYX_LATEST_VERSION;