Skip to content
BOLDVelocity BOLDVelocity BOLDVelocity Docs

V6 Build-Out Playbook (T12 / T13 / T14) — Dashboard UI/UX Impeccable Enhancement Pass

V6 Build-Out Playbook (T12 / T13 / T14) — Dashboard UI/UX Impeccable Enhancement Pass

File: docs/playbooks/v6-ui-ux-impeccable-playbook.md Base branch: dev (integration branch — main stays protected/production; PRs target dev) Branch: feature/112671-ai-assisted-percentage-v5-pr11 (this pass rode on the same in-flight branch as the V5/T11 PR — see prs/112671-ai-assisted-percentage-v5-pr11.md for the combined PR write-up; T12–T14 are not separately branched) Plan date: 2026-08-06 (written retroactively — this playbook documents already-shipped work) Owner: Sultan (driver via /impeccable), with Fatima assisting on bug-fixing the Impeccable-generated code (CSS custom-property completion pass, T13) Status: COMPLETE. All three tasks are merged to feature/112671-ai-assisted-percentage-v5-pr11 (commits 4ee7a33, 0d8155f, ef4ea54, 9bd7718) and pending merge to dev via PR-11. Source: Ad-hoc session work driven by the impeccable skill (bolder, animate, critique commands) plus direct user requests for dark mode and dark-mode logo variants — no formal ADO work item exists for this playbook; it is documented here for traceability since real product code shipped from it, not because a ticket preceded it.

How to Use This Document

Unlike the other playbooks in this directory, this one is written after the fact: T12–T14 were driven interactively via the Impeccable design skill and direct user requests rather than planned up front from a work item. It exists so this body of UI/UX work has the same file-touched/verification/rollback record as ticket-driven playbooks, and so the still-open findings from the Impeccable critique (see §5, Out of Scope) are tracked instead of lost.

T12 (Impeccable enhancement pass) promotes the AI-Assisted % KPI visually, adds motion, and fixes a Team Table contradiction where a contributor could show both an AI-tool label and an “AI Enabled” badge that disagreed with each other. T13 (dark mode) adds OS-default dark-mode detection plus a manual toggle, tokenizing the entire stylesheet into CSS custom properties as a prerequisite. T14 (dark-mode logos) generates dark-safe logo variants after T13 exposed that both production logo assets render invisibly or with a visual artifact on a dark background.

1. Executive Summary

#ItemGapDepends on
T12AI-Assisted % KPI was implemented (T11) but not visually promoted; no motion on KPI/chart changes; Team Table could show a contributor’s primary-tool label and an “AI Enabled” badge that contradicted itT11 shipped the data; presentation laggedT11
T13dashboard.css had zero CSS custom properties (every color a repeated hex literal); no dark mode at allDashboard was light-mode-only; OS dark-mode users got a jarring light UINone
T14Both logo assets are unusable on a dark background: boldvelocity-logo-transparent-bg.png’s “BOLD” text is near-black (invisible on dark); alphabold-logo.png is not actually transparent — commit ef4ea54 (T13’s CSS follow-up) replaced it with a fully-opaque asset carrying a baked-in checkerboard pattern instead of true alpha, so it also shows a gray box artifactT13 (dark mode existing at all is what surfaces this)

PR Strategy — 1 combined PR (folded into PR-11)

  • T12–T14 shipped as three sequential commits on the already-open feature/112671-...-pr11 branch rather than as separate PRs, since dark mode and its logo fallout were discovered while verifying the T11 KPI PR interactively, not as separately-scoped planned work.

Merge Sequencing

  1. T12 (4ee7a33) — KPI promotion, motion, AI-Enabled signal fix.
  2. T13 (0d8155f + ef4ea54) — dark mode + CSS tokenization (ef4ea54 is Fatima’s follow-up completing the custom-property conversion Impeccable’s first pass left partially literal).
  3. T14 (9bd7718) — dark-mode logo variants, fixing the transparency regression ef4ea54 introduced to alphabold-logo.png for the new dark-mode file specifically.

Model Guidance

