feat(ui): rebuild all tools pages on Carbon Design System web components

- @carbon/web-components v2.50.0 via the IBM CDN (version-pinned); @carbon/styles CSS + IBM Plex Sans for tokens/typography - landing: Carbon header + cds-tile tool cards - fingerprint wizard: Carbon-styled form controls, cds-progress-bar scan progress, cds-tag badges, cds-inline-notification replacing swal - cropper: cds-toast replacing toastr, cds-checkbox review reasons, cds-tag process badge; vue-croppa pad kept in the Carbon layout - Bootstrap 4, swal, toastr and jQuery removed from all pages - behavior frozen: same flows, endpoints, validation and copy
2026-10-01 02:03:07 +01:00
parent 22d9ba40e3
commit 930af97f05
12 changed files with 522 additions and 343 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-01
@@ -0,0 +1,60 @@
+# 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.
@@ -0,0 +1,42 @@
+# Proposal: carbon-ui-redesign
+
+## Why
+
+The tools pages are styled with ad-hoc Bootstrap 4 overrides and ad-hoc dialogs
+(swal/toastr). Adopting the Carbon Design System gives the two tools a single
+professional design language (IBM Plex typography, Carbon components, Carbon
+tokens) consistent with the wider YOUreka ecosystem.
+
+## What Changes
+
+- **BREAKING (visual only)**: All three surfaces — landing, `/fingerprint`
+  wizard, `/cropper` — are rebuilt on Carbon Design System web components
+  (`@carbon/web-components` v2.50.0 via the IBM CDN, version-pinned) with IBM
+  Plex Sans typography and Carbon tokens for layout/colors.
+- Bootstrap 4, swal, toastr and jQuery are removed from the pages; errors and
+  confirmations surface as Carbon inline notifications and toasts.
+- Form fields use Carbon-styled native controls (text input, select, checkbox,
+  textarea) so Vue state bindings are unchanged; buttons, tags, notifications,
+  toasts, progress bar and tiles are Carbon web components.
+- **Behavior is frozen**: flows, endpoints, validation and copy stay exactly as
+  they are. The vue-croppa crop pad is kept (no Carbon equivalent), framed in a
+  Carbon tile/panel.
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+- `tools-app`: adds a requirement that the tools UI is built on Carbon Design
+  System web components with Carbon notifications.
+
+## Impact
+
+- Pages and `style.css` rewritten; `app.js` files adapted (notification/toast
+  models replace swal/toastr calls; `Vue.config.ignoredElements` for cds-*).
+- No server-side changes; no new npm dependencies; component JS + Plex font +
+  Carbon CSS delivered via CDN (IBM CDN for components, jsdelivr for
+  @carbon/styles, Google Fonts for Plex).
@@ -0,0 +1,16 @@
+# Spec Delta: tools-app
+
+## ADDED Requirements
+
+### Requirement: Carbon Design System UI
+The tools pages SHALL be built on the Carbon Design System: Carbon web
+components (version-pinned via CDN) for buttons, notifications, toasts, tags,
+progress and tiles; Carbon-styled native form controls; IBM Plex Sans
+typography and Carbon color tokens for layout. Errors, confirmations and
+successes SHALL surface as Carbon notifications rather than ad-hoc alert
+dialogs.
+
+#### Scenario: Pages render with Carbon components
+- **WHEN** any tools page is opened
+- **THEN** its interactive controls are Carbon components (or Carbon-styled
+  native controls) and its notifications render as Carbon notifications
@@ -0,0 +1,13 @@
+# Tasks
+
+- [x] 1. Retheme `style.css` on Carbon tokens (Plex, dark header, layers,
+  sharp corners); drop Bootstrap/swal/toastr/jQuery from all pages; load
+  pinned Carbon CDN artifacts + Plex + @carbon/styles CSS.
+- [x] 2. Rebuild the landing page (Carbon header + cds-tile tool cards).
+- [x] 3. Rebuild the fingerprint wizard with Carbon components (inputs,
+  dropdown, cds-progress-bar scan progress, cds-tag badges,
+  cds-inline-notification replacing swal); verify at 390/768/1280 via the
+  visual harness.
+- [x] 4. Rebuild the cropper page with Carbon components (cds-toast replacing
+  toastr, cds-checkbox reasons, cds-tag); verify at 390/768/1280.
+- [x] 5. Run unit tests + docker smoke; sync/archive the change and commit.
@@ -132,4 +132,17 @@ environment variables and SHALL NOT be stored in source.
 #### Scenario: Cropper credentials from the environment
 - **WHEN** the cropper credentials are supplied as environment variables
 - **THEN** the cropper routes use them without any change to the hardcoded
-  URL/port configuration
+  URL/port configuration
+
+### Requirement: Carbon Design System UI
+The tools pages SHALL be built on the Carbon Design System: Carbon web
+components (version-pinned via CDN) for buttons, notifications, toasts, tags,
+progress and tiles; Carbon-styled native form controls; IBM Plex Sans
+typography and Carbon color tokens for layout. Errors, confirmations and
+successes SHALL surface as Carbon notifications rather than ad-hoc alert
+dialogs.
+
+#### Scenario: Pages render with Carbon components
+- **WHEN** any tools page is opened
+- **THEN** its interactive controls are Carbon components (or Carbon-styled
+  native controls) and its notifications render as Carbon notifications