@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Text/Text.spec.md

@@ -1,199 +1,187 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Text
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
+    .github/visual-baseline/manifest.json,
     packages/core/src/Text/Text.test.tsx,
-    packages/core/src/Heading/Heading.test.tsx,
+    packages/core/src/Text/useTruncation.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
+    apps/storybook/stories/Text.stories.tsx,
   ]
 modules: []
 families: []
 design_specs: []
-architecture: [architecture:component-theming-surface]
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-009]
 ---
 
 # Text component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A polymorphic text element with a semantic `type`, optional `size`, `color`, and `weight` overrides, an `as` element choice, and the text layout controls documented in `Text.doc.mjs`.    |
+| Behavior                | `type` sets size, weight, and default color from the theme; theme-added types and colors fall back to the body and primary baselines; truncated text offers its full content in a Tooltip. |
+| End-user impact         | Readers get consistent type across the product; clamped text keeps its full content available on hover and in the DOM.                                                                     |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                               |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                    |
+| Review checks           | Reject a theme-added type or color that renders unstyled, a native `title` beside the truncation Tooltip, or measurement when the tooltip is off.                                          |
+| Governing rules         | `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`.                                                                                   |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Text renders themed body text through the Text component and semantic headings
-through its referenced Heading member. This draft records their current consumer
-anatomy, the two live root targets owned by the canonical Text documentation, and
-the conditional Tooltip delegation used for truncated content. It does not
-change runtime behavior, styling, targets, or public API.
+Text renders themed body copy, labels, captions, and display text. It owns the
+mapping from a semantic type to theme typography, the element it renders, and
+the truncation behavior of that element. Heading is documented beside Text in
+`Text.doc.mjs` but is a separate component with its own record.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Truncation tooltip not reachable by keyboard (FR4).** A truncated Text
+  is not focusable, so Tooltip attaches no focus trigger and sighted keyboard
+  users cannot reveal the clipped text, where WCAG 2.2 2.1.1 expects
+  functionality to be keyboard operable. The full text stays in the DOM for
+  assistive technology.
+
 ## Ownership boundary
 
 **Owns**
 
-- The polymorphic Text element and its current `text` theming target.
-- The referenced Heading member's semantic heading element and its current
-  `heading` theming target.
-- Deciding from the current truncation state whether to compose Tooltip against
-  the Text or Heading element.
+- The polymorphic text element and its `text` theming target.
+- Type-based size, weight, and default color; size, color, and weight
+  overrides; and the text layout controls on that element.
+- Measuring truncation and deciding when to compose the truncation Tooltip.
 
 **Does not own / non-goals**
 
-- The truncation tooltip surface, layer behavior, or `tooltip` target — owned by
-  Tooltip when that composed surface renders.
-- Content supplied as Text or Heading children — owned by the caller.
-- A separate Heading component contract; Heading remains a referenced member of
-  the canonical Text documentation and target inventory.
-- New typography behavior, truncation behavior, semantics, styling, targets,
-  public API, or target aliases.
+- Heading, its `h1`–`h6` element, and its `heading` target — owned by
+  `component:Heading`. The `heading` target and Heading anatomy listed in
+  `Text.doc.mjs` belong to that record.
+- The truncation tooltip surface, layer, and `tooltip` target — owned by
+  Tooltip.
+- Typography token values — owned by the active theme.
+- Text content — owned by the caller.
 
 ## Public concepts
 
