Adopt Adobe Spectrum 2 design system

[lamontacrook]

Summary

Adopt Spectrum 2 across drago-toolkit so internal tools and author-facing surfaces share Adobe’s current design language: updated tokens, typography, iconography, accessibility defaults, and (where appropriate) Spectrum Web Components (SWC).

References

• Spectrum 2 overview: https://s2.spectrum.adobe.com/
• SWC Spectrum 2 migration: https://opensource.adobe.com/spectrum-web-components/migrating-to-spectrum2/
• Design tokens (tokens-v2): https://opensource.adobe.com/spectrum-web-components/tools/styles/
• Theme / sp-theme (system="spectrum-two"): https://opensource.adobe.com/spectrum-web-components/tools/theme/api/

---

Current state (baseline)

Surface	Stack	Design today
tools/inventory/	Lit 3, light DOM, ~1.1k lines custom CSS	Hand-rolled Spectrum 1–style CSS variables on ema-inventory; custom tab shell modeled on React Spectrum ARIA
tools/eds-migration/	Lit (planned/parallel pattern)	Duplicated hand-rolled Spectrum-style tokens on ema-eds-migration
tools/scheduler/	Lit, shadow DOM	Ad-hoc light-dark() colors, not aligned to Spectrum
Site blocks / styles/styles.css	Helix blocks, Montserrat	README documents spacing/emphasis/button tokens (XS–XXL, accent/primary, gray scales) — not Spectrum 2
Build	esbuild bundles deps/lit only	No @spectrum-web-components/* dependencies yet

Implication: Inventory is the best pilot (already Spectrum-minded, largest UI). Site blocks are a separate, later track to avoid blocking tool work.

---

Goals

1. Single source of truth for color, type, spacing, radius, and focus rings via official Spectrum 2 token CSS (tokens-v2).
2. Consistent components for repeated patterns (Button, TextField, Tabs, Table, Progress, Dialog) via SWC where bundle size allows.
3. Accessibility by default — keyboard models, focus visibility, prefers-reduced-motion, contrast-ready light/dark.
4. Incremental migration — no big-bang rewrite; inventory proves the pattern, then eds-migration and scheduler.

Non-goals (initial pass)

• Rebuilding every Helix block in SWC in one release.
• Introducing React / React Spectrum (repo is Lit + vanilla).
• Custom fork of Spectrum tokens.

---

Recommended technical approach

Option A — Tokens only (smallest diff)

Import @spectrum-web-components/styles tokens-v2 + typography.css; map existing BEM classes to token variables; drop duplicated hex values in inventory.css / eds-migration.css.

Option B — Tokens + sp-theme + selective SWC (recommended)

1. Wrap tool roots in <sp-theme system="spectrum-two" scale="medium" color="light"> (and dark variant behind a toggle or prefers-color-scheme).
2. Import token CSS as documented for Spectrum 2.
3. Replace high-churn primitives incrementally: sp-button, sp-textfield, sp-tabs / sp-tab-panel, sp-table, sp-progress-circle, sp-toast (for copy feedback).
4. Keep domain-specific UI (sitemap tree, DA repo browser, compare columns) as custom markup styled with tokens until a SWC pattern exists.

Option C — Full SWC everywhere

Highest consistency, largest bundle and import-graph cost — not recommended for Helix-delivered author pages without a dedicated bundle strategy.

Decision: Target Option B for tools/*; evaluate Option A only for blocks/ until performance budget is defined.

---

Implementation phases

Phase 0 — Discovery & standards (1–2 days)

• Inventory audit: list every UI primitive in tools/inventory/inventory.js (buttons, inputs, tabs, tables, pills, panels, trees).
• Map primitives → SWC component (or “stay custom”).
• Define bundle budget for tool pages (target max kB gzipped for Spectrum additions).
• Pin SWC versions: all @spectrum-web-components/* packages same semver (required by SWC).
• Extend npm run lint:css to include tools/**/*.css.
• Document conventions in README “Design System” (link Spectrum 2, token import pattern, sp-theme usage).

Phase 1 — Shared Spectrum 2 foundation (3–5 days)

• Add dependencies: @spectrum-web-components/styles, @spectrum-web-components/theme (and component packages as needed).
• Create deps/spectrum/ (or styles/spectrum/) entry that imports:

  @import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
  @import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
  @import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
  @import '@spectrum-web-components/styles/typography.css';

• Add esbuild (or documented static copy) step for SWC JS if tools import sp-* modules from node_modules.
• Introduce shared tools/shared/spectrum-theme.js helper that registers sp-theme once.
• Load Adobe Clean / Source Sans 3 per Spectrum typography guidance (avoid Montserrat inside tools).

Acceptance: A minimal demo page shows sp-theme system="spectrum-two" with one sp-button and token-driven background/text.

Phase 2 — Inventory pilot (1–2 weeks)

Highest value; already references React Spectrum tab behavior in comments.

• Wrap ema-inventory content in sp-theme (light DOM can remain if CSS targets ema-inventory sp-button — verify SWC style penetration).
• Replace hand-rolled --spectrum-gray-* / --spectrum-blue-* blocks in inventory.css with tokens-v2 variables; delete duplicate hex definitions.
• Migrate tabs to sp-tabs + sp-tab + sp-tab-panel OR keep custom tab markup but style exclusively with S2 tab tokens.
• Migrate buttons (ema-inv__btn, primary/compact) → sp-button variants (accent, secondary, quiet).
• Migrate text fields / file inputs → sp-textfield / sp-picker where applicable.
• Migrate status / banners → sp-inline-alert or toast pattern.
• Tables: align ema-inv__analysis-table with sp-table or token-based table styles from SWC.
• Verify keyboard interaction for tabs and tree (role="tree") still passes manual a11y check.
• Visual regression pass: dashboard cards, compare columns, migration panel.

