Skip to content

docs: barebones component analysis docs #5720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 15 commits into
base: 2nd-gen-component-analysis
Choose a base branch
from
+1,445 −251
Open

docs: barebones component analysis docs #5720

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
cac3e9d
docs: migration roadmap, initial WIP docs
rise-erpelding Sep 5, 2025
6845805
docs(alert-banner): prompt adjustments and alert-banner docs
rise-erpelding Sep 5, 2025
c32ab5a
docs: resource section
rise-erpelding Sep 5, 2025
03f01f2
docs: dom diff
rise-erpelding Sep 5, 2025
f8bdd63
docs(badge): update docs
rise-erpelding Sep 5, 2025
4777b3a
docs(divider): update docs
rise-erpelding Sep 8, 2025
b323530
docs: update cursor prompt
rise-erpelding Sep 8, 2025
e520d1e
docs(progresscircle): update docs
rise-erpelding Sep 8, 2025
2a0817d
docs(statuslight): update docs
rise-erpelding Sep 8, 2025
b67cf32
docs(asset): update docs
rise-erpelding Sep 8, 2025
14530b9
docs(alert-banner, divider): more concise summary section
rise-erpelding Sep 8, 2025
cc546c2
docs: updates pt 1
rise-erpelding Sep 10, 2025
d7bb524
docs: updates pt 2
rise-erpelding Sep 10, 2025
3d255d8
docs: remove visual comparison from prompt and docs
rise-erpelding Sep 12, 2025
2e70168
docs(statuslight): spelling error
rise-erpelding Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 166 additions & 93 deletions migration-roadmap/alert-banner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Alert Banner migration roadmap

## Component specifications

### CSS

<details>
<summary>CSS selectors</summary>

Expand All @@ -12,7 +16,9 @@
- `.spectrum-AlertBanner-text`
- `.spectrum-AlertBanner.is-open`
- `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body`
- `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)`
- `.spectrum-AlertBanner:lang(ja)`
- `.spectrum-AlertBanner:lang(ko)`
- `.spectrum-AlertBanner:lang(zh)`

</details>

Expand All @@ -26,23 +32,6 @@

</details>

<details>
<summary>Attributes</summary>

- `open` (Boolean) - Controls the display of the alert banner
- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner
- `variant` (String) - The variant applies specific styling when set to `negative`, `neutral`, or `info`

</details>

<details>
<summary>Slots</summary>

- Default slot - The alert banner text context
- `action` - Slot for the button element that surfaces the contextual action a user can take

</details>

<details>
<summary>Modifiers</summary>

Expand Down Expand Up @@ -75,7 +64,28 @@

</details>

## Visual Comparison
### SWC

<details>
<summary>Attributes</summary>

- `open` (Boolean) - Controls the display of the alert banner
- `dismissible` (Boolean) - Whether to include an icon-only close button to dismiss the alert banner
- `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`

</details>

<details>
<summary>Slots</summary>

- Default slot - The alert banner text context
- `action` - Slot for the button element that surfaces the contextual action a user can take

</details>

## Comparison

### Visual comparison

**Legacy Component:**

Expand All @@ -85,21 +95,57 @@

<!-- Screenshot of Spectrum 2 component will be added here -->

## DOM Structure Changes
### DOM structure changes

**Legacy (main branch):**
<details>
<summary>Spectrum Web Components:</summary>

```html
<div class="spectrum-AlertBanner spectrum-AlertBanner--{variant} is-open">
<div class="body" role="alert">
<div class="content">
<sp-icon-info label="Information" class="type"></sp-icon-info>
<div class="text"><slot></slot></div>
</div>
<slot name="action"></slot>
</div>
<div class="end">
<sp-close-button
@click="${this.shouldClose}"
label="Close"
static-color="white"
></sp-close-button>
</div>
```

</details>

<details>
<summary>Legacy (CSS main branch):</summary>

```html
<div class="spectrum-AlertBanner is-open spectrum-AlertBanner--info">
<div class="spectrum-AlertBanner-body">
<div class="spectrum-AlertBanner-content">
<svg class="spectrum-AlertBanner-icon">[icon]</svg>
<p class="spectrum-AlertBanner-text">[text]</p>
<div
class="spectrum-Icon spectrum-Icon--sizeM spectrum-AlertBanner-icon"
aria-hidden="true"
>
<svg
class="spectrum-Icon-svg"
focusable="false"
aria-hidden="true"
>
<use xlink:href="#spectrum-icon-18-Info"></use>
</svg>
</div>
<p class="spectrum-AlertBanner-text">
Your trial will expire in 3 days
</p>
</div>
<button
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite"
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite spectrum-Button--sizeM"
>
[action button]
<span class="spectrum-Button-label">Action</span>
</button>
</div>
<div class="spectrum-AlertBanner-end">
Expand All @@ -109,107 +155,134 @@
<button
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
>
[close button]
<span class="spectrum-CloseButton-icon" aria-hidden="true">
<svg
class="spectrum-Icon spectrum-Icon--sizeS"
focusable="false"
aria-hidden="true"
>
<use xlink:href="#spectrum-icon-18-Cross"></use>
</svg>
</span>
</button>
</div>
</div>
```

