@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/locales/en.json

@@ -235,10 +235,22 @@
     "defaultMessage": "Mobile navigation",
     "description": "Screen-reader-only accessible name for the mobile-only navigation region on small viewports. \"Mobile\" = phone/tablet (small screen), not \"movable\"."
   },
+  "@astryx.avatar.nameWithStatus": {
+    "defaultMessage": "{name}, {status}",
+    "description": "Screen-reader accessible name for an Avatar showing a status indicator; composes the person's name with the status label, e.g. \"Jane Doe, Online\". {name} = the avatar's name/alt text, {status} = the status dot's label. Adjust separator and order per locale."
+  },
   "@astryx.avatarGroup.label": {
     "defaultMessage": "Avatars",
     "description": "Screen-reader-only fallback name for a horizontal cluster of user avatar images. Plural noun; consumers usually override with \"Team members\", \"Attendees\", etc."
   },
+  "@astryx.avatarGroup.keyboardHint": {
+    "defaultMessage": "Use arrow keys to move between avatars",
+    "description": "Screen-reader-only instruction attached (via aria-describedby) to a group of interactive avatars that share a single Tab stop. Tells keyboard users the Left/Right arrow keys move focus between the avatars. Only announced when the group has interactive (link/button) avatars."
+  },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "{count, number} more",
+    "description": "Accessible name for the \"+N\" overflow indicator at the end of an AvatarGroup — announces how many additional avatars are not shown. Example: `5 more`. The visible \"+N\" text is unaffected; this is the aria-label only."
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "Dismiss",
     "description": "\"Dismiss\" = close/hide this notification (not \"reject a person\"). Aria label AND tooltip on the small X button on a Banner."
@@ -251,6 +263,34 @@
     "defaultMessage": "Next month",
     "description": "Screen-reader-only label on the right-arrow button in a Calendar's month header (navigates one month forward). Pairs with `calendar.previousMonth`."
   },
+  "@astryx.calendar.daySelected": {
+    "defaultMessage": "{date}, selected",
+    "description": "Accessible name for the Calendar day button that is the current single-mode selection. `{date}` is the localized full date, e.g. \"Thursday, January 15, 2026\". The trailing state word tells screen-reader users the focused day is selected."
+  },
+  "@astryx.calendar.dayRangeStart": {
+    "defaultMessage": "{date}, range start",
+    "description": "Accessible name for the Calendar day button that begins the selected date range (or the first pick of an in-progress range). `{date}` is the localized full date."
+  },
+  "@astryx.calendar.dayRangeEnd": {
+    "defaultMessage": "{date}, range end",
+    "description": "Accessible name for the Calendar day button that ends the selected date range. `{date}` is the localized full date. Pairs with `calendar.dayRangeStart`."
+  },
+  "@astryx.calendar.dayRangeStartAndEnd": {
+    "defaultMessage": "{date}, range start and range end",
+    "description": "Accessible name for a Calendar day button that both begins and ends a completed one-day range. `{date}` is the localized full date."
+  },
+  "@astryx.calendar.dayInRange": {
+    "defaultMessage": "{date}, in range",
+    "description": "Accessible name for a Calendar day button strictly inside the selected date range (not an endpoint). `{date}` is the localized full date."
+  },
+  "@astryx.calendar.rangeStartAnnounce": {
+    "defaultMessage": "Start date {date}. Select an end date.",
+    "description": "Screen-reader announcement after the first pick of a Calendar range selection. `{date}` is the localized full date. Prompts the user that a second pick completes the range."
+  },
+  "@astryx.calendar.rangeCompleteAnnounce": {
+    "defaultMessage": "Selected range: {start} to {end}.",
+    "description": "Screen-reader announcement after the second pick completes a Calendar range selection. `{start}` and `{end}` are localized full dates in chronological order."
+  },
   "@astryx.carousel.label": {
     "defaultMessage": "Carousel",
     "description": "Screen-reader-only fallback name for a horizontally-scrolling row of items. If \"carousel\" is unfamiliar in your locale, prefer the standard term (e.g. \"slider\")."
@@ -307,6 +347,18 @@
     "defaultMessage": "Type to search",
     "description": "Onboarding empty-state text shown inside a CommandPalette on first open, before the user has typed anything. Imperative sentence fragment."
   },
