Skip to content

Commit d69fdff

Browse files
rise-erpeldingrise-erpelding
committed
docs: barebones component analysis docs, prompt updates (#5720)
1 parent ae1918b commit d69fdff

File tree

7 files changed

+1458
-251
lines changed

7 files changed

+1458
-251
lines changed

‎migration-roadmap/alert-banner.md‎

Lines changed: 164 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Alert Banner migration roadmap
22

3+
## Component specifications
4+
5+
### CSS
6+
37
<details>
48
<summary>CSS selectors</summary>
59

@@ -12,7 +16,9 @@
1216
- `.spectrum-AlertBanner-text`
1317
- `.spectrum-AlertBanner.is-open`
1418
- `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body`
15-
- `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)`
19+
- `.spectrum-AlertBanner:lang(ja)`
20+
- `.spectrum-AlertBanner:lang(ko)`
21+
- `.spectrum-AlertBanner:lang(zh)`
1622

1723
</details>
1824

@@ -26,23 +32,6 @@
2632

2733
</details>
2834

29-
<details>
30-
<summary>Attributes</summary>
31-
32-
- `open` (Boolean) - Controls the display of the alert banner
33-
- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner
34-
- `variant` (String) - The variant applies specific styling when set to `negative`, `neutral`, or `info`
35-
36-
</details>
37-
38-
<details>
39-
<summary>Slots</summary>
40-
41-
- Default slot - The alert banner text context
42-
- `action` - Slot for the button element that surfaces the contextual action a user can take
43-
44-
</details>
45-
4635
<details>
4736
<summary>Modifiers</summary>
4837

@@ -75,31 +64,81 @@
7564

7665
</details>
7766

78-
## Visual Comparison
67+
### SWC
68+
69+
<details>
70+
<summary>Attributes</summary>
71+
72+
- `open` (Boolean) - Controls the display of the alert banner
73+
- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner
74+
- `variant` (String) - The variant applies specific styling when set to `negative` or `info`; `variant` attribute is removed when it's passed an invalid variant. Valid values: `neutral`, `info`, `negative`
7975

80-
**Legacy Component:**
76+
</details>
8177

82-
<!-- Screenshot of legacy component will be added here -->
78+
<details>
79+
<summary>Slots</summary>
8380

84-
**Spectrum 2 Component:**
81+
- Default slot - The alert banner text context
82+
- `action` - Slot for the button element that surfaces the contextual action a user can take
8583

86-
<!-- Screenshot of Spectrum 2 component will be added here -->
84+
</details>
8785

88-
## DOM Structure Changes
86+
## Comparison
8987

90-
**Legacy (main branch):**
88+
### DOM structure changes
89+
90+
<details>
91+
<summary>Spectrum Web Components:</summary>
92+
93+
```html
94+
<sp-alert-banner variant="info" dismissible>
95+
#shadow-root
96+
<div class="body" role="alert">
97+
<div class="content">
98+
<sp-icon-info label="Information" class="type"></sp-icon-info>
99+
<div class="text"><slot></slot></div>
100+
</div>
101+
<slot name="action"></slot>
102+
</div>
103+
<div class="end">
104+
<sp-close-button
105+
@click="${this.shouldClose}"
106+
label="Close"
107+
static-color="white"
108+
></sp-close-button>
109+
</div>
110+
</sp-alert-banner>
111+
```
112+
113+
</details>
114+
115+
<details>
116+
<summary>Legacy (CSS main branch):</summary>
91117

92118
```html
93-
<div class="spectrum-AlertBanner spectrum-AlertBanner--{variant} is-open">
119+
<div class="spectrum-AlertBanner is-open spectrum-AlertBanner--info">
94120
<div class="spectrum-AlertBanner-body">
95121
<div class="spectrum-AlertBanner-content">
96-
<svg class="spectrum-AlertBanner-icon">[icon]</svg>
97-
<p class="spectrum-AlertBanner-text">[text]</p>
122+
<div
123+
class="spectrum-Icon spectrum-Icon--sizeM spectrum-AlertBanner-icon"
124+
aria-hidden="true"
125+
>
126+
<svg
127+
class="spectrum-Icon-svg"
128+
focusable="false"
129+
aria-hidden="true"
130+
>
131+
<use xlink:href="#spectrum-icon-18-Info"></use>
132+
</svg>
133+
</div>
134+
<p class="spectrum-AlertBanner-text">
135+
Your trial will expire in 3 days
136+
</p>
98137
</div>
99138
<button
100-
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite"
139+
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite spectrum-Button--sizeM"
101140
>
102-
[action button]
141+
<span class="spectrum-Button-label">Action</span>
103142
</button>
104143
</div>
105144
<div class="spectrum-AlertBanner-end">
@@ -109,107 +148,135 @@
109148
<button
110149
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
111150
>
112-
[close button]
151+
<span class="spectrum-CloseButton-icon" aria-hidden="true">
152+
<svg
153+
class="spectrum-Icon spectrum-Icon--sizeS"
154+
focusable="false"
155+
aria-hidden="true"
156+
>
157+
<use xlink:href="#spectrum-icon-18-Cross"></use>
158+
</svg>
159+
</span>
113160
</button>
114161
</div>
115162
</div>
116163
```
117164

118-
**Spectrum 2 (spectrum-two branch):**
165+
</details>
166+
167+
<details>
168+
<summary>Spectrum 2 (CSS spectrum-two branch):</summary>
119169

120170
```html
121-
<div class="spectrum-AlertBanner spectrum-AlertBanner--{variant} is-open">
171+
<div class="spectrum-AlertBanner is-open spectrum-AlertBanner--info">
122172
<div class="spectrum-AlertBanner-body">
123173
<div class="spectrum-AlertBanner-content">
124-
<svg class="spectrum-AlertBanner-icon">[icon]</svg>
125-
<p class="spectrum-AlertBanner-text">[text]</p>
174+
<div
175+
class="spectrum-Icon spectrum-Icon--sizeM spectrum-AlertBanner-icon"
176+
aria-hidden="true"
177+
>
178+
<svg
179+
class="spectrum-Icon-svg"
180+
focusable="false"
181+
aria-hidden="true"
182+
>
183+
<use xlink:href="#spectrum-icon-18-Info"></use>
184+
</svg>
185+
</div>
186+
<p class="spectrum-AlertBanner-text">
187+
Your trial will expire in 3 days
188+
</p>
126189
</div>
127190
<button
128-
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite"
191+
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite spectrum-Button--sizeM"
129192
>
130-
[action button]
193+
<span class="spectrum-Button-label">Action</span>
131194
</button>
132195
</div>
133196
<div class="spectrum-AlertBanner-end">
134197
<button
135198
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
136199
>
137-
[close button]
200+
<span class="spectrum-CloseButton-icon" aria-hidden="true">
201+
<svg
202+
class="spectrum-Icon spectrum-Icon--sizeS"
203+
focusable="false"
204+
aria-hidden="true"
205+
>
206+
<use xlink:href="#spectrum-icon-18-Cross"></use>
207+
</svg>
208+
</span>
138209
</button>
139210
</div>
140211
</div>
141212
```
142213

143-
## Comparison
144-
145-
| CSS selector | Attribute or slot | Status |
146-
| ---------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- |
147-
| `.spectrum-AlertBanner` | Root element | Implemented |
148-
| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented |
149-
| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented |
150-
| `.spectrum-AlertBanner-body` | - | Implemented |
151-
| `.spectrum-AlertBanner-content` | - | Implemented |
152-
| `.spectrum-AlertBanner-icon` | - | Implemented |
153-
| `.spectrum-AlertBanner-text` | Default slot | Implemented |
154-
| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented |
155-
| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented |
156-
| `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented |
157-
| - | `action` slot | Missing from CSS |
158-
| - | `dismissible` attribute | Missing from CSS |
159-
160-
## Key Structural Changes
161-
162-
**Element Hierarchy Changes:**
163-
164-
- Removed divider element between content and close button in Spectrum 2
165-
- Simplified end container structure
166-
167-
**Class Name Changes:**
168-
169-
- No major class name changes
170-
- Maintained consistent naming convention
171-
172-
**Attribute Changes:**
173-
174-
- Added `open` attribute for controlling display state
175-
- Added `dismissible` attribute for controlling close button visibility
176-
177-
**Slot/Content Changes:**
178-
179-
- Added dedicated `action` slot for button elements
180-
- Default slot remains for text content
181-
182-
**Migration Impact:**
183-
184-
- Removal of divider element will affect visual separation between content and close button
185-
- Web component provides better semantic structure with slots
214+
</details>
186215

187-
### Implementation Gaps
216+
<details>
217+
<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>
218+
219+
```diff
220+
<div class="spectrum-AlertBanner-end">
221+
- <div
222+
- class="spectrum-Divider spectrum-Divider--vertical spectrum-Divider--sizeS"
223+
- ></div>
224+
<button
225+
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
226+
>
227+
<span class="spectrum-CloseButton-icon" aria-hidden="true">
228+
<svg
229+
class="spectrum-Icon spectrum-Icon--sizeS"
230+
focusable="false"
231+
aria-hidden="true"
232+
>
233+
<use xlink:href="#spectrum-icon-18-Cross"></use>
234+
</svg>
235+
</span>
236+
</button>
237+
</div>
238+
```
188239

189-
**CSS Features Missing from Web Component:**
240+
</details>
190241

191-
- All CSS selectors are properly implemented in the web component
242+
### CSS => SWC mapping
192243

193-
**Web Component Features Missing from CSS:**
244+
| CSS selector | Attribute or slot | Status |
245+
| ------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- |
246+
| `.spectrum-AlertBanner` | Base component, `variant="neutral"` | Implemented |
247+
| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented |
248+
| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented |
249+
| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented |
250+
| `.spectrum-AlertBanner-text` | Default slot within `.text` | Implemented |
251+
| `.spectrum-AlertBanner-icon` | Icon rendering (info/negative variants) | Implemented |
252+
| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented |
253+
| `.spectrum-AlertBanner:lang(ja), .spectrum-AlertBanner:lang(ko), .spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented |
254+
| `.spectrum-AlertBanner-body` | `.body` | Implemented |
255+
| `.spectrum-AlertBanner-content` | `.content` | Implemented |
256+
| `.spectrum-AlertBanner-end` | `.end` | Implemented |
257+
| Corresponds to `.spectrum-Button` within `.spectrum-AlertBanner` | `action` slot | Implemented |
194258

195-
- `action` slot - needs CSS support for slotted action button positioning
196-
- `dismissible` attribute - CSS should provide conditional styling based on this attribute
259+
Note: the `neutral` variant of Alert banner is the default variant in both CSS and SWC.
197260

198-
**Features Being Deprecated/Removed:**
261+
## Summary of changes
199262

200-
- Divider element between content and close button has been removed in Spectrum 2
263+
### CSS => SWC implementation gaps
201264

202-
### Action Items for Web Component Maintainers
265+
**No missing features.** All CSS selectors have corresponding web component implementations:
203266

204-
**Required Additions:**
267+
- **Variants**: `--info` → `variant="info"`, `--negative` → `variant="negative"`
268+
- **State**: `.is-open` → `open` attribute
269+
- **Content**: Text and icon selectors → default slot and programmatic icon rendering
270+
- **Dismissible**: Close button presence → `dismissible` attribute
271+
- **Action slot**: Available in SWC but not in CSS templates
205272

206-
- No major additions needed - component is well-aligned with CSS implementation
273+
### CSS Spectrum 2 changes
207274

208-
**Required Removals:**
275+
**Divider element removed in spectrum-two branch**: The `<div class="spectrum-Divider spectrum-Divider--vertical spectrum-Divider--sizeS"></div>` element is no longer included in the close button section. The spectrum-two branch template only includes the close button without the divider separator.
209276

210-
- None identified
277+
This divider does not appear to be present in SWC, and therefore will not need to be removed for Spectrum 2.
211278

212-
**Breaking Changes:**
279+
## Resources
213280

214-
- Divider removal may affect existing implementations expecting visual separation
215-
- Migration guidance: Update expectations for visual separation between content and close button
281+
- [CSS migration](https://github.com/adobe/spectrum-css/pull/2652)
282+
- [Spectrum 2 preview](https://spectrumcss.z13.web.core.windows.net/pr-2352/index.html?path=/docs/components-alert-banner--docs)

0 commit comments

Comments
 (0)