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

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 Astryx 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 Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+        },
+      ],
+    },
+  ],
+};

package/docs/motion.doc.mjs

@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'motion',
+  title: 'Motion',
+  category: 'foundations',
+  description:
+    'Duration and easing tokens for animations and transitions.',
+  tokenCategory: 'duration',
+
+  sections: [
+    {
+      title: 'Overview',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Motion serves two purposes: it makes interfaces easier to understand, and it makes them more pleasant to use. A panel animating open helps the eye track what changed and where new content sits in the layout. These moments reduce cognitive load and make the interface feel responsive.',
+        },
+        {
+          type: 'prose',
+          text: 'At the same time, well-tuned motion gives an application a sense of craft and polish that users notice, even if they can\'t name it.',
+        },
+        {
+          type: 'prose',
+          text: 'The design system provides duration and easing tokens that keep these moments consistent across your application.',
+        },
+      ],
+    },
+    {
+      title: 'Duration',
+  category: 'foundations',
+      content: [
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Duration Tokens',
+        },
+      ],
+    },
+    {
+      title: 'Easing',
+  category: 'foundations',
+      content: [
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Easing Tokens',
+        },
+      ],
+    },
+    {
+      title: 'Where Motion Helps',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Some parts of the interface benefit from animation. Panels, dialogs, and collapsible sections are disorienting when they appear instantly, so animation gives the eye something to follow. Toasts and notifications need just enough entrance to be noticed without startling. State changes like a switch flipping or a selection highlighting feel more intentional with a brief transition.',
+        },
+        {
+          type: 'prose',
+          text: 'The common thread is that these are moments where the user needs to understand what happened.',
+        },
+      ],
+    },
+    {
+      title: 'Where Motion Hurts',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Table row hovers. List item highlights. Anything the user does dozens of times per minute. Adding perceptible duration to these interactions makes the interface feel like it\'s catching up to the cursor. Keep these fast enough that the user never notices a delay.',
+        },
+        {
+          type: 'prose',
+          text: 'Animations that block interaction are worse. If a user has to wait for a panel to finish sliding before they can click something inside it, the animation has become an obstacle. Motion should never stand between the user and their next action.',
+        },
+      ],
+    },
+    {
+      title: 'Movement Principles',
+  category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Not everything needs an animated exit. Elements the user is moving away from, such as tooltips, hover cards, and dropdown menus, can disappear instantly. The user has already shifted their attention. Animate the exit only when it helps orient the user, like a panel closing or a dialog dismissing to reveal what\'s underneath.',
+            'When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.',
+            'Direction should match the action. Navigating deeper into content should feel like moving forward. Going back should feel like returning. This keeps the user oriented in the structure of the application.',
+            'Contextual UI should feel connected to its trigger. A dropdown should expand from the button that opened it. A popover should appear near the element it describes. This doesn\'t apply to global UI like command palettes or toasts, which have their own fixed positions.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Respecting User Preferences',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Components should honor the operating system\'s reduced motion setting. When it\'s enabled, replace animations with instant state changes.',
+        },
+      ],
+    },
+    {
+      title: 'Usage',
+  category: 'foundations',
+      content: [
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Applying motion tokens',
+          code: `import {durationVars, easeVars} from '@astryxdesign/core';
+
+const styles = stylex.create({
+  fadeIn: {
+    transitionProperty: 'opacity',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  slideUp: {
+    transitionProperty: 'transform, opacity',
+    transitionDuration: durationVars['--duration-medium'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+});`,
+        },
+      ],
+    },
+    {
+      title: 'Best Practices',
+  category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Animate transitions that involve spatial change: panels opening, content expanding, elements entering the screen.',
+            'Use fast tokens for small, frequent interactions. Use medium tokens for larger transitions that rearrange the layout.',
+            'Honor reduced motion preferences at the OS level.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Let hover states or high-frequency interactions feel like they\'re lagging behind the user.',
+            'Let animation delay when a user can interact with new content. The transition should complete before (or not block) the next action.',
+            'Move elements in ways that contradict where they came from or where they\'re going.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/docs/principles.doc.dense.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsDense = {
+  description: 'core design principles + rules for the design system',
+  sections: [
+    { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
+    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
+    { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
+    { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'read docs before inventing props'] }] },
+    { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
+  ],
+};

