---
name: vue-primevue-dashboard-migration
description: "Incrementally migrate Vue/Vite dashboards to PrimeVue/Aura: light app shells, shared UI components, DataTables, charts, responsive UX, tests, bundle checks."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [vue, primevue, vite, ui-migration, dashboard, frontend, charts, responsive]
    related_skills: [test-driven-development, requesting-code-review, popular-web-designs, claude-design]
---

# Vue + PrimeVue Dashboard UI Migration

## When to Use

Use this skill when migrating an existing Vue/Vite dashboard to a more professional component system, especially PrimeVue/Aura, while preserving existing routes, API clients, and business logic.

Typical triggers:
- "Make the dashboard look professional / modern / light / compact"
- "Migrate to PrimeVue / Aura / Sakai style"
- "Refactor UI only; no backend changes"
- "Unify app shell/sidebar/mobile nav"
- "Convert tables, filters, dialogs, badges, and charts to PrimeVue"
- "Keep existing FastAPI/Vue structure, no Big-Bang rewrite"

## Core Rules

1. **UI-only means UI-only.** Do not add domain features, providers, import engines, or backend business logic unless strictly required for API compatibility.
2. **No template copy-paste.** Use Sakai/Aura/Vuestic as design inspiration; do not import whole templates, foreign assets, or example code blindly.
3. **Preserve routes and API clients first.** Refactor components behind the same route paths and data contracts.
4. **Light theme default.** Use calm finance colors, bright surfaces, compact density, modest radius, subtle shadows.
5. **Shared components before many page edits.** Create reusable wrappers so every page does not invent its own cards, badges, tables, dialogs, and headers.
6. **TDD and interaction tests.** Add tests before implementation for shell navigation, page rendering, DataTables, selection, dialogs/drawers, and chart data.
7. **Verify bundle impact.** PrimeVue/Chart.js can grow bundles; use route-based lazy imports and document remaining large chunks.
8. **No secrets/runtime data.** Never commit `.env`, runtime DBs, build caches, real data, API keys, or provider credentials.

## Recommended Migration Sequence

### 1. Baseline and Safety

- Check branch, working tree, existing UI-framework commit, and running dashboard health.
- Inventory current Vue pages/components and dark-mode class usage.
- Confirm dependencies and licenses: `primevue`, `@primeuix/themes`, `primeicons`, `chart.js` are MIT at time of writing.
- Document the framework decision and integration approach.

### 2. RED Tests First

Add tests that fail before the migration:
- App shell renders light UI and new navigation groups.
- Mobile navigation still exists.
- Shared components exist and render.
- Critical routes are lazy-loaded.
- Budget/finance pages render PrimeVue DataTables/Charts where expected.
- Old dark user-dashboard classes are absent from migrated pages.
- Low-contrast light-theme conflicts are absent from user pages and shared finance components: scan not only Tailwind classes (`text-white`, `text-slate-100/200/300`, pale status text, dark surfaces) but also scoped raw CSS color/background pairs from the previous dark theme.
- Dialogs/drawers can open, close, and reopen, including reopening the same selected row/card.

### 3. Global PrimeVue Setup

In `main.ts`:
- Register PrimeVue with Aura via `@primeuix/themes/aura`.
- Register Chart.js elements once if using PrimeVue Chart.
- Import `primeicons/primeicons.css` and the project stylesheet.

Prefer local component imports inside pages instead of registering every PrimeVue component globally.

### 4. Shared UI Components

Create a class-level UI kit, usually under `src/components/ui/`:
- `PageHeader`
- `KpiCard`
- `StatusBadge`
- `DataQualityBadge`
- `FilterToolbar`
- `PrimeDataTable`
- `MoneyValue`
- `PercentValue`
- `EmptyState`
- `ConfirmDialog`
- `DetailDialog` or `DetailDrawer`
- `ChartPanel`
- `ActionToolbar`
- `SectionCard`
- `LoadingState`
- `ErrorState`

Keep wrappers thin. They should standardize density, tone, and layout, not hide PrimeVue so deeply that page code becomes opaque.

### 5. App Shell and Navigation

Migrate the shell first:
- Light background, white sidebar, subtle borders/shadows.
- De-emphasize technical runtime/provider notes.
- Group User Mode navigation by job-to-be-done: Command Center, Portfolio, Crypto, Budget, Transactions, Analysis, Reports.
- Keep Admin/Debug separate from the main User flow.
- Keep mobile bottom nav, but align it with the new route grouping.

### 6. Page Migration Pattern