-No new public concept is introduced. Text and Heading props, defaults, and usage
-remain documented in `Text.doc.mjs` and `Heading.doc.mjs`.
+| Concept    | Closed values or states                                                                                           | Meaning                                               | Availability by variant/orientation/state | Default                                                               | Owner            | Stability | Invalid-value behavior                                                            |
+| ---------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | ---------------- | --------- | --------------------------------------------------------------------------------- |
+| Type       | `body`, `large`, `label`, `supporting`, `code`, `display-1`, `display-2`, `display-3`, `inherit`; theme additions | Selects size, weight, line height, and default color. | Always                                    | `body`                                                                | `component:Text` | Stable    | A theme-added type is reflected on `text` and renders with body baseline styles.  |
+| Color      | built-in text colors; theme additions                                                                             | Text color.                                           | Always                                    | `secondary` for `supporting`, `inherit` for `inherit`, else `primary` | `component:Text` | Stable    | A theme-added color is reflected on `text` and renders with the primary baseline. |
+| Element    | `span`, `p`, `div`, `label`, `h1`, `h2`, `h3`                                                                     | The rendered element.                                 | Always                                    | `span`                                                                | `component:Text` | Stable    | TypeScript rejects other values.                                                  |
+| Truncation | `maxLines` 0 (none), 1, or more; tooltip on, off, or at a placement                                               | Clamps lines and offers the full text in a Tooltip.   | Always                                    | 0; tooltip on                                                         | `component:Text` | Stable    | —                                                                                 |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                          | Basis                                             | Draft review state                                    |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------- |
-| FR1 | Text renders one polymorphic text element carrying the current `text` target.                                                                                                                                                                                                                | Current source, docs, and tests                   | Verified current behavior; no new behavior decided    |
-| FR2 | Heading renders one semantic `h1`–`h6` element carrying the current `heading` target. Heading is a referenced member of Text rather than a nested Text element.                                                                                                                              | Current source, docs, tests, and target history   | Verified current behavior and canonical ownership     |
-| FR3 | Text or Heading composes Tooltip only when `maxLines` is positive, truncation tooltips are enabled, and measurement reports that the rendered content is truncated. Otherwise the truncation Tooltip path does not render.                                                                   | Current source, tests, and truncation history     | Verified current conditional behavior                 |
-| FR4 | When the conditional truncation path renders, Tooltip owns the layer surface and applies the `tooltip` target. Text and Heading retain their own root targets and do not apply or claim Tooltip's target.                                                                                    | Current source and owner target metadata          | Verified current ownership; no target change          |
-| FR5 | Text reflects `type`, `size`, and resolved `color` on `text`; Heading reflects `level`, `color`, and an explicitly supplied `type` on `heading`. Display mode, truncation state, semantic element choice, and Tooltip open state do not become separate anatomy parts or Text-owned targets. | Current source, docs, tests, and target inventory | Verified current capabilities; no new anatomy decided |
-
-### Observed current behavior
-
-These observations describe the implementation; they do not establish new
-intent:
-
-- Text defaults to a `span` and may render another supported text element through
-  `as`. Heading maps `level` directly to `h1` through `h6`.
-- Both members render caller content directly inside their targeted root element;
-  neither creates a separately targeted content wrapper.
-- Both members measure truncation only when `maxLines` is positive. When the
-  measurement reports overflow and `hasTruncateTooltip` is not `false`, they
-  lazy-load Tooltip in sibling-anchor mode.
-- Tooltip owns its layer lifecycle and applies `tooltip` only to its own rendered
-  layer. The truncated Text or Heading element remains the anchor and keeps only
-  its own target.
-- Text and Heading no longer add a native `title` for this path; the composed
-  Tooltip is the single tooltip presentation.
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| FR1 | Text renders one element chosen by `as` (default `span`) carrying the `text` target, which reflects `type`, `size`, and the resolved `color`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source and tests |
+| FR2 | A built-in `type` applies its size, line height, and default weight; a theme-added type applies the body baseline. `size` overrides the type's size while keeping its other properties; `weight` overrides the type's default weight. The resolved color is `color`, else the type's default; a theme-added color applies the primary baseline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR3 | `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `inline`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap`, `hasStrikethrough`, and `hasTabularNumbers` apply their text treatments.                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
+| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the element shows the full text at the given placement (default `above`), and Text adds no native `title`. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the element is not focusable (Current-state impact). Truncation re-measures when the content changes without a resize. | Current source and tests |
+| FR5 | `ref` reaches the element. Supported DOM, ARIA, data, and event props reach it; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
 
 ### Allowed variation
 