+  "@astryx.commandPalette.resultCount": {
+    "defaultMessage": "{count, number} {count, plural, one {result} other {results}}",
+    "description": "Screen-reader-only announcement of how many commands match the CommandPalette query as the user types. Example: `12 results`, `1 result`; keep compact."
+  },
+  "@astryx.commandPalette.noResultsFor": {
+    "defaultMessage": "No results for {query}",
+    "description": "Screen-reader-only announcement when a CommandPalette query matches nothing. `{query}` is the user's verbatim search text; keep it last if your language allows so truncation-by-AT still conveys the outcome."
+  },
+  "@astryx.commandPalette.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only announcement that a CommandPalette search has started and results are being fetched. Present-progressive form; matches the visible spinner."
+  },
   "@astryx.dateRangeInput.presetDateRanges": {
     "defaultMessage": "Preset date ranges",
     "description": "Screen-reader-only accessible name for the sidebar of quick-pick preset ranges inside a DateRangeInput popover (e.g. \"Last 7 days\", \"This month\")."
@@ -359,6 +411,10 @@
     "defaultMessage": "Search options",
     "description": "Screen-reader-only accessible name for that same search input inside a MultiSelector."
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "{label}, partially selected",
+    "description": "Accessible name for the MultiSelector select-all option while only some options are selected. `{label}` is the visible select-all label (e.g. \"Select all\"). ARIA forbids aria-selected=\"mixed\" on options, so the indeterminate state is conveyed through the name instead. \"Partially\" = some but not all."
+  },
   "@astryx.popover.close": {
     "defaultMessage": "Close popover",
     "description": "\"Close\" = shut/dismiss, not \"nearby\". Screen-reader-only label on the close button inside a Popover."
@@ -635,6 +691,10 @@
     "defaultMessage": "Expand",
     "description": "\"Expand\" = reveal more, not grow physically. Aria label AND tooltip on the same toggle when currently collapsed. Pairs with `banner.collapse`."
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense (\"work in progress\"), not a noun. Kept separate from `typeahead.loading` — translations may diverge."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."
@@ -643,6 +703,14 @@
     "defaultMessage": "Collapse {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is expanded. Example: `Collapse Attachments`. Pairs with `expand`."
   },
+  "@astryx.chatDictationButton.startDictation": {
+    "defaultMessage": "Start dictation",
+    "description": "Accessible label for the microphone button when idle (not listening)."
+  },
+  "@astryx.chatDictationButton.stopDictation": {
+    "defaultMessage": "Stop dictation",
+    "description": "Accessible label for the microphone button when actively listening."
+  },
   "@astryx.chatLayout.newMessages": {
     "defaultMessage": "New messages",
     "description": "Text on a floating pill at the bottom of a chat viewport when unseen messages arrive below the fold; clicking scrolls to bottom. Keep short — narrow pill."
@@ -663,6 +731,14 @@
     "defaultMessage": "Send",
     "description": "Primary button label on the chat submit button (paperplane icon). Imperative verb; pairs with `Stop`. Very short."
   },
+  "@astryx.chatToolCalls.error": {
+    "defaultMessage": "Error: {message}",
+    "description": "Screen-reader text for a tool call that failed. {message} is the error detail."
+  },
+  "@astryx.chatToolCalls.groupLabel": {
+    "defaultMessage": "{count} tool calls",
+    "description": "Summary label shown in the group header when multiple tool calls are expanded. {count} is the number of calls."
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "Suggestions",
     "description": "Screen-reader-only fallback label for the popover listbox opened by a trigger character (`@`, `/`) in the chat composer when the trigger provides no specific label."
@@ -683,18 +759,42 @@
     "defaultMessage": "Code",
     "description": "Screen-reader-only fallback name for a code-snippet scroll container when the code's language is unknown. \"Code\" = source code, not secret code or code of conduct."
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "Optional",
+    "description": "Visible indicator shown next to a form field's label when the field is optional (isOptional). Mutually exclusive with the required indicator. Very short — appears inline after the label text."
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "Required",
+    "description": "Visible indicator shown next to a form field's label when the field must be filled in (isRequired). Mutually exclusive with the optional indicator. Very short — appears inline after the label text."
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that removes the selected file from a FileInput. Example: `Clear Attachment`, `Clear Résumé`."
   },
+  "@astryx.fileInput.required": {
+    "defaultMessage": "Required",
+    "description": "Screen-reader-only description on the FileInput trigger indicating the field must be filled in. Mirrors the visible `Required` indicator next to the field label; conveyed via description because aria-required is not supported on role=\"button\"."
+  },
   "@astryx.fileInput.triggerWithFiles": {
     "defaultMessage": "{label}, {fileNames}",
     "description": "Accessible name for a FileInput trigger that has files attached, composing the field label with the selected filenames. Example: `Attachments, report.pdf, notes.txt`."
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "to navigate",
+    "description": "Trailing text in the keyboard-hint badge, shown after arrow-key icons — reads as `← → to navigate`. Lowercase sentence fragment completing the visual phrase; the badge is aria-hidden, so this is for sighted users only."
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "Media viewer",
     "description": "Screen-reader-only fallback name for the Lightbox dialog when the current media item has no alt text. Should rarely render — consumers should provide alt."
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "Show more",
+    "description": "Button label under a MetadataList that reveals items hidden beyond the configured maximum. Toggles with `metadataList.showLess` — keep the pair parallel in your language."
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "Show less",
+    "description": "Button label under a MetadataList that re-hides the extra items revealed by `metadataList.showMore`. Keep the pair parallel."
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "Navigation",
     "description": "Screen-reader-only fallback name for the MobileNav overlay dialog when no explicit label was passed."
@@ -703,6 +803,18 @@
     "defaultMessage": "Clear all {label}",
     "description": "Screen-reader-only label on the X that clears every selected value from a MultiSelector. Example: `Clear all Countries`. `{label}` is typically already plural in English."
   },
+  "@astryx.input.statusButton.error": {
+    "defaultMessage": "Error details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is error. Activating or focusing the button reveals the error message in a tooltip. Keep it short — it labels an icon-only button."
+  },
+  "@astryx.input.statusButton.warning": {
+    "defaultMessage": "Warning details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is warning. Activating or focusing the button reveals the warning message in a tooltip."
+  },
+  "@astryx.input.statusButton.success": {
+    "defaultMessage": "Success details",
+    "description": "Accessible name for the focusable status icon button inside an input when statusVariant is 'tooltip' and the status type is success. Activating or focusing the button reveals the success message in a tooltip."
+  },
   "@astryx.numberInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a NumberInput. Example: `Clear Age`, `Clear Quantity`."
@@ -771,6 +883,14 @@
     "defaultMessage": "Expand all rows",
     "description": "Aria label for the Table tree-data header toggle when rows are collapsed and clicking it expands them."
   },
