@astryxdesign/core 0.6.3-canary.f22695a → 0.6.3

package/dist/theme/generateThemeRules.js

@@ -9,17 +9,11 @@
  * Used by both the runtime path (Theme injects <style>) and the build
  * path (`astryx theme build` pre-compiles to CSS files).
  *
- * Every consumer-supplied declaration is checked by declarationBoundary.ts
- * before it is emitted, so a value can never end its declaration or rule
- * early. A refused declaration is dropped and reported in the supplied
- * warnings array (build receipts), or through `console.warn` (runtime).
- *
  * Extracted from defineTheme.ts to reduce cyclomatic complexity and provide
  * a clear single-responsibility module for CSS generation.
  *
- * @input DefinedTheme (resolved theme object from defineTheme), optional warnings array
- * @output CSS rule strings, split by layer (component vs prose), and warning text
- *   for each dropped declaration
+ * @input DefinedTheme (resolved theme object from defineTheme)
+ * @output CSS rule strings, split by layer (component vs prose)
  * @position packages/core/src/theme/generateThemeRules.ts
  */
 
@@ -28,7 +22,6 @@ import { parseStyleKey } from "../utils/parseStyleKey.js";
 import { getDerivedVars } from "./derivedVarRegistry.js";
 import { dataTokenDefaults } from "./domainTokens/dataTokens.js";
 import { cssVar, classPrefix, dataAttrNamespace } from "../naming.js";
-import { checkDeclarationName, checkDeclarationValue } from "./declarationBoundary.js";
 
 /**
  * Theme @scope selectors.
@@ -291,77 +284,6 @@ function expandContainerPadding(component, parsed, resetInheritedSpecificity = f
   return tokens;
 }
 
-// =============================================================================
-// Declaration assembly: a declaration always stays one declaration
-// =============================================================================
-
-const warnToConsole = message => {
-  console.warn(`[astryx theme] ${message}`);
-};
-
-/** Build receipts collect warning text; runtime callers warn by default. */
-function diagnosticSink(warnings) {
-  return warnings ? message => warnings.push(message) : warnToConsole;
-}
-
-/** Shorten an authored value for a one-line message. */
-function previewValue(value) {
-  const oneLine = JSON.stringify(value);
-  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}..."` : oneLine;
-}
-function reportDrop(sink, property, value, location, reason) {
-  sink(`dropped "${property}" in ${location}: ${reason} (value: ${previewValue(value)})`);
-}
-
-/**
- * True when `name: value;` stays exactly one declaration; otherwise reports
- * the drop and returns false. Both checks follow CSS syntax, so valid CSS a
- * browser keeps inside one declaration (a `data:` URI, `Gill\ Sans`, a closed
- * comment, a vendor-prefixed property) is never refused; see
- * declarationBoundary.ts for the rules.
- */
-function acceptDeclaration(property, value, location, sink) {
-  const reason = checkDeclarationName(property) ?? checkDeclarationValue(value);
-  if (reason === null) {
-    return true;
-  }
-  reportDrop(sink, property, value, location, reason);
-  return false;
-}
-
-/**
- * Assemble `prop: value;` lines, dropping (and reporting) any entry whose
- * property or value could not stay a single declaration. Theme definitions
- * are code, but apps do assemble them from stored input (brand colors,
- * white-labeling), so the generated stylesheet must never extend beyond the
- * declarations it means to emit.
- */
-function joinDeclarations(entries, location, sink, mapProp = p => p) {
-  const lines = [];
-  for (const [rawProp, rawValue] of entries) {
-    // Legacy unenrolled tokens retain non-string values. Scan the same text
-    // interpolation has always emitted, without changing the normalized theme.
-    const value = `${rawValue}`;
-    const prop = mapProp(rawProp);
-    if (acceptDeclaration(prop, value, location, sink)) {
-      lines.push(`    ${prop}: ${value};`);
-    }
-  }
-  return lines.join('\n');
-}
-
-/** The `:scope` token block for portable and theme-local token values. */
-function tokenBlock(source, location, sink) {
-  const declarations = [joinDeclarations(Object.entries(source.tokens), `${location}tokens`, sink), joinDeclarations(Object.entries(source.localTokens ?? {}), `${location}localTokens`, sink)].filter(block => block.length > 0).join('\n');
-  const hasEntries = Object.keys(source.tokens).length > 0 || Object.keys(source.localTokens ?? {}).length > 0;
-  return hasEntries ? `  :scope {\n${declarations}\n  }` : null;
-}
-
-/** `components.button["variant:secondary"]`-style location for a rule. */
-function componentLocation(prefix, component, key) {
-  return `${prefix}components.${component}[${JSON.stringify(key)}]`;
-}
-
 // =============================================================================
 // Public API
 // =============================================================================
