@astryxdesign/cli 0.1.4-canary.d813abd → 0.1.4-canary.d869d88

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/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\u2019s 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/package.json

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

package/src/commands/swizzle.mjs

@@ -26,6 +26,7 @@ import {jsonOut, humanLog} from '../lib/json.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 import {checkGhCli} from '../utils/github.mjs';
+import {getRunPrefix} from '../utils/package-manager.mjs';
 import {Project} from '../lib/project.mjs';
 import {
   CORE_PACKAGE,
@@ -339,6 +340,10 @@ export function registerSwizzle(program) {
       // Copy all non-test, non-doc, non-README files
       const files = fs.readdirSync(componentDir);
       let copied = 0;
+      // Track whether any copied source uses StyleX. Swizzled StyleX source
+      // needs a build-time StyleX compiler in the consumer's app or it renders
+      // unstyled with no error — so we surface a setup note after copying.
+      let usesStyleX = false;
 
       for (const file of files) {
         // Skip test files, doc files, and README
@@ -355,6 +360,13 @@ export function registerSwizzle(program) {
           content = rewriteImports(content, owner.ownerPackage);
         }
 
+        if (
+          (file.endsWith('.ts') || file.endsWith('.tsx')) &&
+          content.includes('@stylexjs/stylex')
+        ) {
+          usesStyleX = true;
+        }
+
         fs.writeFileSync(path.join(outputDir, file), content);
         copied++;
       }
@@ -376,6 +388,7 @@ export function registerSwizzle(program) {
           outputDir: relOutput,
           filesCopied: copied,
           files: copiedFiles.map(f => f),
+          usesStyleX,
         };
         if (feedback) payload.feedback = feedback;
         return jsonOut('swizzle.copy', payload);
@@ -387,6 +400,27 @@ export function registerSwizzle(program) {
       );
       humanLog('You can now customize the component source freely.\n');
 
+      // StyleX build requirement. Swizzled components ship raw StyleX source,
+      // which needs a build-time StyleX compiler in the consumer's app to
+      // produce atomic CSS. Without it the component compiles but renders
+      // unstyled, with no error — a confusing silent failure, so call it out.
+      if (usesStyleX) {
+        humanLog(
+          '⚠ These components use StyleX and require a StyleX compiler in your build.',
+        );
+        humanLog(
+          '  Without one they render unstyled (no error). See setup per framework:',
+        );
+        humanLog(`  ${getRunPrefix()} astryx docs styling`);
+        humanLog(
+          '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font —',
+        );
+        humanLog(
+          '  use an SWC-based StyleX transform instead (covered in the guide).',
+        );
+        humanLog('');
+      }
+
       // Maintainer feedback note. If we couldn't swizzle cleanly, the team
       // wants to know — point users at the issue tracker. Skipped when the
       // owning package ships no issues URL.

package/src/commands/swizzle.routing.test.mjs

@@ -277,3 +277,70 @@ describe('swizzle — ambiguous ownership', () => {
     expect(out).toContain(`from '@astryxdesign/core/theme'`);
   });
 });
+
+/**
+ * Build a fake @astryxdesign/core with a component that imports StyleX directly
+ * (so the swizzle StyleX-build note should fire) and one that doesn't.
+ */
+function buildStyleXCore(project) {
+  const core = path.join(project, 'node_modules', '@astryxdesign', 'core');
+  // StyleX component.
+  const styledDir = path.join(core, 'src', 'Styled');
+  fs.mkdirSync(styledDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    '{"name":"@astryxdesign/core","version":"0.0.13"}',
+  );
+  fs.writeFileSync(
+    path.join(styledDir, 'Styled.tsx'),
+    [
+      `import * as stylex from '@stylexjs/stylex';`,
+      `const styles = stylex.create({base: {color: 'red'}});`,
+      `export const Styled = () => null;`,
+      '',
+    ].join('\n'),
+  );
+  // Plain component (no StyleX).
+  const plainDir = path.join(core, 'src', 'Plain');
+  fs.mkdirSync(plainDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(plainDir, 'Plain.tsx'),
+    `export const Plain = () => null;\n`,
+  );
+  return core;
+}
+
+describe('swizzle — StyleX build setup note (#3373)', () => {
+  it('reports usesStyleX and prints a setup note for StyleX components', () => {
+    buildStyleXCore(project);
+    writeProjectPackageJson(project);
+
+    // JSON payload carries the machine-readable flag.
+    const jsonResult = runCli(['--json', 'swizzle', 'Styled', '-f'], project);
+    expect(jsonResult.code).toBe(0);
+    const env = JSON.parse(jsonResult.stdout);
+    expect(env.data.usesStyleX).toBe(true);
+
+    // Human output surfaces the compiler requirement + Next.js caveat.
+    const humanResult = runCli(['swizzle', 'Styled', '-f'], project);
+    expect(humanResult.code).toBe(0);
+    expect(humanResult.stdout).toMatch(/StyleX compiler/i);
+    expect(humanResult.stdout).toMatch(/unstyled/i);
+    expect(humanResult.stdout).toMatch(/next\/font/i);
+    expect(humanResult.stdout).toMatch(/astryx docs styling/);
+  });
+
+  it('does not print the StyleX note for components without StyleX', () => {
+    buildStyleXCore(project);
+    writeProjectPackageJson(project);
+
+    const jsonResult = runCli(['--json', 'swizzle', 'Plain', '-f'], project);
+    expect(jsonResult.code).toBe(0);
+    const env = JSON.parse(jsonResult.stdout);
+    expect(env.data.usesStyleX).toBe(false);
+
+    const humanResult = runCli(['swizzle', 'Plain', '-f'], project);
+    expect(humanResult.code).toBe(0);
+    expect(humanResult.stdout).not.toMatch(/StyleX compiler/i);
+  });
+});