chore(text-field): migration plan

[miwha-adobe]

Description

Adds the text field migration plan — the Phase 1 (Preparation) planning output for the 1st-gen sp-textfield → 2nd-gen swc-text-field migration under Epic SWC-2325 (parent Epic SWC-2323).

This is a documentation-only change. It introduces one new planning document plus a single index entry:

• CONTRIBUTOR-DOCS/03_project-planning/03_components/text-field/migration-plan.md (new)
• CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md (index link)

The plan captures the full 1st-gen API surface, the recommended 2nd-gen API decisions, architecture (core vs SWC split), a phase-by-phase migration checklist, and the open questions/blockers that must be resolved before implementation. Headline recommendations: scope narrows to single-line (multiline moves to a separate swc-text-area); labelling and help/error move in-shadow via a shared LabellingController (SWC-2466) with form participation via a FieldAssociationController (SWC-2467); breaking changes include removing quiet, renaming label → accessible-label, and dropping the truncated-value tooltip.

The plan is explicitly provisional and its Blockers section is the review surface — see "Open questions for reviewers" below.

Motivation and context

The text field migration is a large, multi-phase effort with architectural decisions (single-line/multiline split, field-family sharing model, shared labelling/form-association controllers) that must be agreed before any code is written. Landing this plan first gives reviewers a single authoritative document to sign off on scope, breaking changes, and sequencing before Phase 2+ implementation PRs stack on top of it.

Open questions for reviewers

Please engage with the plan's Blockers and open questions section. The genuinely blocking item that gates implementation:

• Q7 — field-family sharing model for number-field/color-field/text-area (shared base à la ButtonBase vs. controllers-only à la Tooltip/Popover vs. shared mixin à la progress-bar/meter). The decision hinges on how much the LabellingController renders (Q8) and pulls in Q22 (shared styles).

Effectively decided, needs acknowledgment only:

• Q1 — remove the quiet variant. Three independent sources agree on removal (spectrum-css/Spectrum 2, the rendering analysis, and the S2 Figma matrix). The quiet use case (dense/table layouts) likely maps to the new inline variant (Q17). Design to acknowledge the breaking-change/consumer impact.

Design context and newer questions worth a look:

• A full S2 state × variant matrix has been received (all four sizes × top/side label × five states × content/error variants). It confirms side-label as first-class at every size (Q2) and that there is no quiet variant; it does not cover readonly (Q3) or an explicit valid/checkmark state (both unconfirmed). Figma is the source of truth; exact token values still need extracting from Figma (Q20).
• Q23 — in-field ContextualHelp placement ("in-field" per the plan vs. "next to the label" per React Spectrum); confirm the LabellingController API models description sources as an extensible set.
• • Q25 — non-text contrast (WCAG 1.4.11): re-evaluate border/focus-ring 3:1 against S2 tokens (re-check SWC-214).
• Q24 — label text overflow / wrapping behavior (top and side).
• Q17 — the inline text-field variant is now published in Figma; treated as deferred/additive unless prioritized.

Related issue(s)

• fixes SWC-2325
• Epic: SWC-2323
• Depends on planning inputs: accessibility migration analysis; forms strategy RFC (SWC-1888); controllers SWC-2466 / SWC-2467

Screenshots (if appropriate)

N/A — markdown documentation only, no visual/UI change.

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes. — N/A, documentation-only change (no code)
• I have included a well-written changeset if my change needs to be published. — N/A, no published package is affected
• I have included updated documentation if my change required it. — this PR is the documentation

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Plan renders and navigates correctly

  1. Open CONTRIBUTOR-DOCS/03_project-planning/03_components/text-field/migration-plan.md in the PR's Files changed tab
  2. Confirm the generated breadcrumbs and TOC render and the in-page anchors resolve
  3. Expect all headings/anchors to match with no broken internal links

• Index entry is wired up

  1. Open CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md
  2. Follow the newly added Text Field link
  3. Expect it to resolve to the new migration plan document

• Blockers section is coherent

  1. Read the Blockers and open questions section
  2. Cross-check the blocking item (Q7) and the 2026-08-18 design-context note against the API decisions
  3. Expect every breaking change to map to a resolved decision or an open question

Device review

• Did it pass in Desktop? — N/A, documentation-only change
• Did it pass in (emulated) Mobile? — N/A, documentation-only change
• Did it pass in (emulated) iPad? — N/A, documentation-only change

Accessibility testing checklist

This PR adds a planning markdown document only — there is no component, interactive control, or rendered UI introduced, and no runtime accessibility surface to exercise. (The plan's content specifies the 2nd-gen component's a11y requirements; those are implemented and tested in the Accessibility phase of the migration.)

• Keyboard — N/A: no interactive/focusable parts are added by this change. Documentation renders as static prose.
• Screen reader — N/A: no component roles, names, or states are introduced; standard markdown heading structure and links only.

[changeset-bot]

⚠️ No Changeset found

Latest commit: dcd9702

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6629

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[cdransf]

Looks great! ✨