Acceptance: Inventory matches Spectrum 2 look on light theme; no duplicated legacy token hex in inventory.css; axe/keyboard smoke test documented.

Phase 3 — Other tools (1 week)

• tools/eds-migration/: reuse shared theme + tokens; remove duplicated CSS variables.
• tools/scheduler/: adopt sp-theme + tokens; replace light-dark() ad hoc palette.
• tools/quick-edit/, tools/sidekick/: align if they expose UI chrome.

Phase 4 — Theming, motion, accessibility (3–5 days)

• Dark mode: color="dark" on sp-theme + tokens-v2/dark-vars.css; respect prefers-color-scheme.
• Scale: document medium vs large for touch-heavy views.
• prefers-reduced-motion: gate animations (copy banner, loading states) per Spectrum 2 motion guidance.
• Focus rings: use S2 global focus tokens, remove custom --spectrum-focus-ring-color overrides unless required.
• Icons: plan migration to Spectrum 2 icon set for any inline SVGs / chevrons.

Phase 5 — Author site / blocks (optional, separate epic)

• Decide whether public author pages adopt Spectrum 2 or keep Montserrat brand typography.
• Map README tokens (XS–XXL spacing, emphasis, button types) → Spectrum 2 semantic tokens.
• Pilot one block (e.g. blocks/hero or blocks/card) before repo-wide block migration.

---

Dependency & delivery constraints

Constraint	Mitigation
Helix “buildless” delivery	Bundle SWC + lit into deps/ via esbuild; tools import from /deps/... like existing Lit pattern
Package version skew	Single locked version for all @spectrum-web-components/* in package.json
Light DOM in inventory	Test SWC components with createRenderRoot() { return this; }; fall back to token-only if shadow styles break
CSS lint scope	Add tools/**/*.css to lint:css script
Security	No user input in dynamic import() paths; pin SWC versions; run npm audit on SWC adds

---

Suggested work breakdown (issues / PRs)

1. chore(spectrum): add SWC deps, shared token CSS, esbuild bundle, README
2. feat(inventory): sp-theme wrapper + token migration (CSS-only PR)
3. feat(inventory): replace buttons/inputs with SWC
4. feat(inventory): tabs + alerts/toast
5. feat(eds-migration): align to shared spectrum foundation
6. feat(scheduler): align to shared spectrum foundation
7. feat(spectrum): dark mode + reduced motion
8. docs: design system decision record + screenshots

---

Risks & open questions

1. Bundle size: How much SWC is acceptable on DA-hosted tool URLs? Measure before migrating all primitives.
2. Light DOM + SWC: Confirm styling works without shadow DOM; may require sp-theme as ancestor in document, not inside component render root.
3. Brand vs Spectrum: Site uses Montserrat — do tools use Spectrum typography exclusively while marketing pages keep brand fonts?
4. Express vs Spectrum 2: SWC also supports express system — confirm product choice is spectrum-two only.

---

Success criteria

• Official Spectrum 2 tokens drive colors/type/spacing in inventory (no local hex palette duplication).
• sp-theme system="spectrum-two" documented and used in all Lit tools.
• Primary actions, forms, and tabs use SWC or token-equivalent S2 styling.
• WCAG-minded focus and keyboard behavior preserved or improved.
• README design system section links to Spectrum 2 and implementation docs in repo.

---

Test plan

• npm run lint passes with expanded CSS scope
• Manual: inventory flows (load sitemap, tabs, compare, DA tree, copy feedback)
• Keyboard: tab list arrows, Home/End, tree navigation
• Visual: light + dark theme screenshots attached to closing PR
• Optional: add Playwright or WTR screenshot test for inventory shell once stable

[lamontacrook]

Phase 1 foundation — in progress (local working tree)

Uncommitted work aligns with Phase 1 of this issue:

Done locally

• @spectrum-web-components/{theme,button,styles} @ 1.12.1 in package.json
• npm run build:spectrum / build:deps scripts → deps/spectrum/dist/{index.js,tokens.css}
• deps/spectrum/src/index.js — registers sp-theme (system="spectrum-two") + sp-button
• tools/shared/spectrum-theme.js — initSpectrum() helper
• tools/spectrum-demo/ — acceptance page (sp-theme + token-driven sp-button variants)
• deps/spectrum/README.md + README Design System → Spectrum 2 (tools) section
• lint:css expanded to tools/**/*.css

Verify

npm i && npm run build:deps
aem up
# → /tools/spectrum-demo/spectrum-demo.html

Next (Phase 2 — inventory pilot)

• Link /deps/spectrum/dist/tokens.css in tools/inventory/inventory.html
• Wrap ema-inventory in <sp-theme system="spectrum-two" …> via initSpectrum()
• Remove duplicated hand-rolled --spectrum-gray-* / --spectrum-blue-* hex block from inventory.css
• Incrementally replace ema-inv__btn with sp-button where low-risk

Refs: Spectrum 2 · SWC migration guide