An open source design system that's fully customizable and agent ready
TypeScript
docs(core): record factual anatomy batch 4 (#5747)
Cindy Zhangc0fb56db7b28
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjsindex 48efff8be7..3dc819e32d 100644--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs@@ -1,5 +1,64 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Group',+ required: true,+ description: 'Container for the labeled checkbox group.',+ },+ {+ name: 'Group label',+ required: true,+ description: 'Text identifying what the checkbox options represent.',+ },+ {+ name: 'Description',+ required: false,+ description: 'Helper text below the group label.',+ },+ {+ name: 'Options list',+ required: true,+ description: 'List containing the available checkbox options.',+ },+ {+ name: 'Option row',+ required: true,+ description: 'Selectable row containing one option.',+ },+ {+ name: 'Checkbox',+ required: true,+ description: 'Selection indicator for an option.',+ },+ {+ name: 'Option label',+ required: true,+ description: 'Primary content identifying an option.',+ },+ {+ name: 'Option description',+ required: false,+ description: 'Secondary text below an option label.',+ },+ {+ name: 'End content',+ required: false,+ description: 'Caller-provided content at the end of an option row.',+ },+ {+ name: 'Spinner',+ required: false,+ description: 'Loading indicator shown inside the pending checkbox.',+ },+ {+ name: 'Status message',+ required: false,+ description: 'Error, warning, or success message below the group.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -8,13 +67,22 @@ export const docs = {group: 'Checkbox',category: 'Form Controls',isHiddenFromOverview: true,- keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],- description: 'Checkbox group container with field integration for label, description, and status.',+ keywords: [+ 'checkboxlist',+ 'checkbox',+ 'checkboxgroup',+ 'multichoice',+ 'multiselect',+ 'checklist',+ ],+ description:+ 'Checkbox group container with field integration for label, description, and status.',props: [{name: 'label',type: 'string',- description: 'Label text for the checkbox group (always rendered for accessibility).',+ description:+ 'Label text for the checkbox group (always rendered for accessibility).',required: true,},{@@ -97,41 +165,89 @@ export const docs = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization. Must be a stylex.create() value.',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',},],- components: [- {name: 'CheckboxListItem'},- ],+ components: [{name: 'CheckboxListItem'}],usage: {- description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',+ anatomy,+ description:+ 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',bestPractices: [- { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },- { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },- { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },- { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },- { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },- { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',+ },+ {+ guidance: true,+ description:+ 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',+ },+ {+ guidance: true,+ description:+ 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',+ },+ {+ guidance: false,+ description:+ 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',+ },+ {+ guidance: false,+ description:+ 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},theming: {- targets: [- {className: 'astryx-checkbox-list'},- ],+ targets: [{className: 'astryx-checkbox-list'}],},};/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsZh = {usage: {- description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',+ description:+ 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',bestPractices: [- { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },- { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },- { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },- { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },- { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },- { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',+ },+ {+ guidance: true,+ description:+ 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',+ },+ {+ guidance: true,+ description:+ 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',+ },+ {+ guidance: false,+ description:+ 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',+ },+ {+ guidance: false,+ description:+ 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},};@@ -141,14 +257,39 @@ export const docsDense = {description:'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',usage: {- description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',+ description:+ 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',bestPractices: [- { guidance: true, description: 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.' },- { guidance: true, description: 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.' },- { guidance: true, description: 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".' },- { guidance: false, description: 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.' },- { guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },- { guidance: false, description: 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.',+ },+ {+ guidance: true,+ description:+ 'Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.',+ },+ {+ guidance: true,+ description:+ 'Write a group label that says what the choices represent: "Export formats" tells users more than "Options".',+ },+ {+ guidance: false,+ description:+ 'Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.',+ },+ {+ guidance: false,+ description:+ 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled CheckboxList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},};diff --git a/packages/core/src/CheckboxList/CheckboxList.spec.md b/packages/core/src/CheckboxList/CheckboxList.spec.mdnew file mode 100644index 0000000000..deb32cd222--- /dev/null+++ b/packages/core/src/CheckboxList/CheckboxList.spec.md@@ -0,0 +1,214 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:CheckboxList+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/CheckboxList/CheckboxList.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+families: []+design_specs: []+architecture: [architecture:component-theming-surface]+contributing: []+system_specs: []+---++# CheckboxList component contract++## Intent++CheckboxList presents a labeled group of checkbox options. This draft records+its current consumer anatomy and the theming ownership of parts rendered by+CheckboxList, List, CheckboxInput, Field, FieldStatus, and Spinner. It changes no+runtime behavior or public API.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: additive documentation only; runtime, DOM, styling,+ targets, and public API remain unchanged+- Controlled/uncontrolled behavior: unchanged+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The checkbox-group composition and its existing `checkbox-list` target.+- Collection state shared with CheckboxListItem.++**Does not own / non-goals**++- List and option-row presentation — owned by `component:List`; its+ `list-item` target reaches only the row root.+- Standard option-label and option-description wrappers — rendered as separate,+ untargeted spans by Item rather than Text; rich label content and end content+ remain caller-owned.+- The checkbox indicator — owned by `component:CheckboxInput`.+- Group-label and validation-message presentation — owned by `component:Field`+ and `component:FieldStatus`.+- Loading-indicator presentation — owned by `component:Spinner`.+- New targets for untargeted descriptions or caller-provided item content.++## Public concepts++No new public concept is introduced. Consumer props, collection and standalone+item modes, and usage remain documented in `CheckboxList.doc.mjs` and+`CheckboxListItem.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |+| FR1 | The current render places CheckboxListItem children inside a List and a group named by the group label. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |+| FR2 | The CheckboxList root carries the current `checkbox-list` target. | Current source and public docs | Verified current behavior; no target change |+| FR3 | The option-row root and checkbox indicator continue to be rendered by List and CheckboxInput rather than reimplemented. | Current source | Verified composition boundary |+| FR5 | Item renders option label and description as separate untargeted children; end content remains caller-provided inside its own untargeted slot wrapper. | Current source and focused tests | Verified child ownership; no target change |+| FR4 | A pending item renders Spinner inside that item's checkbox; a status message renders through detached FieldStatus. | Current source, docs, and focused tests | Verified conditional composition |++### Allowed variation++- Option labels, descriptions, and end content may vary with caller-provided+ CheckboxListItem content without becoming new CheckboxList targets.+- Density, dividers, checked state, and disabled state remain capabilities of+ their current owning components rather than separate anatomy parts.++### Representative states++| State | Required invariant | Allowed variation |+| ------------------------- | --------------------------------------------------------------- | ---------------------------------- |+| Default collection | Named group, options list, rows, and checkbox indicators render | Option content and selected values |+| Item pending | Only the pending checkbox includes a Spinner | Which option is pending |+| Group status with message | Detached FieldStatus follows the group | Error, warning, or success status |++### Transformation and precedence order++- No new state, event, layout, or styling precedence rule is introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend CheckboxList's existing group naming,+checkbox semantics, focus order, busy state, or description/status association.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------------------ | ---------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |+| Group | Contains the current checkbox-group composition. | Current source and public docs | Supporting | FR1, FR2 |+| Options and rows | Present the List-owned list and row root plus Item-rendered child structure. | Current source | Supporting | FR1, FR3 |+| Checkbox | Presents each option's current selection indicator. | Current CheckboxInput source | Prominent | FR3 |+| Spinner and status | Present the current conditional feedback components. | Current shared-component source | Supporting | FR4 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Group": {"target": "checkbox-list"},+ "Group label": {+ "delegatesTo": {"owner": "component:Field", "target": "field-label"}+ },+ "Description": {+ "none": {+ "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"+ }+ },+ "Options list": {+ "delegatesTo": {"owner": "component:List", "target": "list"}+ },+ "Option row": {+ "delegatesTo": {"owner": "component:List", "target": "list-item"}+ },+ "Checkbox": {+ "delegatesTo": {+ "owner": "component:CheckboxInput",+ "target": "checkbox-indicator"+ }+ },+ "Option label": {+ "none": {+ "reason": "unsettled: Item rather than Text renders the stable Option label in a separate untargeted span; future exposure still needs an owner decision"+ }+ },+ "Option description": {+ "none": {+ "reason": "unsettled: Item rather than Text renders the stable Option description in a separate untargeted span; future exposure still needs an owner decision"+ }+ },+ "End content": {+ "none": {+ "reason": "intentional: End content is caller-provided content outside CheckboxList's public theming ownership"+ }+ },+ "Spinner": {+ "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}+ },+ "Status message": {+ "delegatesTo": {+ "owner": "component:FieldStatus",+ "target": "field-status"+ }+ }+}+```++`Description` remains stable consumer anatomy, but no current public target+reaches it. Item, not Text, renders option labels and descriptions in separate+untargeted spans, so neither delegates to Text nor inherits the row-root+`list-item` target; future exposure remains unsettled. Rich label content and end+content are caller-provided, and end content intentionally stays outside+CheckboxList's public theming ownership.++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, factual+ `none` dispositions, and composition-preserving target ownership.+- List, CheckboxInput, Field, FieldStatus, and Spinner retain their existing+ public target contracts when composed by CheckboxList.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |+| FR1, FR3, FR5 | `CheckboxList.test.tsx` structure, content, and interaction suites plus `Item.tsx` source inspection | Collection mode; string/rich label; description; end content | Removing the group, row, checkbox, or separate content children breaks existing DOM and interaction assertions. | `audit:CheckboxList/anatomy` |+| FR4 | `CheckboxList.test.tsx` loading and status suites | Pending item and detached status | Removing composed feedback breaks existing spinner, busy-state, or message assertions. | `audit:CheckboxList/anatomy` |+| Local target source | `themingTargets.test.ts` | `checkbox-list` | Source/docs target drift fails the repository target guard. | `audit:CheckboxList/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:CheckboxList/theming` |++The focused CheckboxList suite does not pin the exact delegated target classes+or the local `checkbox-list` class in rendered DOM. The source/metadata target+guard independently verifies that each owner's emitted targets remain+documented. No current repository check resolves `delegatesTo` owner/target+pairs; the pairs in this draft were verified manually, so semantic delegation+drift remains a validation gap.++## Decision log++None. This draft records current facts and introduces no component-local design+or API decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, implementation+steps, or shared-component contracts. It links to their owners.diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjsindex 6992a7e542..2a1796f1de 100644--- a/packages/core/src/Switch/Switch.doc.mjs+++ b/packages/core/src/Switch/Switch.doc.mjs@@ -1,5 +1,44 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Field',+ required: true,+ description: 'Container arranging the switch, label, and feedback.',+ },+ {+ name: 'Track',+ required: true,+ description: 'Pill-shaped surface that shows the off or on state.',+ },+ {+ name: 'Thumb',+ required: true,+ description: 'Indicator that moves across the track when state changes.',+ },+ {+ name: 'Label',+ required: true,+ description: 'Text identifying the setting controlled by the switch.',+ },+ {+ name: 'Description',+ required: false,+ description: 'Helper text below the label.',+ },+ {+ name: 'Spinner',+ required: false,+ description: 'Loading indicator shown inside the thumb while busy.',+ },+ {+ name: 'Status message',+ required: false,+ description: 'Error, warning, or success message below the switch.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -171,6 +210,7 @@ export const docs = {],},usage: {+ anatomy,description:'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',bestPractices: [diff --git a/packages/core/src/Switch/Switch.spec.md b/packages/core/src/Switch/Switch.spec.mdnew file mode 100644index 0000000000..dd8988655c--- /dev/null+++ b/packages/core/src/Switch/Switch.spec.md@@ -0,0 +1,174 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:Switch+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/Switch/Switch.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+families: []+design_specs: []+architecture: [architecture:component-theming-surface]+contributing: []+system_specs: []+---++# Switch component contract++## Intent++Switch presents a labeled boolean control whose change takes effect immediately.+This draft records current consumer anatomy and theming ownership without+changing runtime behavior, styling, targets, or public API.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: additive documentation only; runtime, DOM, styling,+ targets, and public API remain unchanged+- Controlled/uncontrolled behavior: unchanged; Switch remains controlled+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The switch field, track, thumb, and label presentations represented by the+ existing `switch-field`, `switch`, `switch-thumb`, and `switch-label` targets.++**Does not own / non-goals**++- Description styling through a dedicated public target; none currently exists.+- Validation-message presentation — owned by `component:FieldStatus`.+- Loading-indicator presentation — owned by `component:Spinner`.+- Tooltip surfaces used for shared label and disabled-reason behavior.++## Public concepts++No new public concept is introduced. Consumer props, states, and usage remain+documented in `Switch.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |+| FR1 | The current render places a thumb inside the switch track and arranges that control with its label. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |+| FR2 | The field, track, thumb, and label carry their existing local targets. | Current source, public docs, and tests | Verified current behavior; no target change |+| FR3 | A busy switch renders Spinner inside the thumb; a status message renders through detached FieldStatus. | Current source, docs, and focused tests | Verified conditional composition |++### Allowed variation++- Label position and spacing, size, checked state, and disabled state remain+ current target capabilities rather than separate anatomy parts.+- A description may be absent without changing the remaining anatomy.++### Representative states++| State | Required invariant | Allowed variation |+| ------------------- | ------------------------------------------------------- | -------------------------------------- |+| Off or on | Track, thumb, and label render within the switch field. | Checked state, size, label placement |+| Busy | Spinner renders inside the thumb. | Controlled or optimistic checked value |+| Status with message | Detached FieldStatus follows the switch row. | Error, warning, or success status |++### Transformation and precedence order++- No new state, event, layout, or styling precedence rule is introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend Switch's existing accessible name, switch+role, checked state, busy state, description/status association, or disabled+behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | -------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |+| Field | Arranges the switch control with its label and feedback. | Current source and public docs | Supporting | FR1, FR2 |+| Track and thumb | Present the current on/off control. | Current source and public docs | Prominent | FR1, FR2 |+| Label | Identifies the controlled setting. | Current source and public docs | Prominent | FR1, FR2 |+| Spinner/status | Present conditional progress and validation feedback. | Current shared-component source | Supporting | FR3 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Field": {"target": "switch-field"},+ "Track": {"target": "switch"},+ "Thumb": {"target": "switch-thumb"},+ "Label": {"target": "switch-label"},+ "Description": {+ "none": {+ "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"+ }+ },+ "Spinner": {+ "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}+ },+ "Status message": {+ "delegatesTo": {+ "owner": "component:FieldStatus",+ "target": "field-status"+ }+ }+}+```++`Description` remains stable consumer anatomy, but no current public target+reaches it. The map classifies future exposure as unsettled rather than silently+making the absence intentional.++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, factual+ `none` dispositions, and composition-preserving target ownership.+- FieldStatus and Spinner retain their existing public target contracts when+ composed by Switch.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |+| FR1 | `Switch.test.tsx` structure and interaction suites | On/off, size, label position, hidden label | Removing or reordering stable parts breaks existing role, label, or DOM assertions. | `audit:Switch/anatomy` |+| FR2 | `Switch.test.tsx` label-target suite and `themingTargets.test.ts` | Current local targets | Removing the label target fails focused coverage; source/docs drift fails the target guard. | `audit:Switch/theming` |+| FR3 | `Switch.test.tsx` loading and status suites | Busy and detached status | Removing composed feedback breaks existing spinner, busy-state, or message assertions. | `audit:Switch/anatomy` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and all current targets | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |++The focused Switch suite pins `switch-label`, but does not separately assert the+exact `switch-field`, `switch`, or `switch-thumb` class placement. The+source/metadata target guard covers those local declarations. No current+repository check resolves `delegatesTo` owner/target pairs; the pairs in this+draft were verified manually, so semantic delegation drift remains a validation+gap.++## Decision log++None. This draft records current facts and introduces no component-local design+or API decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, implementation+steps, or shared-component contracts. It links to their owners.diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex c9d80150f6..8ba4c7ccad 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -1,18 +1,95 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Label',+ required: true,+ description: 'Text identifying the multi-line field.',+ },+ {+ name: 'Description',+ required: false,+ description: 'Helper text between the label and the input.',+ },+ {+ name: 'Input container',+ required: true,+ description: 'Painted boundary containing the text area and its overlays.',+ },+ {+ name: 'Text area',+ required: true,+ description: 'Multi-line control that displays and edits the value.',+ },+ {+ name: 'Placeholder',+ required: false,+ description: 'Hint text shown inside the empty text area.',+ },+ {+ name: 'Start icon',+ required: false,+ description:+ 'Astryx Icon rendered at the start when startIcon is a semantic name or icon component.',+ },+ {+ name: 'Custom start content',+ required: false,+ description:+ 'Caller-provided ReactNode rendered at the start instead of an Astryx Icon.',+ },+ {+ name: 'Spinner',+ required: false,+ description: 'Loading indicator shown at the end of the input container.',+ },+ {+ name: 'Status icon',+ required: false,+ description: 'Error, warning, or success icon shown inside the input.',+ },+ {+ name: 'Character counter',+ required: false,+ description:+ 'Current and maximum character counts shown inside the input container.',+ },+ {+ name: 'Field status message',+ required: false,+ description:+ 'Attached or detached error, warning, or success message associated with the field.',+ },+ {+ name: 'Tooltip status message',+ required: false,+ description:+ 'Tooltip surface presenting the status message for the tooltip variant.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {name: 'TextArea',displayName: 'Text Area',category: 'Form Controls',- keywords: ["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],+ keywords: [+ 'textarea',+ 'textfield',+ 'multiline',+ 'comment',+ 'message',+ 'autoresize',+ 'autosize',+ 'charlimit',+ ],props: [{name: 'ref',type: 'React.Ref<HTMLTextAreaElement>',- description:- 'Ref forwarded to the underlying <textarea> element.',+ description: 'Ref forwarded to the underlying <textarea> element.',},{name: 'label',@@ -147,7 +224,8 @@ export const docs = {{name: 'size',type: "'sm' | 'md' | 'lg'",- description: 'Size of the textarea, affecting internal padding. Height is controlled by rows, not size.',+ description:+ 'Size of the textarea, affecting internal padding. Height is controlled by rows, not size.',default: "'md'",},{@@ -186,12 +264,21 @@ export const docs = {],theming: {targets: [- {className: 'astryx-text-area', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},+ {+ className: 'astryx-text-area',+ visualProps: ['size', 'status'],+ states: ['disabled', 'readonly'],+ },{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},// Still emitted beside the names above, so themes written against// them keep working. Drop in the next major.- {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly'], deprecatedFor: 'text-area'},+ {+ className: 'astryx-textarea',+ visualProps: ['size', 'status'],+ states: ['disabled', 'readonly'],+ deprecatedFor: 'text-area',+ },],vars: [{@@ -203,21 +290,58 @@ export const docs = {},],derived: [- {property: 'paddingInline', vars: ['--_textarea-inline-padding'], replaces: true},+ {+ property: 'paddingInline',+ vars: ['--_textarea-inline-padding'],+ replaces: true,+ },],},usage: {+ anatomy,description:'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',bestPractices: [- { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit; it helps users stay within bounds before they submit.' },- { guidance: true, description: 'Use the status prop to surface validation feedback inline: show success when input is valid, warning for soft limits, and error for hard failures.' },- { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail," but never rely on placeholder alone as the only label.' },- { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },- { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },- { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },- { 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.' },+ {+ guidance: true,+ description:+ 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.',+ },+ {+ guidance: true,+ description:+ 'Set maxLength with a character counter when there is a defined limit; it helps users stay within bounds before they submit.',+ },+ {+ guidance: true,+ description:+ 'Use the status prop to surface validation feedback inline: show success when input is valid, warning for soft limits, and error for hard failures.',+ },+ {+ guidance: true,+ description:+ 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail," but never rely on placeholder alone as the only label.',+ },+ {+ guidance: false,+ description:+ 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.',+ },+ {+ guidance: false,+ description:+ "Don't rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.",+ },+ {+ guidance: false,+ description:+ "Don't show a status message without also setting the status type; the colored border and icon are what draw the user's attention to the message.",+ },+ {+ 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.",+ },],},};@@ -252,7 +376,8 @@ export const docsZh = {{name: 'changeAction',type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',- description: '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',+ description:+ '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',},{name: 'isLabelHidden',@@ -274,7 +399,8 @@ export const docsZh = {{name: 'isRequired',type: 'boolean',- description: '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',+ description:+ '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',default: 'false',},{@@ -316,12 +442,14 @@ export const docsZh = {{name: 'maxLength',type: 'number',- description: '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制:超出时计数器显示错误样式。',+ description:+ '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制:超出时计数器显示错误样式。',},{name: 'status',type: "{ type: 'warning' | 'error' | 'success'; message?: string }",- description: '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',+ description:+ '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',},{name: 'statusVariant',@@ -381,17 +509,27 @@ export const docsZh = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象。',+ description:+ 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象。',},],theming: {targets: [- {className: 'astryx-text-area', visualProps: ['size', 'status'], states: ['disabled', 'readonly']},+ {+ className: 'astryx-text-area',+ visualProps: ['size', 'status'],+ states: ['disabled', 'readonly'],+ },{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},// Still emitted beside the names above, so themes written against// them keep working. Drop in the next major.- {className: 'astryx-textarea', visualProps: ['size', 'status'], states: ['disabled', 'readonly'], deprecatedFor: 'text-area'},+ {+ className: 'astryx-textarea',+ visualProps: ['size', 'status'],+ states: ['disabled', 'readonly'],+ deprecatedFor: 'text-area',+ },],vars: [{@@ -403,21 +541,57 @@ export const docsZh = {},],derived: [- {property: 'paddingInline', vars: ['--_textarea-inline-padding'], replaces: true},+ {+ property: 'paddingInline',+ vars: ['--_textarea-inline-padding'],+ replaces: true,+ },],},usage: {description:'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',bestPractices: [- { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit; it helps users stay within bounds before they submit.' },- { guidance: true, description: 'Use the status prop to surface validation feedback inline: show success when input is valid, warning for soft limits, and error for hard failures.' },- { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail," but never rely on placeholder alone as the only label.' },- { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.' },- { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.' },- { guidance: false, description: 'Don\'t show a status message without also setting the status type; the colored border and icon are what draw the user\'s attention to the message.' },- { 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.' },+ {+ guidance: true,+ description:+ 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.',+ },+ {+ guidance: true,+ description:+ 'Set maxLength with a character counter when there is a defined limit; it helps users stay within bounds before they submit.',+ },+ {+ guidance: true,+ description:+ 'Use the status prop to surface validation feedback inline: show success when input is valid, warning for soft limits, and error for hard failures.',+ },+ {+ guidance: true,+ description:+ 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail," but never rely on placeholder alone as the only label.',+ },+ {+ guidance: false,+ description:+ 'Avoid using TextArea for short, single-line values like names or emails; use TextInput instead.',+ },+ {+ guidance: false,+ description:+ "Don't rely solely on placeholder text to communicate the purpose of the field; placeholders disappear on focus and are not accessible labels.",+ },+ {+ guidance: false,+ description:+ "Don't show a status message without also setting the status type; the colored border and icon are what draw the user's attention to the message.",+ },+ {+ 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.",+ },],},};@@ -429,14 +603,44 @@ export const docsDense = {description:'Multi-line input for comments, descriptions, messages. Use when input spans multiple lines; use TextInput for single-line.',bestPractices: [- { guidance: true, description: 'Visible label or isLabelHidden with descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength for character counter when a limit exists.' },- { guidance: true, description: 'Use status prop for inline validation: success, warning, error.' },- { guidance: true, description: 'Add description or placeholder for context; never placeholder alone as label.' },- { guidance: false, description: 'Avoid TextArea for single-line values; use TextInput.' },- { guidance: false, description: 'Don\'t use placeholder as only label; disappears on focus, not accessible.' },- { guidance: false, description: 'Don\'t show status message without status type; border and icon draw attention.' },- { guidance: false, description: 'Don\'t wrap a disabled TextArea in Tooltip to explain the disabled state; use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Visible label or isLabelHidden with descriptive label for screen readers.',+ },+ {+ guidance: true,+ description: 'Set maxLength for character counter when a limit exists.',+ },+ {+ guidance: true,+ description:+ 'Use status prop for inline validation: success, warning, error.',+ },+ {+ guidance: true,+ description:+ 'Add description or placeholder for context; never placeholder alone as label.',+ },+ {+ guidance: false,+ description: 'Avoid TextArea for single-line values; use TextInput.',+ },+ {+ guidance: false,+ description:+ "Don't use placeholder as only label; disappears on focus, not accessible.",+ },+ {+ guidance: false,+ description:+ "Don't show status message without status type; border and icon draw attention.",+ },+ {+ guidance: false,+ description:+ "Don't wrap a disabled TextArea in Tooltip to explain the disabled state; use the disabledMessage prop instead.",+ },],},propDescriptions: {@@ -444,11 +648,13 @@ export const docsDense = {label: 'Label text for textarea; always rendered for a11y.',value: 'Current textarea value.',onChange: 'Fired on textarea value change.',- changeAction: 'Async action after onChange in React transition. Enables useOptimistic.',+ changeAction:+ 'Async action after onChange in React transition. Enables useOptimistic.',isLabelHidden: 'Visually hides label; keeps screen reader access.',description: 'Helper text between label+textarea.',isOptional: 'Shows "Optional" indicator. Mutually exclusive w/ isRequired.',- isRequired: 'Shows "Required" indicator+sets aria-required. Mutually exclusive w/ isOptional.',+ isRequired:+ '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.',@@ -457,9 +663,12 @@ export const docsDense = {isLoading: 'Loading state w/ spinner inside input.',placeholder: 'Placeholder when textarea empty.',rows: 'Visible text rows.',- maxLength: 'Max chars allowed. Shows counter (current/max) inside the container, bottom-right beneath the text. No native enforcement; over-limit shows red + a warning icon and is announced to screen readers.',- status: 'Colored border+icon status. Optional floating message below textarea.',- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',+ maxLength:+ 'Max chars allowed. Shows counter (current/max) inside the container, bottom-right beneath the text. No native enforcement; over-limit shows red + a warning icon and is announced to screen readers.',+ status:+ 'Colored border+icon status. Optional floating message below textarea.',+ statusVariant:+ 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',labelTooltip: 'Tooltip in info icon at label end.',startIcon: 'Icon inside leading edge of textarea wrapper.',hasSpellCheck: 'Enables/disables browser spell checking.',@@ -469,6 +678,7 @@ export const docsDense = {htmlName: 'HTML name attr for form submissions.',onFocus: 'Callback on focus.',onBlur: 'Callback on blur.',- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',+ xstyle:+ 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',},};diff --git a/packages/core/src/TextArea/TextArea.spec.md b/packages/core/src/TextArea/TextArea.spec.mdnew file mode 100644index 0000000000..06ac494f4b--- /dev/null+++ b/packages/core/src/TextArea/TextArea.spec.md@@ -0,0 +1,204 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:TextArea+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/TextArea/TextArea.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+families: []+design_specs: []+architecture: [architecture:component-theming-surface]+contributing: []+system_specs: []+---++# TextArea component contract++## Intent++TextArea presents a labeled multi-line text field. This draft records its current+consumer anatomy and the theming ownership of parts rendered by TextArea, Field,+FieldStatus, and Spinner. It changes no runtime behavior or public API.++## Compatibility and migration++- Released default preserved: `yes`+- Compatibility class: additive documentation only; runtime, DOM, styling,+ targets, aliases, and public API remain unchanged+- Controlled/uncontrolled behavior: unchanged; TextArea remains controlled+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The painted input container, native text area, and character counter represented+ by the existing `text-area`, `text-area-control`, and `text-area-counter`+ targets.++**Does not own / non-goals**++- Label and attached/detached validation-message presentation — owned by+ `component:Field` and `component:FieldStatus`.+- The tooltip-variant status surface — owned by `component:Tooltip`.+- Standard start-icon presentation and the shared on-field status icon — owned+ by `component:Icon` and `component:Field`, respectively.+- Loading-indicator presentation — owned by `component:Spinner`.+- Caller-provided custom start content outside Icon's supported source forms.+- The deprecated `textarea` alias as separate anatomy.++## Public concepts++No new public concept is introduced. Consumer props, states, and usage remain+documented in `TextArea.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |+| FR1 | The current render places the native text area inside its painted input container. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |+| FR2 | The input container, native control, and conditional character counter carry the three current local targets. | Current source and public docs | Verified current behavior; no target change |+| FR3 | Label, standard start icon, loading indicator, status icon, and status surfaces continue to use their shared Field, Icon, Spinner, FieldStatus, and Tooltip owners. | Current source | Verified conditional composition boundary |+| FR4 | Placeholder text remains part of the native control; the over-limit glyph remains part of the character counter. | Current source, docs, and focused tests | Verified current grouping |++### Allowed variation++- Value, placeholder, row count, size, status, disabled/read-only state, and+ optional slots remain current capabilities rather than separate target names.+- Start-icon content may be an Icon-supported value or caller-supplied ReactNode.++### Representative states++| State | Required invariant | Allowed variation |+| -------------------- | ---------------------------------------------------------------------- | ----------------------------------- |+| Default editable | Label, input container, and native text area render. | Value, placeholder, rows, and size |+| With character limit | Character counter renders inside the input container. | Count and over-limit state |+| Busy or status | Shared Spinner or status presentation renders in its current location. | Status variant and message presence |++### Transformation and precedence order++- No new value, layout, status, or styling precedence rule is introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend TextArea's existing label, description,+status, counter, busy state, disabled/read-only state, or announcement behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| --------------------- | -------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |+| Input container | Presents the current painted field boundary. | Current source and public docs | Supporting | FR1, FR2 |+| Text area | Presents and edits the current multi-line value. | Current source and public docs | Prominent | FR1, FR2 |+| Character counter | Presents current and maximum character counts. | Current source and public docs | Supporting | FR2, FR4 |+| Shared field feedback | Presents current label, standard icons, status, and loading content. | Current shared-component source | Supporting | FR3 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Label": {+ "delegatesTo": {"owner": "component:Field", "target": "field-label"}+ },+ "Description": {+ "none": {+ "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"+ }+ },+ "Input container": {"target": "text-area"},+ "Text area": {"target": "text-area-control"},+ "Placeholder": {"inherits": "text-area-control"},+ "Start icon": {+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}+ },+ "Custom start content": {+ "none": {+ "reason": "intentional: Custom start content is caller-provided ReactNode content outside TextArea's public theming ownership"+ }+ },+ "Spinner": {+ "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}+ },+ "Status icon": {+ "delegatesTo": {+ "owner": "component:Field",+ "target": "input-status-icon"+ }+ },+ "Character counter": {"target": "text-area-counter"},+ "Field status message": {+ "delegatesTo": {+ "owner": "component:FieldStatus",+ "target": "field-status"+ }+ },+ "Tooltip status message": {+ "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}+ }+}+```++`Description` remains stable consumer anatomy, but no current public target+reaches it; future exposure remains unsettled. Semantic names and icon component+values render through Icon and delegate to its `icon` target; arbitrary ReactNode+start content is caller-provided and intentionally stays outside TextArea's+public theming ownership. Attached and detached status messages delegate to+FieldStatus, while the tooltip variant delegates its rendered surface to Tooltip.+The deprecated `textarea` alias is compatibility evidence only and does not+appear in the map.++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, factual+ `none` dispositions, composition-preserving ownership, and alias exclusion.+- Field, FieldStatus, Icon, Spinner, and Tooltip retain their existing public+ target contracts when composed by TextArea.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1, FR4 | `TextArea.test.tsx` structure and counter suites | Default, placeholder, counter, over limit | Removing or regrouping stable parts breaks existing role, content, or DOM assertions. | `audit:TextArea/anatomy` |+| FR2 | `TextArea.test.tsx` root-target suite and `themingTargets.test.ts` | Current and deprecated root names; current targets | Removing root compatibility classes fails focused coverage; source/docs drift fails the target guard. | `audit:TextArea/theming` |+| FR3 | `TextArea.test.tsx`, `useInputStatusIcon.test.tsx`, and source inspection of `renderIconSlot` | Standard/custom start content; Spinner; attached/detached/tooltip status | Removing or rerouting composed content breaks existing icon, spinner, tooltip, message, or association assertions. | `audit:TextArea/anatomy` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | `audit:TextArea/theming` |++The focused TextArea suite pins the current and deprecated root classes, but does+not separately assert the exact `text-area-control` or `text-area-counter` class+placement. The source/metadata target guard covers those local declarations. No+current repository check resolves `delegatesTo` owner/target pairs; the pairs in+this draft were verified manually, so semantic delegation drift remains a+validation gap.++## Decision log++None. This draft records current facts and introduces no component-local design+or API decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, implementation+steps, or shared-component contracts. It links to their owners.