Skip to content

Commit 9e7a40d

Browse files
rise-erpeldingrise-erpelding
authored
docs: textfield-based component analysis docs (#5741)
1 parent ab5ae6a commit 9e7a40d

File tree

5 files changed

+1799
-132
lines changed

5 files changed

+1799
-132
lines changed

‎migration-roadmap/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Spectrum 2 migration roadmap
2+
3+
This directory contains comprehensive migration documentation for 2nd generation Spectrum Web Components based on the implementation of Spectrum 2 components that were previously migrated in [Spectrum CSS](https://github.com/adobe/spectrum-css/tree/spectrum-two). It helps engineers understand what needs to be implemented, updated, or aligned between the two systems to guide development of 2nd generation web components.
4+
5+
## Purpose
6+
7+
### Why we do this analysis
8+
9+
The migration roadmap facilitates development of 2nd generation, full-fidelity Spectrum 2 web components by providing:
10+
11+
- **Feature gap analysis**: Identifies new features and capabilities needed to match Spectrum 2 design specifications
12+
- **Implementation comparison**: Maps CSS selectors to existing SWC properties and notes markup differences between systems
13+
- **Deprecation tracking**: Documents features or variants being removed in Spectrum 2
14+
- **Planning guidance**: High-level overview of changes to assist with estimating migration effort
15+
16+
### The bigger picture
17+
18+
When engineers begin 2nd generation Spectrum 2 implementation work, this documentation provides:
19+
20+
- **Clear starting point**: Entry point for development work that identifies specific areas needing adjustment
21+
- **Gap analysis**: Differences that would prevent Spectrum 2 CSS from working in SWC
22+
- **Reference materials**: Links to CSS and React implementations, and previous migration work
23+
24+
## What we analyze
25+
26+
### Component specifications
27+
28+
We extract and document:
29+
30+
- **CSS selectors**: All selectors from `metadata.json` in the spectrum-css `spectrum-two` branch
31+
- **Passthroughs**: CSS passthrough custom properties
32+
- **Modifiers**: CSS modifier custom properties (note that `--mod` properties will be deprecated in the 2nd-gen implementation)
33+
- **SWC attributes**: Properties with `@property` decorators (which use getter/setter patterns) in TypeScript
34+
- **SWC slots**: Slot patterns from render methods
35+
- **Nested components**: Child components used within the component
36+
37+
### DOM structure comparison
38+
39+
We analyze markup from three sources:
40+
41+
1. **Spectrum Web Components**: Current HTML structure from web component `render()` method
42+
2. **Legacy CSS**: HTML structure from spectrum-css `main` branch template files
43+
3. **Spectrum 2 CSS**: HTML structure from spectrum-css `spectrum-two` branch template files
44+
45+
This three-way comparison reveals:
46+
47+
- DOM changes specific to Spectrum 2 features (Legacy → Spectrum 2)
48+
- Structural differences between CSS and SWC implementations
49+
- Additional work needed for SWC render methods beyond new features
50+
51+
### CSS to SWC mapping
52+
53+
We create mapping tables that connect:
54+
55+
- **CSS selectors** to **SWC attributes or slots**
56+
- **Variants** (CSS selectors with `--` notation) typically map to component attributes
57+
- **Base elements** (selectors with single `-`) typically map to slots
58+
- **Status tracking** for implementation gaps
59+
60+
### Implementation gaps
61+
62+
The analysis surfaces:
63+
64+
- **Missing from SWC**: CSS features without web component equivalents
65+
- **Missing from CSS**: Web component features without CSS support
66+
- **New for Spectrum 2**: Features that need to be added for 2nd generation
67+
- **Deprecated**: Features being removed in Spectrum 2
68+
69+
## Documentation structure
70+
71+
Each component follows this format:
72+
73+
```markdown
74+
# [Component name] migration roadmap
75+
76+
## Component specifications
77+
78+
**Note**: CSS selectors and attributes/slots are often grouped by elements, states, variants, or other logical categories to improve readability.
79+
80+
### CSS
81+
82+
- CSS selectors (collapsible)
83+
- Passthroughs (collapsible)
84+
- Modifiers (deprecated) (collapsible)
85+
86+
### SWC
87+
88+
- Attributes (collapsible)
89+
- Slots (collapsible)
90+
91+
## Comparison
92+
93+
### DOM structure changes
94+
95+
- Spectrum Web Components (collapsible)
96+
- Legacy CSS main branch (collapsible)
97+
- Spectrum 2 CSS spectrum-two branch (collapsible)
98+
- Diff: Legacy → Spectrum 2, based on changes made to template in CSS migration work (collapsible, if changes exist)
99+
100+
### CSS => SWC mapping
101+
102+
| CSS selector | Attribute or slot | Status |
103+
| ------------ | ----------------- | ------------------------------------------------------- |
104+
| ... | ... | Implemented/Missing from WC/Missing from CSS/Deprecated |
105+
106+
## Summary of changes
107+
108+
### CSS => SWC implementation gaps
109+
110+
### CSS Spectrum 2 changes
111+
112+
**Note**: Some of this information may be summarized in the component's changelog in the spectrum-two branch.
113+
114+
## Resources
115+
116+
- [CSS migration]()
117+
- [Spectrum 2 preview]()
118+
- [React]()
119+
```
120+
121+
## How to generate documentation
122+
123+
### Prerequisites
124+
125+
Set up a Cursor workspace with both repositories:
126+
127+
- `spectrum-css` (primarily `spectrum-two` branch, with comparisons to `main`)
128+
- `spectrum-web-components` (`main` branch)
129+
130+
### Using the cursor prompt
131+
132+
**Model recommendation**: This type of detailed migration analysis is better handled by slower but more advanced thinking models like Claude or GPT-5, which can provide more thorough analysis and better understand complex component relationships.
133+
134+
1. **Load the prompt**: Reference `migration-roadmap/cursor_prompt.md`
135+
2. **Specify component**: Replace `[COMPONENT_NAME]` with the target component
136+
3. **Branch verification**: Ensure correct branches are checked out:
137+
- `spectrum-css`: `spectrum-two` for specifications, both `main` and `spectrum-two` for comparisons
138+
- `spectrum-web-components`: `main` branch
139+
4. **Generate documentation**: Follow the structured prompt to create component markdown files
140+
141+
### Quality assurance
142+
143+
**Human review is required** for all generated documentation:
144+
145+
- **Verify data accuracy**: Check extracted information against source repositories/branches
146+
- **Validate mappings**: Ensure CSS selector to SWC feature mappings are correct
147+
- **Review summaries**: Confirm summaries provide clear, actionable guidance
148+
- **Check DOM structures**: Verify HTML snippets match actual template/render method output
149+
- **Audit diffs**: Ensure branch comparisons are accurate and meaningful
150+
151+
### Common issues to watch for
152+
153+
- **Branch confusion**: AI may analyze wrong branches or mix up repositories
154+
- **Incomplete mappings**: AI may incorrectly mark implemented states or variants as missing in mapping tables
155+
- **Verbose summaries**: Trim AI-generated text to focus on actionable changes and human readability
156+
- **DOM accuracy**: Verify render method HTML matches documented structure
157+
- **Missing components**: Note when components don't exist in one system or the other
158+
159+
## Contributing
160+
161+
### Modifying the cursor prompt
162+
163+
The cursor prompt template (`cursor_prompt.md`) can be modified to improve AI performance. Consider updates for:
164+
165+
- Better mapping accuracy
166+
- Clearer summary generation
167+
- Additional analysis sections
168+
- Improved error handling
169+
170+
### Adding new components
171+
172+
1. Use the cursor prompt with the target component name
173+
2. Generate the markdown file in `migration-roadmap/[component-name].md`
174+
3. Review and validate all sections for accuracy
175+
4. Submit a PR to the `2nd-gen-component-analysis` branch
176+
177+
## Resources
178+
179+
- [Cursor prompt template](cursor_prompt.md)
180+
- [Spectrum CSS repository](https://github.com/adobe/spectrum-css)
181+
- [Spectrum Web Components repository](https://github.com/adobe/spectrum-web-components)

‎migration-roadmap/color-field.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Color field migration roadmap
2+
3+
There is no CSS implementation for this component; it only exists in SWC.
4+
5+
## Component specifications
6+
7+
### SWC
8+
9+
<details>
10+
<summary>Attributes</summary>
11+
12+
**Color Field specific attributes:**
13+
14+
- `view-color` - Whether to show the color preview
15+
16+
**Inherited from TextfieldBase:**
17+
18+
- `allowed-keys` - A regular expression outlining the keys that will be allowed to update the value
19+
- `autocomplete` - What form of assistance should be provided when attempting to supply a value
20+
- `focused` - Whether the color field is focused
21+
- `grows` - Whether a form control with multiline attribute will change size vertically
22+
- `invalid` - Whether the color field is invalid
23+
- `label` - A string applied via aria-label to the form control when a user visible label is not provided
24+
- `maxlength` - Defines the maximum string length that the user can enter
25+
- `minlength` - Defines the minimum string length that the user can enter
26+
- `multiline` - Whether the form control should accept a value longer than one line
27+
- `name` - Name of the form control
28+
- `pattern` - Pattern the value must match to be valid
29+
- `placeholder` - Text that appears in the form control when it has no value set
30+
- `quiet` - Whether to display the form control with no visible background
31+
- `readonly` - Whether a user can interact with the value of the form control
32+
- `required` - Whether the form control will be found to be invalid when it holds no value
33+
- `rows` - The specific number of rows the form control should provide in the user interface
34+
- `type` - The type of the form control (defaults to 'text')
35+
- `valid` - Whether the value held by the form control is valid
36+
- `value` - The value held by the form control
37+
38+
**Inherited from SizedMixin:**
39+
40+
- `size` - Size of the color field (s, m, l, xl)
41+
42+
**Inherited from Focusable:**
43+
44+
- `autofocus` - When this control is rendered, focus it automatically
45+
- `disabled` - Disable this control. It will not receive focus or events
46+
- `tabIndex` - The tab index to apply to this control
47+
48+
</details>
49+
50+
<details>
51+
<summary>Slots</summary>
52+
53+
- `help-text` - Help text for the color field (inherited from TextfieldBase)
54+
- `negative-help-text` - Negative help text when invalid (inherited from TextfieldBase)
55+
56+
</details>
57+
58+
### React implementation
59+
60+
<details>
61+
<summary>Props</summary>
62+
63+
- `label` - The label for the color field
64+
- `autoFocus` - Whether the element should receive focus on render
65+
- `channel` - The color channel that this field edits, if not provided, the color is edited as a hex value (`hue` | `saturation` | `brightness` | `lightness` | `red` | `green` | `blue` | `alpha`)
66+
- `colorSpace` - The color space that the color field operates in if a channel prop is provided, if no channel is provided, the color field always displays the color as an RGB hex value (`rgb` | `hsl` | `hsb`)
67+
- `defaultValue` - The default value
68+
- `description` - A description for the field, provides a hint such as specific requirements for what to choose
69+
- `errorMessage` - An error message for the field
70+
- `excludeFromTabOrder` - Whether to exclude the element from the sequential tab order
71+
- `form` - The `<form>` element to associate the input with
72+
- `isDisabled` - Whether the input is disabled
73+
- `isInvalid` - Whether the input value is invalid
74+
- `isReadonly` - Whether the input can be selected but not changed by the user
75+
- `isRequired` - Whether the color field is required before form submission
76+
- `isWheelDisabled` - Enables or disables changing the value with scroll
77+
- `labelAlign` - The label's horizontal alignment relative to the element it is labeling (`start` | `end`)
78+
- `labelPosition` - The label's overall position relative to the element it is labeling (`top` | `side`)
79+
- `name` - The name of the input element, used when submitting an HTML form
80+
- `necessityIndicator`
81+
- `size` - Size of the color field (s, m, l, xl)
82+
- `validate` - A function that returns an error message if a given value is invalid
83+
- `validationBehavior` - Whether to use native HTML form validation to prevent form submission when the value is missing or invalid
84+
- `value` - The value of the color field
85+
86+
</details>
87+
88+
## DOM structure
89+
90+
### SWC DOM structure
91+
92+
```html
93+
<div id="textfield">
94+
<!-- State icons (when invalid or valid) -->
95+
<sp-icon-alert id="invalid" class="icon"></sp-icon-alert>
96+
<!-- OR -->
97+
<sp-icon-checkmark100
98+
id="valid"
99+
class="icon spectrum-UIIcon-Checkmark100"
100+
></sp-icon-checkmark100>
101+
102+
<!-- Input element -->
103+
<input
104+
type="text"
105+
class="input"
106+
aria-describedby="sp-help-text-..."
107+
aria-label="Label"
108+
name="..."
109+
maxlength="..."
110+
minlength="..."
111+
pattern="..."
112+
placeholder="..."
113+
autocomplete="..."
114+
?disabled
115+
?required
116+
?readonly
117+
/>
118+
</div>
119+
120+
<!-- Help text container (inherited from TextfieldBase) -->
121+
<div id="sp-help-text-..." aria-live="assertive">
122+
<slot name="negative-help-text"></slot>
123+
<!-- OR -->
124+
<slot name="help-text"></slot>
125+
</div>
126+
127+
<!-- Color handle (only when view-color=true and valid=true) -->
128+
<sp-color-handle size="m" color="rgb(...)"></sp-color-handle>
129+
```
130+
131+
## Summary of changes
132+
133+
### Inherited from TextfieldBase
134+
135+
The ColorField component extends TextfieldBase, which means it will inherit all the changes and improvements made to the Textfield component in Spectrum 2 CSS, for example:
136+
137+
- **Quiet variant**: removed in Spectrum 2
138+
- **Label position**: CSS supports side label as well as the default top label
139+
140+
## Resources
141+
142+
- [Spectrum React ColorField documentation](https://react-spectrum.adobe.com/s2/index.html?path=/docs/colorfield--docs)

0 commit comments

Comments
 (0)