**Spectrum 2 (spectrum-two branch):**
</details>

<details>
<summary>Spectrum 2 (CSS spectrum-two branch):</summary>

```html
<div class="spectrum-AlertBanner spectrum-AlertBanner--{variant} is-open">
<div class="spectrum-AlertBanner is-open spectrum-AlertBanner--info">
<div class="spectrum-AlertBanner-body">
<div class="spectrum-AlertBanner-content">
<svg class="spectrum-AlertBanner-icon">[icon]</svg>
<p class="spectrum-AlertBanner-text">[text]</p>
<div
class="spectrum-Icon spectrum-Icon--sizeM spectrum-AlertBanner-icon"
aria-hidden="true"
>
<svg
class="spectrum-Icon-svg"
focusable="false"
aria-hidden="true"
>
<use xlink:href="#spectrum-icon-18-Info"></use>
</svg>
</div>
<p class="spectrum-AlertBanner-text">
Your trial will expire in 3 days
</p>
</div>
<button
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite"
class="spectrum-Button spectrum-Button--outline spectrum-Button--staticWhite spectrum-Button--sizeM"
>
[action button]
<span class="spectrum-Button-label">Action</span>
</button>
</div>
<div class="spectrum-AlertBanner-end">
<button
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
>
[close button]
<span class="spectrum-CloseButton-icon" aria-hidden="true">
<svg
class="spectrum-Icon spectrum-Icon--sizeS"
focusable="false"
aria-hidden="true"
>
<use xlink:href="#spectrum-icon-18-Cross"></use>
</svg>
</span>
</button>
</div>
</div>
```

## Comparison

| CSS selector | Attribute or slot | Status |
| ---------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- |
| `.spectrum-AlertBanner` | Root element | Implemented |
| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented |
| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented |
| `.spectrum-AlertBanner-body` | - | Implemented |
| `.spectrum-AlertBanner-content` | - | Implemented |
| `.spectrum-AlertBanner-icon` | - | Implemented |
| `.spectrum-AlertBanner-text` | Default slot | Implemented |
| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented |
| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented |
| `.spectrum-AlertBanner:lang(ja)`, `.spectrum-AlertBanner:lang(ko)`, `.spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented |
| - | `action` slot | Missing from CSS |
| - | `dismissible` attribute | Missing from CSS |

## Key Structural Changes

**Element Hierarchy Changes:**

- Removed divider element between content and close button in Spectrum 2
- Simplified end container structure

**Class Name Changes:**

- No major class name changes
- Maintained consistent naming convention

**Attribute Changes:**

- Added `open` attribute for controlling display state
- Added `dismissible` attribute for controlling close button visibility

**Slot/Content Changes:**

- Added dedicated `action` slot for button elements
- Default slot remains for text content

**Migration Impact:**

- Removal of divider element will affect visual separation between content and close button
- Web component provides better semantic structure with slots
</details>

### Implementation Gaps
<details>
<summary>Diff: Legacy (CSS main) → Spectrum 2 (CSS spectrum-two)</summary>

```diff
<div class="spectrum-AlertBanner-end">
- <div
- class="spectrum-Divider spectrum-Divider--vertical spectrum-Divider--sizeS"
- ></div>
<button
class="spectrum-CloseButton spectrum-CloseButton--sizeM spectrum-CloseButton--staticWhite"
>
<span class="spectrum-CloseButton-icon" aria-hidden="true">
<svg
class="spectrum-Icon spectrum-Icon--sizeS"
focusable="false"
aria-hidden="true"
>
<use xlink:href="#spectrum-icon-18-Cross"></use>
</svg>
</span>
</button>
</div>
```

**CSS Features Missing from Web Component:**
</details>

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

**Web Component Features Missing from CSS:**
| CSS selector | Attribute or slot | Status |
| ------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- |
| `.spectrum-AlertBanner` | Base component, `variant="neutral"` | Implemented |
| `.spectrum-AlertBanner--info` | `variant="info"` | Implemented |
| `.spectrum-AlertBanner--negative` | `variant="negative"` | Implemented |
| `.spectrum-AlertBanner.is-open` | `open` attribute | Implemented |
| `.spectrum-AlertBanner-text` | Default slot | Implemented |
| `.spectrum-AlertBanner-icon` | Icon rendering (info/negative variants) | Implemented |
| `.spectrum-AlertBanner:has(.spectrum-CloseButton) .spectrum-AlertBanner-body` | `dismissible` attribute | Implemented |
| `.spectrum-AlertBanner:lang(ja), .spectrum-AlertBanner:lang(ko), .spectrum-AlertBanner:lang(zh)` | Language-specific styling | Implemented |
| `.spectrum-AlertBanner-body` | `.body` | Implemented |
| `.spectrum-AlertBanner-content` | `.content` | Implemented |
| Corresponds to `.spectrum-Button` within `.spectrum-AlertBanner` | `action` slot | Implemented |

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

**Features Being Deprecated/Removed:**
## Summary of changes

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

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

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

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

**Required Removals:**
**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.

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

**Breaking Changes:**
## Resources

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