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

package/docs/tokens.doc.zh.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsZh = {
+  description: '间距、颜色、圆角、排版和阴影设计令牌参考。',
+  sections: [
+    { title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
+    { title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
+    { title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色，支持 light-dark() 自动切换模式。' }, null, null, null] },
+    { title: '圆角令牌', content: [null] },
+    { title: '阴影令牌', content: [null] },
+    { title: '排版令牌', content: [null, null, null, null] },
+    { title: 'StyleX 用法', content: [null, null] },
+  ],
+};

package/docs/typography.doc.mjs

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'typography',
+  title: 'Typography',
+  category: 'foundations',
+  description:
+    'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',
+  tokenCategory: 'typography',
+
+  sections: [
+    // ── Overview ────────────────────────────────────────────────────────────
+    {
+      title: 'Overview',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height, so components express intent (heading, body, label) rather than raw values.',
+        },
+        {
+          type: 'prose',
+          text: 'Two layers work together: raw size tokens (--font-size-xs ... --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme; all semantic tokens recompute automatically.',
+        },
+      ],
+    },
+
+    // ── Font Families ───────────────────────────────────────────────────────
+    {
+      title: 'Font Families',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role; heading inherits from body when not explicitly set.',
+        },
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Font Family Tokens',
+        },
+      ],
+    },
+
+    // ── Font Sizes ──────────────────────────────────────────────────────────
+    {
+      title: 'Font Sizes',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Geometric scale: round(base × ratio^step), expressed in rem. The default scale is 14px × 1.2, producing 12 steps from 4xs (6px) to 5xl (42px). Adjusting base and ratio in defineTheme regenerates every size token while preserving proportional relationships.',
+        },
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Font Size Tokens',
+        },
+      ],
+    },
+
+    // ── Font Weights ────────────────────────────────────────────────────────
+    {
+      title: 'Font Weights',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Four semantic weights: normal (400, body/code), medium (500, labels/data), semibold (600, headings/titles), bold (700, strong emphasis). Type scale tokens reference these by var() so themes can remap numeric values.',
+        },
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Font Weight Tokens',
+        },
+      ],
+    },
+
+    // ── Line Height ─────────────────────────────────────────────────────────
+    {
+      title: 'Line Height',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Line heights are computed from a tiered target ratio and snapped to a 4px vertical grid. Small text (<20px) targets 1.5, medium text (20–31px) targets 1.4, and large text (≥32px) targets 1.25. A minimum gap of fontSize + 4px is enforced. The result is a unitless ratio stored in each --text-*-leading token.',
+        },
+        {
+          type: 'prose',
+          text: 'The 4px grid matters: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio, so you should never need to set line-height manually.',
+        },
+      ],
+    },
+
+    // ── Type Scale ──────────────────────────────────────────────────────────
+    {
+      title: 'Type Scale',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Semantic tokens that combine size, weight, and line-height into a single type style. Each token triplet (--text-*-size, --text-*-weight, --text-*-leading) is consumed by Text and Heading. Use the component props rather than composing raw font tokens.',
+        },
+        {
+          type: 'token-ref',
+          topic: 'tokens',
+          section: 'Type Scale Tokens',
+        },
+      ],
+    },
+
+    // ── Display Text ────────────────────────────────────────────────────────
+    {
+      title: 'Display Text',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2), since large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts, not for document headings.',
+        },
+        {
+          type: 'prose',
+          text: 'Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: <Heading level={1} type="display-1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.',
+        },
+      ],
+    },
+
+    // ── Usage ────────────────────────────────────────────────────────────────
+    {
+      title: 'Usage',
+  category: 'foundations',
+      content: [
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Heading for document structure',
+          code: `import {Heading} from '@astryxdesign/core';
+
+// Heading levels map to semantic tokens: level 1 → --text-heading-1-*
+<Heading level={1}>Page Title</Heading>
+<Heading level={2}>Section</Heading>
+<Heading level={3}>Subsection</Heading>
+
+// Display type for hero/marketing headings — level sets the HTML element
+<Heading level={1} type="display-1">Hero Title</Heading>
+<Heading level={2} type="display-2">$1.2M Revenue</Heading>
+
+// Override the accessibility level when visual ≠ document hierarchy
+<Heading level={2} accessibilityLevel={3}>
+  Sidebar Section
+</Heading>`,
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Text for body, label, and display text',
+          code: `import {Text} from '@astryxdesign/core';
+
+<Text type="body">Body text at the base scale.</Text>
+<Text type="large">Emphasized body text.</Text>
+<Text type="label">Form label</Text>
+<Text type="supporting">Helper text, timestamps, metadata.</Text>
+<Text type="code">{'const x = 1;'}</Text>
+
+// Display without heading semantics (data callouts, decorative)
+<Text type="display-2">$1.2M Revenue</Text>`,
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Customizing the type scale via defineTheme',
+          code: `import {defineTheme} from '@astryxdesign/core';
+
+// Adjust the entire ramp holistically with base and ratio
+const editorialTheme = defineTheme({
+  name: 'editorial',
+  typography: {
+    scale: { base: 16, ratio: 1.25 },          // airy / article feel
+    body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },
+    heading: { weight: 'bold' },
+    code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' },
+  },
+});
+
+const denseTheme = defineTheme({
+  name: 'dense',
+  typography: {
+    scale: { base: 12, ratio: 1.125 },          // compact / data-dense UI
+  },
+});`,
+        },
+      ],
+    },
+
+    // ── Best Practices ──────────────────────────────────────────────────────
+    {
+      title: 'Best Practices',
+  category: 'foundations',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Use Heading for document headings and Text for everything else; they apply the full type scale automatically.',
+            'Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).',
+            'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use <Heading level={1} type="display-1"> which handles both semantics and styling.',
+            'Let line-height snap to the 4px grid via the type scale; expandTypeScale computes leading automatically from base and ratio.',
+            'Use the supporting type for secondary information: timestamps, helper text, metadata, captions.',
+            'Use accessibilityLevel on Heading when the visual hierarchy doesn\u0027t match the document outline (e.g. sidebar or card headings).',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Set font-size or line-height manually; use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned.',
+            'Skip heading levels (e.g. h1 to h3); screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level.',
+            'Use display types for body content or in-page sections; they\u0027re designed for hero/marketing/data-callout contexts only.',
+            'Override individual size tokens (--font-size-lg) to "tweak" a heading; adjust base/ratio instead so proportions remain coherent across the entire scale.',
+            'Use raw numeric font-weight values (400, 600); reference the semantic weight tokens so themes can remap them.',
+          ],
+        },
+      ],
+    },
+  ],
+};

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

