@astryxdesign/cli 0.3.0-canary.fbc60c5 → 0.3.0-canary.fcbc342

package/assets/templates/pages/login/page.tsx

@@ -17,7 +17,6 @@ import {CubeIcon} from '@heroicons/react/24/outline';
 const pageStyle: CSSProperties = {
   minHeight: '100%',
   backgroundColor: 'var(--color-background-body)',
-  padding: 'var(--spacing-6)',
 };
 // Cap the column at 400px but let it shrink to fit narrow screens (Stack
 // has no maxWidth prop, so it's set here).
@@ -43,7 +42,7 @@ export default function LoginPage() {
   };
 
   return (
-    <Center axis="both" style={pageStyle}>
+    <Center axis="both" padding={6} style={pageStyle}>
       <VStack gap={4} hAlign="center" style={contentStyle}>
         {/* Logo */}
         <VStack gap={2} hAlign="center">

package/assets/templates/pages/login-card/page.tsx

@@ -58,7 +58,6 @@ const GoogleIcon = (props: React.SVGProps<SVGSVGElement>) => (
 const pageStyle: CSSProperties = {
   minHeight: '100%',
   backgroundColor: 'var(--color-background-body)',
-  padding: 'var(--spacing-6)',
 };
 // Cap the column at 400px but let it shrink to fit narrow screens (Stack
 // has no maxWidth prop, so it's set here).
@@ -87,7 +86,7 @@ export default function LoginSimple() {
   };
 
   return (
-    <Center axis="both" style={pageStyle}>
+    <Center axis="both" padding={6} style={pageStyle}>
       <VStack gap={4} hAlign="center" style={contentStyle}>
         {/* Logo */}
         <VStack gap={2} hAlign="center">

package/assets/templates/pages/login-split/page.tsx

@@ -18,11 +18,11 @@ import {Link} from '@astryxdesign/core/Link';
 import {Divider} from '@astryxdesign/core/Divider';
 
 const COVER_IMAGE_URL =
-  'https://lookaside.facebook.com/assets/astryx/light-working-vertical-1.png';
+  '/template-assets/light-working-vertical-1.png';
 const APPLE_LOGO_URL =
-  'https://lookaside.facebook.com/assets/astryx/AppleLogo.png';
+  '/template-assets/AppleLogo.png';
 const GOOGLE_LOGO_URL =
-  'https://lookaside.facebook.com/assets/astryx/GoogleLogo.png';
+  '/template-assets/GoogleLogo.png';
 
 // Grid emits minmax(MIN, 1fr) where MIN is a hard floor, so MIN plus the
 // grid inset and page padding must fit the narrowest phone or the column is
@@ -33,11 +33,10 @@ const COLUMN_MIN_WIDTH = 240;
 // tightens the inset at that same point, keyed to the card width (not the
 // window) so it never desyncs.
 // minHeight:100% fills the host so the centered card never leaves an unpainted
-// band; padding keeps it off the surface edges.
+// band; Center's padding prop keeps it off the surface edges.
 const pageStyle: CSSProperties = {
   minHeight: '100%',
   backgroundColor: 'var(--color-background-body)',
-  padding: 'var(--spacing-6)',
 };
 const cardWrap: CSSProperties = {
   width: '100%',
@@ -98,7 +97,7 @@ export default function LoginTwoColumn() {
   };
 
   return (
-    <Center axis="both" style={pageStyle}>
+    <Center axis="both" padding={6} style={pageStyle}>
       <style>{LOGIN_SPLIT_CSS}</style>
       <VStack gap={4} width="100%">
         <div style={cardWrap}>

package/assets/templates/pages/login-sso/page.tsx

@@ -20,14 +20,13 @@ import {Avatar} from '@astryxdesign/core/Avatar';
 // Styles
 // ---------------------------------------------------------------------------
 
-const BG_URL = 'https://lookaside.facebook.com/assets/astryx/building.png';
+const BG_URL = '/template-assets/building.png';
 
 const pageStyle: CSSProperties = {
   minHeight: '100%',
   backgroundImage: `url(${BG_URL})`,
   backgroundSize: 'cover',
   backgroundPosition: 'center',
-  padding: 'var(--spacing-6)',
 };
 
 type SSOProvider = {
@@ -98,7 +97,7 @@ export default function LoginSSO() {
   };
 
   return (
-    <Center axis="both" style={pageStyle}>
+    <Center axis="both" padding={6} style={pageStyle}>
       <Card padding={8} width="100%" maxWidth={400}>
         <VStack gap={4} hAlign="stretch">
           {/* ── Step 1: Email entry ── */}

package/assets/templates/pages/mixed-gallery/page.tsx

@@ -66,23 +66,23 @@ interface GalleryImage {
 // All landscape photos so the uniform 3:2 / 3:1 tiles crop cleanly.
 const IMAGES: GalleryImage[] = [
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-1.png',
+    src: '/template-assets/illustrative-horizontal-1.png',
     title: 'Going places',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-home-horizontal-1.png',
+    src: '/template-assets/light-home-horizontal-1.png',
     title: 'Making memories',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-lifestyle-horizontal-1.png',
+    src: '/template-assets/light-lifestyle-horizontal-1.png',
     title: 'Being free',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-working-horizontal-2.png',
+    src: '/template-assets/light-working-horizontal-2.png',
     title: 'Getting it done',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+    src: '/template-assets/light-scene-horizontal-1.png',
     title: 'Finding calm',
   },
 ];

package/assets/templates/pages/payment-form/page.tsx

@@ -111,13 +111,13 @@ const US_STATES = [
 // docsite; the CLI swaps these for an inline placeholder on scaffold).
 const ITEM_IMAGES: Record<string, {src: string}> = {
   '1': {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-product-1.png',
+    src: '/template-assets/light-product-1.png',
   },
   '2': {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-product-4.png',
+    src: '/template-assets/light-product-4.png',
   },
   '3': {
-    src: 'https://lookaside.facebook.com/assets/astryx/light-product-5.png',
+    src: '/template-assets/light-product-5.png',
   },
 };
 

package/assets/templates/pages/product-detail/page.tsx

@@ -74,13 +74,13 @@ function StarRating({rating, count}: {rating: number; count: number}) {
 // ─── Image URLs ─────────────────────────────────────────────────────────────
 // IMAGES[0] = fallback hero; IMAGES[1..6] = thumbnails (first is selected by default)
 const IMAGES = [
-  'https://lookaside.facebook.com/assets/astryx/light-product-1.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-1.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-2.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-3.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-4.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-5.png',
-  'https://lookaside.facebook.com/assets/astryx/light-product-3.png',
+  '/template-assets/light-product-1.png',
+  '/template-assets/light-product-1.png',
+  '/template-assets/light-product-2.png',
+  '/template-assets/light-product-3.png',
+  '/template-assets/light-product-4.png',
+  '/template-assets/light-product-5.png',
+  '/template-assets/light-product-3.png',
 ];
 
 // ─── Product Data ───────────────────────────────────────────────────────────

package/assets/templates/pages/product-gallery/page.tsx

@@ -40,7 +40,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 75.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-1.png',
+      '/template-assets/illustrative-horizontal-1.png',
   },
   {
     id: 2,
@@ -49,7 +49,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 80.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-1.png',
+      '/template-assets/illustrative-vertical-1.png',
   },
   {
     id: 3,
@@ -58,7 +58,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 75.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-3.png',
+      '/template-assets/illustrative-horizontal-3.png',
   },
   {
     id: 4,
@@ -67,7 +67,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 75.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-4.png',
+      '/template-assets/illustrative-horizontal-4.png',
   },
   {
     id: 5,
@@ -76,7 +76,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 60.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-5.png',
+      '/template-assets/illustrative-horizontal-5.png',
   },
   {
     id: 6,
@@ -85,7 +85,7 @@ const PRODUCTS: Product[] = [
       "Sometimes all it takes is one small thing to turn your whole day around. That's what good design is for.",
     price: 80.0,
     image:
-      'https://lookaside.facebook.com/assets/astryx/illustrative-horizontal-2.png',
+      '/template-assets/illustrative-horizontal-2.png',
   },
 ];
 

package/assets/templates/pages/shell-top-nav/page.tsx

@@ -158,7 +158,7 @@ export default function ShellTopNav() {
                   <MegaFeatured
                     title="The Autumn Edit"
                     description="Layering staples in warm, earthy tones."
-                    image="https://lookaside.facebook.com/assets/astryx/texture-beige-horizontal-1.png"
+                    image="/template-assets/texture-beige-horizontal-1.png"
                     imageAlt="Autumn collection lookbook"
                     linkLabel="Shop the edit"
                     linkHref="#autumn-edit"
@@ -172,7 +172,7 @@ export default function ShellTopNav() {
                   <MegaFeatured
                     title="Meet Studio Mara"
                     description="Modern tailoring, made to last."
-                    image="https://lookaside.facebook.com/assets/astryx/texture-beige-horizontal-2.png"
+                    image="/template-assets/texture-beige-horizontal-2.png"
                     imageAlt="Studio Mara lookbook"
                     linkLabel="Discover the label"
                     linkHref="#studio-mara"

package/assets/templates/pages/side-gallery/page.tsx

@@ -25,39 +25,39 @@ const imageClip = {
 
 const IMAGES = [
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-3.png',
+    src: '/template-assets/colorful-lifestyle-vertical-3.png',
     alt: 'Colorful lifestyle scene',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-horizontal-1.png',
+    src: '/template-assets/colorful-lifestyle-horizontal-1.png',
     alt: 'Colorful lifestyle horizontal',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-1.png',
+    src: '/template-assets/colorful-lifestyle-vertical-1.png',
     alt: 'Colorful lifestyle vertical',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-2.png',
+    src: '/template-assets/colorful-home-vertical-2.png',
     alt: 'Colorful home interior',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-3.png',
+    src: '/template-assets/colorful-home-vertical-3.png',
     alt: 'Colorful home scene',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-home-vertical-1.png',
+    src: '/template-assets/colorful-home-vertical-1.png',
     alt: 'Colorful home vertical',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-horizontal-2.png',
+    src: '/template-assets/colorful-lifestyle-horizontal-2.png',
     alt: 'Colorful lifestyle wide',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-2.png',
+    src: '/template-assets/colorful-lifestyle-vertical-2.png',
     alt: 'Colorful lifestyle detail',
   },
   {
-    src: 'https://lookaside.facebook.com/assets/astryx/colorful-lifestyle-vertical-4.png',
+    src: '/template-assets/colorful-lifestyle-vertical-4.png',
     alt: 'Colorful lifestyle portrait',
   },
 ];

package/assets/templates/pages/table-page-chart/page.tsx

@@ -46,37 +46,37 @@ const PRODUCTS = [
   {
     name: 'Ceremonial Matcha Latte',
     category: 'Matcha' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-1.png',
+    image: '/template-assets/matcha-product-1.png',
     price: 6,
   },
   {
     name: 'Oat Milk Cappuccino',
     category: 'Coffee' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-2.png',
+    image: '/template-assets/matcha-product-2.png',
     price: 5,
   },
   {
     name: 'Jasmine Green Tea',
     category: 'Tea' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-3.png',
+    image: '/template-assets/matcha-product-3.png',
     price: 4,
   },
   {
     name: 'Mango Matcha Smoothie',
     category: 'Smoothie' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-4.png',
+    image: '/template-assets/matcha-product-4.png',
     price: 8,
   },
   {
     name: 'Hojicha Latte',
     category: 'Specialty' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-5.png',
+    image: '/template-assets/matcha-product-5.png',
     price: 7,
   },
   {
     name: 'Iced Yuzu Matcha',
     category: 'Matcha' as ProductCategory,
-    image: 'https://lookaside.facebook.com/assets/astryx/matcha-product-6.png',
+    image: '/template-assets/matcha-product-6.png',
     price: 7,
   },
 ];

package/assets/templates/pages/theme-showcase/page.tsx

@@ -283,13 +283,13 @@ const DEFAULT_PRODUCTS: ProductSpec[] = [
 // Neutral product photos, served from the shared astryx asset CDN so the
 // scaffolded template renders real imagery without needing local public assets.
 const DEFAULT_IMAGES: Record<string, string> = {
-  watch: 'https://lookaside.facebook.com/assets/astryx/Neutral-Watch.png',
+  watch: '/template-assets/Neutral-Watch.png',
   headphones:
-    'https://lookaside.facebook.com/assets/astryx/Neutral-Headphones.png',
-  backpack: 'https://lookaside.facebook.com/assets/astryx/Neutral-Backpack.png',
-  wallet: 'https://lookaside.facebook.com/assets/astryx/Neutral-Wallet.png',
-  tumbler: 'https://lookaside.facebook.com/assets/astryx/Neutral-Tumbler.png',
-  throw_: 'https://lookaside.facebook.com/assets/astryx/Neutral-Blanket.png',
+    '/template-assets/Neutral-Headphones.png',
+  backpack: '/template-assets/Neutral-Backpack.png',
+  wallet: '/template-assets/Neutral-Wallet.png',
+  tumbler: '/template-assets/Neutral-Tumbler.png',
+  throw_: '/template-assets/Neutral-Blanket.png',
 };
 
 export interface ThemeShowcaseProps {

package/assets/templates/themes/neutral/neutralTheme.ts

@@ -323,8 +323,11 @@ export const neutralTheme = defineTheme({
 
     // =========================================================================
     // Radius — slightly larger than default (kept as-is)
+    // --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.25rem',
+    '--radius-none': '0px',
     '--radius-inner': '0.375rem',
     '--radius-element': '0.625rem',
     '--radius-container': '0.75rem',

package/authoring/codemod/codemod.doc.mjs

@@ -42,7 +42,7 @@ export const doc = {
       name: 'fileExtensions',
       type: 'string[]',
       description:
-        'File extensions this codemod applies to. Code codemods only — a ' +
+        'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
       example: "['.tsx', '.ts']",
     },
@@ -140,7 +140,7 @@ export const doc = {
       type: 'prose',
       text:
         "The config-codemod variant (type: 'config') carries the same fields " +
-        'as a code codemod except fileExtensions — it always targets the ' +
+        'as a code codemod except fileExtensions: it always targets the ' +
         'astryx.config.* file rather than a set of source files.',
     },
     {

package/authoring/config/config.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',
-      description: 'Unstable features — may change without a breaking bump.',
+      description: 'Unstable features; may change without a breaking bump.',
       fields: [
         {
           name: 'experimental.xle.components',

package/authoring/doctypes/base/type.ts

@@ -260,6 +260,8 @@ export interface ComponentSlotElement {
  * { property: 'padding', vars: ['--_card-padding'] },
  * ```
  */
+// SYNC: apps/docsite/scripts/generate-data.mjs (interface DerivedVar) — see the
+// note on ComponentThemingTarget below.
 export interface ComponentThemingDerivedVar {
   /** The standard CSS property name (camelCase) that theme authors write.
    *  e.g. `'borderRadius'`, `'padding'`, `'paddingBlock'` */
@@ -270,6 +272,12 @@ export interface ComponentThemingDerivedVar {
   /** Named expansion strategy instead of specific vars.
    *  `'container'` — expands padding to 7 container layout tokens. */
   expand?: 'container';
+  /** Emit only the internal `vars`, dropping the source property from the
+   *  generated rule. Use when the class-carrying element must not receive the
+   *  standard property itself — the value reaches a child through the var
+   *  (e.g. TextArea's flush wrapper drives the inner textarea's inline
+   *  padding). Without this, the property is emitted alongside the var. */
+  replaces?: boolean;
 }
 
 /**
@@ -285,6 +293,10 @@ export interface ComponentThemingDerivedVar {
  * {className: 'astryx-card'}
  * ```
  */
+// SYNC: When adding a field here, add it to the docsite's generated-registry
+// copy too — apps/docsite/scripts/generate-data.mjs (interface ThemingTarget).
+// `next build` type-checks the emitted componentRegistry.ts against that copy,
+// so a field present in a .doc.mjs but missing there fails the docsite build.
 export interface ComponentThemingTarget {
   /** The stable CSS class name rendered by the component.
    *  Always starts with `astryx-`.
@@ -304,6 +316,15 @@ export interface ComponentThemingTarget {
    *  `[data-checked="checked"]`. Legacy state classes are still emitted for
    *  compatibility. Omit if the element has no state-driven selectors. */
   states?: string[];
+  /** Set when this target has been RENAMED and this entry is the old name.
+   *  The component still emits the class (via `themeProps`'s `legacyNames`),
+   *  so existing themes keep working, but the docsite should steer readers to
+   *  the replacement. The value is the class name that supersedes this one,
+   *  without the `astryx-` prefix — e.g. `"checkbox-indicator"`.
+   *
+   *  A theme target is public API; renaming one without this is a silent
+   *  break for every theme styling it. */
+  deprecatedFor?: string;
 }
 
 /**

package/authoring/doctypes/command/command.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'CommandDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a CLI command — the terminal binding of an operation. A command ' +
+    'The doc-type for a CLI command: the terminal binding of an operation. A command ' +
     'is not its own behavior; it is a FunctionDoc exposed on the CLI, referenced via `fn`, ' +
     'carrying only CLI-surface facts (args, flags, subcommands, examples, exit codes). ' +
     'A `defineCommand` converter turns it into Commander config + `--help`.',
@@ -231,7 +231,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn` — the function does not know it has a CLI.',
+      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn`; the function does not know it has a CLI.',
     },
     {
       type: 'prose',

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

@@ -50,7 +50,7 @@ export const doc = {
       name: 'hiddenComponents',
       type: 'string[]',
       description:
-        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable — agents and tooling can still discover them via source.',
+        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source.',
     },
     {
       name: 'hidden',
@@ -104,7 +104,7 @@ export const doc = {
           name: 'theming.derived',
           type: 'ComponentThemingDerivedVar[]',
           description:
-            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority — earlier entries emit first.',
+            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first.',
         },
       ],
     },
@@ -170,7 +170,7 @@ export const doc = {
       name: 'description',
       type: 'string',
       description:
-        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description — they derive their summary from `usage`.",
+        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description; they derive their summary from `usage`.",
     },
   ],
   examples: [
@@ -187,7 +187,7 @@ export const docs = {
       'A Switch toggles a single setting on or off. Use it for instant, binary preferences that apply immediately without a submit step.',
     bestPractices: [
       {guidance: true, description: 'Apply the change immediately when toggled.'},
-      {guidance: false, description: 'Use a Switch for actions that need confirmation — prefer a Checkbox in a form.'},
+      {guidance: false, description: 'Use a Switch for actions that need confirmation; prefer a Checkbox in a form.'},
     ],
   },
   props: [
@@ -226,9 +226,9 @@ export const docs = {
       type: 'list',
       style: 'unordered',
       items: [
-        'SingleComponentDoc — one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
-        'MultiComponentDoc — a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
-        'SubComponentDoc — a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
+        'SingleComponentDoc: one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
+        'MultiComponentDoc: a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
+        'SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
       ],
     },
     {

package/authoring/doctypes/enum/enum.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'EnumDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a closed vocabulary — a fixed set of literal values such as ' +
+    'The doc-type for a closed vocabulary: a fixed set of literal values such as ' +
     'error codes or response-type discriminants. Colocated as a `.doc.mjs` next to ' +
     'the source of truth it documents.',
   appliesTo: '<enum>.doc.mjs',
@@ -59,7 +59,7 @@ export const doc = {
     {
       name: 'members',
       type: 'EnumMemberDoc[]',
-      description: 'The enumerated members — one entry per literal value.',
+      description: 'The enumerated members: one entry per literal value.',
       required: true,
       fields: [
         {

package/authoring/doctypes/function/function.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
       name: 'kind',
       type: "'hook' | 'api'",
       description:
-        'Which flavor — drives docsite sectioning; inferred from importPath if omitted.',
+        'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
     },
     {
       name: 'summary',
@@ -127,7 +127,7 @@ export const doc = {
         {
           name: 'returns[].name',
           type: 'string',
-          description: 'Field name (hooks) — omit for API envelope entries.',
+          description: 'Field name (hooks); omit for API envelope entries.',
         },
         {
           name: 'returns[].type',
@@ -191,7 +191,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Usage documentation (hooks) — description, best practices, anatomy. Same shape as HookDoc.usage.',
+        'Usage documentation (hooks): description, best practices, anatomy. Same shape as HookDoc.usage.',
     },
     {
       name: 'command',

package/authoring/doctypes/hook/hook.doc.mjs

@@ -43,7 +43,7 @@ export const doc = {
       name: 'group',
       type: 'string',
       description:
-        'Optional group for sidebar/docs organization — same as ComponentDoc.group.',
+        'Optional group for sidebar/docs organization; same as ComponentDoc.group.',
     },
     {
       name: 'keywords',
@@ -117,7 +117,7 @@ export const doc = {
     {
       name: 'usage',
       type: 'UsageDoc',
-      description: 'Usage documentation — description and best practices.',
+      description: 'Usage documentation: description and best practices.',
       required: true,
       fields: [
         {
@@ -190,7 +190,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "A hook's discriminant is `type: 'function'` — HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
+      text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/reference.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'ReferenceDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a reference/topic doc — tokens, principles, theming, patterns, ' +
+    'The doc-type for a reference/topic doc: tokens, principles, theming, patterns, ' +
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
@@ -120,7 +120,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock — a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',
@@ -140,7 +140,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables — one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
     },
   ],
 };

package/authoring/doctypes/schema/schema.doc.mjs

@@ -190,7 +190,7 @@ export const doc = {
       type: 'list',
       style: 'dont',
       items: [
-        'Set `required: false` for optional fields — omit `required` entirely instead.',
+        'Set `required: false` for optional fields; omit `required` entirely instead.',
       ],
     },
   ],