-- **AV1 — Text element and content.** Text may use any currently supported `as`
-  element and either member may contain caller-supplied content without changing
-  target ownership.
-- **AV2 — Typography.** Level, type, size, color, weight, wrapping, decoration,
-  and theme or consumer styling may vary through the existing APIs and targets.
-- **AV3 — Conditional tooltip.** Fitting content, disabled truncation tooltips,
-  and non-truncating configurations omit the delegated Tooltip path.
+- **AV1 — Theme paint.** A theme may restyle `text` per `type`, `size`, and
+  `color`, and define added types and colors, without changing the element.
+- **AV2 — Element.** Callers choose any supported `as` element.
 
 ### Representative states
 
-| State                                     | Required invariant                                                                         | Allowed variation                                 |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------- |
-| Text without truncation                   | One Text element carries `text`; no truncation Tooltip path renders.                       | Supported element, content, and typography props. |
-| Heading without truncation                | One semantic heading carries `heading`; no Text target or truncation Tooltip path renders. | Heading level, accessibility level, and type.     |
-| Truncation configured but content fits    | The owning Text or Heading root remains; no truncation Tooltip path renders.               | Line limit and available width.                   |
-| Truncated with tooltip disabled           | The owning root remains clipped; no truncation Tooltip path renders.                       | Text or Heading owner.                            |
-| Truncated with tooltip enabled and opened | The owning root anchors one Tooltip-owned surface carrying `tooltip`.                      | Placement and full text content.                  |
+| State                   | Required invariant                                      | Allowed variation |
+| ----------------------- | ------------------------------------------------------- | ----------------- |
+| Default                 | `span` with body type and primary color.                | Content.          |
+| Supporting              | Supporting type with secondary color.                   | Color override.   |
+| Theme-added type        | Body baseline; `data-type` names the added type.        | Theme paint.      |
+| Truncated with tooltip  | Clamped element anchors one Tooltip; no native `title`. | Placement.        |
+| Truncation, tooltip off | Clamped element; no measurement; no Tooltip.            | —                 |
 
 ### Transformation and precedence order
 
-- No new typography, truncation, element-selection, or styling precedence rule is
-  introduced.
+- **ORD1 — Color.** `color` → type default → `primary`; a theme-added value
+  styles from the primary baseline.
+- **ORD2 — Size and weight.** `size` and `weight` → type values → body baseline
+  for a theme-added type.
+- **ORD3 — Display.** `hasCapsize` (`block`) → `maxLines` above 1 (line-clamp
+  box) → `maxLines={1}` (`block`) → `display` prop.
 
 ### Performance and resources
 
-- This draft records the current shared ResizeObserver-based truncation path and
-  lazy Tooltip composition but introduces no new measurement, observer, render,
-  or loading requirement.
+- **PR1 — Measured only when needed.** Truncation is measured only when
+  `maxLines` is positive and the tooltip is enabled; re-measuring follows size
+  and content changes without a per-element observer; the Tooltip module loads
+  only when the text is truncated.
 
 ## Accessibility contract
 
-This draft does not change or extend Text's polymorphic semantics, Heading's
-native heading level and optional `aria-level`, or Tooltip's existing
-`aria-describedby` ownership for truncated content.
+- **AR1 — Caller-chosen semantics.** Text adds no role; its semantics are those
+  of the `as` element. Heading semantics for section titles come from
+  `component:Heading`.
+- **AR2 — Truncated text.** The full text stays in the element's DOM; the
+  truncation Tooltip is the only tooltip, and any description it adds is
+  Tooltip's.
 
 ## Design relationships
 
