@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/docs/getting-started.doc.mjs

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'getting-started',
+  title: 'Getting Started',
+  category: 'guide',
+  description:
+    'Add the design system to your project and start building.',
+
+  sections: [
+    {
+      title: 'Quick Start with AI',
+      content: [
+        {
+          type: 'prose',
+          text: 'Paste this into your AI coding tool and let it handle the setup:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Paste this into your AI',
+          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
+        },
+      ],
+    },
+    {
+      title: 'Install',
+      content: [
+        {
+          type: 'prose',
+          text: 'Add the core package, a theme, and the CLI to your existing project.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Terminal',
+          code: `npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli`,
+        },
+        {
+          type: 'prose',
+          text: 'Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Terminal',
+          code: `npx astryx init`,
+        },
+      ],
+    },
+    {
+      title: 'Add the theme CSS',
+      content: [
+        {
+          type: 'prose',
+          text: 'Import the reset stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'globals.css',
+          code: `@import '@astryxdesign/core/reset.css';
+@import '@astryxdesign/core/astryx.css';
+@import '@astryxdesign/theme-neutral/theme.css';`,
+        },
+        {
+          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.',
+        },
+      ],
+    },
+    {
+      title: 'Add your first component',
+      content: [
+        {
+          type: 'prose',
+          text: 'Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'app/page.tsx',
+          code: `import {Button} from '@astryxdesign/core/Button';
+import {VStack} from '@astryxdesign/core/Layout';
+
+export default function Page() {
+  return (
+    <VStack gap={2}>
+      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
+    </VStack>
+  );
+}`,
+        },
+      ],
+    },
+    {
+      title: 'Customize with StyleX',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Style overrides',
+          code: `import * as stylex from '@stylexjs/stylex';
+
+const overrides = stylex.create({
+  save: { alignSelf: 'flex-end', marginTop: 16 },
+});
+
+<Button label="Save" xstyle={overrides.save} />`,
+        },
+      ],
+    },
+    {
+      title: 'Example Apps',
+      content: [
+        {
+          type: 'prose',
+          text: 'For a full working project, clone one of the example apps from the repo. These are complete setups with routing, theming, and components wired together.',
+        },
+        {
+          type: 'table',
+          headers: ['Example', 'Stack', 'Path'],
+          rows: [
+            ['Next.js', 'Next.js + theme CSS', '[apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs)'],
+            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', '[apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex)'],
+            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
+            ['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
+            ['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Clone and run an example',
+          code: `git clone https://github.com/facebook/astryx.git
+cd astryx/apps/example-nextjs
+pnpm install
+pnpm dev`,
+        },
+      ],
+    },
+    {
+      title: 'Explore the CLI',
+      content: [
+        {
+          type: 'prose',
+          text: 'The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `"scripts": {
+  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Then discover what\'s available:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Terminal',
+          code: `npx astryx component          # list all components
+npx astryx component Button   # props, usage, theming for Button
+npx astryx docs               # list all doc topics
+npx astryx template --list    # available page templates
+npx astryx docs tokens        # spacing, color, radius reference`,
+        },
+      ],
+    },
+  ],
+};

package/docs/icons.doc.mjs

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Icons reference doc: semantic icon names available in XDS
+ */
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+export const docs = {
+  name: 'icons',
+  title: 'Icons',
+  category: 'foundations',
+  description:
+    "Semantic icon names available in the design system. These adapt to the active theme's icon registry.",
+
+  sections: [
+    {
+      title: 'Available Names',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Components that accept an icon prop use IconType: either a semantic name string or a direct SVG component. The semantic names below are resolved through the global icon registry.',
+        },
+        {
+          type: 'table',
+          headers: ['Name', 'Usage'],
+          rows: [
+            ['close', 'Dismiss, close dialogs/panels'],
+            ['chevronDown', 'Dropdown triggers, expand/collapse'],
+            ['chevronLeft', 'Navigate back, previous'],
+            ['chevronRight', 'Navigate forward, next'],
+            ['check', 'Checkbox checked, confirm'],
+            ['success', 'Success status indicator'],
+            ['error', 'Error status indicator'],
+            ['warning', 'Warning status indicator'],
+            ['info', 'Info status indicator, tooltips'],
+            ['calendar', 'Date pickers, scheduling'],
+            ['clock', 'Time pickers, timestamps'],
+            ['externalLink', 'Links opening in new tab'],
+            ['menu', 'Hamburger menu, navigation toggle'],
+            ['moreHorizontal', 'Overflow menu, additional actions'],
+            ['search', 'Search inputs, find'],
+            ['arrowUp', 'Sort ascending, move up'],
+            ['arrowDown', 'Sort descending, move down'],
+            ['arrowsUpDown', 'Sortable column indicator'],
+            ['funnel', 'Filter controls'],
+            ['eyeSlash', 'Hidden/visibility toggle'],
+            ['viewColumns', 'Column visibility settings'],
+            ['copy', 'Copy to clipboard'],
+            ['checkDouble', 'Copied confirmation'],
+            ['wrench', 'Settings, configuration'],
+            ['stop', 'Stop/cancel action'],
+            ['microphone', 'Voice input, audio recording'],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Custom Icons',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'For icons not in the semantic list, pass an SVG component directly. Any ComponentType<SVGProps<SVGSVGElement>> works; Icon applies size and color styling automatically.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Using custom SVG components',
+          code: `import { PhotoIcon } from '@heroicons/react/24/outline';
+import { HeartIcon } from 'lucide-react';
+
+<Icon icon={PhotoIcon} size="lg" />
+<Icon icon={HeartIcon} color="negative" />`,
+        },
+      ],
+    },
+    {
+      title: 'Theme Overrides',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Themes can replace the default SVGs for any semantic name using registerIcons(). This lets you swap the entire icon set (e.g. heroicons \u2192 lucide) without touching component code.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Registering theme icons',
+          code: `import { registerIcons } from '@astryxdesign/core/Icon';
+import { XMarkIcon, ChevronDownIcon } from '@heroicons/react/24/outline';
+
+registerIcons({
+  close: <XMarkIcon />,
+  chevronDown: <ChevronDownIcon />,
+  // ... override as many as needed
+});`,
+        },
+      ],
+    },
+    {
+      title: 'Adding New Icons',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'To add a new semantic icon name to the design system:',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Add the name to IconName type in packages/core/src/Icon/globalIconRegistry.tsx',
+            'Add the default SVG to packages/core/src/Icon/defaultIcons.tsx',
+            'Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/docs/illustrations.doc.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+export const docs = {
+  name: 'illustrations',
+  title: 'Illustrations',
+  category: 'foundations',
+  description:
+    'Illustration guidelines for empty states, onboarding flows, and feature highlights.',
+
+  sections: [
+    {
+      title: 'When to Use',
+      category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Consistent illustration usage reinforces brand identity and helps users understand context at a glance. Use illustrations in these contexts:',
+        },
+        {
+          type: 'table',
+          headers: ['Context', 'Examples'],
+          rows: [
+            ['Empty states', 'No data, first-time experience, search with no results'],
+            ['Onboarding', 'Welcome screens, feature introduction, setup wizards'],
+            ['Feature highlights', 'New feature announcements, upgrade prompts'],
+            ['Error states', 'Permission denied, not found, service unavailable'],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Guidelines',
+      category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Keep illustrations consistent in style across the product.',
+            'Use simple, flat illustrations that work in both light and dark mode.',
+            'Size illustrations proportionally to the container, typically 120\u2013240px.',
+            'Center illustrations with supporting text below.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Mix illustration styles from different sources.',
+            'Use illustrations as decoration without purpose.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Placement',
+      category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Center illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Empty state with illustration',
+          code: `<Center>
+  <Stack direction="vertical" gap={3} hAlign="center">
+    <img
+      src="/illustrations/empty-search.svg"
+      alt="No results"
+      style={{ width: 200, height: 200 }}
+    />
+    <Heading level={3}>No results found</Heading>
+    <Text type="body" color="secondary">
+      Try adjusting your search or filters to find what you\u2019re
+      looking for.
+    </Text>
+  </Stack>
+</Center>`,
+        },
+      ],
+    },
+  ],
+};

