adobe / adobe/spectrum-web-components
Audit: 1st-gen @deprecated properties lack in-place replacements and public docs don't disclose deprecation
- 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
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