+  "@astryx.textArea.charactersRemaining": {
+    "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} remaining",
+    "description": "Screen-reader-only announcement of how many characters the user can still type before hitting a TextArea's maxLength. Announced politely as the count nears the limit. `{count}` is the number remaining — example: `12 characters remaining`."
+  },
+  "@astryx.textArea.charactersOverLimit": {
+    "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} over the limit",
+    "description": "Screen-reader-only assertive announcement when the user has typed past a TextArea's maxLength. `{count}` is how many characters over — example: `3 characters over the limit`."
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a TextInput. Example: `Clear Email`, `Clear Name`."

package/locales/pseudo.json

@@ -176,9 +176,18 @@
   "@astryx.appShell.mobileNavigation": {
     "defaultMessage": "⟦Ṁóƀíłé ñàṽíĝàţíóñ⟧"
   },
+  "@astryx.avatar.nameWithStatus": {
+    "defaultMessage": "⟦{name}, {status}⟧"
+  },
   "@astryx.avatarGroup.label": {
     "defaultMessage": "⟦Àṽàţàřš⟧"
   },
+  "@astryx.avatarGroup.keyboardHint": {
+    "defaultMessage": "⟦Úšé àřřóŵ ķéýš ţó ɱóṽé ƀéţŵééñ àṽàţàřš⟧"
+  },
+  "@astryx.avatarGroup.overflow": {
+    "defaultMessage": "⟦{count, number} ɱóřé⟧"
+  },
   "@astryx.banner.dismiss": {
     "defaultMessage": "⟦Ðíšɱíšš⟧"
   },
@@ -188,6 +197,27 @@
   "@astryx.calendar.nextMonth": {
     "defaultMessage": "⟦Ñéẋţ ɱóñţĥ⟧"
   },
+  "@astryx.calendar.daySelected": {
+    "defaultMessage": "⟦{date}, šéłéçţéð⟧"
+  },
+  "@astryx.calendar.dayRangeStart": {
+    "defaultMessage": "⟦{date}, řàñĝé šţàřţ⟧"
+  },
+  "@astryx.calendar.dayRangeEnd": {
+    "defaultMessage": "⟦{date}, řàñĝé éñð⟧"
+  },
+  "@astryx.calendar.dayRangeStartAndEnd": {
+    "defaultMessage": "⟦{date}, řàñĝé šţàřţ àñð řàñĝé éñð⟧"
+  },
+  "@astryx.calendar.dayInRange": {
+    "defaultMessage": "⟦{date}, íñ řàñĝé⟧"
+  },
+  "@astryx.calendar.rangeStartAnnounce": {
+    "defaultMessage": "⟦Šţàřţ ðàţé {date}. Šéłéçţ àñ éñð ðàţé.⟧"
+  },
+  "@astryx.calendar.rangeCompleteAnnounce": {
+    "defaultMessage": "⟦Šéłéçţéð řàñĝé: {start} ţó {end}.⟧"
+  },
   "@astryx.carousel.label": {
     "defaultMessage": "⟦Çàřóúšéł⟧"
   },
@@ -230,6 +260,15 @@
   "@astryx.commandPalette.emptyBootstrap": {
     "defaultMessage": "⟦Ţýþé ţó šéàřçĥ⟧"
   },
+  "@astryx.commandPalette.resultCount": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {result} other {results}}⟧"
+  },
+  "@astryx.commandPalette.noResultsFor": {
+    "defaultMessage": "⟦Ñó řéšúłţš ƒóř {query}⟧"
+  },
+  "@astryx.commandPalette.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.dateRangeInput.presetDateRanges": {
     "defaultMessage": "⟦Þřéšéţ ðàţé řàñĝéš⟧"
   },
