@astryxdesign/cli 0.4.1 → 0.4.2-canary.464a445

package/api/theme/themeTemplate.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `themeTemplate()` / `astryx theme template`. Colocated with the
+ * API function it documents; the response-shape source of truth stays in
+ * `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/theme/themeTemplate.doc.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `themeTemplate()` / `astryx theme template`. Colocated with the
+ * API function it documents; the response-shape source of truth stays in
+ * `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'themeTemplate',
+  displayName: 'themeTemplate()',
+  summary: 'Write the annotated theme template into a project.',
+  description:
+    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'defineTheme field, the token families, the component override syntax, and how a theme is ' +
+    'consumed — with the CLI command that prints the authoritative reference for each section. ' +
+    'Read it, copy what you need into your own theme file, delete it. Where `theme add` starts ' +
+    'you from a theme we ship, this starts you from a blank one. Refuses to overwrite without ' +
+    '`overwrite`, so it is safe to re-run.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'themeTemplate(options?: {targetPath?: string, overwrite?: boolean, cwd?: string}): ThemeNewResponse',
+  keywords: ['theme', 'template', 'starter', 'defineTheme', 'scaffold', 'reference', 'tokens'],
+  params: [
+    {
+      name: 'options.targetPath',
+      type: 'string',
+      description: 'Destination file. Must resolve within cwd.',
+      default: "'theme.template.ts'",
+    },
+    {
+      name: 'options.overwrite',
+      type: 'boolean',
+      description: 'Replace an existing file instead of reporting it untouched.',
+      default: 'false',
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'Directory the target path resolves against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'theme.template',
+      description:
+        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success, not a failure.',
+    },
+  ],
+  throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],
+  examples: [
+    {label: 'Write it at the project root', code: 'themeTemplate();'},
+    {
+      label: 'Somewhere else, replacing what is there',
+      code: "themeTemplate({targetPath: 'src/themes/template.ts', overwrite: true});",
+    },
+  ],
+  command: 'theme template',
+  related: ['themeAdd', 'themeBuild', 'themeList'],
+};

package/assets/docs/getting-started.doc.mjs

@@ -20,9 +20,19 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          label: 'Paste this into your AI',
+          label: 'Set up the design system',
           code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
