Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: rename product name XDS -> Astryx in .doc.mjs component docs (#3138)

EJ Hammonda90745749731
diff --git a/packages/cli/docs/icons.doc.mjs b/packages/cli/docs/icons.doc.mjs
index 9a970ac21a..e2d8d2504d 100644
--- a/packages/cli/docs/icons.doc.mjs
+++ b/packages/cli/docs/icons.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Icons reference doc: semantic icon names available in XDS
+ * @file Icons reference doc: semantic icon names available in Astryx
*/
/** @type {import('../../core/src/docs-types').ReferenceDoc} */
diff --git a/packages/cli/docs/migration.doc.mjs b/packages/cli/docs/migration.doc.mjs
index 61e8fc0a47..0eda5946ec 100644
--- a/packages/cli/docs/migration.doc.mjs
+++ b/packages/cli/docs/migration.doc.mjs
@@ -234,7 +234,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
type: 'code',
lang: 'text',
label: 'Paste this into your AI',
- code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+ code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
First run:
- npx astryx docs migration --dense
@@ -242,7 +242,7 @@ First run:
- npx astryx docs styling --dense
- npx astryx template AppShellTopNavWithSideNav --skeleton
-Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with XDS components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
},
],
},
diff --git a/packages/cli/docs/shape.doc.mjs b/packages/cli/docs/shape.doc.mjs
index 5d2b841915..9b30b584c9 100644
--- a/packages/cli/docs/shape.doc.mjs
+++ b/packages/cli/docs/shape.doc.mjs
@@ -44,7 +44,7 @@ export const docs = {
type: 'code',
lang: 'css',
label: 'Concentric radius formula',
- code: `/* Automatic in XDS Card */
+ code: `/* Automatic in Astryx Card */
--card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
},
],
diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjs
index fe0a73641a..e59c45e299 100644
--- a/packages/cli/docs/styling.doc.mjs
+++ b/packages/cli/docs/styling.doc.mjs
@@ -231,7 +231,7 @@ const overrides = stylex.create({
content: [
{
type: 'prose',
- text: 'When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
+ text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
},
{
type: 'code',
@@ -273,7 +273,7 @@ const overrides = stylex.create({
content: [
{
type: 'prose',
- text: 'XDS still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
+ text: 'Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
},
{
type: 'code',
diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjs
index 49ce9d8739..04498dc14d 100644
--- a/packages/cli/docs/working-with-ai.doc.mjs
+++ b/packages/cli/docs/working-with-ai.doc.mjs
@@ -34,7 +34,7 @@ export const docs = {
type: 'code',
lang: 'text',
label: 'Paste this into your AI',
- code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your XDS context. Read the generated file.',
+ code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
},
{
type: 'prose',
@@ -103,7 +103,7 @@ npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
type: 'code',
lang: 'text',
label: 'Paste this into your AI',
- code: `Before writing any XDS code, check your knowledge:
+ code: `Before writing any Astryx code, check your knowledge:
1. What is the correct import path for Button?
2. How do you make an Dialog non-dismissible?
@@ -165,7 +165,7 @@ npx astryx docs tokens --dense`,
content: [
{
type: 'prose',
- text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
+ text: 'Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
},
{
type: 'prose',
diff --git a/packages/core/src/Collapsible/useCollapsible.doc.mjs b/packages/core/src/Collapsible/useCollapsible.doc.mjs
index 650377f5bb..075f44047e 100644
--- a/packages/core/src/Collapsible/useCollapsible.doc.mjs
+++ b/packages/core/src/Collapsible/useCollapsible.doc.mjs
@@ -38,7 +38,7 @@ export const docs = {
usage: {
description: 'Reusable hook that encapsulates the collapsible state machine. Supports three modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), and uncontrolled (self-managed with defaultIsOpen). Used internally by Card and Section.',
bestPractices: [
- {guidance: true, description: 'Use the hook directly when building custom collapsible components that need XDS collapsible behavior without Collapsible wrapper.'},
+ {guidance: true, description: 'Use the hook directly when building custom collapsible components that need Astryx collapsible behavior without Collapsible wrapper.'},
{guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup and pass unique value props.'},
{guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; the hook handles group coordination automatically.'},
],
@@ -64,7 +64,7 @@ export const docsDense = {
usage: {
description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by Card + Section.',
bestPractices: [
- {guidance: true, description: 'Use directly when building custom collapsible components needing XDS collapsible behavior w/o Collapsible wrapper.'},
+ {guidance: true, description: 'Use directly when building custom collapsible components needing Astryx collapsible behavior w/o Collapsible wrapper.'},
{guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup + pass unique value props.'},
{guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; hook handles group coordination automatically.'},
],
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
index 9890c4bb9f..7eeb3f2d96 100644
--- a/packages/core/src/Divider/Divider.doc.mjs
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -108,7 +108,7 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'visual separator w/ optional label, using XDS design tokens',
+ description: 'visual separator w/ optional label, using Astryx design tokens',
usage: {
description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
bestPractices: [
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index f60f6a4778..cf2efd32ba 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -20,7 +20,7 @@ export const docs = {
name: 'children',
type: 'ReactNode',
description:
- 'Form fields to arrange. Accepts XDS inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
+ 'Form fields to arrange. Accepts Astryx inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
},
{
name: 'xstyle',
@@ -68,7 +68,7 @@ export const docsZh = {
name: 'children',
type: 'ReactNode',
description:
- '要排列的表单字段。接受 XDS 输入组件(TextInput、Selector 等)和 Field 包装的自定义控件。',
+ '要排列的表单字段。接受 Astryx 输入组件(TextInput、Selector 等)和 Field 包装的自定义控件。',
},
{
name: 'xstyle',
@@ -122,7 +122,7 @@ export const docsDense = {
},
propDescriptions: {
direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
- children: 'Form fields to arrange. Accepts XDS inputs + Field-wrapped custom controls.',
+ children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
},
};
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index 3835b83e66..9b004d1067 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -17,7 +17,7 @@ export const docs = {
{
name: 'color',
type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
- description: 'Color variant mapped to XDS icon color tokens.',
+ description: 'Color variant mapped to Astryx icon color tokens.',
default: "'inherit'",
},
{
@@ -62,7 +62,7 @@ export const docsZh = {
{
name: 'color',
type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
- description: '映射到 XDS 图标颜色令牌的颜色变体。',
+ description: '映射到 Astryx 图标颜色令牌的颜色变体。',
default: "'inherit'",
},
{
@@ -96,7 +96,7 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
- 'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
+ 'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
usage: {
description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
bestPractices: [
@@ -113,7 +113,7 @@ export const docsDense = {
},
propDescriptions: {
icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
- color: 'Color variant mapped to XDS icon color tokens.',
+ color: 'Color variant mapped to Astryx icon color tokens.',
size: 'Icon size.',
},
};
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index d57cd9a0a0..5b08e3eeeb 100644
--- a/packages/core/src/Item/Item.doc.mjs
+++ b/packages/core/src/Item/Item.doc.mjs
@@ -51,7 +51,7 @@ export const docs = {
],
usage: {
description:
- 'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
+ 'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across Astryx. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
bestPractices: [
{guidance: true, description: 'Use named slots (startContent, label, description, endContent) for the common layout. These cover the 80% case.'},
{guidance: true, description: 'Use density="compact" for menus and dense lists, "balanced" for standard rows, and "spacious" for roomier layouts.'},
@@ -104,7 +104,7 @@ export const docsZh = {
],
usage: {
description:
- '通用项目原语,统一 XDS 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
+ '通用项目原语,统一 Astryx 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
bestPractices: [
{guidance: true, description: '使用命名插槽(startContent、label、description、endContent)处理常见布局。'},
{guidance: true, description: '菜单和密集列表使用 density="compact",标准行使用 "balanced",宽松布局使用 "spacious"。'},
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index e086155414..ace91233d0 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -99,7 +99,7 @@ export const docs = {
isHiddenFromOverview: true,
displayName: 'Link Provider',
description:
- 'Provider that sets the default link component for all XDS link-rendering components in the subtree. ' +
+ 'Provider that sets the default link component for all Astryx link-rendering components in the subtree. ' +
'Wrap your app root to replace native <a> elements with your framework router (Next.js Link, React Router Link, etc.).',
props: [
{
@@ -226,7 +226,7 @@ export const docsZh = {
isHiddenFromOverview: true,
displayName: 'Link Provider',
description:
- '为子树中所有 XDS 链接组件设置默认链接组件的 Provider。',
+ '为子树中所有 Astryx 链接组件设置默认链接组件的 Provider。',
props: [
{
name: 'component',
@@ -310,7 +310,7 @@ export const docsDense = {
isHiddenFromOverview: true,
displayName: 'Link Provider',
description:
- 'Provider setting default link component for all XDS links in subtree.',
+ 'Provider setting default link component for all Astryx links in subtree.',
propDescriptions: {
component: 'Component for all link elements',
children: 'Subtree',
diff --git a/packages/core/src/Link/LinkProvider.doc.mjs b/packages/core/src/Link/LinkProvider.doc.mjs
index 22a675261b..f522ece8a3 100644
--- a/packages/core/src/Link/LinkProvider.doc.mjs
+++ b/packages/core/src/Link/LinkProvider.doc.mjs
@@ -10,7 +10,7 @@ export const docs = {
isHiddenFromOverview: true,
keywords: ['link', 'provider', 'router', 'nextjs', 'client-side-routing'],
usage: {
- description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
},
props: [
{name: 'component', type: 'LinkComponentType', required: true, description: 'Link component to use for all link elements in the subtree (e.g. Next.js Link).'},
@@ -20,9 +20,9 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
usage: {
- description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
},
propDescriptions: {
component: 'link component for all link elements in subtree (e.g. Next.js Link)',
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index ba47290ff2..3d8f39ebda 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -131,7 +131,7 @@ export const docs = {
},
usage: {
description:
- 'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+ 'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
bestPractices: [
{ guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
{ guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -294,7 +294,7 @@ export const docsZh = {
},
usage: {
description:
- 'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+ 'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
bestPractices: [
{ guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
{ guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -306,10 +306,10 @@ export const docsZh = {
export const docsDense = {
description:
- 'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
+ 'Renders markdown string as Astryx-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
usage: {
description:
- 'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+ 'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
bestPractices: [
{ guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
{ guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
diff --git a/packages/core/src/Resizable/Resizable.doc.mjs b/packages/core/src/Resizable/Resizable.doc.mjs
index 1d71a4aa6c..bd10c7a833 100644
--- a/packages/core/src/Resizable/Resizable.doc.mjs
+++ b/packages/core/src/Resizable/Resizable.doc.mjs
@@ -27,7 +27,7 @@ export const docs = {
{
guidance: true,
description:
- 'Use useResizable() with existing XDS layout components. ' +
+ 'Use useResizable() with existing Astryx layout components. ' +
'Pass the returned props to the resizable prop on LayoutPanel or SideNav.',
},
{
@@ -195,7 +195,7 @@ export const docsDense = {
description:
'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
bestPractices: [
- {guidance: true, description: 'Use useResizable() w/ existing XDS layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
+ {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
{guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
{guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
],
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index dd2b8f416c..9163984fb4 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -104,7 +104,7 @@ export const docs = {
'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
bestPractices: [
{ guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
- { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+ { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
{ guidance: true, description: 'Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum.' },
{ guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
@@ -128,7 +128,7 @@ export const docsZh = {
'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
bestPractices: [
{ guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
- { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+ { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
{ guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
],
@@ -151,7 +151,7 @@ export const docsDense = {
'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
bestPractices: [
{ guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
- { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+ { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
{ guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
{ guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
diff --git a/packages/core/src/hooks/useEntryAnimation.doc.mjs b/packages/core/src/hooks/useEntryAnimation.doc.mjs
index d394599bd1..98890a9ec5 100644
--- a/packages/core/src/hooks/useEntryAnimation.doc.mjs
+++ b/packages/core/src/hooks/useEntryAnimation.doc.mjs
@@ -23,7 +23,7 @@ export const docs = {
],
usage: {
description:
- 'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
+ 'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
bestPractices: [
{ guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
{ guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
@@ -39,7 +39,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
paramDescriptions: {
preset: 'animation preset applied on mount.',
},
@@ -48,7 +48,7 @@ export const docsDense = {
},
usage: {
description:
- 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
bestPractices: [
{ guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
{ guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },
diff --git a/packages/core/src/hooks/useMediaQuery.doc.mjs b/packages/core/src/hooks/useMediaQuery.doc.mjs
index 5c89c33b42..7c327e9d0d 100644
--- a/packages/core/src/hooks/useMediaQuery.doc.mjs
+++ b/packages/core/src/hooks/useMediaQuery.doc.mjs
@@ -24,7 +24,7 @@ export const docs = {
description: 'SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility.',
bestPractices: [
{ guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
- { guidance: true, description: 'Prefer XDS responsive tokens and component props over manual breakpoint logic when possible.' },
+ { guidance: true, description: 'Prefer Astryx responsive tokens and component props over manual breakpoint logic when possible.' },
{ guidance: false, description: 'Use for server-rendered content that must match on first paint; the hook always returns false initially.' },
],
},
@@ -47,7 +47,7 @@ export const docsDense = {
description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
bestPractices: [
{ guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
- { guidance: true, description: 'Prefer XDS responsive tokens + component props over manual breakpoint logic when possible.' },
+ { guidance: true, description: 'Prefer Astryx responsive tokens + component props over manual breakpoint logic when possible.' },
{ guidance: false, description: 'Use for server-rendered content that must match on first paint; hook always returns false initially.' },
],
},
diff --git a/packages/core/src/hooks/useStreamingText.doc.mjs b/packages/core/src/hooks/useStreamingText.doc.mjs
index 8b2afb0c40..9e9f2bcac1 100644
--- a/packages/core/src/hooks/useStreamingText.doc.mjs
+++ b/packages/core/src/hooks/useStreamingText.doc.mjs
@@ -41,7 +41,7 @@ export const docs = {
],
usage: {
description:
- 'Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.',
+ 'Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.',
bestPractices: [
{ guidance: true, description: 'Pass the accumulated text (not individual chunks) as targetText; the hook handles incremental reveal internally.' },
{ guidance: true, description: 'Set isStreaming to false when the stream completes to snap to the final text.' },
@@ -58,7 +58,7 @@ export const docs = {
/** @type {import('../docs-types').HookTranslationDoc} */
export const docsDense = {
description:
- 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
+ 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
paramDescriptions: {
targetText: 'full target text to reveal. As new chunks arrive, update this value w/ accumulated text.',
isStreaming: 'whether text currently being streamed. When false, hook returns full targetText immediately.',
@@ -70,7 +70,7 @@ export const docsDense = {
},
usage: {
description:
- 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
+ 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
bestPractices: [
{ guidance: true, description: 'Pass accumulated text (not individual chunks) as targetText; hook handles incremental reveal internally.' },
{ guidance: true, description: 'Set isStreaming to false when stream completes to snap to final text.' },
diff --git a/packages/core/src/theme/Theme.doc.mjs b/packages/core/src/theme/Theme.doc.mjs
index e9f52ec7f7..390acd71c9 100644
--- a/packages/core/src/theme/Theme.doc.mjs
+++ b/packages/core/src/theme/Theme.doc.mjs
@@ -39,7 +39,7 @@ export const docs = {
},
usage: {
description:
- 'Wraps a subtree with a specific XDS theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n name: \'ocean\',\n tokens: {\n \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n \'--radius-container\': \'16px\',\n },\n});\n```',
+ 'Wraps a subtree with a specific Astryx theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n name: \'ocean\',\n tokens: {\n \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n \'--radius-container\': \'16px\',\n },\n});\n```',
bestPractices: [
{
guidance: true,
@@ -90,7 +90,7 @@ export const docs = {
export const docsDense = {
usage: {
description:
- 'Wraps subtree w/ specific XDS theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
+ 'Wraps subtree w/ specific Astryx theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
bestPractices: [
{
guidance: true,