# Design

## Context

Pages are Vue 2 + Bootstrap 4 via CDN with swal/toastr dialogs; behavior and
endpoints are frozen for this change (see proposal.md). Carbon web components
v2.50.0 are available as bundled per-component `.min.js` artifacts on IBM's CDN
(verified: button, text-input, dropdown, notification [inline-notification +
toast], progress-bar, tag, checkbox, textarea, tile, ui-shell, modal, loading);
`@carbon/styles` CSS (jsdelivr) provides tokens + Carbon-styled native
controls; IBM Plex Sans comes from Google Fonts.

## Goals / Non-Goals

**Goals:** Carbon look across landing + both tools with zero build step;
Vue 2 kept as the thin state layer; server untouched.

**Non-Goals:** Framework rewrite; UX/flow changes; self-hosting assets;
replacing vue-croppa.

## Decisions

1. **CDN delivery, version-pinned (v2.50.0)** — same pattern as the existing
   Vue/axios CDNs; zero tooling. Self-hosting is the fallback if CDN
   availability becomes a field problem.
2. **Hybrid controls** — true web components where Vue interacts lightly
   (cds-button click, cds-tag, cds-inline-notification, cds-toast,
   cds-progress-bar, cds-tile); Carbon-styled native controls where v-model
   matters (text inputs, selects, checkboxes, textarea use
   `cds--text-input`/`cds--select-input`/`cds--checkbox` classes from
   @carbon/styles CSS). Avoids value/event adapter friction with shadow-DOM
   inputs.
3. **Notification models replace dialogs** — wizard: one inline-notification
   slot (`notif` state, auto-dismiss on success); cropper: a fixed
   `cds-toast` viewport fed by a `toasts` array with timed removal. Native
   `confirm()` stays for dequeue (behavior frozen).
4. **`Vue.config.ignoredElements = [/^cds-/]`** plus a
   `customElements.whenDefined('cds-button').then($forceUpdate)` so
   pre-upgrade property bindings (disabled, progress value) re-apply after
   upgrade.
5. **style.css rewritten on Carbon tokens** (layout helpers kept: grid, gaps,
   details grid, editor grid, croppa pad, footer).

## Risks / Trade-offs

- [Shadow-DOM inputs would fight Vue v-model] → native controls for fields;
  web components only for click/display surfaces.
- [IBM CDN availability] → pinned version; self-hosting is a drop-in swap of
  the script/link URLs.
- [Lit property set before upgrade] → forceUpdate after whenDefined; disabled
  states verified in the visual harness.

## Migration Plan

Rewrite pages/styles → visual harness screenshots (landing, wizard, cropper at
390/768/1280) → unit tests (server untouched) → docker smoke → walkthrough.

## Open Questions

None.