npm - @astryxdesign/cli - Versions diffs - 0.4.1 → 0.4.2-canary.356d2f9 - Mend

@astryxdesign/cli 0.4.1 → 0.4.2-canary.356d2f9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/CHANGELOG.md +34 -0
package/README.md +1 -0
package/api/init/init.doc.mjs +2 -2
package/api/init/init.test.mjs +19 -2
package/api/init/init.type.d.mts +9 -1
package/api/init/init.type.mjs +3 -1
package/api/init/run/run.mjs +36 -6
package/api/theme/add/add.mjs +2 -13
package/api/theme/build/build.font-warning.test.mjs +161 -0
package/api/theme/build/build.mjs +95 -26
package/api/theme/build/build.test.mjs +227 -0
package/api/theme/build/font-warning.d.mts +26 -0
package/api/theme/build/font-warning.mjs +214 -0
package/api/theme/build/font-warning.test.mjs +242 -0
package/api/theme/template/template.d.mts +21 -0
package/api/theme/template/template.mjs +69 -0
package/api/theme/template/template.test.mjs +82 -0
package/api/theme/theme.d.mts +1 -0
package/api/theme/theme.mjs +1 -0
package/api/theme/theme.type.d.mts +13 -0
package/api/theme/theme.type.mjs +11 -1
package/api/theme/themeTemplate.doc.d.mts +11 -0
package/api/theme/themeTemplate.doc.mjs +64 -0
package/assets/docs/getting-started.doc.mjs +11 -1
package/assets/docs/theme.doc.dense.mjs +2 -2
package/assets/docs/theme.doc.mjs +26 -10
package/assets/docs/theme.doc.zh.mjs +1 -1
package/assets/docs/typography.doc.mjs +38 -0
package/assets/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleCustomContent.doc.mjs +13 -0
package/assets/templates/blocks/components/ChatMessageBubble/ChatMessageBubbleCustomContent.tsx +55 -0
package/assets/templates/pages/ai-chat/page.tsx +18 -13
package/assets/templates/themes/butter/butterTheme.ts +4 -1
package/assets/templates/themes/chocolate/chocolateTheme.ts +4 -1
package/assets/templates/themes/gothic/gothicTheme.ts +4 -1
package/assets/templates/themes/stone/stoneTheme.ts +4 -1
package/assets/theme.template.ts +322 -0
package/authoring/doctypes/base/type.ts +9 -1
package/authoring/doctypes/component/component.doc.mjs +1 -1
package/clients/cli/commands/build-theme.font-warning.test.mjs +138 -0
package/clients/cli/commands/build-theme.mjs +50 -0
package/clients/cli/commands/init.behavior.test.mjs +13 -2
package/clients/cli/commands/theme-template.behavior.test.mjs +85 -0
package/clients/cli/commands/theme-template.doc.mjs +42 -0
package/clients/cli/commands/theme.doc.mjs +2 -2
package/clients/cli/index.mjs +1 -0
package/clients/cli/lib/manifest.mjs +2 -0
package/foundation/agent-docs/agent-docs.mjs +1 -1
package/foundation/response/response-types.doc.mjs +5 -0
package/foundation/text/copyright-header.d.mts +11 -0
package/foundation/text/copyright-header.mjs +35 -0
package/foundation/text/copyright-header.test.mjs +58 -0
package/package.json +9 -9

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

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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',

package/assets/theme.template.ts ADDED Viewed

