adobe / adobe/spectrum-web-components

Audit: 1st-gen @deprecated properties lack in-place replacements and public docs don't disclose deprecation

Open
#6,661 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1.5k
Forks
262
Avg merge
3d 10h
Merged PRs (30d)
68

Description

## Summary

While investigating a support question about the deprecated `quiet` property on `sp-button`, we found the same pattern repeated across most 1st-gen components that carry `@deprecated` JSDoc tags: the deprecation is disclosed only in a changelog entry and/or a runtime console warning gated behind `window.__swc.DEBUG`. The component's own README (which powers the public docs site) continues to teach the deprecated attribute as the normal, canonical way to use the component, with no callout at all.

In several cases there is also no working same-generation replacement: the only replacement lives on a different Spectrum 2 component in a different package (`@adobe/spectrum-wc`), so 1st-gen consumers have no way to satisfy an "avoid deprecated APIs" lint rule short of migrating the whole component.

## Confirmed findings

### Broken guidance (tracked separately, fix in progress: #TBD)
- `ProgressBar.ts` deprecation warnings for `progress` and `side-label` reference `value` / `label-position` attributes that don't exist anywhere in the `progress-bar` package. They only exist on the 2nd-gen `swc-progress-bar`.

### No in-place (1st-gen) replacement, but documented as canonical usage in the package README
| Component | Deprecated prop | Real replacement |
|---|---|---|
| `sp-button` | `treatment`, `quiet` | `fill-style` on `swc-button` only |
| `sp-accordion-item` | `label` | `label` slot on `swc-accordion-item` only |
| `sp-progress-bar` | `label`, `progress`, `side-label` | `swc-progress-bar` only (see broken-guidance note above) |
| `sp-button-group` | `vertical` | `orientation="vertical"` on `swc-button-group` only |
| `sp-action-group` | `vertical`, `selects`, `selected`, `emphasized` | `swc-toggle-button-group` / `swc-segmented-control` only |
| `sp-action-button` | `selected`, `toggles` | `swc-toggle-button` only |
| `sp-tooltip` | `self-managed` | none named in JSDoc ("an updated binding method") |
| `sp-status-light` | `disabled` | none stated at all |

### No replacement stated anywhere (needs a product decision)
- `ActionButton.emphasized`, `ActionGroup.emphasized`, `Tooltip.tipPadding`, `StatusLight.disabled` — `@deprecated` with no migration path mentioned. Unclear whether these are a straight removal or need a documented target.

### Already handled well (use as the template for fixing the rest)
- `AccordionItem.level` → `Accordion.level`: real, working, same-generation replacement with a runtime warning, already cascading correctly.
- `ClearButton.variant="overBackground"` → `staticColor`: replacement already implemented and works today.
- `IllustratedMessage.heading`/`description` → named slots: already implemented and rendering correctly.
- `Dropzone.isDragged`/`isFilled`: intentionally has no runtime warning because the underlying attribute is unchanged; only the JS property name changes.

## Proposed follow-up work
1. Fix the broken `progress-bar` warnings (separate PR, in progress).
2. Add a deprecation callout to each affected README wherever the doc's own example currently uses the deprecated attribute as canonical usage.
3. Resolve the no-replacement cases (`emphasized` x2, `tipPadding`, `disabled`) with either a documented replacement or an explicit "removed with no replacement" note.
4. Adopt a standing rule: every `@deprecated` JSDoc tag must either name a replacement that exists and works today on the same component, or explicitly state that no 1st-gen replacement exists and migration requires the Spectrum 2 component.

Contributor guide

Open the contributing guide

Research direction

Review the affected component READMEs and their @deprecated JSDoc tags, using the listed handled cases as templates. Confirm which deprecated attributes lack same-generation replacements, add documentation callouts where appropriate, and record an explicit migration or no-replacement decision for each unresolved case.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, frontend
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.