For each page:
1. Keep the route and API calls unchanged.
2. Replace native/dark cards with `Card`/`SectionCard`.
3. Replace tables with `DataTable` + `Column` where useful.
4. Replace status text with `Tag`/`StatusBadge`.
5. Replace ad hoc filters with `Toolbar`, `Select`, `MultiSelect`, `InputText`, `DatePicker`.
6. Replace side panels/details with `Dialog`/`Drawer` and explicit state transitions.
7. Add or preserve mobile card lists where DataTable is too dense.
8. Ensure disabled/incomplete actions are visually disabled and do not fire.

### 7. Charts

Use PrimeVue Chart / Chart.js for standard finance charts:
- Bar/horizontal bar for budget-vs-actual.
- Doughnut for category or asset allocation.
- Line or combined bar/line for monthly comparisons.

Keep charts compact and responsive. Add visible labels or adjacent ranking lists so tests and accessibility do not depend only on canvas pixels.

### 8. Bundle / Code Splitting

- Convert route components from static imports to lazy imports: `const Page = () => import('@/pages/Page.vue')`.
- Rebuild and inspect Vite output.
- Document large chunks such as `datatable`, `tag`, `dialog`, and Chart.js rather than over-optimizing prematurely.
- If warnings remain, consider lazy-loading chart-heavy pages/components.

## Verification Checklist

Run before commit:
- Python compile if repo includes backend Python.
- Backend tests if API-backed dashboard.
- Frontend tests.
- Frontend build.
- Source/staged secret scan.
- Frontend build secret scan.
- Git safety tests if present.
- `git diff --check`.
- Browser or HTTP route sanity for critical dashboard routes.
- Visual contrast sanity on the pages the user called out, using screenshots/vision when available; route `200` alone is not enough for a contrast bug.
- For any user-reported unreadable value, write a focused RED test against the shared component/value line that renders it, verify the failure, then change the central token/class and rerun the targeted test plus build.
- Independent code review via `requesting-code-review` for multi-file migrations; specifically ask reviewers to inspect scoped CSS/raw colors, not just class names.

## Common Pitfalls