PRTaskRecommended ModelEffortReason
PR-11 (T12)Impeccable enhancement passClaude SonnetmediumCross-file visual/motion changes, one behavioral bug fix (AI-signal contradiction)
PR-11 (T13)Dark modeClaude SonnethighFull-stylesheet tokenization (~130 replacements) + new reactive state module + tests
PR-11 (T14)Dark-mode logosClaude SonnetmediumPixel-level image manipulation (PIL) + a real pre-existing asset bug found and fixed

2. PR Plan

PRBranchItemsBranches fromEst.
PR-11feature/112671-ai-assisted-percentage-v5-pr11T12, T13, T14 (+ T11)dev3 commits, ~1 session

ADO task IDs: T12=N/A, T13=N/A, T14=N/A (no formal work items — see Source note above).

3. Files Touched

File / pathPR
public/src/components/KpiRow.vue, VelocityChart.vue, TeamTable.vue, mockData.js, store/db.pyT12
PRODUCT.md, DESIGN.md, .impeccable/*T12
public/dashboard.css, public/src/theme.js, public/src/components/TopBar.vue, public/tests/theme.spec.jsT13
.github/copilot-instructions.md, CLAUDE.md (never-auto-git rule, added alongside T13)T13
assets/boldvelocity-logo-transparent-bg-dark.png, assets/alphabold-logo-dark.png (new), public/src/components/TopBar.vue, public/src/views/ContributorView.vueT14

4. Hard Rules

(Inherits Hard Rules from docs/playbooks/v1-dev-productivity-dashboard-playbook.md §4, and Hard Rule 12: no automatic git actions. The following are additive, specific to this playbook.)

  1. Any AI-Assisted %/estimate-style KPI must retain its “estimate” labeling when visually promoted (Hard Rule 3, never present an estimate as precise) — T12 kept the badge.
  2. A contributor row must never show two contradicting AI-tool signals at once (T12’s fix).
  3. Dark-mode palettes must meet WCAG AA contrast at minimum (T13 verified 6.1–15.6:1).
  4. New logo variants must preserve the icon and off-target text color exactly — only the specified text recolors (T14).

5. Out of Scope

  • ToolPills.vue not rendered on the main dashboard — exists as a built component with wired filter state but is never mounted in TopBar.vue/DashboardView.vue (regressed in commit 34cc820, before this playbook’s work began). Flagged as the top P1 finding in .impeccable/critique/2026-08-06T11-20-32Z__public-boldvelocity-dashboard.md; user explicitly declined to fix it in this session. Candidate for a future PR.
  • Nested-card visual sameness (P1 in the same critique) — KPI cards, tool-empty cards, story columns, etc. share near-identical soft-rect chrome; not addressed this pass.
  • No-data/“Coming Soon” empty states feel generic (P2) and main dashboard read order isn’t hierarchy-sharpened (P2) — both noted, neither in scope here.
  • alphabold-logo.png’s checkerboard-opacity bug in the light-mode asset itself — only the new dark-mode variant (alphabold-logo-dark.png) got true transparency; the original light-mode file committed in ef4ea54 still has the baked-in checkerboard pattern (less visible against the light parchment background, but present). Flagged, not fixed.

6. Per-Session Contract

Followed the standing project rule (not this playbook’s invention): implementation work proceeds autonomously, but no git add/commit/push without explicit, on-topic user approval — the “autonomy fallback” from ask_user does not count as approval for git actions. All three commits below were made only after explicit user confirmation each time.

PR 11 (T12) — Impeccable Enhancement Pass

Commit: 4ee7a33 — “feat: promote AI-Assisted KPI, animate dashboard, add AI-enabled signal”

Problem

T11 shipped the real AI-Assisted % KPI as data, but it rendered with the same visual weight as every other KPI card, with no motion anywhere, and TeamTable.vue could show a contributor’s primary-tool label next to an “AI Enabled” badge that contradicted it (e.g. label says “Cursor” while the badge implies Copilot-only usage).

What changed

  1. Flagged AI-Assisted % as isHeadline in mockData.js/store/db.py; promoted it visually in KpiRow.vue.
  2. Added a crossfade transition on KPI value changes and a line-draw-in animation on VelocityChart.vue; fade/rise entrance transitions on contributor/date-picker popovers, all behind a prefers-reduced-motion guard.
  3. Added isAiPrimaryTool/showAiBadge helper logic in TeamTable.vue so a row shows exactly one AI signal (the tool label OR the badge, never both).
  4. Authored PRODUCT.md and DESIGN.md (Impeccable’s product/design context files) plus .impeccable/design.json and a critique artifact.

PR 11 (T13) — Dark Mode

Commits: 0d8155f — “feat: add dark mode with system default and manual toggle”; ef4ea54 — “feat: update dashboard styles to use CSS custom properties for improved theming”

Problem

dashboard.css (1672 lines) had zero CSS custom properties — every color was a repeated hex literal — so there was no mechanism to swap palettes, and the dashboard was light-mode-only regardless of OS preference.

What changed

  1. Tokenized ~130 color/shadow occurrences into :root custom properties matching DESIGN.md’s named tokens (left ~40 one-off functional badge/chip colors as literals — theme-independent).
  2. Added a prefers-color-scheme: dark override block with a new dark palette (WCAG contrast 6.1–15.6:1 verified) plus a hairline card border for dark-mode edge definition.
  3. Added public/src/theme.js: reactive theme state, manual override via data-theme attribute (wins over the media query by specificity), localStorage persistence (try/catch-guarded), jsdom-safe matchMedia stub for tests.
  4. Added a 🌙/☀️ toggle button to TopBar.vue; added theme.spec.js (system-default, toggle+persist, reload-restores).
  5. ef4ea54 (Fatima) completed the custom-property conversion for colors the first pass left as literals — but its assets/alphabold-logo.png change (69 KB → 1 MB) is what introduced the checkerboard-opacity regression T14 had to work around.
  6. Added a hard “never stage/commit/push without explicit approval” rule to CLAUDE.md/copilot-instructions.md after an earlier autonomy-fallback mix-up this session.

PR 11 (T14) — Dark-Mode Logo Variants

Commit: 9bd7718 — “feat: add dark-mode logo variants and wire theme-aware logos”

Problem

Once dark mode existed, both logos broke: boldvelocity-logo-transparent-bg.png’s “BOLD” text is near-black and disappears on a dark background; alphabold-logo.png (post-ef4ea54) is fully opaque with a baked-in checkerboard pattern instead of true alpha, showing a gray box artifact.

What changed

  1. Generated assets/boldvelocity-logo-transparent-bg-dark.png via targeted pixel recoloring (PIL): “BOLD” text → white, “Velocity”/icon untouched, true transparency preserved.
  2. Generated assets/alphabold-logo-dark.png: “alpha” text → white, “bold”/icon untouched, and fixed the true-transparency bug — checkerboard background pixels converted to real alpha-0, verified at all four image corners.
  3. Bound both logos’ <img src> to themeState.isDark in TopBar.vue; discovered ContributorView.vue has its own separate, non-theme-aware duplicated logo markup and fixed it identically.

7. Verification Samples

  • cd public && npm run build — clean production build after each commit.
  • npm run test (vitest) — 3/3 → 6/6 (added theme.spec.js) across the three commits.
  • python3 -m pytest tests/ -v --tb=short — unaffected (no Python files touched by T12–T14).
  • Impeccable detector (detect.mjs --json <file>) — 0 findings on every touched file.
  • T14: pixel-sampled all four corners of both new PNGs — (0,0,0,0) alpha confirmed; composited onto a dark background and visually inspected both wordmarks and icons.

8. Rollback

Each task is an isolated commit on feature/112671-ai-assisted-percentage-v5-pr11: git revert 4ee7a33 (T12), git revert 0d8155f ef4ea54 (T13), or git revert 9bd7718 (T14) cleanly undoes that task alone — no schema/data-migration concerns, since all three are UI/asset-only changes. Reverting T13 without reverting T14 would leave the dark-mode logo files orphaned but harmless (unreferenced once theme.js/the data-theme mechanism is gone).