-| Anatomy or state   | Design requirement                                                                | Representation authority       | Hierarchy role | Component contract |
-| ------------------ | --------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Text               | Presents caller content in the current polymorphic text element.                  | Current source and public docs | Prominent      | FR1, FR5           |
-| Heading            | Presents caller content in the referenced semantic Heading member.                | Current source and public docs | Prominent      | FR2, FR5           |
-| Truncation tooltip | Presents the full content only on the current measured-overflow and enabled path. | `component:Tooltip`            | Supporting     | FR3, FR4           |
+| Anatomy or state   | Design requirement                           | Representation authority | Hierarchy role | Component contract |
+| ------------------ | -------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Text               | Caller content in themed typography.         | Current source and docs  | Prominent      | FR1–FR3, AR1       |
+| Heading            | A separate component documented beside Text. | `component:Heading`      | Prominent      | —                  |
+| Truncation tooltip | The full text when the element is clamped.   | Tooltip                  | Supporting     | FR4, AR2           |
 
-Text and Heading are sibling public components represented by the canonical Text
-documentation; Heading is not nested inside Text. The Tooltip row is conditional
-composition rather than a Text- or Heading-owned surface.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Text": {"target": "text"},
-  "Heading": {"target": "heading"},
-  "Truncation tooltip": {
-    "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
-  }
-}
-```
-
-The two local targets are the exact current targets declared by the canonical
-Text doc. The delegated `tooltip` target applies only when the conditional
-truncation path reaches Tooltip and Tooltip renders its layer; it is not a
-Text- or Heading-owned target. No anatomy part requires a `none` disposition.
+Theming: the element is the single `text` target. `Text.doc.mjs` also lists the
+`heading` target and Heading anatomy, which `component:Heading` owns, so this
+record declares no anatomy-theming block rather than assign `heading` to Text.
 
 ## Family and system relationships
 
-- `architecture:component-theming-surface` owns anatomy qualification, aggregate
-  parent/member target ownership, exact target mapping, and delegation.
-- Text is the canonical documentation and contract owner for both `text` and
-  `heading`; Heading remains a referenced member and does not receive a separate
-  component spec.
-- Tooltip retains ownership of its delegated surface, interaction behavior, and
-  `tooltip` target.
+- `component:Heading` shares Text's type styles and truncation mechanism and
+  owns its own element, target, and accessibility.
+- `architecture:component-theming-surface` sets the rules the `text` target
+  follows (INV6) and the safe baseline for theme-added types and colors
+  (INV14).
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR5 applies them.
 
 ## Verification map
 
-| Contract            | Verification                                                                                   | Representative states                                   | Mutation or failure expectation                                                                                     | Audit section           |
-| ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, FR5            | `Text.test.tsx` and `themingTargets.test.ts`                                                   | Default, polymorphic, custom type/color, explicit size  | Removing, renaming, or changing the current Text target capabilities fails focused or global target assertions.     | `audit:Text/theming`    |
-| FR2, FR5            | `Heading.test.tsx`, `themingTargets.test.ts`, and target-introduction history                  | Levels 1–6, display type, custom color                  | Removing, renaming, or changing the current Heading target capabilities fails focused or global assertions.         | `audit:Heading/theming` |
-| FR3, FR4            | Text and Heading source inspection, truncation tests, Tooltip target metadata, and fix history | Fitting, overflowing, disabled, enabled                 | Moving the surface or target into Text/Heading, or restoring a native duplicate tooltip, violates current evidence. | `audit:Text/anatomy`    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                  | Canonical anatomy, both local targets, Tooltip delegate | Missing, extra, prefixed, stale, multiply assigned, or invalid delegated mappings fail repository validation.       | `audit:Text/theming`    |
-
-Current focused tests pin both local target names and Text's lack of a duplicate
-native `title`. The conditional Tooltip path and Heading's matching no-`title`
-behavior are established by shared source shape and history rather than a
-separate focused assertion in each suite.
+| Contract      | Verification                                                                               | Representative states                                          | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Audit section         |
+| ------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| FR1, AR1      | `Text.test.tsx` element, target, and reflection tests                                      | Default `span`; `p`, `div`, `label`                            | A wrong element, a lost `text` class, or a lost `data-type`, `data-size`, or `data-color` reflection fails. Gap: no test asserts that Text adds no role, and no accessibility-tree check proves the element's role (`spec:AST-009` FR3).                                                                                                                                                                                                                                                                                                                                                                                        | `audit:Text/behavior` |
+| FR2           | `Text.test.tsx` theme-added type and color tests; stable visual baseline `core-text--body` | Theme-added type and color; built-in color; body default       | A theme-added type or color losing its reflection, a theme-added color losing its primary baseline, or a lost color override, fails; a changed body scale or color comes back changed for review. Gap: no test asserts a theme-added type's body baseline (the custom-type test checks only the class and `data-type`), and the built-in type tests assert presence only, so each type's size, line height, and weight, and the `size` and `weight` overrides in paint, have no automated check. Each type's default color and a built-in color's paint also have no automated check; the color tests assert `data-color` only. | `audit:Text/theming`  |
+| FR3           | `Text.stories.tsx`                                                                         | Display, cap-height trim, wrap, strikethrough, tabular numbers | Gap: the prop tests assert presence only, so `display` precedence, `justify`, and every text treatment have no automated check.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `audit:Text/behavior` |
+| FR4, AR2, PR1 | `Text.test.tsx` native-title and truncation-measurement tests; `useTruncation.test.tsx`    | Truncated with tooltip; tooltip off; content change            | A native `title`, measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check.                                                                                                                                                                                                                                                                                                                                                                                       | `audit:Text/a11y`     |
+| FR5           | `Text.test.tsx` ref and passthrough tests                                                  | Rerender; `data-testid`                                        | A detached ref or a lost test id fails. Gap: no test covers other DOM passthrough, the styling-input merge order, or the line clamp after `style`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `audit:Text/behavior` |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-API, behavior, accessibility, or theming decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -201,6 +189,5 @@ None.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables/examples, typography token
-values, truncation measurement mechanics, Tooltip internals, implementation
-steps, current audit results, or system theming rules. It links to their owners.
+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/TextArea/TextArea.doc.mjs

@@ -151,14 +151,14 @@ export const docs = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.',
+        'Makes the textarea read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only textarea is not dimmed and keeps its form value. isDisabled takes precedence when both are set.',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip, so the reason is attached to the field itself.',
     },
     {
       name: 'isLoading',
@@ -364,7 +364,7 @@ export const docs = {
       {
         guidance: false,
         description:
-          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
   },
@@ -437,7 +437,7 @@ export const docsZh = {
       name: 'isReadOnly',
       type: 'boolean',
       description:
-        '将文本域设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读文本域不会变暗，并保留在 Tab 顺序中。同时设置时 isDisabled 优先。',
+        '将文本域设为只读：值以完整不透明度显示并仍随表单提交，但无法编辑。与 isDisabled 不同，只读文本域不会变暗，并保留其表单值。同时设置时 isDisabled 优先。',
       default: 'false',
     },
     {
@@ -637,7 +637,7 @@ export const docsZh = {
       {
         guidance: false,
         description:
-          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.",
+          "Don't wrap a disabled TextArea in Tooltip to explain why it's disabled. Use the disabledMessage prop, which attaches the reason to the field itself.",
       },
     ],
   },
@@ -710,7 +710,7 @@ export const docsDense = {
       'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',
     isDisabled: 'Disables textarea, prevents interaction.',
     isReadOnly:
-      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed, stays in tab order.',
+      'Read-only: value visible + still submits, but not editable. Unlike isDisabled: not dimmed.',
     disabledMessage:
       'Explains why textarea is disabled. With isDisabled, shows tooltip on hover/focus + keeps textarea focusable via aria-disabled (field becomes read-only). Use instead of wrapping a disabled TextArea in Tooltip.',
     isLoading: 'Loading state w/ spinner inside input.',