#20498: UI: modularize control UI architecture and normalize spacing.
app: web-ui
size: XL
## Summary
- Problem: `ui/src/ui` and `ui/src/styles` were tightly coupled (loose root files + monolithic CSS), making maintenance harder.
- Why it matters: higher risk of layout/style regressions and expensive refactors/reviews.
- What changed:
- Modularized `ui/src/ui` by domain: `app`, `core`, `lib`, `models`, `navigation`, `theme`, `tools`, `usage`, `identity`.
- Updated imports/paths and entrypoint (`ui/src/main.ts` -> `./ui/app/app.ts`).
- Modularized styles and normalized spacing with `--space-*` tokens across `ui/src/styles/**`.
- What did NOT change (scope boundary): no gateway/backend/API/contract changes.
## Change Type (select all)
- [ ] Bug fix
- [ ] Feature
- [x] Refactor
- [ ] Docs
- [ ] Security hardening
- [ ] Chore/infra
## Scope (select all touched areas)
- [ ] Gateway / orchestration
- [ ] Skills / tool execution
- [ ] Auth / tokens
- [ ] Memory / storage
- [ ] Integrations
- [ ] API / contracts
- [x] UI / DX
- [ ] CI/CD / infra
## Linked Issue/PR
- Closes #N/A
- Related #N/A
## User-visible / Behavior Changes
- More consistent UI spacing.
- No intended functional behavior changes.
## Security Impact (required)
- New permissions/capabilities? (`No`)
- Secrets/tokens handling changed? (`No`)
- New/changed network calls? (`No`)
- Command/tool execution surface changed? (`No`)
- Data access scope changed? (`No`)
- If any `Yes`, explain risk + mitigation: `N/A`
## Repro + Verification
### Environment
- OS: Windows
- Runtime/container: Node + pnpm
- Model/provider: N/A
- Integration/channel (if any): N/A
- Relevant config (redacted): N/A
### Steps
1. `pnpm format:check`
2. `pnpm ui:build`
3. `pnpm test:ui` (optional)
### Expected
- UI build succeeds and import/path resolution is valid.
- Styles compile without errors.
### Actual
- `pnpm format:check` ✅
- `pnpm ui:build` ✅
- `pnpm test:ui` ✅
## Evidence
- [x] Trace/log snippets
- [ ] Failing test/log before + passing after
- [ ] Screenshot/recording
- [ ] Perf numbers (if relevant)
## Human Verification (required)
- Verified scenarios: UI build, import resolution after file moves, formatting checks.
- Edge cases checked: relative paths between moved modules and stylesheet loading.
- What you did **not** verify:NA
## Compatibility / Migration
- Backward compatible? (`Yes`)
- Config/env changes? (`No`)
- Migration needed? (`No`)
- If yes, exact upgrade steps: `N/A`
## Failure Recovery (if this breaks)
- How to disable/revert this change quickly: revert this PR.
- Files/config to restore: `ui/src/ui/**`, `ui/src/styles/**`, `ui/src/main.ts`.
- Known bad symptoms reviewers should watch for: broken views, unresolved imports, missing styles.
## Risks and Mitigations
- Risk: visual regression from spacing normalization.
- Mitigation: consistent tokenization + validated build.
- Risk: broken paths after file moves.
- Mitigation: global import rewrite + validated build.
Most Similar PRs
#21326: Security/UI: harden Control UI gatewayUrl URL overrides
by bmendonca3 · 2026-02-19
70.0%
#16445: fix(ui): consistent visual styling across all views
by jasonkneen · 2026-02-14
69.8%
#23729: fix : normalize local file paths for Windows compatibility across m...
by jayy-77 · 2026-02-22
69.5%
#20892: docs: Fix quick wins - broken links, configure UX, Tailscale Aperture
by chilu18 · 2026-02-19
69.2%
#17448: ui: make tool cards collapsible with inline expansion
by karimStekelenburg · 2026-02-15
69.0%
#13960: fix(ui): preserve structured config validation error details
by constansino · 2026-02-11
68.6%
#20415: fix(extensions): use dist/ import paths for bundled extensions
by 88plug · 2026-02-18
68.3%
#21054: fix(cli): fix memory search hang — close undici pool + destroy QMD ...
by BinHPdev · 2026-02-19
68.1%
#20843: docs: add troubleshooting for A2UI bundling and missing node_modules
by yahiag04 · 2026-02-19
67.9%
#23796: Config UI: tag filters and complete schema help/labels coverage
by Takhoffman · 2026-02-22
67.9%