NL
All work
04

Flow Designer → Lit.js

A full UI rewrite needed a way in, a way out, and an answer to the visual debt it shipped with. The audit found seven stories’ worth of bugs traced back to three decisions.

UX designer EPIC1181956 · Karuna repo Mar → Jun 2026 with Yifan Deng, Marli Renee

Customer problem

Engineering leadership greenlit replacing Flow Designer’s Angular-era UI with a Lit.js / DaisyUI rewrite, three engineers dedicated, shipping side by side with the old UI and reaching parity over monthly releases. That created two design problems at once.

First: how does a user step into an experience that is deliberately not at full parity yet, and how do they get back out when something they need is missing? Second: the new canvas shipped with real visual and accessibility debt. Seven acceptance stories carried a scattering of small defects, and the tempting response was seven small pull requests.

The brief

Explicit at kickoff: just enough process to clear the path for engineering. Flows parity, not new functionality. Accessibility folded in rather than tracked as a separate stream. Design’s first assignment, handed over in the kickoff meeting: figure out how a user steps into the new experience, and decide who leads.

Personas

Existing flow author

Mid-project, real deadlines
Needs
To try the new UI without risking the work in front of them.
Gap
V1 is knowingly incomplete, so a way back is a requirement, not a nicety.

Instance admin

Rollout control
Needs
To decide whether the new UI is available on their instance at all.
Gap
Per-user preference persistence was not possible in V1. Session storage only.

Engineering

Three devs, trunk-based
Needs
Findings that map to code decisions, not a flat list to triage themselves.
Gap
Seven separate fixes would each reimplement the same pattern and lock it in.

The design team itself

Scaling past 7 stories
Needs
An audit anyone can run, and a single source of truth for what’s fixed, filed or pending.
Gap
The story count went from 7 to 40.

Solution

  1. Five entry-point directions, explored and narrowed to one. A header toggle, an announcement banner, a new-flow-creation entry, a first-visit modal, and an admin system property. Each was built as a clickable demo, then consolidated into one comparison deck. We converged on a fixed, non-dismissible banner inside Flow Designer, deferring Workflow Studio-level banners and preference persistence. Engineering constraints landed mid-exploration: no virtual tabs, session storage only, Zustand, trunk-based. I translated those into design risk areas rather than treating them as blockers.
  2. The audit’s central move: seven stories’ bugs traced to three systemic patterns. Hand-rolled buttons instead of the shared DaisyUI/Horizon component. Icon buttons sat at 30% opacity until hover, invisible to touch and keyboard. Tap targets fell under the WCAG 2.5.8 24×24px minimum. The same destructive trash action had two different implementations. Two tooltip languages on one canvas: native HTML title in the node toolbar, the themed DaisyUI tooltip everywhere else, with different timing and no keyboard access. A reorder indicator borrowing semantic colour it had not earned: green for step reorder, blue for variable reorder, for what is a neutral drag.
  3. Framing that changed what got built. The whole audit collapses into 3 decisions. Getting alignment on the root cause before code meant it landed as one deliberately-scoped systemic PR, STRY63907565. And because the delete confirmation modal is reused canvas-wide, one component swap fixed every destructive flow at once.
  4. A disposition vocabulary, so every finding had a next action. Fixed is a pure value change, bundled. Filed needs real code, handed over with a written problem and a proposed direction. Decision is a design call to confirm before anyone builds. Two Activate/Deactivate stories turned out not to be value-fixable at all, so they were flagged as needing the Sand theme properly applied rather than patched cosmetically. One story audited clean, and was recorded as such, so “reviewed and fine” never looks like “not yet reviewed.”
  5. Fix-preview mockups built for each pattern and referenced straight from the audit doc, so engineering had a visual target rather than prose.
  6. The process itself got tooled. A design-audit checklist with an embedded how-to, a ticket-creation step and a markdown summary generator. A per-story audit template. And living status dashboards that scaled the same tracking model from 7 stories to 40, by owner and PR status.
  7. Two parallel feature audits on the same pattern. Stages produced six findings, all shipped as value fixes. Among them: an Add-Stage button that disappeared behind its own picker, and a delete × that turned invisible-red on coloured bands. Flow History produced a missing close button, flagged as a WCAG 2.1.1 / 2.4.3 keyboard regression. That directly contradicted an engineering test’s assumption that it had been “deliberately removed in design audit #3398”, so it was surfaced for revisit rather than left to stand.

The audit artefacts, running

The three documents the audit actually produced, embedded here as they were written. Each is a before/after comparison rather than a description of one — which is the point: engineering got a visual target, not prose.

These are the working files, unmodified. The first is the audit that argued the three systemic patterns; the second and third are the fix previews it pointed at.

[UX] Flows LitJS v1 Audit — Visual Findings Open full screen
The audit itself: Pattern 1 (hand-rolled buttons — the node action toolbar, two different implementations of the same destructive intent, destructive primaries in the wrong variant), Pattern 2 (two tooltip languages), Pattern 3 (semantic colour on a neutral drag). Each finding shows the current state beside the proposed one.
Drag-to-reorder — visual consistency mockup Open full screen
Pattern 3 in isolation, and the reason it got filed as a defect rather than bundled into the systemic PR: the canvas used a line-and-dot indicator with an invalid-red state, while the variables table used a whole-row highlight with no invalid state at all. Two mechanisms, not just two colours.
Stages UX audit — before & after Open full screen
The parallel Stages audit, all six findings shipped as value fixes: the Add-a-Stage button staying visible when the picker opens, themed tooltips replacing native ones, a neutral delete × that still reads on a coloured band, and the accessible hover states.

User flows

Opt in, and back out existing flow author
  1. Legacy Flow Designer
  2. Fixed banner: try the new UI
  3. Lit.js canvas, labelled early access
  4. Hits a capability not yet at parity
  5. Toggle back
  6. Legacy UI, work intact
Run a design audit — the tool, usable by anyone on the team
  1. Pick a story
  2. Walk each element
  3. Check states & design lens
  4. Classify: fixed / filed / decision
  5. Generate the markdown summary
  6. Create the BT1 ticket
  7. Tracked on the dashboard

KPIs

Measured 7 → 3

acceptance stories’ findings resolved into three root-cause decisions

Measured 40

stories tracked on one dashboard, up from the original 7

Measured 24×24

px minimum tap target restored, for WCAG 2.5.8 compliance

Measured 6 / 6

Stages findings shipped as value fixes in one branch

The handoff doc shows this surviving contact with reality.

  • A soft-red button variant chased to match Figma was reverted, because it introduced an accessibility regression.
  • A reviewer’s “794 files changed” alarm turned out to be base-branch drift. Diffed properly, the real change was around 50 files.
  • 14 pre-existing failing tests from unrelated tooltip-migration debt had to be triaged separately, to keep the PR mergeable during a repo migration freeze.

Still open

  • Preference persistence. V1 remembers a choice for the session only. Per-user persistence was deferred, so an author opts in again on every visit.
  • Workflow Studio-level banners. The entry point lives inside Flow Designer. Announcing the new UI one level up was explored and left for later.
  • The two Sand-theme stories. Flagged as needing the theme properly applied rather than patched. Whether that landed is outside what I can see.
  • Flow History’s close button. Surfaced for revisit against an engineering assumption. The revisit itself is not recorded.