docs: textfield-based component analysis docs by rise-erpelding · Pull Request #5741 · adobe/spectrum-web-components

rise-erpelding · 2025-09-18T15:45:49Z

Description

Creates AI-generated migration documentation to analyze component differences to guide SWC migration to S2, with human vetting. The documentation serves as a bridge between the migrated Spectrum 2 CSS work and the corresponding web components, in order to help engineers understand what needs to be implemented, updated, or aligned between the two systems to guide the development of 2nd generation web components.

This batch is for the barebones components: Textfield/Textarea, Number field, Search, and Color field (which does not exist in CSS or S2 design spec)

Motivation and context

Clear development roadmap: Provides comprehensive feature gap analysis for building 2nd generation web components
Implementation requirements: Identifies all features and capabilities that need to be implemented to match Spectrum 2 CSS and design specs
Breaking change transparency: Establishes implementation requirements and design changes that may lead to breaking changes and/or API changes for the next major version
Adoption planning: Enables developers and consuming teams to plan for 2nd gen web component adoption and understand migration effort required

Related issue(s)

SWC-1208

Screenshots (if appropriate)

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.~~
~~I have included a well-written changeset if my change needs to be published.~~
I have included updated documentation if my change required it.

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

Documentation Quality

All files follow template structure with proper collapsible sections
CSS => SWC mapping tables use correct status values
Summary sections are concise and actionable
No broken markdown syntax

Cross-Reference Accuracy

CSS selectors match actual metadata.json files
SWC attributes match actual TypeScript source files
DOM structure comparisons match template files
Implementation gaps are complete and accurate

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

changeset-bot · 2025-09-18T15:45:53Z

⚠️ No Changeset found

Latest commit: b2e4dd6

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 · 2025-09-18T15:50:25Z

📚 Branch Preview

🔍 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:

Deployed to Azure Blob Storage: pr-5741

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.

github-actions · 2025-09-18T15:53:30Z

Tachometer results

Currently, no packages are changed by this PR...

marissahuysentruyt

I feel like I've been holding onto a bunch of comments so...here come a flood! I have to go through the text field file, but that one was just so long and I didn't want to hold these up.

marissahuysentruyt

Leaving the remainder for textfield.

marissahuysentruyt · 2025-09-24T17:23:04Z

+
+- **Label position**: This is controlled by field label in SWC, but controlled by textfield in CSS
+- **Character count**: SWC doesn't currently support a visible character count that would track the number of characters within the text field
+- **Keyboard focus state**: CSS has slightly different styling for focused vs. keyboard-focused state (keyboard focus shows the blue outline, mouse focus does not), this distinction is not visible in the current SWC implementation


oh great callout here about the differences between focused and keyboard-focused!

rise-erpelding · 2025-09-26T18:31:22Z

+
+### Common issues to watch for
+
+- **Branch confusion**: AI may analyze wrong branches or mix up repositories


I love AI writing and summarizing all the things that AI might not be able to do here 😆

rise-erpelding · 2025-09-29T18:44:23Z

+<details>
+<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
+
+```diff


Happy to have any feedback on this numberfield diff... it's really unpleasant to look at, I think, because just about every line changes due to class name changes.

Could we preface the diff with something to the affect of: "Most of the diff below is due to the change in classname from .spectrum-Stepper to .spectrum-NumberField"?

Regarding the number field diff also- we could foreseeably add those --top and --bottom modifier classes to the legacy infield buttons, as well. They're in the legacy DOM example, just not in this portion with the markup diff. And speaking of infield buttons- the changes to infield button are also a big reason this diff looks so severe.

Just some thoughts.

rise-erpelding · 2025-09-29T19:27:35Z

+|                                                                                       | `action`                   | Missing from CSS             |
+|                                                                                       | `method`                   | Missing from CSS             |
+|                                                                                       | `holdValueOnEscape`        | Missing from CSS             |
+|                                                                                       | `negative-help-text` slot  | Missing from CSS             |


"Missing from CSS" doesn't feel super valuable for our purposes, taking this out if no one is opposed.

marissahuysentruyt

I know I left a TON of comments, and everything is looking great! Thanks for all of your hard work on this! I only found a couple of really small things this time around! 🎉

marissahuysentruyt · 2025-09-30T16:26:46Z

+**Inherited from SizedMixin:**
+
+- `size` - Size of the color field (s, m, l, xl)
+
+**Inherited from Focusable:**


I love the reorganization of all of this information you and Cassondra have done 😍

marissahuysentruyt · 2025-09-30T18:15:44Z

+<details>
+<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
+
+```diff


Could we preface the diff with something to the affect of: "Most of the diff below is due to the change in classname from .spectrum-Stepper to .spectrum-NumberField"?

Regarding the number field diff also- we could foreseeably add those --top and --bottom modifier classes to the legacy infield buttons, as well. They're in the legacy DOM example, just not in this portion with the markup diff. And speaking of infield buttons- the changes to infield button are also a big reason this diff looks so severe.

Just some thoughts.

castastrophe · 2025-10-01T12:32:07Z

+- **CSS selectors**: All selectors from `metadata.json` in the spectrum-css `spectrum-two` branch
+- **Passthroughs**: CSS passthrough properties
+- **Modifiers**: CSS modifier classes
+- **SWC attributes**: Properties with `@property` decorators in TypeScript


Tiny nit, these can also be handled using getters and setters (@property is an alias for a simple getter and setter pattern).

Does this update look better?

SWC attributes: Properties with @property decorators (which use getter/setter patterns) in TypeScript

What about:

SWC attributes: Properties with @property decorators or attribute getters/setters in TypeScript