+        {
+          type: 'prose',
+          text: 'Then give it a look. Every app gets a theme whether or not anyone picks one, so it is worth one question at setup rather than revisiting screens later that were built around the wrong look:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Give it a look',
+          code: "Ask me what look and feel this app should have. Run `npx @astryxdesign/cli theme list` and start from the closest shipped theme with `theme add <slug>`, which copies it in as editable source; if none of them fit, run `npx @astryxdesign/cli theme template` and fill in the annotated template it writes. Default to neutral if I have no preference, and show me the result before moving on.",
+        },
       ],
     },
     {

package/assets/docs/theme.doc.dense.mjs

@@ -8,9 +8,9 @@ export const docsDense = {
     { section: 'Quick Start', title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
     { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { section: 'Theme Props', title: 'Props', content: [null] },
-    { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
+    { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: '`theme list` + `theme add <slug>` to start from a shipped theme, or defineTheme from scratch. only override tokens that differ.' }, null, { type: 'prose', text: '`astryx theme template` writes theme.template.ts: every defineTheme field + token families + override syntax, annotated, with the CLI command that prints each reference.' }] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
-    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
     { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },

package/assets/docs/theme.doc.mjs

@@ -142,13 +142,17 @@ function App() {
       content: [
         {
           type: 'prose',
-          text: 'Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.',
+          text: 'Start from a theme we ship, or write one from scratch with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Scaffold with CLI',
-          code: 'astryx theme',
+          label: 'Browse, then copy a theme in as editable source',
+          code: 'astryx theme list\nastryx theme add stone',
+        },
+        {
+          type: 'prose',
+          text: 'For an annotated map of the whole surface — every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference — run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup).',
         },
       ],
     },
@@ -275,14 +279,17 @@ const brandTheme = defineTheme({
     base: { borderRadius: '20px', padding: '24px' },
   },
   button: {
-    base: { borderRadius: '9999px', textTransform: 'uppercase' },
+    base: {
+      borderRadius: '9999px',
+      textTransform: 'uppercase',
+      // Some components have public CSS vars for properties that don't map
+      // to standard CSS. Set these directly. Take the name from
+      // \`astryx component <Name>\` — a var the component does not define
+      // compiles to CSS that never applies.
+      '--button-focus-offset': '3px',
+    },
     'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },
   },
-  // Some components have public CSS vars for properties that don't map
-  // to standard CSS. Set these directly.
-  button: {
-    base: { '--button-press-scale': 'scale(0.95)' },
-  },
 }`,
         },
         {
@@ -410,6 +417,10 @@ import './themes/ocean.css';
   <App />
 </Theme>`,
         },
+        {
+          type: 'prose',
+          text: 'The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add — the built CSS only sets font-family, so loading the font files stays the app\'s job. See `astryx docs typography` for the full recipe.',
+        },
       ],
     },
     {

package/assets/docs/theme.doc.zh.mjs

@@ -8,7 +8,7 @@ export const docsZh = {
     { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
     { section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
     { section: 'Theme Props', title: 'Theme 属性', content: [null] },
-    { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
+    { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题开始，或用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts：带注释的完整参考，涵盖每个 defineTheme 字段、令牌族和覆盖语法，并标明打印各自参考的 CLI 命令。' }] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
     { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },

package/assets/docs/typography.doc.mjs

@@ -44,6 +44,44 @@ export const docs = {
       ],
     },
 
+    // ── Loading Custom Fonts ────────────────────────────────────────────────
+    {
+      title: 'Loading Custom Fonts',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx never loads font files. defineTheme and the built CSS only set font-family — naming a webfont (Fraunces, JetBrains Mono, …) makes every browser look for it, and quietly fall back when the app has not loaded it. `astryx theme build` warns when a theme names families that are neither CSS generics nor common system fonts and prints the snippet to add; loading the font is always the app\'s job.',
+        },
+        {
+          type: 'code',
+          lang: 'html',
+          label: 'Google Fonts — add to your document <head>',
+          code: `<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Fraunces:wght@400;600;700&family=JetBrains+Mono&display=swap"
+/>`,
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Self-hosted — one @font-face per family and weight',
+          code: `@font-face {
+  font-family: 'Fraunces';
+  src: url('/fonts/fraunces.woff2') format('woff2');
+  font-weight: 400 700; /* variable-font range, or one weight per file */
+  font-display: swap; /* fallback text stays visible while the font loads */
+}`,
+        },
+        {
+          type: 'prose',
+          text: "Always pair a webfont with a real fallback stack — metric-similar system fonts plus a generic — so text stays readable before the font loads and wherever it never does: defineTheme({typography: {heading: {family: 'Fraunces', fallbacks: 'Georgia, serif'}}}).",
+        },
+      ],
+    },
+
     // ── Font Sizes ──────────────────────────────────────────────────────────
     {
       title: 'Font Sizes',

package/assets/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleCustomContent.doc.mjs

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ChatMessageBubble',
+  name: 'ChatMessageBubble — Custom Content',
+  displayName: 'ChatMessageBubble — Custom Content',
+  description: 'Custom in-message content aligned to the bubble text column. An artifact card is wrapped in a ghost bubble with width="100%", so its left edge matches the bubble text and it spans the full message column instead of the default bubble width cap; the timestamp rides the bubble metadata slot.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Chat', 'ChatMessage', 'ChatMessageBubble', 'ChatMessageMetadata', 'ClickableCard', 'Text', 'Timestamp'],
+};

package/assets/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleCustomContent.tsx

@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+  ChatMessageList,
+  ChatMessage,
+  ChatMessageBubble,
+  ChatMessageMetadata,
+} from '@astryxdesign/core/Chat';
+import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {Text} from '@astryxdesign/core/Text';
+import {Timestamp} from '@astryxdesign/core/Timestamp';
+
+export default function ChatMessageBubbleCustomContent() {
+  return (
+    <ChatMessageList style={{maxWidth: 520}}>
+      <ChatMessage sender="user">
+        <ChatMessageBubble>Can you pull up the Q3 report?</ChatMessageBubble>
+      </ChatMessage>
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble name="Navi">
+          Sure, here is the artifact from last quarter.
+        </ChatMessageBubble>
+        {/* A ghost bubble aligns custom content with the bubble text column;
+            width="100%" spans the full message column instead of the default
+            bubble width cap. Metadata rides the bubble's metadata slot. */}
+        <ChatMessageBubble
+          variant="ghost"
+          width="100%"
+          metadata={
+            <ChatMessageMetadata
+              timestamp={
+                <Timestamp value="2026-04-28T09:45:00" format="time" />
+              }
+              footer={
+                <Text type="supporting" color="secondary">
+                  Claude Opus 4.6
+                </Text>
+              }
+            />
+          }>
+          <ClickableCard label="Open Q3 performance report" onClick={() => {}}>
+            <Text type="body" weight="semibold" display="block">
+              Q3 Performance Report
+            </Text>
+            <Text type="supporting" color="secondary" display="block">
+              12 pages · updated 2 days ago
+            </Text>
+          </ClickableCard>
+        </ChatMessageBubble>
+      </ChatMessage>
+    </ChatMessageList>
+  );
+}

package/assets/templates/pages/ai-chat/page.tsx

@@ -70,9 +70,6 @@ const chatLayout: CSSProperties = {
   flex: 1,
   minHeight: 0,
 };
-const artifactCard: CSSProperties = {
-  marginBlockStart: 'var(--spacing-2)',
-};
 const artifactScroll: CSSProperties = {
   flex: 1,
   overflowY: 'auto',
@@ -250,8 +247,7 @@ function ArtifactCard({onOpen}: {onOpen: () => void}) {
       onClick={onOpen}
       variant="muted"
       padding={3}
-      maxWidth={360}
-      style={artifactCard}>
+      maxWidth={360}>
       <HStack gap={3} vAlign="center" width="100%">
         <Icon icon={DocumentTextIcon} size="md" color="secondary" />
         <StackItem size="fill">
@@ -614,15 +610,24 @@ The fix is to catch \`TokenExpiredError\` specifically and attempt a refresh bef
                           {`I've drafted a design doc covering the problem, the fix, and the test matrix — pulling straight from the changes we just made.\n\nOpen the document below to review it. Want me to expand any section?`}
                         </Markdown>
                       </ChatMessageBubble>
-                      <ArtifactCard onOpen={openArtifact} />
-                      <ChatMessageMetadata
-                        timestamp={
-                          <Timestamp
-                            value="2026-04-29T10:18:40"
-                            format="time"
+                      {/* Ghost + width="100%" aligns the card with the
+                          bubble text column and spans the full message
+                          column; metadata rides the bubble slot. */}
+                      <ChatMessageBubble
+                        variant="ghost"
+                        width="100%"
+                        metadata={
+                          <ChatMessageMetadata
+                            timestamp={
+                              <Timestamp
+                                value="2026-04-29T10:18:40"
+                                format="time"
+                              />
+                            }
                           />
-                        }
-                      />
+                        }>
+                        <ArtifactCard onOpen={openArtifact} />
+                      </ChatMessageBubble>
                     </ChatMessage>
 
                     {/* User follow-up */}

package/assets/templates/themes/butter/butterTheme.ts

@@ -202,8 +202,11 @@ export const butterTheme = defineTheme({
     // Radius
     //   --radius-element drives buttons, badges, inputs — 8px per design
     //   --radius-container drives cards, banners, popovers — 12px per design
+    //   --radius-none and --radius-full are always fixed and must never be
+    //   scaled by a theme (see defineTheme's radius config docs) — 0 and
+    //   9999px respectively, matching @astryxdesign/core's own defaults.
     // =========================================================================
-    '--radius-none': '0.125rem',
+    '--radius-none': '0px',
     '--radius-inner': '0.375rem',
     '--radius-element': '0.5rem', // 8px
     '--radius-container': '0.75rem', // 12px

package/assets/templates/themes/chocolate/chocolateTheme.ts

@@ -176,8 +176,11 @@ export const chocolateTheme = defineTheme({
 
     // =========================================================================
     // Radius — soft and rounded
+    //   --radius-none and --radius-full are always fixed and must never be
+    //   scaled by a theme (see defineTheme's radius config docs) — 0 and
+    //   9999px respectively, matching @astryxdesign/core's own defaults.
     // =========================================================================
-    '--radius-none': '0.125rem',
+    '--radius-none': '0px',
     '--radius-inner': '0.375rem',
     '--radius-element': '0.625rem',
     '--radius-container': '0.75rem',

package/assets/templates/themes/gothic/gothicTheme.ts

@@ -201,8 +201,11 @@ export const gothicTheme = defineTheme({
 
     // =========================================================================
     // Radius — subtle rounding (original gothic)
+    //   --radius-none and --radius-full are always fixed and must never be
+    //   scaled by a theme (see defineTheme's radius config docs) — 0 and
+    //   9999px respectively, matching @astryxdesign/core's own defaults.
     // =========================================================================
-    '--radius-none': '0.125rem',
+    '--radius-none': '0px',
     '--radius-inner': '0.25rem',
     '--radius-element': '0.5rem',
     '--radius-container': '0.75rem',

package/assets/templates/themes/stone/stoneTheme.ts

@@ -219,8 +219,11 @@ export const stoneTheme = defineTheme({
 
     // =========================================================================
     // Radius — clean and subtle
+    //   --radius-none and --radius-full are always fixed and must never be
+    //   scaled by a theme (see defineTheme's radius config docs) — 0 and
+    //   9999px respectively, matching @astryxdesign/core's own defaults.
     // =========================================================================
-    '--radius-none': '0.125rem',
+    '--radius-none': '0px',
     '--radius-inner': '0.25rem',
     '--radius-element': '0.5rem',
     '--radius-container': '0.75rem',