- **Watcher/object identity modal bug:** If a dialog opens via `selected = row`, closing the dialog but leaving `selected` unchanged can prevent reopening the same row. Use an explicit `openDetail(row) { selected = row; visible = true }` and regression-test close/reopen.
- **Build-only confidence is insufficient:** A UI migration can build and still break row-click, batch selection, dialog reopen, mobile nav, or disabled-action semantics.
- **Canvas-only charts are hard to test:** Keep nearby textual rankings/labels or assert the data passed into chart components.
- **Bulk dark-class replacement can hurt contrast:** After replacing dark backgrounds, scan for low-contrast classes like pale text on white/light surfaces.
- **Scoped raw CSS can evade Tailwind scans:** Old dark-theme scoped styles such as `background: rgb(15 23 42 / .75)` plus newly darkened text can create dark-on-dark or light-on-light bugs. Add regex/allowlist tests for raw RGB/hex colors or migrate scoped styles to shared light-theme tokens.
- **Allocation/card headings are easy to miss:** Visual cards can appear mostly correct while section headings remain nearly invisible (`text-slate-50` on white). Use browser screenshot/vision checks for pages the user names, especially Crypto/Portfolio/Equity.
- **Primary KPI values can hide in shared cards:** Do not only scan pages; inspect shared KPI/card components such as `SummaryCard` and `KpiCard`. A single pale value class (`text-slate-50`) in a shared card can make critical figures like “Gesamtportfolio CHF” unreadable across Portfolio/Command Center pages. Add a regression test that extracts the KPI value line and requires a dark readable class (`text-slate-950`/`text-slate-900` or equivalent), not just absence of old dark surfaces.
- **PrimeVue wrappers can hide attrs:** Ensure `data-test`, `href`, `disabled`, and click handlers pass through where tests and accessibility need them.
- **Lazy route imports can break tests that expect direct imports:** Update tests to mount pages directly or assert lazy route text via raw file checks.
- **Vue template bindings cannot use `v-model` on expressions:** In review/edit forms, avoid constructs like `v-model="condition ? draft.description : draft.caption"`; Vue requires a valid member expression. Split into conditional inputs (`v-if`/`v-else`) or use a computed getter/setter. Add a frontend build after form refactors because this fails at compile time, not runtime.
- **Fixed dev ports can silently show the wrong app:** If a user specifies a frontend dev port, set Vite `server.strictPort = true` and keep the npm dev script on the requested host/port. Otherwise Vite may auto-increment when the port is occupied, while browser QA against the requested port shows an unrelated dashboard. If the port is occupied, fail loudly and report it.
- **`vue-tsc -b` can emit source-side artifacts:** Add `noEmit: true` to TS build configs and ignore `*.tsbuildinfo`; otherwise generated `.js` twins or `.tsbuildinfo` files can appear under `src/`/project root and be accidentally staged after tests/builds.
- **Tailwind v4 changed PostCSS wiring:** For a conservative Vite shell using classic `postcss.config.cjs`, either pin Tailwind 3 (`^3.4.x`) or add and configure `@tailwindcss/postcss` for Tailwind 4. Do not leave `tailwindcss` directly configured as a PostCSS plugin on Tailwind 4; builds fail on CSS processing.
- **Repo safety scans must understand frontend source without broad allowlists:** When adding Vue/TS apps under a safety-scanned repo, scan `.ts`, `.vue`, `.css`, `.html`, `.cjs` as text; skip dependency/build dirs such as `node_modules` and `dist`; allowlist only explicit safety-test files that intentionally contain forbidden sentinel strings.
- **Tailscale/mobile dev access can fail despite local 200s:** If the frontend is served over a Tailscale IP for phone/tablet testing, do not start Vite with `VITE_API_BASE_URL=http://127.0.0.1:8000`; mobile browsers resolve that to the device itself. Prefer a server-side dev proxy: keep backend bound to localhost/internal, set `VITE_API_PROXY_TARGET=http://127.0.0.1:<backend-port>`, expose only the frontend on `0.0.0.0:<frontend-port>`, and verify both `<tailnet-ip>:<frontend-port>/dashboard` and `<tailnet-ip>:<frontend-port>/api/health`. Use Tailscale Serve when permitted; if `tailscale serve` needs sudo/operator rights, report the exact `sudo tailscale set --operator=$USER` prerequisite rather than pretending Serve is active.
- **Hidden desktop-only sidebars make dashboards look empty on tablets/phones:** Avoid `hidden ... lg:block` without an explicit mobile/topbar navigation replacement. Add tests or browser QA for at least one narrow viewport/menu state when changing app shells.
- **Absolute sidebar cards can overlap navigation:** Avoid `absolute bottom-*` info cards in fixed sidebars unless the nav area is height-constrained. Prefer `lg:flex`, `min-h-0 flex-1 overflow-y-auto` for nav plus a `shrink-0` bottom card, then verify visually at realistic laptop heights.
- **Empty MVP dashboards need product guidance, not blank space:** When there is no data yet, show meaningful onboarding/action cards (upload sample, scan import folder, verification checklist, workflow steps). A green build with an empty dashboard is not enough for stakeholder review.
- **Do not leak internal automation language into creator/customer UI:** If a dashboard manages content produced by agents, bots, AI pipelines, Jarvis/Hermes, or other internal systems, do not expose those names in navigation, headings, cards, and empty states unless the product is explicitly an operator console. Prefer user-facing objects like prepared packages, content inbox, topic pipeline, approval workflow, private upload, schedule, and audit trail. Add a visible-copy scan and browser snapshot check before claiming the UI is polished.
- **Product-core before provider API glamour:** For creator/publishing dashboards, stabilize the operational workflow before TikTok/YouTube/OAuth work: prepared-package import, review/approval, topic/idea steering, seed/demo data, dashboard summary, and audit/status surfaces. Platform upload APIs come after the review loop is usable.
- **CSV analytics can unblock the learning loop before OAuth:** When the user asks for creator analytics and explicitly deprioritizes platform OAuth, implement normalized CSV snapshot import first. Do not stop at row counts: parse provider CSVs with a real CSV parser, store import batches/files, external posts, daily aggregates and post snapshots, compute deltas, generate rule-based insights, and verify via API import plus browser charts. Preserve partial rows and treat daily-vs-video total mismatches as warnings, not fatal errors.

## Reference Files

- `references/financemanager-primevue-migration-v1.md` — condensed notes from the FinanceManager global PrimeVue/Aura migration sprint, including verification outcomes and a modal state regression fix.
- `references/financemanager-light-contrast-fix.md` — follow-up contrast/readability sprint notes: raw scoped CSS contrast testing, visual audit workflow, and safe feature-continuation pattern for Position hinzufügen.
- `references/creator-facing-content-dashboard.md` — product framing, copy-neutralization, prepared-package workflow, operations cockpit, review page, and topic/idea database pattern for content publishing dashboards.
- `references/mock-only-command-dashboard-shell.md` — notes from a mock-only JARVIS command dashboard shell: strict Vite ports, TS no-emit hygiene, Tailwind/PostCSS compatibility, safety-scan handling for Vue/TS, and read-only dashboard verification gates.
- `references/youtube-csv-analytics-learning-loop.md` — YouTube Studio CSV import pattern for creator dashboards: file-shape detection, normalized analytics models, snapshot deltas, ECharts learning views, rule-based insights, and verification gates.
- `references/mock-gateway-vue-integration-hardening.md` — mock-only/read-only Gateway↔Vue hardening pattern: Store/API as source of truth, visible fixture fallback, GET-only client, local smoke checks, and safety tests.