package/docs/principles.doc.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'principles',
+  title: 'Principles',
+  category: 'guide',
+  description:
+    'Core design principles and rules for building with the design system.',
+
+  sections: [
+    {
+      title: 'Design Philosophy',
+  category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'A design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Components over primitives: use components for everything they cover before reaching for raw HTML',
+            'Semantic tokens over hardcoded values: colors, spacing, and radii are named by purpose, not appearance',
+            'Theme-agnostic code: your app code never references specific colors or measurements, so themes and dark mode work automatically',
+            'Open internals: every primitive is exported and composable, so you can build on top of it without fighting it',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Rules',
+  category: 'guide',
+      content: [
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Use components for everything they cover',
+            'StyleX or Tailwind for custom styling; both are first-class (see \`npx astryx docs styling\`)',
+            'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
+            'CSS custom properties for colors, not hex values',
+            'Form inputs are controlled (value + onChange)',
+            'Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Styling Approach',
+  category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'The design system supports multiple styling approaches. Every component accepts an \`xstyle\` prop for StyleX style overrides via \`stylex.create()\`. For layout and wrapper styling outside of components, use StyleX or Tailwind utilities; both resolve to the same design tokens.',
+        },
+        {
+          type: 'prose',
+          text: 'See \`npx astryx docs styling\` for the complete guide with examples.',
+        },
+      ],
+    },
+    {
+      title: 'Anti-Patterns',
+  category: 'guide',
+      content: [
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Inline styles on raw elements. Use xstyle on components',
+            'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
+            'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
+            'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
+            'Inventing props. Read component docs first',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Design Tokens',
+  category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`npx astryx docs tokens\` for the full reference with all values.',
+        },
+      ],
+    },
+  ],
+};

package/docs/principles.doc.zh.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsZh = {
+  description: 'XDS 核心设计原则和规则。',
+  sections: [
+    { title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
+    { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
+    { title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
+    { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要自创属性。先阅读组件文档'] }] },
+    { title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
+  ],
+};

package/docs/shape.doc.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'shape',
+  title: 'Shape',
+  category: 'foundations',
+  description:
+    'Border radius tokens for consistent component rounding, from sharp corners to full pills.',
+  tokenCategory: 'radius',
+
+  sections: [
+    {
+      title: 'Overview',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'The radius scale uses a semantic naming system: inner → element → container → page. Each level fits a specific context. Themes can multiply the entire scale via a radius multiplier, with --radius-none and --radius-full as fixed anchors.',
+        },
+      ],
+    },
+    {
+      title: 'Radius Scale',
+  category: 'foundations',
+      content: [
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Radius Tokens',
+        },
+      ],
+    },
+    {
+      title: 'Concentric Radius',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'When a rounded container has padding, inner elements need a smaller radius to appear concentric. Components like Card handle this automatically; the inner radius is computed as max(0, outerRadius - padding).',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Concentric radius formula',
+          code: `/* Automatic in Astryx Card */
+--card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
+        },
+      ],
+    },
+    {
+      title: 'Best Practices',
+  category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Use --radius-element for interactive controls (buttons, inputs, selectors).',
+            'Use --radius-container for content containers (cards, panels, dialogs).',
+            'Use --radius-full for pill shapes (badges, tags, avatar status dots).',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            "Use --radius-page for small elements; it's meant for page-level containers.",
+            "Hardcode radius values; they won't scale with theme radius multipliers.",
+          ],
+        },
+      ],
+    },
+  ],
+};