package/docs/migration.doc.mjs

@@ -0,0 +1,250 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'migration',
+  title: 'Migration Guide',
+  category: 'guide',
+  description:
+    'How to migrate an existing Tailwind, shadcn, or Radix application to the design system incrementally.',
+
+  sections: [
+    {
+      title: 'Overview',
+      content: [
+        {
+          type: 'prose',
+          text: 'Treat migration as a product-shell and workflow migration, not a global class replacement. Start by putting the app inside Theme and AppShell, then move one route or surface at a time to design system primitives while keeping existing data, routing, and business logic intact.',
+        },
+        {
+          type: 'prose',
+          text: 'Tailwind can coexist during migration. Use it for legacy wrappers and local layout while replacing interactive controls, navigation, command surfaces, forms, alerts, dialogs, and settings UI with components.',
+        },
+      ],
+    },
+    {
+      title: 'Recommended Order',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            '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.',
+            '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.',
+            'Remove legacy Tailwind classes from each completed surface, keeping only token-backed layout utilities or local wrappers that still need to be migrated.',
+            'Verify both light and dark modes, keyboard navigation, responsive layout, and empty/error/loading states before moving to the next route.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'CLI Workflow',
+      content: [
+        {
+          type: 'prose',
+          text: 'Use the CLI as the migration checklist. Read the docs for the pattern you are about to touch, inspect a matching template skeleton, then read the exact component docs before editing.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Migration-oriented CLI pass',
+          code: `npx astryx docs migration
+npx astryx docs theme
+npx astryx docs styling
+npx astryx template --list --type block
+npx astryx template AppShellTopNavWithSideNav --skeleton
+npx astryx template PopoverSettingsPanel --skeleton
+npx astryx component AppShell
+npx astryx component SideNav
+npx astryx component TopNav
+npx astryx component CommandPalette
+npx astryx component Button
+npx astryx component TextInput`,
+        },
+        {
+          type: 'prose',
+          text: 'Use --dense when pasting output into an AI coding tool, and use --json when building automated migration reports.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Dense and JSON modes',
+          code: `npx astryx docs migration --dense
+npx astryx component Button --json`,
+        },
+      ],
+    },
+    {
+      title: 'Theme and CSS Setup',
+      content: [
+        {
+          type: 'prose',
+          text: 'Mount Theme at the app root so every migrated component reads the same token set. Keep the mode in application state if users can switch between light and dark themes.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Root provider with explicit mode',
+          code: `import {Theme} from '@astryxdesign/core/theme';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
+import {useState} from 'react';
+import '@astryxdesign/theme-neutral/theme.css';
+
+export function AppRoot({children}: {children: React.ReactNode}) {
+  const [mode, setMode] = useState<'system' | 'light' | 'dark'>('system');
+
+  return (
+    <Theme theme={neutralTheme} mode={mode}>
+      <SettingsContext.Provider value={{mode, setMode}}>
+        {children}
+      </SettingsContext.Provider>
+    </Theme>
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'When Tailwind remains in the app, declare layer order once in the global CSS file. design system reset and theme CSS should load before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Tailwind v4 coexistence',
+          code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+@import "@astryxdesign/core/tailwind-theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);`,
+        },
+      ],
+    },
+    {
+      title: 'Move the App Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'Start with AppShell so page migration happens inside the final navigation, spacing, surface, and responsive frame. This also exposes theme and color issues early because every route shares the same shell.',
+        },
+        {
+          type: 'table',
+          headers: ['Legacy surface', 'Component', 'Notes'],
+          rows: [
+            ['Header', 'TopNav', 'Use for product identity, global actions, account entry, and command/search trigger.'],
+            ['Sidebar', 'SideNav', 'Use sections and nested nav items for route groups. Keep selection state driven by the router.'],
+            ['Main page wrapper', 'AppShell + Layout', 'Let the shell own persistent structure; let route components own page content.'],
+            ['Mobile drawer nav', 'MobileNav or AppShell mobile behavior', 'Verify focus, close behavior, and route changes on narrow viewports.'],
+            ['Settings menu', 'Popover + Layout + Switch', 'Use as the home for theme mode and app preferences.'],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Map shadcn and Radix Primitives',
+      content: [
+        {
+          type: 'prose',
+          text: 'Do not wrap old shadcn components in design system styles. Replace the primitive with the component that owns the behavior, accessibility, state classes, and token usage.',
+        },
+        {
+          type: 'table',
+          headers: ['Existing primitive', 'Component', 'Migration note'],
+          rows: [
+            ['button / shadcn Button', 'Button or IconButton', 'Use Button for labeled commands and IconButton for icon-only toolbar actions.'],
+            ['input', 'TextInput', 'Keep validation state in status props rather than ad hoc border classes.'],
+            ['textarea', 'TextArea', 'Use when multiline editing is the primary action.'],
+            ['switch', 'Switch', 'Use for persisted boolean settings, including theme mode when represented as a binary choice.'],
+            ['checkbox', 'CheckboxInput or CheckboxList', 'Use list variants for grouped selection.'],
+            ['radio group', 'RadioList', 'Use when one option must be selected from a visible set.'],
+            ['select / combobox', 'Selector or Typeahead', 'Use Selector for bounded options and Typeahead for searchable async options.'],
+            ['tabs used as page nav', 'TabList', 'Use route state or current page state as the source of truth.'],
+            ['command dialog', 'CommandPalette', 'Keep app-specific search sources outside the shell and feed searchable items.'],
+            ['dropdown action menu', 'DropdownMenu or MoreMenu', 'Use MoreMenu for compact overflow actions.'],
+            ['alert / callout', 'Banner or Toast', 'Use Banner for page or section messages and Toast for transient feedback.'],
+            ['dialog', 'Dialog or AlertDialog', 'Use AlertDialog for destructive confirmation and Dialog for task flows.'],
+            ['card-like list row', 'ListItem', 'Prefer ListItem for selectable rows instead of styling Button as a row.'],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Command Palette, Settings, and Theme',
+      content: [
+        {
+          type: 'prose',
+          text: 'Move global search to CommandPalette once the shell exists. Treat the palette as a view over app commands: routes, contextual actions, create actions, filters, recent items, and entity results. Keep data normalization in app code so search sources always return arrays of searchable items.',
+        },
+        {
+          type: 'prose',
+          text: 'Put light and dark mode controls in the settings popover or account menu. The switch or selector should update the mode passed to Theme, not toggle isolated body classes.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Settings popover theme control',
+          code: `function ThemeModeSwitch() {
+  const {mode, setMode} = useSettings();
+  const isDark = mode === 'dark';
+
+  return (
+    <Switch
+      label="Dark mode"
+      description="Use the dark color theme"
+      value={isDark}
+      onChange={next => setMode(next ? 'dark' : 'light')}
+    />
+  );
+}`,
+        },
+      ],
+    },
+    {
+      title: 'Verification Checklist',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',
+            'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',
+            'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',
+            'Verify settings popovers and dialogs in jsdom and in a real browser because native dialog and Popover APIs may need test shims.',
+            'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',
+            'Run component tests, build, and at least one browser screenshot pass for each migrated route.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'AI Migration Prompt',
+      content: [
+        {
+          type: 'prose',
+          text: 'When using an AI coding agent, give it an explicit migration loop instead of asking for a full-app rewrite.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Paste this into your AI',
+          code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+
+First run:
+- npx astryx docs migration --dense
+- npx astryx docs theme --dense
+- 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.`,
+        },
+      ],
+    },
+  ],
+};