@@ -269,6 +308,9 @@
   "@astryx.multiSelector.searchOptions": {
     "defaultMessage": "⟦Šéàřçĥ óþţíóñš⟧"
   },
+  "@astryx.multiSelector.selectAllPartiallySelected": {
+    "defaultMessage": "⟦{label}, þàřţíàłłý šéłéçţéð⟧"
+  },
   "@astryx.popover.close": {
     "defaultMessage": "⟦Çłóšé þóþóṽéř⟧"
   },
@@ -476,12 +518,21 @@
   "@astryx.banner.expand": {
     "defaultMessage": "⟦Éẋþàñð⟧"
   },
+  "@astryx.button.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },
   "@astryx.chatComposerDrawer.collapse": {
     "defaultMessage": "⟦Çółłàþšé {label}⟧"
   },
+  "@astryx.chatDictationButton.startDictation": {
+    "defaultMessage": "⟦Šţàřţ ðíçţàţíóñ⟧"
+  },
+  "@astryx.chatDictationButton.stopDictation": {
+    "defaultMessage": "⟦Šţóþ ðíçţàţíóñ⟧"
+  },
   "@astryx.chatLayout.newMessages": {
     "defaultMessage": "⟦Ñéŵ ɱéššàĝéš⟧"
   },
@@ -497,6 +548,12 @@
   "@astryx.chatSendButton.send": {
     "defaultMessage": "⟦Šéñð⟧"
   },
