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

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 XDS 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.",
+          ],
+        },
+      ],
+    },
+  ],
+};

package/docs/spacing.doc.mjs

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'spacing',
+  title: 'Spacing',
+  category: 'foundations',
+  description:
+    'Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.',
+  tokenCategory: 'spacing',
+
+  sections: [
+    {
+      title: 'Overview',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'The design system uses a 4px base-unit spacing scale. Component gap props accept step values that map to these tokens. The scale provides fine-grained control at the small end (2px, 4px, 6px) and consistent rhythm at larger sizes (multiples of 4px).',
+        },
+      ],
+    },
+    {
+      title: 'Scale',
+  category: 'foundations',
+      content: [
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Spacing Tokens',
+        },
+      ],
+    },
+    {
+      title: 'Usage',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Spacing via component props vs StyleX',
+          code: `// Via component props (preferred)
+<Stack gap={4}>{/* 16px gap */}</Stack>
+
+// Via StyleX tokens (custom layouts)
+import {spacingVars} from '@astryxdesign/core';
+
+const styles = stylex.create({
+  custom: {
+    padding: spacingVars['--spacing-4'],
+    gap: spacingVars['--spacing-3'],
+  },
+});`,
+        },
+      ],
+    },
+    {
+      title: 'Best Practices',
+  category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Use component gap props when available; they handle automatic spacing compensation.',
+            "Stick to the scale for consistency. If a value isn't on the scale, reconsider the design.",
+            'Use smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Use arbitrary pixel values outside the scale.',
+            'Mix spacing tokens with raw px/rem values in the same component.',
+          ],
+        },
+      ],
+    },
+  ],
+};