@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/DropdownMenu/__tests__/Menu.a11y.test.tsx

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Menu.a11y.test.tsx
+ * @input MENU_PATTERN bound to the open DropdownMenu pointer menu
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for the DropdownMenu menu surface (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {describe, expect, it} from 'vitest';
+import {
+  MENU_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {MENU_KNOWN_FAILURES} from './Menu.a11y.known-failures';
+import {renderMenuState} from './Menu.a11y.renders';
+import {
+  MENU_BINDING_STATES,
+  MENU_EXCLUSIONS,
+  type MenuBindingState,
+} from './Menu.a11y.states';
+
+function trigger(state: MenuBindingState): HTMLElement {
+  return screen.getByRole('button', {name: state.label});
+}
+
+function menuFor(state: MenuBindingState): HTMLElement {
+  const id = trigger(state).getAttribute('aria-controls');
+  const menu = id == null ? null : document.getElementById(id);
+  if (menu == null) {
+    throw new Error(`menu state "${state.id}" has no controlled menu`);
+  }
+  return menu;
+}
+
+function relatedFor(
+  state: MenuBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {opener: trigger(state)};
+  for (const [relation, [role, name]] of Object.entries(state.items)) {
+    related[relation] = screen.getByRole(role, {name, hidden: true});
+  }
+  return related;
+}
+
+async function open(state: MenuBindingState): Promise<void> {
+  render(renderMenuState(state));
+  await userEvent.setup().click(trigger(state));
+}
+
+async function checkState(state: MenuBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_PATTERN,
+    binding: 'DropdownMenu.menu',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_KNOWN_FAILURES,
+    mount: async () => {
+      await open(state);
+      return createJsdomHarness({
+        subject: menuFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('DropdownMenu pointer menu — menu pattern, jsdom lane', () => {
+  it.each(
+    MENU_BINDING_STATES.map(state => [state.id, state.summary, state] as const),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: MENU_PATTERN,
+      binding: 'DropdownMenu.menu',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: MENU_KNOWN_FAILURES,
+      render: async () => {
+        await open(state);
+      },
+      subject: () => menuFor(state),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of MENU_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(MENU_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('menu binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = MENU_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps the opening control, submenus and dialog presentations explicit', () => {
+    expect(MENU_EXCLUSIONS.map(row => row.id)).toEqual([
+      'opening-control',
+      'submenus',
+      'bottom-sheet-and-header-footer',
+    ]);
+    for (const exclusion of MENU_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the menu and every item relation it names for every state', async () => {
+    for (const state of MENU_BINDING_STATES) {
+      await open(state);
+      expect(menuFor(state).getAttribute('role'), state.id).toBe('menu');
+      expect(Object.keys(relatedFor(state)), state.id).toEqual([
+        'opener',
+        ...Object.keys(state.items),
+      ]);
+      cleanup();
+    }
+  });
+});

package/src/EmptyState/EmptyState.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
       name: 'title',
       type: 'string',
       description:
-        'Primary message rendered as an <h3> heading inside the empty state.',
+        'Primary message rendered as the configured heading level inside the empty state.',
       required: true,
     },
     {
@@ -81,6 +81,7 @@ export const docs = {
       { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
     ],
     anatomy: [
+      {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},
       {name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
       {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
       {name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},
@@ -98,7 +99,7 @@ export const docsZh = {
       name: 'title',
       type: 'string',
       description:
-        '在空状态内部渲染为 <h3> 标题的主要信息。',
+        '在空状态内部按配置的标题级别渲染主要信息。',
       required: true,
     },
     {

package/src/EmptyState/EmptyState.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:EmptyState
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
+verified_by:
+  [
+    packages/core/src/EmptyState/EmptyState.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/docPropReferences.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: [spec:AST-020/FR1, spec:AST-029/FR3]
+---
+
+# EmptyState component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one status region; callers choose heading level and compact layout.                |
+| Behavior                | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions.   |
+| End-user impact         | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline.                       |
+| Builder impact          | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required.                                                 |
+| Compatibility/readiness | The released default is preserved. This draft observes shipped behavior plus the narrow scalar-slot remediation; it adds no API, default, or compatibility promise.                              |
+| Review checks           | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
+| Governing rules         | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2.          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`EmptyState` gives an otherwise empty content area a semantic heading, supporting
+context, optional decorative visual, and optional caller-owned next actions.
+
+## Compatibility and migration
+
+- Released default preserved: yes
+- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- the status-region root, content order, heading element, and default/compact layout;
+- hiding the icon slot from assistive technology as decorative; and
+- whether optional slots create component-owned wrappers and spacing.
+
+**Does not own / non-goals**
+
+- the message copy, icon meaning, action controls, or action behavior — those belong to the product callsite and the components it supplies;
+- page-level heading order — the caller chooses `headingLevel` for its document; or
+- error, loading, or populated-content behavior.
+
+## Public concepts
+
+| Concept        | Closed values or states | Meaning                                                                   | Availability by variant/orientation/state | Default  | Owner                  | Stability | Invalid-value behavior                                  |
+| -------------- | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ---------------------- | --------- | ------------------------------------------------------- |
+| title          | string                  | The empty region's heading content.                                       | all                                       | required | `component:EmptyState` | stable    | type rejection                                          |
+| description    | string or absent        | Optional supporting context below the title.                              | all                                       | absent   | `component:EmptyState` | stable    | nullish and empty-string values omit the part           |
+| icon           | React node or absent    | Optional caller visual, exposed as decorative beside the textual message. | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
+| actions        | React node or absent    | Optional caller-owned next actions below the message.                     | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
+| heading level  | `1` through `6`         | The title's HTML heading level in the surrounding document outline.       | all                                       | `3`      | product callsite       | stable    | type rejection                                          |
+| layout variant | default, compact        | Compact reduces spacing and stacks the action slot vertically.            | all                                       | default  | `component:EmptyState` | stable    | type rejection                                          |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID  | Candidate invariant                                                                                                                                                                     | Basis                                                                                | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
+| FR1 | The component MUST render one status-region root containing the icon, text group, and actions in that reading order when present.                                                       | Current implementation and consumer docs; WCAG 2.2 SC 1.3.2 and SC 4.1.3             | verify             |
+| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     | verify             |
+| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify             |
+| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  | verify             |
+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the status-region root.                                                               | `architecture:public-component-api` INV5–INV8                                        | verify             |
+| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     | verify             |
+
+### Allowed variation
+
+- **AV1 — Caller content.** Message wording, decorative artwork, and action
+  composition may vary at the product callsite.
+- **AV2 — Theme paint.** Theme-controlled paint and typography may vary through
+  the documented targets while anatomy and content order remain stable.
+
+### Representative states
+
+| State                         | Required invariant                                        | Allowed variation                      |
+| ----------------------------- | --------------------------------------------------------- | -------------------------------------- |
+| title only                    | status root and selected heading level remain present     | message wording                        |
+| description                   | supporting text follows the title                         | text length and wrapping               |
+| decorative icon               | visual precedes text and is hidden from assistive tech    | artwork supplied by the caller         |
+| actions                       | caller controls follow the text group                     | one or more caller-owned controls      |
+| compact                       | reduced spacing and vertical actions preserve semantics   | theme paint and caller content         |
+| shallow-empty optional scalar | nullish, boolean, and empty-string values emit no wrapper | which optional slot receives the value |
+
+### Transformation and precedence order
+
+- **ORD1 — Root composition.** Component semantics and theme metadata combine
+  with component styles, then consumer `xstyle`, `className`, and `style` under
+  the shared merge contract; component-owned `role="status"` remains authoritative.
+
+### Performance and resources
+
+- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
+  observer, timer, or external resource.
+
+## Accessibility contract
+
+- **AR1 — Heading semantics.** The title is a heading at the caller-selected level.
+- **AR2 — Decorative visual.** The icon slot is hidden from assistive technology;
+  callers keep all necessary meaning in the title or description.
+- **AR3 — Status exposure.** The root exposes the empty message as a status region
+  without moving focus; action controls keep their own names, roles, and behavior.
+
+## Design relationships
+
+No current design record governs EmptyState-specific representation. Visual
+judgment remains evidence, not product authority.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "empty-state"},
+  "Icon": {
+    "none": {
+      "reason": "intentional: caller-supplied decorative content keeps its own styling and has no component-owned paint target"
+    }
+  },
+  "Title": {"target": "empty-state-title"},
+  "Description": {"target": "empty-state-description"},
+  "Actions": {
+    "none": {
+      "reason": "intentional: caller-supplied controls keep their own component targets and behavior"
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+No current family record owns EmptyState-specific behavior.
+
+## Verification map
+
+| Contract       | Verification                                                        | Representative states                             | Mutation or failure expectation                                      | Audit section             |
+| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
+| FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence   | title only, all slots, absent/shallow-empty slots | order, heading, status, or decorative treatment regresses            | `audit:EmptyState/a11y`   |
+| FR5, ORD1      | focused root composition tests plus shared API guards               | DOM/data/event/style inputs, ref, root target     | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api`    |
+| FR6            | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow              | compact state, spacing, or action direction no longer applies        | `audit:EmptyState/layout` |
+| PR1            | source review                                                       | every render path                                 | a retained resource appears without a named owner                    | `audit:EmptyState/code`   |
+
+## Decision log
+
+No component-local decision is approved in this draft.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/EmptyState/EmptyState.test.tsx

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {EmptyState} from './EmptyState';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -11,6 +12,12 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   return [prose, component].filter(Boolean).join('\n\n');
 }
 
+const testStyles = stylex.create({
+  root: {
+    minWidth: '123px',
+  },
+});
+
 describe('EmptyState', () => {
   it('renders with title', () => {
     render(<EmptyState title="No results found" />);
@@ -52,7 +59,7 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
-    // Description renders as <div> (never <p>) so block content composes safely.
+    // Description keeps its stable target element instead of paragraph semantics.
     expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
@@ -132,6 +139,70 @@ describe('EmptyState', () => {
     expect(screen.getByTestId('empty-state')).toBeInTheDocument();
   });
 
+  it('does not render empty optional slot wrappers', () => {
+    const {container} = render(
+      <EmptyState title="No results" description="" icon={false} actions="" />,
+    );
+    const root = screen.getByRole('status');
+    expect(root).toHaveTextContent('No results');
+    expect(root).toHaveTextContent(/^No results$/);
+    expect(root.children).toHaveLength(1);
+    expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
+    expect(
+      container.querySelector('.astryx-empty-state-description'),
+    ).toBeNull();
+  });
+
+  it('composes root props and keeps component semantics authoritative', () => {
+    const onClick = vi.fn();
+    const expectedXstyleClass = stylex.props(testStyles.root).className;
+    if (expectedXstyleClass == null) {
+      throw new Error('Expected the test xstyle to produce a class name.');
+    }
+    render(
+      <EmptyState
+        title="No results"
+        role="region"
+        data-owner="consumer"
+        className="consumer-class"
+        style={{width: '321px'}}
+        xstyle={testStyles.root}
+        onClick={onClick}
+      />,
+    );
+
+    const root = screen.getByRole('status');
+    expect(root).toHaveClass('astryx-empty-state', 'consumer-class');
+    expect(root).toHaveClass(expectedXstyleClass);
+    expect(root).toHaveAttribute('data-owner', 'consumer');
+    expect(root).toHaveStyle({width: '321px'});
+    fireEvent.click(root);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('reflects compact layout on the root and preserves slot order', () => {
+    render(
+      <EmptyState
+        title="No results"
+        description="Try again."
+        icon={<span data-testid="icon">Icon</span>}
+        actions={<button type="button">Retry</button>}
+        isCompact
+      />,
+    );
+
+    const root = screen.getByRole('status');
+    expect(root).toHaveAttribute('data-variant', 'compact');
+    expect(root.children).toHaveLength(3);
+    expect(root.children[0]).toContainElement(screen.getByTestId('icon'));
+    expect(root.children[1]).toContainElement(
+      screen.getByRole('heading', {name: 'No results'}),
+    );
+    expect(root.children[2]).toContainElement(
+      screen.getByRole('button', {name: 'Retry'}),
+    );
+  });
+
   it('renders all slots together', () => {
     render(
       <EmptyState

package/src/EmptyState/EmptyState.tsx

@@ -23,7 +23,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -169,7 +169,7 @@ export function EmptyState({
         className,
         style,
       )}>
-      {icon != null && <div aria-hidden="true">{icon}</div>}
+      {isRenderable(icon) && <div aria-hidden="true">{icon}</div>}
       <div {...stylex.props(styles.textGroup)}>
         {createElement(
           HeadingTag,
@@ -181,11 +181,7 @@ export function EmptyState({
           ),
           title,
         )}
-        {description != null && (
-          // Rendered as <div> (not <p>): description accepts ReactNode and a
-          // <p> cannot legally contain block children, which causes hydration
-          // mismatches. The StyleX style sets margin: 0, so appearance is
-          // unchanged.
+        {isRenderable(description) && (
           <div
             {...mergeProps(
               themeProps('empty-state-description', {
@@ -200,7 +196,7 @@ export function EmptyState({
           </div>
         )}
       </div>
-      {actions != null && (
+      {isRenderable(actions) && (
         <div
           {...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>
           {actions}

package/src/Field/Field.doc.mjs

@@ -114,7 +114,7 @@ export const docs = {
     },
     {
       name: 'labelIcon',
-      type: 'IconType',
+      type: 'ReactNode | IconType',
       description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
@@ -129,8 +129,8 @@ export const docs = {
     },
     {
       name: 'statusVariant',
-      type: "'attached' | 'detached'",
-      description: 'How the status message renders relative to the input. Attached overlaps the input border; detached floats below.',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description: 'How status feedback is placed. Attached overlaps an eligible opaque, bordered, fixed-height control; detached renders a message below custom or non-bordered controls; tooltip leaves the visible affordance to the wrapped input and announces its message without a FieldStatus box.',
       default: "'attached'",
     },
     {
@@ -170,17 +170,23 @@ export const docs = {
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
       { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
       { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
-      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
+      { guidance: true, description: 'Use attached status only when the wrapped control is opaque, bordered, and fixed-height; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
     anatomy: [
+      {name: 'Container', required: true, description: 'Root field box that owns layout, width, and local stacking for the label, control, and status.'},
       {name: 'Label', required: true, description: 'Text identifying the field. Always rendered for accessibility, optionally hidden visually.'},
-      {name: 'Description', required: false, description: 'Helper text between the label and input explaining what to enter.'},
+      {name: 'Ordinary description', required: false, description: 'Helper text under the label in the ordinary field layout.'},
+      {name: 'Horizontal-label description', required: false, description: 'Helper text in the control column when FormLayout owns horizontal labels.'},
       {name: 'Control slot', required: true, description: 'A custom, native, or third-party control that does not already render a field shell.'},
       {name: 'Status message', required: false, description: 'Inline validation feedback showing error, warning, or success with a message.'},
+      {name: 'Input status icon', required: false, description: 'Shared status affordance used by Field-composed input controls.'},
+      {name: 'Input clear button', required: false, description: 'Shared clear action used by Field-composed input controls.'},
+      {name: 'Input clear icon', required: false, description: 'Glyph inside the shared input clear action.'},
       {name: 'Optional/Required indicator', required: false, description: 'Badge next to the label showing whether the field is optional or required.'},
-      {name: 'Label tooltip', required: false, description: 'Info icon at the end of the label with a tooltip explaining the field.'},
+      {name: 'Label tooltip trigger', required: false, description: 'Info icon beside the label that opens explanatory content.'},
+      {name: 'Label tooltip surface', required: false, description: 'Layer-hosted explanatory content for the label tooltip.'},
     ],
   },
   examples: [
@@ -279,7 +285,7 @@ export const docsZh = {
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
       { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
       { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
-      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
+      { guidance: true, description: 'Use attached status only when the wrapped control is opaque, bordered, and fixed-height; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
@@ -297,7 +303,7 @@ export const docsDense = {
       { guidance: true, description: 'Always provide a label; visually hide it only when context is clear.' },
       { guidance: true, description: 'Wire inputID/descriptionID to htmlFor and aria-describedby on the inner control.' },
       { guidance: false, description: 'Nest Field around styled inputs; it double-renders labels and status UI.' },
-      { guidance: false, description: 'Use attached status on sliders/switches/checkboxes; use detached so messages do not overlap.' },
+      { guidance: true, description: 'Use attached status only for opaque, bordered, fixed-height controls; use detached for custom, tall, translucent, or non-bordered controls.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
       { guidance: false, description: 'Hide the label without another way to understand field purpose.' },
     ],