+  "@astryx.chatToolCalls.error": {
+    "defaultMessage": "⟦Éřřóř: {message}⟧"
+  },
+  "@astryx.chatToolCalls.groupLabel": {
+    "defaultMessage": "⟦{count} ţóół çàłłš⟧"
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "⟦Šúĝĝéšţíóñš⟧"
   },
@@ -512,21 +569,48 @@
   "@astryx.codeBlock.code": {
     "defaultMessage": "⟦Çóðé⟧"
   },
+  "@astryx.field.optional": {
+    "defaultMessage": "⟦Óþţíóñàł⟧"
+  },
+  "@astryx.field.required": {
+    "defaultMessage": "⟦Řéɋúířéð⟧"
+  },
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.fileInput.required": {
+    "defaultMessage": "⟦Řéɋúířéð⟧"
+  },
   "@astryx.fileInput.triggerWithFiles": {
     "defaultMessage": "⟦{label}, {fileNames}⟧"
   },
+  "@astryx.keyboardHint.toNavigate": {
+    "defaultMessage": "⟦ţó ñàṽíĝàţé⟧"
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "⟦Ṁéðíà ṽíéŵéř⟧"
   },
+  "@astryx.metadataList.showMore": {
+    "defaultMessage": "⟦Šĥóŵ ɱóřé⟧"
+  },
+  "@astryx.metadataList.showLess": {
+    "defaultMessage": "⟦Šĥóŵ łéšš⟧"
+  },
   "@astryx.mobileNav.navigation": {
     "defaultMessage": "⟦Ñàṽíĝàţíóñ⟧"
   },
   "@astryx.multiSelector.clearAll": {
     "defaultMessage": "⟦Çłéàř àłł {label}⟧"
   },
+  "@astryx.input.statusButton.error": {
+    "defaultMessage": "⟦Éřřóř ðéţàíłš⟧"
+  },
+  "@astryx.input.statusButton.warning": {
+    "defaultMessage": "⟦Ŵàřñíñĝ ðéţàíłš⟧"
+  },
+  "@astryx.input.statusButton.success": {
+    "defaultMessage": "⟦Šúççéšš ðéţàíłš⟧"
+  },
   "@astryx.numberInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
@@ -578,6 +662,12 @@
   "@astryx.tableTree.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.textArea.charactersRemaining": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} řéɱàíñíñĝ⟧"
+  },
+  "@astryx.textArea.charactersOverLimit": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} óṽéř ţĥé łíɱíţ⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.9",
+  "version": "0.2.0-canary.0b7a99e",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -54,21 +54,16 @@
       "types": "./src/tailwind-theme.css.d.ts",
       "default": "./src/tailwind-theme.css"
     },
+    "./BaseProps": {
+      "source": "./src/BaseProps.ts",
+      "types": "./dist/BaseProps.d.ts",
+      "default": "./dist/BaseProps.js"
+    },
     "./naming": {
       "source": "./src/naming.ts",
       "types": "./dist/naming.d.ts",
       "default": "./dist/naming.js"
     },