castastrophe · 2025-10-01T12:39:16Z

+
+### CSS => SWC implementation gaps
+
+### CSS Spectrum 2 changes


Should we add a note somewhere that some of this information might be summarized in the component's changelog in the spectrum-two branch?

castastrophe · 2025-10-01T12:40:27Z

+- `spectrum-css` (primarily `spectrum-two` branch, with comparisons to `main`)
+- `spectrum-web-components` (`main` branch)
+
+### Using the cursor prompt


Let's add a suggestion here for what models to use. This type of work is better handled by the slower but more advanced thinking models like Claude or gpt-5

marissahuysentruyt

All of the comments I left look to be addressed- thanks again!

* chore: add cursor prompt * docs: add prompt output files for subset of components * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * first docs feedback * docs(link): WIP * docs(s2): addressing feedback in link, tag, tooltip * docs(swc): review feedback pt 3 * chore: add cursor prompt * docs: add prompt output files for subset of components * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * docs(s2): migrating new comments * docs(s2): addressing more feedback * docs(s2): addressing tooltip feedback * docs(s2): update link, tag, group and tt * docs(s2): updating feedback from marissa * chore: add cursor prompt * docs: add prompt output files for subset of components * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * chore: add cursor rule for CONTRIBUTOR-DOCS * docs: add CONTRIBUTOR-DOCSreminder to regenerate nav and verify links When changing doc structure or headings, point readers to Authoring contributor docs for running the nav script and link verification. (Cursor said it would do a better job if I added this to the documentation.) * docs: move component analysis docs into CONTRIBUTOR-DOCS * chore: add cursor prompt * docs: add prompt output files for subset of components * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * chore: add cursor rule for CONTRIBUTOR-DOCS * docs(s2): re-review docs * docs: add CONTRIBUTOR-DOCS reminder to regenerate nav and verify links When changing doc structure or headings, point readers to Authoring contributor docs for running the nav script and link verification. (Cursor said it would do a better job if I added this to the documentation.) * docs: move component analysis docs into CONTRIBUTOR-DOCS * chore: clean up component analysis docs - Add content to the components README - Update broken React links - Add status note for POC components in migration analysis docs - Update component status table * first docs feedback * docs(link): WIP * docs(s2): addressing feedback in link, tag, tooltip * docs(swc): review feedback pt 3 * docs(s2): migrating new comments * docs(s2): addressing more feedback * docs(s2): addressing tooltip feedback * docs(s2): update link, tag, group and tt * docs(s2): updating feedback from marissa * docs(s2): re-review docs * chore: add cursor prompt * docs: add prompt output files for subset of components * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * chore(docs): address feedback * chore(docs): address feedback * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs(checkbox): migration roadmap * docs(fieldgroup): migration roadmap * docs(radio): migration roadmap * docs(switch): migration roadmap * docs(checkbox, field-group): update migration roadmap - gives clarification on invalid checkbox consideration - clarifies some of the implementation gaps for field group * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * docs: add component analysis docs adds migration roadmap and component analysis docs for meter, progress bar, slider, illustrated message and drop zone. * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * chore: update cursor rule for CONTRIBUTOR-DOCS * docs: add CONTRIBUTOR-DOCS reminder to regenerate nav and verify links When changing doc structure or headings, point readers to Authoring contributor docs for running the nav script and link verification. (Cursor said it would do a better job if I added this to the documentation.) * docs: move component analysis docs into CONTRIBUTOR-DOCS * chore: clean up component analysis docs - Add content to the components README - Update broken React links - Add status note for POC components in migration analysis docs - Update component status table - name change "Spectrum 2 migration roadmap" to "Analyze rendering and styling" * docs(s2): updating file structure * docs(s2): addressing rise feedback * docs(s2): updating tooltip docs --------- Co-authored-by: Marissa Huysentruyt <marissa.huysentruyt@heysparkbox.com> Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com> Co-authored-by: Cory Dransfeldt <hi@coryd.dev> Co-authored-by: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com> Co-authored-by: Rise Erpelding <rise@heysparkbox.com>

* chore: add cursor prompt * docs: barebones component analysis docs, prompt updates (#5720) * chore(docs): barebones analysis for Field label, Help text, Picker button, In-field button and In-field progress circle (#5738) * chore(docs): barebones analysis for SWC-1218 * docs(switch,radio,checkbox,fieldgroup): component analysis migration roadmap (#5729) * docs: textfield-based component analysis docs (#5741) * docs(slider,meter,progressbar,dropzone,illustratedmessage): migration roadmap (#5775) * chore(docs): 2nd gen component analysis for avatar, opacity checkerboard, swatch + swatchgroup, thumbnail (#5740) * docs(button, buttongroup, actionbutton, actiongroup): component analysis (#5788) * chore: update cursor rule for CONTRIBUTOR-DOCS * docs: move component analysis docs into CONTRIBUTOR-DOCS * docs(link, tag, taggroup, tooltip): component analysis (#5980) --------- Co-authored-by: Marissa Huysentruyt <marissa.huysentruyt@heysparkbox.com> Co-authored-by: Cory Dransfeldt <hi@coryd.dev> Co-authored-by: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com> Co-authored-by: aramos-adobe <abdulr@adobe.com>

rise-erpelding requested a review from a team as a code owner September 18, 2025 15:45

rise-erpelding added Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. Status:Ready for review PR ready for review or re-review. labels Sep 18, 2025

rise-erpelding force-pushed the rise-erpelding/swc-1208-component-analysis-docs branch from 830facd to 2c217ea Compare September 18, 2025 15:48

rise-erpelding self-assigned this Sep 18, 2025