cameleer-server/docs/superpowers/specs/2026-04-09-ui-consistency-fix-design.md

Status: COMPLETED — All 5 phases executed on 2026-04-09.

UI Consistency Fix — Design Spec

Date: 2026-04-09 Goal: Bring the cameleer-server UI to consistent design system usage — eliminate CSS duplication, hardcoded colors, inline styles, and native HTML where DS components exist. Source: UI-CONSISTENCY-AUDIT.md (same repo, same date)

---

Approach: Fix by Category

Extract shared patterns first (unblocks everything), then sweep all files per issue type. Phases are independent after Phase 1 and can run in parallel.

Phase 1: Extract Shared CSS Modules

1a. Table Section Pattern

Create ui/src/styles/table-section.module.css containing:

• .tableSection, .tableHeader, .tableTitle, .tableMeta, .tableRight

Update these 5 files to import from shared module instead of local definitions:

• pages/DashboardTab/DashboardTab.module.css
• pages/Admin/AuditLogPage.module.css
• pages/Admin/ClickHouseAdminPage.module.css
• pages/Routes/RoutesMetrics.module.css
• pages/Routes/RouteDetail.module.css

1b. Log Panel Pattern

Create ui/src/styles/log-panel.module.css containing:

• .logCard, .logHeader, .logToolbar, .logSearchWrap, .logSearchInput, .logSearchClear, .logClearFilters, .logEmpty, .sortBtn, .refreshBtn, .headerActions

Update AgentHealth.module.css and AgentInstance.module.css to import shared.

1c. Rate Color Classes

Create ui/src/styles/rate-colors.module.css:

• .rateGood, .rateWarn, .rateBad, .rateNeutral

Update DashboardTab, RouteDetail, RoutesMetrics.

1d. Tap Modal Dedup

Remove duplicate tap modal CSS from RouteDetail.module.css — it already uses the TapConfigModal component which has its own CSS module.

1e. Refresh Indicator Dedup

Move .refreshIndicator, .refreshDot, .refreshText, @keyframes pulse to shared module. Update DashboardTab and RoutesMetrics.

1f. Other Small Dedup

• .chartCard — shared between AgentInstance and RouteDetail
• .section — shared between AppConfigDetailPage and OidcConfigPage
• .metaGrid/.metaLabel/.metaValue — shared between AboutMeDialog and UserManagement

Phase 2: Fix Hardcoded Colors in CSS

For each CSS module file:

• Replace naked hex values with design system variables
• Strip hex fallbacks from var(--token, #hex) -> var(--token)
• Fix undefined variable names:
  • --accent -> --amber
  • --bg-base -> --bg-body
  • --surface -> --bg-surface
  • --bg-surface-raised -> --bg-raised
• For tint colors without DS tokens (e.g., #FDF2F0 error background), check if DS provides equivalents. If not, define them as local CSS custom properties at the component level using color-mix() from DS base colors.

Files to fix (priority order):

1. ExecutionDiagram/ExecutionDiagram.module.css (~57 violations)
2. ProcessDiagram/ProcessDiagram.module.css (~20 violations)
3. Dashboard/Dashboard.module.css (4 violations including naked #5db866)
4. DashboardTab/DashboardTab.module.css (rgba shadow)
5. RoutesMetrics/RoutesMetrics.module.css (rgba shadow)
6. AppsTab/AppsTab.module.css (--accent + rgba)
7. AgentHealth/AgentHealth.module.css (#fff)
8. LoginPage.module.css, ContentTabs.module.css, EnvironmentSelector.module.css (undefined vars)

Phase 3: Fix Hardcoded Colors in TSX

Create ui/src/utils/theme-colors.ts:

// Reads CSS custom properties from the document root at call time.
// Use for SVG attributes where var() isn't supported in JS string contexts.
export function cssVar(name: string): string {
  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
}

Then replace all hex literals in ProcessDiagram components:

• DiagramNode.tsx (~20 values)
• CompoundNode.tsx (~8 values)
• DiagramEdge.tsx (~3 values)
• ConfigBadge.tsx (~3 values)
• ErrorSection.tsx (~2 values)
• NodeToolbar.tsx (~2 values)
• Minimap.tsx (~3 values)
• ProcessDiagram.tsx (~2 values)

Note: SVG fill and stroke attributes DO support var() in modern browsers. Where the color is a static attribute (not computed in JS), use fill="var(--success)" directly. Only use cssVar() where the value must be a JS string (e.g., in computed color logic).

Also fix TSX color references in:

• pages/Dashboard/Dashboard.tsx (hardcoded #3D7C47)
• components/LayoutShell.tsx (inline color: 'var(--error)' -> CSS class)

Leave data-visualization computed hsl() values (Treemap, PunchcardHeatmap, DiagramNode heatmap) — these are intentional gradients.

Phase 4: Eliminate Inline Styles

4a. Create Missing CSS Modules

• pages/Admin/AdminLayout.module.css — extract the single inline layout style
• pages/Admin/DatabaseAdminPage.module.css — extract all inline layout/typography
• auth/OidcCallback.module.css — extract full-page layout

4b. Extract Shared Components

• Create components/PageLoader.tsx — replaces the 3 copy-pasted <Spinner> + flex + padding patterns in router.tsx, RuntimePage, DashboardPage

4c. Move Static Inline Styles to CSS Modules

Priority files (most violations):

• AppsTab.tsx — fixed-width inputs -> size classes, visually-hidden pattern, table cell layouts
• LayoutShell.tsx — StarredList styles
• EnvironmentsPage.tsx — save/cancel button rows, raw <select> styling
• RouteDetail.tsx — heading styles, tab panel margins

Phase 5: Replace Native HTML with DS Components (time-permitting)

1. EnvironmentSelector.tsx — bare <select> -> DS Select
2. ExecutionDiagram/tabs/LogTab.tsx — raw table -> DS LogViewer
3. AppsTab.tsx sub-tab bars -> DS SegmentedTabs or Tabs
4. AppConfigDetailPage.tsx — <select> -> DS Select, <input checkbox> -> DS Toggle, <label> -> DS FormField
5. AgentHealth.tsx — config bar <select> -> DS Select, action <button> -> DS Button

Out of Scope

• Responsive design (zero @media queries) — separate initiative
• Data visualization color scales (Treemap, PunchcardHeatmap) — intentional computed gradients
• ProcessDiagram SVG structural class names (className="nodes") — semantic, acceptable
• Adding new DS tokens to the design-system package — use color-mix() locally if needed

Success Criteria

• Zero naked hex values in CSS modules
• Zero var(--token, #fallback) patterns (strip fallbacks)
• Zero undefined CSS variable names
• CSS class duplication reduced from ~22% to <5%
• All pages with >3 inline styles get a CSS module
• Shared PageLoader component replaces copy-pasted spinner pattern