-    "./config": {
-      "source": "./src/config.ts",
-      "types": "./dist/config.d.ts",
-      "default": "./dist/config.js"
-    },
-    "./authoring": {
-      "source": "./src/authoring/index.ts",
-      "types": "./dist/authoring/index.d.ts",
-      "default": "./dist/authoring/index.js"
-    },
     "./theme/tokens": {
       "source": "./src/theme/tokens.ts",
       "types": "./dist/theme/tokens.d.ts",
@@ -649,7 +644,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.29.7",
+    "@astryxdesign/cli": "0.2.0-canary.0b7a99e",
+    "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^7.29.7",
@@ -664,7 +660,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
+    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
     "build:i18n": "node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",
     "build:css": "node ../../scripts/build-css.mjs",

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AlertDialog',
@@ -30,7 +30,7 @@ export const docs = {
   },
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
-  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
   // in docs-types.ts (#3657).
   playground: {
     defaults: {
@@ -120,7 +120,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {

package/src/AlertDialog/AlertDialog.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/AlertDialog/AlertDialog.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/AlertDialog/index.ts (exports if types change)
  * - /apps/storybook/stories/AlertDialog.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/AlertDialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AlertDialog/ (showcase blocks)
  */
 
 import React, {useId, useCallback} from 'react';

package/src/AlertDialog/useImperativeAlertDialog.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'useImperativeAlertDialog',

package/src/AppShell/AppShell.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AppShell',
@@ -120,7 +120,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'AppShell',
   displayName: 'App Shell',
@@ -182,7 +182,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'app-level layout shell w/ header, side nav, main content; composes Layout internally, replaces Page+PageLayout',

package/src/AppShell/AppShell.tsx

@@ -17,7 +17,7 @@ import React from 'react';
  * - /packages/core/src/AppShell/index.ts
  * - /packages/core/src/AppShell/AppShell.test.tsx
  * - /apps/storybook/stories/AppShell.stories.tsx
- * - /packages/cli/templates/blocks/components/AppShell/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AppShell/ (showcase blocks)
  */
 
 import {
@@ -55,6 +55,7 @@ import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import type {AppShellVariantMap} from './index';
 
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
@@ -101,25 +102,6 @@ export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'none';
  * - `elevated`: Wash nav background with elevated surface content + border radius
  * @default 'elevated'
  */
-/**
- * Extensible variant map for AppShell.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/AppShell' {
- *   interface AppShellVariantMap {
- *     'glass': true;
- *   }
- * }
- * ```
- */
-export interface AppShellVariantMap {
-  wash: true;
-  surface: true;
-  section: true;
-  elevated: true;
-}
 
 /**
  * Navigation background style. Extensible via module augmentation of AppShellVariantMap.

package/src/AppShell/index.ts

@@ -11,12 +11,31 @@
  * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs
  */
 
+/**
+ * Extensible variant map for AppShell.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/AppShell' {
+ *   interface AppShellVariantMap {
+ *     'glass': true;
+ *   }
+ * }
+ * ```
+ */
+export interface AppShellVariantMap {
+  wash: true;
+  surface: true;
+  section: true;
+  elevated: true;
+}
+
 export {AppShell} from './AppShell';
 export type {
   AppShellProps,
   AppShellBreakpoint,
   AppShellVariant,
-  AppShellVariantMap,
   MobileNavConfig,
 } from './AppShell';
 export {

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useAppShellMobile',
   displayName: 'useAppShellMobile',
@@ -109,7 +109,7 @@ export const docs = {
   importPath: '@astryxdesign/core/AppShell',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Reads/controls AppShell mobile nav context. Use for custom triggers, closing drawer after route changes, or syncing AppShell-adjacent mobile UI to the same breakpoint as mobile nav.',

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AspectRatio',
@@ -62,7 +62,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'AspectRatio',
   displayName: 'Aspect Ratio',
@@ -105,7 +105,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {

package/src/AspectRatio/AspectRatio.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
  * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
- * - /packages/cli/templates/blocks/components/AspectRatio/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';