@@ -381,9 +303,9 @@ function componentLocation(prefix, component, key) {
  * lost for every conditional rule, with no type error to catch it.
  */
 
-export function generateThemeRules(theme, warnings) {
+export function generateThemeRules(theme) {
   const parts = [];
-  const sink = diagnosticSink(warnings);
+  const tokens = theme.tokens;
 
   // Bare prose rules reference semantic variables instead of baking the root
   // value. That lets adaptation token writes take effect through CSS alone
@@ -391,9 +313,10 @@ export function generateThemeRules(theme, warnings) {
   const val = key => `var(${key})`;
 
   // 1. Token block — CSS custom properties on :scope
-  const tokenRules = tokenBlock(theme, '', sink);
-  if (tokenRules !== null) {
-    parts.push(tokenRules);
+  const tokenEntries = [...Object.entries(tokens), ...Object.entries(theme.localTokens ?? {})];
+  if (tokenEntries.length > 0) {
+    const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
+    parts.push(`  :scope {\n${declarations}\n  }`);
   }
 
   // 1b. Base font — apply the theme's declared body font to the scope root.
@@ -402,16 +325,14 @@ export function generateThemeRules(theme, warnings) {
   // sets a page font. `font-family` inherits, so one rule on :scope covers
   // the tree. Only emitted when the theme declares a body font, so a bare
   // theme still contributes no scope rules of its own.
-  if (theme.tokens['--font-family-body']) {
+  if (tokens['--font-family-body']) {
     parts.push(`  :scope {\n    font-family: var(--font-family-body);\n  }`);
   }
 
   // 2. Component overrides: stable .astryx-* target classes combined with
   // reflected data-* selectors for visual props and runtime states.
   if (theme.components) {
-    generateComponentRules(theme.components, parts, {
-      sink
-    });
+    generateComponentRules(theme.components, parts);
   }
 
   // 3. Prose HTML element rules (h1-h6, p, small, code, hr)
@@ -475,21 +396,13 @@ function generateHeadingWeightOverrides(components, parts, {
     parts.push(`  ${selector} { font-weight: ${effectiveWeight}; }`);
   }
 }
-
-/**
- * The `fontWeight` a heading rule authors for `styleKey`, or undefined when
- * it has none. A value that cannot stay one declaration is treated as not
- * authored, so the override falls back to the inherited or token weight
- * instead of interpolating it; the drop itself is reported where that same
- * rule's declarations are emitted, so it is not reported twice here.
- */
 function getAuthoredHeadingWeight(headingRuleMap, styleKey) {
   const rule = headingRuleMap[styleKey];
   if (rule == null || typeof rule !== 'object' || Array.isArray(rule)) {
     return undefined;
   }
   const fontWeight = rule.fontWeight;
-  return typeof fontWeight === 'string' && checkDeclarationValue(fontWeight) === null ? fontWeight : undefined;
+  return typeof fontWeight === 'string' ? fontWeight : undefined;
 }
 
 /** Options shared by root, adaptation, and media-surface component lowering. */
@@ -501,9 +414,7 @@ function getAuthoredHeadingWeight(headingRuleMap, styleKey) {
  */
 function generateComponentRules(components, parts, {
   resetInheritedPaddingSpecificity = false,
-  surface,
-  sink = warnToConsole,
-  location: locationPrefix = ''
+  surface
 } = {}) {
   for (const [component, rules] of Object.entries(components)) {
     for (const [key, styles] of Object.entries(rules)) {
@@ -513,7 +424,6 @@ function generateComponentRules(components, parts, {
       }
       const suffix = parseStyleKey(key);
       const baseSelector = componentSelector(component, suffix, surface);
-      const location = componentLocation(locationPrefix, component, key);
 
       // Separate regular properties from pseudo-class overrides
       const props = [];
@@ -521,7 +431,7 @@ function generateComponentRules(components, parts, {
       for (const [prop, value] of entries) {
         if (prop.startsWith(':') && typeof value === 'object') {
           pseudos.push([prop, value]);
-        } else if (acceptDeclaration(toKebabCase(prop), `${value}`, location, sink)) {
+        } else {
           props.push([prop, value]);
         }
       }
@@ -583,7 +493,7 @@ function generateComponentRules(components, parts, {
 
       // Emit base rule
       if (finalProps.length > 0) {
-        const declarations = joinDeclarations(finalProps, location, sink, toKebabCase);
+        const declarations = finalProps.map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`).join('\n');
         parts.push(`  ${baseSelector} {\n${declarations}\n  }`);
       }
 
@@ -591,7 +501,7 @@ function generateComponentRules(components, parts, {
       for (const [pseudo, pseudoStyles] of pseudos) {
         const pseudoEntries = Object.entries(pseudoStyles);
         if (pseudoEntries.length > 0) {
-          const declarations = joinDeclarations(pseudoEntries, `${location}[${JSON.stringify(pseudo)}]`, sink, toKebabCase);
+          const declarations = pseudoEntries.map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`).join('\n');
           parts.push(`  ${appendPseudoToSelectorList(baseSelector, pseudo)} {\n${declarations}\n  }`);
         }
       }
@@ -729,8 +639,8 @@ function generateSizeOverrides(components, parts, surface) {
  * Component rules (tokens, stable .astryx-* targets plus data-* selectors) are
  * that need to beat StyleX — they stay in astryx-theme (above StyleX layers).
  */
-export function generateThemeRulesSplit(theme, warnings) {
-  const allRules = generateThemeRules(theme, warnings);
+export function generateThemeRulesSplit(theme) {
+  const allRules = generateThemeRules(theme);
   const prose = [];
   const component = [];
   for (const rule of allRules) {
@@ -754,21 +664,19 @@ export function generateThemeRulesSplit(theme, warnings) {
  * to media contexts — only tokens change. Themes can further customize
  * via onDark.components / onLight.components.
  */
-export function generateOnMediaCSS(theme, warnings) {
+export function generateOnMediaCSS(theme) {
   const parts = [];
   const scopeSelector = themeScopeStart(theme.name);
-  const sink = diagnosticSink(warnings);
   for (const surface of ['dark', 'light']) {
     const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
     if (!onMedia) {
       continue;
     }
-    const location = surface === 'dark' ? 'onDark.' : 'onLight.';
 
     // Token overrides
     const tokenEntries = Object.entries(onMedia.tokens);
     if (tokenEntries.length > 0) {
-      const declarations = joinDeclarations(tokenEntries, `${location}tokens`, sink);
+      const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
       parts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
     }
 
@@ -777,9 +685,7 @@ export function generateOnMediaCSS(theme, warnings) {
     if (onMedia.components) {
       generateComponentRules(onMedia.components, parts, {
         resetInheritedPaddingSpecificity: true,
-        surface,
-        sink,
-        location
+        surface
       });
       generateColorOverrides(onMedia.components, parts, surface);
       generateSizeOverrides(onMedia.components, parts, surface);
@@ -801,17 +707,16 @@ export function generateOnMediaCSS(theme, warnings) {
 }
 
 /** Generate only the declarations one adaptation rule writes. */
-function generateAdaptationRuleRules(rule, location, sink) {
+function generateAdaptationRuleRules(rule) {
   const parts = [];
-  const tokens = tokenBlock(rule, location, sink);
-  if (tokens !== null) {
-    parts.push(tokens);
+  const tokenEntries = [...Object.entries(rule.tokens), ...Object.entries(rule.localTokens ?? {})];
+  if (tokenEntries.length > 0) {
+    const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
+    parts.push(`  :scope {\n${declarations}\n  }`);
   }
   if (rule.components) {
     generateComponentRules(rule.components, parts, {
-      resetInheritedPaddingSpecificity: true,
-      sink,
-      location
+      resetInheritedPaddingSpecificity: true
     });
     generateColorOverrides(rule.components, parts);
     generateSizeOverrides(rule.components, parts);
@@ -835,8 +740,7 @@ function generateAdaptationMediaBlock(query, parts, scopeSelector) {
  * rule. Bare prose follows semantic variables, so token writes need no duplicate
  * prose selectors here.
  */
-export function generateAdaptationCSS(theme, warnings) {
-  const sink = diagnosticSink(warnings);
+export function generateAdaptationCSS(theme) {
   // Built themes can reach this compiler without passing through defineTheme.
   // Validate retained metadata even when it has no rules (and therefore emits
   // no CSS): width points remain observable through AppShell and inheritance.
@@ -857,8 +761,8 @@ export function generateAdaptationCSS(theme, warnings) {
   // active whenever the later condition matches, even if the earlier condition
   // does not. Pairwise merging cannot repair that: multiple mutually exclusive
   // earlier rules can each overlap one broad later rule.
-  for (const [index, rule] of rules.entries()) {
-    const parts = generateAdaptationRuleRules(rule, `adaptations[${index}].`, sink);
+  for (const rule of rules) {
+    const parts = generateAdaptationRuleRules(rule);
     if (parts.length === 0) {
       continue;
     }
@@ -893,9 +797,9 @@ export function generateAdaptationCSS(theme, warnings) {
   };
 }
 
-/** Indent the rule start without rewriting newlines inside authored values. */
+/** Indent a generated rule one level further, for nesting inside `@media`. */
 function indentRule(rule) {
-  return `  ${rule}`;
+  return rule.split('\n').map(line => line.length > 0 ? `  ${line}` : line).join('\n');
 }
 
 /**
@@ -934,11 +838,11 @@ export function generateDataTokenDefaultsCSS() {
  * The theme-independent `--color-data-*` defaults are not part of this output:
  * see `generateDataTokenDefaultsCSS`.
  */
-export function generateThemeCSS(theme, warnings) {
+export function generateThemeCSS(theme) {
   const {
     component,
     prose
-  } = generateThemeRulesSplit(theme, warnings);
+  } = generateThemeRulesSplit(theme);
   const scopeSelector = themeScopeStart(theme.name);
   const scopeTo = THEME_SCOPE_TO;
   let proseCss = '';
@@ -957,11 +861,11 @@ export function generateThemeCSS(theme, warnings) {
 
   // Adaptations follow the root theme in authored order. Media-surface rules
   // follow adaptations so onDark/onLight keep their specified precedence.
-  const adaptationCss = generateAdaptationCSS(theme, warnings);
+  const adaptationCss = generateAdaptationCSS(theme);
   if (adaptationCss.component) {
     componentCss = componentCss ? `${componentCss}\n\n${adaptationCss.component}` : adaptationCss.component;
   }
-  const onMediaCss = generateOnMediaCSS(theme, warnings);
+  const onMediaCss = generateOnMediaCSS(theme);
   if (onMediaCss) {
     componentCss = componentCss ? `${componentCss}\n\n${onMediaCss}` : onMediaCss;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.3-canary.f22695a",
+  "version": "0.6.3",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -539,11 +539,6 @@
       "types": "./dist/TimeInput/index.d.ts",
       "default": "./dist/TimeInput/index.js"
     },
-    "./Timer": {
-      "source": "./src/Timer/index.ts",
-      "types": "./dist/Timer/index.d.ts",
-      "default": "./dist/Timer/index.js"
-    },
     "./Timestamp": {
       "source": "./src/Timestamp/index.ts",
       "types": "./dist/Timestamp/index.d.ts",
@@ -692,8 +687,6 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.6.3-canary.f22695a",
-    "@astryxdesign/cli": "0.6.3-canary.f22695a",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -703,7 +696,9 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "@types/babel__core": "^7.20.5"
+    "@types/babel__core": "^7.20.5",
+    "@astryxdesign/a11y-spec": "0.0.0",
+    "@astryxdesign/cli": "0.6.3"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/Button/Button.doc.mjs

@@ -157,8 +157,8 @@ export const docs = {
       name: 'icon',
       type: 'ReactNode',
       description:
-        'Icon element rendered before the label text. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
-      slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
+        'Icon element rendered before the label text.',
+      slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
     },
     {
       name: 'isIconOnly',
@@ -210,7 +210,7 @@ export const docs = {
       name: 'href',
       type: 'string',
       description:
-        'When provided, renders the button as a link element (<a> or custom link component). The destination follows the shared navigation rule described on the Link `href` prop.',
+        'When provided, renders the button as a link element (<a> or custom link component).',
     },
     {
       name: 'as',
@@ -294,7 +294,7 @@ export const docsZh = {
       description: '禁用按钮。存在工具提示时，使用 aria-disabled 代替原生 disabled 以保持可聚焦。',
       default: 'false',
     },
-    {name: 'icon', type: 'ReactNode', description: '图标元素。未显式指定尺寸的 Astryx Icon 在 sm/md 按钮中默认为 sm，在 lg 按钮中默认为 md。仅提供 icon 而不提供 children 时，按钮渲染为正方形的纯图标按钮。'},
+    {name: 'icon', type: 'ReactNode', description: '图标元素。仅提供 icon 而不提供 children 时，按钮渲染为正方形的纯图标按钮。'},
     {name: 'width', type: 'SizeValue', description: "按钮宽度。数字按像素处理，字符串按原样使用（如 '100%' 表示全宽按钮）。默认按内容自适应宽度。"},
     {name: 'children', type: 'ReactNode', description: '可选的可见内容覆盖；label 仍然是必需的（用于无障碍名称）。大多数情况使用 <Button label="Save" />。'},
     {
@@ -361,7 +361,7 @@ export const docsDense = {
     value: 'HTML value for form submission',
     form: 'associates button with form element by ID',
     isLoading: 'shows spinner+disables interaction; announces via live region',
-    icon: 'icon element rendered before label text; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
+    icon: 'icon element rendered before label text',
     isIconOnly: 'when true, renders square icon-only button; label becomes aria-label',
     width: "Width of button. Numbers=pixels, strings=as-is (e.g. '100%' for full-width).",
     children: 'optional visible override; label is still required for a11y. Prefer <Button label="Save" /> over using children',

package/src/Button/Button.tsx

@@ -38,8 +38,6 @@ import {
 } from '../theme/tokens.stylex';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
-import {IconDefaultSizeProvider} from '../Icon/IconDefaultSizeContext';
-import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
@@ -172,6 +170,17 @@ const sizeStyles = stylex.create({
   },
 });
 
+/**
+ * Icon size per button size.
+ * Matches Icon sizing: sm/md=16px, lg=20px.
+ * fontSize is set so emoji and text-based icons scale correctly.
+ */
+const iconSizeStyles = stylex.create({
+  sm: {width: 16, height: 16, fontSize: 16},
+  md: {width: 16, height: 16, fontSize: 16},
+  lg: {width: 20, height: 20, fontSize: 20},
+});
+
 /**
  * Resting elevation for floating buttons (e.g. a FAB). `none` is the default
  * flat button; `low`/`med`/`high` map to the shadow token scale. 'none' stays
@@ -224,12 +233,6 @@ export type ButtonVariant = keyof ButtonVariantMap;
  */
 export type ButtonSize = keyof typeof sizeStyles;
 
-const iconSizeByButtonSize = {
-  sm: 'sm',
-  md: 'sm',
-  lg: 'md',
-} satisfies Record<ButtonSize, IconSize>;
-
 export interface ButtonProps extends BaseProps<HTMLButtonElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLButtonElement>;
@@ -680,8 +683,6 @@ export function Button({
     style,
   );
 
-  const iconSize = iconSizeByButtonSize[size];
-
   const buttonContent = (
     <>
       {isLoadingState && (
@@ -704,11 +705,8 @@ export function Button({
         )}
         aria-hidden={isLoadingState || undefined}>
         {icon && (
-          <span
-            {...stylex.props(styles.iconWrapper, iconBoxSizeStyles[iconSize])}>
-            <IconDefaultSizeProvider value={iconSize}>
-              {icon}
-            </IconDefaultSizeProvider>
+          <span {...stylex.props(styles.iconWrapper, iconSizeStyles[size])}>
+            {icon}
           </span>
         )}
         {isIconOnly ? null : (

package/src/Chat/ChatLayout.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'ChatLayout',
   subComponentOf: 'Chat',
   displayName: 'Chat Layout',
-  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
+  description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Adapts density (compact/balanced/spacious) automatically via container width observation. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
   props: [
     {
       name: 'children',
@@ -53,15 +53,9 @@ export const docs = {
       type: 'React.RefObject<HTMLElement | null>',
       description: 'External scroll container ref. When provided, auto-scroll and scroll-to-bottom target this element instead of the layout root. Use when the chat is embedded in a page where a parent element or the document body scrolls.',
     },
-    {
-      name: 'density',
-      type: "'compact' | 'balanced' | 'spacious'",
-      description: 'Visual density: controls dock padding, message-area max-width and inline padding, and the height of the frosted glass blur layer.',
-      default: "'balanced'",
-    },
   ],
   usage: {
-    description: 'ChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Set the density prop to control spacing; it defaults to balanced. Use it to wrap ChatMessageList and ChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
+    description: 'ChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Density adapts automatically via container width observation. Use it to wrap ChatMessageList and ChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
     bestPractices: [
       {
         guidance: true,
@@ -117,21 +111,20 @@ export const docs = {
 export const docsZh = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过 density 属性控制密度。',
+  description: '完整聊天界面的布局外壳。消息在页面中自然流动，编写器固定在底部，带有毛玻璃效果。通过容器宽度自动适配密度。',
   propDescriptions: {
     children: '消息内容，通常是 ChatMessageList。在页面中自然流动。',
     composer: '编写器元素，通常是 ChatComposer。固定在底部，带有毛玻璃底座。',
     emptyState: '子元素为空时显示的内容。',
     scrollButton: '编写器上方的滚动到底部按钮。默认使用 ChatLayoutScrollButton。传入 null 隐藏。',
     scrollRef: '外部滚动容器引用。提供时，自动滚动和滚动到底部将目标指向此元素。',
-    density: '视觉密度：控制底座内边距、消息区最大宽度和毛玻璃层高度。',
   },
 };
 
 export const docsDense = {
   name: 'ChatLayout',
   displayName: 'Chat Layout',
-  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body',
+  description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; auto density via container width; scrollRef delegates to parent/body',
   usage: {
     bestPractices: [
       {guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},
@@ -147,6 +140,5 @@ export const docsDense = {
     emptyState: 'content when children empty',
     scrollButton: 'scroll-to-bottom btn; defaults to ChatLayoutScrollButton; pass null to hide',
     scrollRef: 'external scroll container ref; targets parent/body instead of layout root',
-    density: 'visual density; dock padding, message max-width, blur height',
   },
 };

package/src/Chat/ChatLayout.test.tsx

@@ -2,7 +2,6 @@
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, render, screen} from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
 import {ChatLayout} from './ChatLayout';
 import {ChatMessageList} from './ChatMessageList';
 import {ChatMessage} from './ChatMessage';
@@ -104,33 +103,6 @@ describe('ChatLayout', () => {
   });
 });
 
-// ---------------------------------------------------------------------------
-// Keyboard reachability of the default scroll-to-bottom button
-//
-// At rest the layout is neither scrolled up nor holding new messages, so the
-// default ChatLayoutScrollButton renders in its hidden state. It is still in
-// the DOM, and it is the first control in the dock — ahead of the composer.
-// A control nobody can see must not be a tab stop: WCAG 2.2 SC 2.4.7 requires
-// a visible focus indicator wherever focus can land, and the hidden pill paints
-// nothing. `opacity: 0` and `pointer-events: none` do not remove an element
-// from sequential focus navigation; only visibility/display/inert do.
-// ---------------------------------------------------------------------------
-
-describe('ChatLayout — default scroll button keyboard reachability', () => {
-  it('does not make the resting scroll-to-bottom button the first tab stop', async () => {
-    const user = userEvent.setup();
-    render(
-      <ChatLayout composer={<button type="button">Send</button>}>
-        <div>msg</div>
-      </ChatLayout>,
-    );
-
-    await user.tab();
-
-    expect(screen.getByRole('button', {name: 'Send'})).toHaveFocus();
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Self-scroll layout contract (#2573)
 //

package/src/Chat/ChatLayout.tsx

@@ -268,25 +268,6 @@ function hasVisibleContent(children: ReactNode): boolean {
 // Component
 // =============================================================================
 
-/**
- * Layout shell for a full chat interface: messages in page flow, composer
- * docked to the bottom behind a frosted glass layer, with auto-scroll and a
- * scroll-to-bottom button wired in.
- *
- * @example
- * ```
- * <ChatLayout
- *   density="spacious"
- *   composer={<ChatComposer onSubmit={send} />}
- *   emptyState={<EmptyState title="No messages yet" />}>
- *   <ChatMessageList>
- *     <ChatMessage sender="assistant">
- *       <ChatMessageBubble>How can I help?</ChatMessageBubble>
- *     </ChatMessage>
- *   </ChatMessageList>
- * </ChatLayout>
- * ```
- */
 export function ChatLayout({
   children,
   composer,

package/src/Chat/ChatLayoutScrollButton.test.tsx

@@ -2,7 +2,6 @@
 
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
 import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
 
 describe('ChatLayoutScrollButton', () => {
@@ -53,34 +52,4 @@ describe('ChatLayoutScrollButton', () => {
     expect(root).toHaveAttribute('data-custom', 'x');
     expect(root).toHaveAttribute('id', 'scroll-1');
   });
-
-  // The hidden state paints nothing, so focus landing on it would have no
-  // visible indicator (WCAG 2.2 SC 2.4.7). `opacity: 0` and
-  // `pointer-events: none` suppress paint and the pointer but leave the button
-  // in sequential focus navigation, so the hidden state must also stop being
-  // focusable — without costing the visible state its keyboard access.
-  it('is keyboard reachable while visible', async () => {
-    const user = userEvent.setup();
-    render(<ChatLayoutScrollButton isVisible onClick={() => {}} />);
-
-    await user.tab();
-
-    expect(
-      screen.getByRole('button', {name: 'Scroll to bottom'}),
-    ).toHaveFocus();
-  });
-
-  it('is not keyboard reachable while hidden', async () => {
-    const user = userEvent.setup();
-    render(
-      <>
-        <ChatLayoutScrollButton isVisible={false} onClick={() => {}} />
-        <button type="button">After</button>
-      </>,
-    );
-
-    await user.tab();
-
-    expect(screen.getByRole('button', {name: 'After'})).toHaveFocus();
-  });
 });