@@ -0,0 +1,322 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * Astryx theme template — every `defineTheme` field, with a note on what it
+ * does and when to reach for it.
+ *
+ * Only `name` is required. Delete what you do not need: the values here are
+ * placeholders that reproduce the built-in defaults, so a field you leave
+ * untouched changes nothing.
+ *
+ * Each section names the CLI command that prints the authoritative reference
+ * for it. These comments are a map; the CLI is the territory — it reads the
+ * same source the components do.  `astryx docs` lists every topic.
+ *
+ * ═══════════════════════════════════════════════════════════════════════
+ * HOW A THEME IS CONSUMED
+ * ═══════════════════════════════════════════════════════════════════════
+ *
+ * 1. WRAP THE APP. A theme does nothing until it is provided.
+ *
+ *      import {Theme} from '@astryxdesign/core';
+ *      import {myTheme} from './theme';
+ *
+ *      <Theme theme={myTheme} mode="system">   // 'system' | 'light' | 'dark'
+ *        <App />
+ *      </Theme>
+ *
+ *    `system` follows the OS. Nest a second `<Theme>` to give one region its
+ *    own theme or mode — a dark sidebar inside a light page.
+ *
+ * 2. SHIP THE FONTS YOU NAME. Astryx sets the `--font-family-*` tokens; it
+ *    never loads a font file, so use whatever typeface the design needs and
+ *    load it yourself. Either add it to your app's <head>:
+ *
+ *      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ *      <link rel="stylesheet"
+ *            href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap" />
+ *
+ *    or self-host it in your global CSS:
+ *
+ *      @font-face {
+ *        font-family: 'Inter';
+ *        src: url('/fonts/Inter.woff2') format('woff2');
+ *        font-weight: 100 900;
+ *        font-display: swap;
+ *      }
+ *
+ *    Always give `fallbacks` as well. A named family with no file loads
+ *    nothing and warns about nothing — the fallback silently becomes your
+ *    theme.
+ *
+ * 3. BUILD IT FOR PRODUCTION.
+ *
+ *      astryx theme build src/theme.ts
+ *
+ *    writes `<name>.css` (tokens, component overrides and prose styles in
+ *    `@scope` rules), `<name>.js` (the theme with `__built: true` and
+ *    pre-resolved values), `<name>.d.ts`, and `<name>.variants.d.ts` when the
+ *    theme adds custom prop values. Import the module and the CSS together:
+ *
+ *      import {myThemeTheme} from './theme/my-theme';
+ *      import './theme/my-theme.css';
+ *
+ *    Unbuilt, `<Theme>` injects a <style> tag at hydration instead — fine for
+ *    dev and client-only apps, but under SSR the component overrides flash on
+ *    hydration. Build for Next.js and Remix. Run the build after every edit:
+ *    it also validates the theme and regenerates the types for custom
+ *    variants.
+ *
+ * 4. LOOK AT IT IN BOTH COLOUR MODES before you ship, including the states you
+ *    did not write. Full guide: `astryx docs theme`.
+ *
+ * SYNC: this template mirrors the theme system. When you change one of these,
+ * update it here — scripts/check-theme-template.test.mjs fails when they drift:
+ * - /packages/core/src/theme/defineTheme.ts     (the fields)
+ * - /packages/core/src/theme/tokens.stylex.ts   (the token families)
+ * - /packages/core/src/theme/expandColorScale.ts
+ * - /packages/core/src/theme/expandTypeScale.ts
+ * - /packages/core/src/theme/expandRadiusScale.ts
+ * - /packages/core/src/theme/expandMotionScale.ts
+ */
+import {defineTheme} from '@astryxdesign/core/theme';
+// import {dracula} from '@astryxdesign/core/theme/syntax';
+// import {neutralTheme} from '@astryxdesign/theme-neutral';
+export const myTheme = defineTheme({
+  /** Required. Becomes the `data-astryx-theme` attribute and the registry key. */
+  name: 'my-theme',
+  /**
+   * Start from another theme instead of the defaults. Tokens are copied then
+   * overridden, `components` deep-merge, `icons` shallow-merge — but the scale
+   * configs below REPLACE the base's rather than merging, because they are
+   * inputs to a generator, not values.
+   *
+   * Reference: `astryx theme list` (themes you can install and extend).
+   */
+  // extends: neutralTheme,
+  // ───────────────────────────────────────────────────────────────────────
+  // Scale configs — a few parameters generate a whole family of tokens.
+  // Reach for these first. They keep a theme internally consistent and cover
+  // far more ground than you would hand-write.
+  // ───────────────────────────────────────────────────────────────────────
+  /**
+   * Generates the neutral ramp and the accent tokens from one seed colour
+   * using the HCT perceptual model: surfaces, text, icons, borders, muted
+   * fills, hover and pressed overlays — light and dark both.
+   *
+   *   accent        seed hex; omit to keep the default accent and re-tone only
+   *                 the neutrals
+   *   neutralStyle  'warm' | 'cool' | 'neutral' — the temperature of the greys
+   *   contrast      'standard' | 'high' — 'high' widens the text/surface tone
+   *                 gap, for dense data UI or bright and clinical screens
+   *
+   * Whatever seed you pass, generated text holds >= 4.5:1 against its surface
+   * and --color-border-emphasized >= 3:1. Two limits on that guarantee:
+   *
+   *   - It covers what this config generates. Write one side of a pair by hand
+   *     in `tokens` below — an accent without its --color-on-accent, a surface
+   *     without its text — and you own the contrast for that pair.
+   *   - Status colours (success, warning, error) and the categorical data hues
+   *     are not derived from the accent. They keep their defaults, which are
+   *     tuned for the default surfaces; check them against yours.
+   *
+   * Either way the check is the same: resolve the pair in BOTH modes and
+   * measure it. `useTheme()` and `resolveThemeTokens()` return the resolved
+   * values, and the rendered DOM is the final word.
+   *
+   * Reference: `astryx docs color` for what each semantic role means,
+   * `astryx docs tokens` for every colour token and its light/dark default.
+   */
+  color: {accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard'},
+  /**
+   * Type scale and the three font roles.
+   *   scale.base   body size in px; scale.ratio  step between sizes
+   *                (1.125 tight/dense · 1.2 default · 1.333 dramatic)
+   *   body / heading / code: {family, fallbacks, weight, weights}
+   *   heading inherits family and fallbacks from body when omitted; `weights`
+   *   sets per-level weight for headings 1–6.
+   *
+   * See §2 above — naming a family here does not load it.
+   *
+   * Reference: `astryx docs typography`.
+   */
+  typography: {
+    scale: {base: 16, ratio: 1.2},
+    body: {family: 'Inter', fallbacks: '-apple-system, system-ui, sans-serif'},
+    heading: {weight: 'semibold', weights: {1: 'bold', 2: 'bold'}},
+    code: {
+      family: 'Geist Mono',
+      fallbacks: '"SF Mono", ui-monospace, monospace',
+    },
+  },
+  /**
+   * Radius scale. `base` is the unit in px; `multiplier` scales every step
+   * (0 = square and brutalist, 2 = very soft). --radius-none and --radius-full
+   * are fixed and never scaled.
+   *
+   * Reference: `astryx docs shape`.
+   */
+  radius: {base: 4, multiplier: 1},
+  /**
+   * Duration scale in ms. Each of fast/medium/slow also gets a -min and -max
+   * sibling computed with `ratio` (min = base × ratio, max = base ÷ ratio), so
+   * a component can pick a longer or shorter variant of the same tempo.
+   *   Snappy {fast: 100, medium: 250} · Default {fast: 175, medium: 410, slow: 975}
+   *   Cinematic {fast: 200, medium: 500, slow: 1200}
+   * `easing` overrides --ease-standard.
+   *
+   * Reference: `astryx docs motion`.
+   */
+  motion: {fast: 175, medium: 410, slow: 975, ratio: 0.75},
+  // ───────────────────────────────────────────────────────────────────────
+  // tokens — explicit overrides, which beat anything the scales generated.
+  // A string applies to both colour modes; a [light, dark] tuple compiles to
+  // CSS light-dark(). List only what you want to change.
+  //
+  // `astryx docs tokens` PRINTS THE WHOLE TABLE — every token with its light
+  // and dark default. Read it before hand-writing colours: most of what you
+  // want already has a semantic name, and the defaults tell you what you are
+  // moving away from.
+  //
+  // The families, so you know what exists:
+  //   --color-*        accent, on-accent · background-{body,surface,card,popover,
+  //                    muted,inverted} · text-* · icon-* · border,
+  //                    border-emphasized · overlay{,-hover,-pressed} ·
+  //                    success/warning/error (+ -muted, on-*) · skeleton, track,
+  //                    shadow, tint-hover · categorical {blue,cyan,gray,green,
+  //                    orange,pink,purple,red,teal,yellow} ×
+  //                    {background,border,icon,text}
+  //   --spacing-*      0 · 0-5 · 1 … 12
+  //   --size-element-* sm · md · lg (control heights)
+  //   --focus-outline-* width · style · color · offset
+  //   --border-width   hairline thickness shared by bordered surfaces
+  //   --radius-*       none · inner · element · container · page · chat · full
+  //   --shadow-*       low/med/high + inset-{hover,selected,success,warning,error}
+  //   --duration-*     {fast,medium,slow} × {-min, base, -max}
+  //   --ease-standard
+  //   --font-family-*  body · heading · code
+  //   --font-size-*    4xs … 5xl
+  //   --font-weight-*  normal · medium · semibold · bold
+  //   --text-*         {heading-1…6, body, large, label, code, supporting,
+  //                    display-1…3} × {-size, -weight, -leading}
+  //   --color-syntax-* code highlighting · --color-data-* charts
+  // ───────────────────────────────────────────────────────────────────────
+  tokens: {
+    '--color-accent': ['#0064E0', '#2694FE'],
+    // Changing an accent means owning its on-colour: this is the label that
+    // sits on top of the fill above, in each mode.
+    '--color-on-accent': ['#FFFFFF', '#FFFFFF'],
+    '--color-background-body': ['#F1F4F7', '#111112'],
+    '--color-background-surface': ['#FFFFFF', '#1F1F22'],
+    '--focus-outline-color': 'var(--color-accent)',
+    '--shadow-low': '0 1px 2px light-dark(#0000001A, #00000066)',
+  },
+  // ───────────────────────────────────────────────────────────────────────
+  // components — per-component CSS, emitted inside
+  // `@scope ([data-astryx-theme="my-theme"])`, so it only touches your theme.
+  //
+  // Keys are the component's stable class minus the `astryx-` prefix
+  // (`astryx-button` → `button`, `astryx-side-nav-item` → `side-nav-item`),
+  // including inner parts like `progressbar-fill`.
+  //
+  // `astryx component <Name>` IS THE REFERENCE HERE. It prints that
+  // component's theming targets, the visual props and states you can key on,
+  // its public CSS variables with defaults, and which standard CSS properties
+  // it expands. `astryx component --list` names every component, and
+  // `astryx docs styling` covers the escape hatches outside a theme.
+  //
+  // Style-key forms:
+  //   'base'                    every instance
+  //   'variant:ghost'           one prop value (any visual prop, not just variant)
+  //   'variant:ghost+size:sm'   intersection of two
+  //   'checked'                 a state the component reflects
+  //   ':hover' / ':focus-visible' / ':disabled' — nested inside any of the above
+  //
+  // Write ordinary CSS properties: `borderRadius` and `padding` expand into
+  // the component's internal vars for you, concentric radius math included.
+  // Set a public CSS var directly when no standard property reaches it — take
+  // the name from `astryx component <Name>`, since a var no component defines
+  // compiles to CSS that never applies. Never set a private `--_`-prefixed
+  // var; the build rejects it.
+  // ───────────────────────────────────────────────────────────────────────
+  components: {
+    button: {
+      base: {
+        borderRadius: 'var(--radius-full)',
+        fontWeight: 'var(--font-weight-semibold)',
+        // A public var from `astryx component Button` — no CSS-property
+        // equivalent exists for it.
+        '--button-focus-offset': '2px',
+        // Interaction states live inside the same block.
+        ':hover': {transform: 'translateY(-1px)'},
+        ':active': {transform: 'translateY(0)'},
+      },
+      'variant:ghost': {borderWidth: '1px', borderStyle: 'solid'},
+      'variant:destructive+size:sm': {letterSpacing: '0.02em'},
+      // A value that is not built in becomes a NEW variant: `astryx theme
+      // build` writes the module augmentation, so <Button variant="quiet" />
+      // typechecks wherever this theme is active. Add one only where the
+      // product will render it — an unused variant is invisible work.
+      'variant:quiet': {
+        backgroundColor: 'var(--color-background-muted)',
+        color: 'var(--color-text-secondary)',
+      },
+    },
+    // Container components take `padding` too; it expands to their layout tokens.
+    card: {
+      base: {
+        borderRadius: 'var(--radius-container)',
+        padding: 'var(--spacing-6)',
+      },
+    },
+    // The same mechanism adds custom Text types: <Text type="hero" />.
+    text: {'type:hero': {fontSize: 'var(--font-size-4xl)', lineHeight: '1.05'}},
+  },
+  // ───────────────────────────────────────────────────────────────────────
+  // Everything below takes React values, so it needs a .tsx file or an
+  // imported module. Commented out for that reason.
+  // ───────────────────────────────────────────────────────────────────────
+  /**
+   * Swap the artwork behind semantic icon names — every component that asks
+   * for `check`, `close`, `chevron-down` gets yours.
+   * Reference: `astryx docs icons` lists the names.
+   */
+  // icons: {check: <MyCheck />, close: <MyClose />},
+  /**
+   * Replace the small components that DRAW control state — the checkbox box,
+   * the radio dot, the mark on a chosen option — by indicator name rather than
+   * per call site. Replacing `check` re-skins every single-selection mark in
+   * the app at once.
+   * Reference: `astryx component Indicator`.
+   */
+  // indicators: {check: RadioIndicator},
+  /**
+   * Code highlighting: sets the --color-syntax-* tokens. Presets live in
+   * `@astryxdesign/core/theme/syntax`.
+   */
+  // syntax: dracula,
+  /**
+   * Content sitting on an inverted surface — a dark toast in light mode, a
+   * light popover in dark mode. Same shape as the theme itself (tokens and
+   * components). Sensible values are generated if you say nothing, so override
+   * only where your palette needs it.
+   * Reference: `astryx component MediaTheme`, which reads these.
+   */
+  // onDark: {tokens: {'--color-accent': '#90CAF9'}, components: {button: {'variant:ghost': {borderWidth: '1px'}}}},
+  // onLight: {tokens: {'--color-accent': '#0B5FCC'}},
+});

package/authoring/doctypes/base/type.ts CHANGED Viewed

@@ -117,6 +117,14 @@ export interface ComponentPlaygroundConfig {
    *  the component is visible on load and knobs stay usable, whereas a real
    *  top-layer modal makes the rest of the page inert (#3657). */
   overlay?: boolean;
+  /** The component reads AppShell mobile context and renders nothing
+   *  without it (e.g. `MobileNavToggle` returns null unless the context
+   *  reports an enabled mobile viewport — the default value outside
+   *  AppShell never does). The interactive preview provides a simulated
+   *  mobile AppShell context so the stage is not an empty box, keeps the
+   *  drawer open state interactive, and notes the simulation under the
+   *  rendered component (#4983). */
+  appShellMobile?: boolean;
   /** Required parent wrapper for sub-components that depend on a parent
    *  context provider (e.g. `Tab` calls `useTabListContext()` and throws
    *  standalone). The preview wraps the component in this parent before
@@ -339,7 +347,7 @@ export interface ComponentThemingTarget {
  * ```
  */
 export interface ComponentThemingVar {
-  /** CSS custom property name, e.g. '--_card-radius' or '--button-press-scale' */
+  /** CSS custom property name, e.g. '--_card-radius' or '--button-focus-offset' */
   name: string;
   /** What this var controls */
   description: string;

package/authoring/doctypes/component/component.doc.mjs CHANGED Viewed

@@ -146,7 +146,7 @@ export const doc = {
       name: 'playground',
       type: 'ComponentPlaygroundConfig',
       description:
-        'Interactive-preview config: initial prop `defaults`, `overlay` for modal-only components, and a `wrapper` for context-dependent sub-components.',
+        'Interactive-preview config: initial prop `defaults`, `overlay` for modal-only components, `appShellMobile` for components gated on AppShell mobile context, and a `wrapper` for context-dependent sub-components.',
     },
     {
       name: 'props',