@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'working-with-ai',
+  title: 'Working with AI',
+  category: 'guide',
+  description:
+    'How to set up AI coding tools to generate correct component code.',
+
+  sections: [
+    {
+      title: 'Overview',
+      content: [
+        {
+          type: 'prose',
+          text: 'The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.',
+        },
+        {
+          type: 'prose',
+          text: 'The CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct component code.',
+        },
+      ],
+    },
+    {
+      title: 'Quick Start',
+      content: [
+        {
+          type: 'prose',
+          text: 'Tell your AI to install the CLI and set itself up:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Paste this into your AI',
+          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
+        },
+        {
+          type: 'prose',
+          text: 'That\'s it. The agent-docs command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
+        },
+        {
+          type: 'prose',
+          text: 'If you prefer to target a specific file format:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Manual options',
+          code: `npx astryx agent-docs --agent claude    # CLAUDE.md
+npx astryx agent-docs --agent cursor    # .cursorrules
+npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
+        },
+      ],
+    },
+    {
+      title: 'What Gets Generated',
+      content: [
+        {
+          type: 'prose',
+          text: 'The generated context teaches your AI a 3-step workflow before writing any UI code:',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            '`npx astryx template --list`: find a related page pattern to use as reference',
+            '`npx astryx template <name> --skeleton`: study the layout structure',
+            '`npx astryx component <Name>`: read props and examples for every component used',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn\'t need to manually correct your AI on these conventions; the agent docs handle it at the system level.',
+        },
+      ],
+    },
+    {
+      title: 'Cursor Setup',
+      content: [
+        {
+          type: 'prose',
+          text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Install as a Cursor user rule',
+          code: `mkdir -p ~/.cursor/rules
+npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
+        },
+      ],
+    },
+    {
+      title: 'Checking Your Setup',
+      content: [
+        {
+          type: 'prose',
+          text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Paste this into your AI',
+          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?
+3. What prop does Selector use for its items?
+
+If you don't know all three, run \`npx astryx init --features agents\` to generate agent docs, then read the generated file.`,
+        },
+      ],
+    },
+    {
+      title: 'The npx astryx Pattern',
+      content: [
+        {
+          type: 'prose',
+          text: 'AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@astryxdesign/cli/bin/docs.mjs instead of astryx.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `"scripts": {
+  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'With this alias, agents use `npx astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Reliable CLI invocation',
+          code: `npx astryx component --list
+npx astryx component Dialog --dense
+npx astryx docs styling --dense
+npx astryx docs tokens --dense`,
+        },
+      ],
+    },
+    {
+      title: 'The --dense Flag',
+      content: [
+        {
+          type: 'prose',
+          text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Dense output for pasting into AI conversations',
+          code: `npx astryx component Dialog --dense
+npx astryx docs styling --dense
+npx astryx docs tokens --dense`,
+        },
+      ],
+    },
+    {
+      title: 'MCP Server',
+      content: [
+        {
+          type: 'prose',
+          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',
+          text: 'The MCP server exposes two tools: search(query) for discovering components, doc topics, and templates; and get(name) for retrieving full documentation with props, usage, and examples.',
+        },
+        {
+          type: 'prose',
+          text: 'Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'MCP config (same for all tools)',
+          code: `{
+  "mcpServers": {
+    "xds": {
+      "type": "url",
+      "url": "https://astryx.atmeta.com/mcp"
+    }
+  }
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.',
+        },
+      ],
+    },
+  ],
+};

package/package.json

@@ -1,11 +1,82 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder published to claim the npm name during trusted publishing setup. Do not install.",
-  "homepage": "https://github.com/facebook/astryx",
+  "version": "0.1.0-canary.08d4cf4",
+  "displayName": "CLI",
+  "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
+  "author": "Meta Open Source",
   "license": "MIT",
+  "homepage": "https://github.com/facebook/astryx#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/facebook/astryx.git"
+    "url": "git+https://github.com/facebook/astryx.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/facebook/astryx/issues"
+  },
+  "keywords": [
+    "astryx",
+    "cli",
+    "design-system",
+    "init",
+    "swizzle",
+    "scaffolding",
+    "theme",
+    "agent-docs"
+  ],
+  "type": "module",
+  "bin": {
+    "astryx": "./bin/astryx.mjs",
+    "cli": "./bin/astryx.mjs"
+  },
+  "exports": {
+    ".": "./bin/astryx.mjs",
+    "./json": {
+      "types": "./src/types/index.d.ts",
+      "import": "./src/lib/parse.mjs"
+    },
+    "./api": {
+      "types": "./src/types/api.d.ts",
+      "import": "./src/api/index.mjs"
+    }
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "commander": "^12.1.0",
+    "jiti": "^2.7.0",
+    "jscodeshift": "^17.3.0"
+  },
+  "peerDependencies": {
+    "@astryxdesign/core": "0.1.0-canary.08d4cf4",
+    "@astryxdesign/lab": "0.1.0-canary.08d4cf4",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.08d4cf4"
+  },
+  "peerDependenciesMeta": {
+    "@astryxdesign/core": {
+      "optional": true
+    },
+    "@astryxdesign/lab": {
+      "optional": true
+    },
+    "@astryxdesign/theme-neutral": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@astryxdesign/core": "0.1.0-canary.08d4cf4",
+    "@astryxdesign/lab": "0.1.0-canary.08d4cf4",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.08d4cf4"
+  },
+  "scripts": {
+    "astryx": "node bin/astryx.mjs",
+    "typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
+    "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"
   }
-}
+}