Remaining audit follow-ups: light theme, confirm dialogs, colony components split

[SantiaGoMode]

Leftover items from the July 2026 systems/design audit (findings 1–14 and most Low items were fixed in 2aa24da). These remain open:

1. Light theme is built from brute-force utility overrides

client/src/index.css redefines individual Tailwind utilities (.bg-gray-800, escaped arbitrary values, !important inputs) for light mode. Any new utility used in a component silently renders wrong in light theme until it's hand-added to the override list.
Fix: move to semantic CSS variables (or Tailwind darkMode: 'class' with proper theme tokens). Needs a visual pass across all pages in both themes.

2. Remaining window.confirm() calls

SchedulesPage now uses the accessible shared Modal, but window.confirm() is still used elsewhere (e.g. useColonyPage.handleDeleteTeam, and other pages). Convert the rest to the shared Modal/DeleteConfirm pattern for consistency and accessibility.

3. run-now result is polled with a 3-second guess

SchedulesPage.jsx refreshes via setTimeout(onRefresh, 3000) after "Run now" — wrong for any agent run that takes more or less than 3s. Replace with polling until last_run changes, or push completion over SSE.

4. Colony components.jsx is 2,061 lines

client/src/pages/colony/components.jsx holds ~30 components in one file. The hook/view split is done (useColonyPage.jsx + views.jsx); this file is the remaining decomposition target — split into per-component (or per-panel) modules.

[SantiaGoMode]

Implementation Plan

This issue is a multi-part UI/platform cleanup. Keep the work split into small, reviewable commits or PRs because each item has different risk and verification needs.

1. Replace brute-force light-theme utility overrides with semantic theme tokens

Likely files:

• client/src/index.css
• client/tailwind.config.js
• client/src/stores/themeStore.js
• Shared UI primitives under client/src/components/ui/ (Button.jsx, Input.jsx, Modal.jsx, Layout.jsx, Skeleton.jsx)
• High-traffic pages/components currently relying on gray utility classes, especially client/src/pages/SchedulesPage.jsx, client/src/pages/SettingsPage.jsx, client/src/pages/colony/views.jsx, client/src/pages/colony/components.jsx, client/src/components/chat/ChatWindow.jsx, client/src/components/mcp/McpServersSection.jsx, and pipeline components under client/src/features/pipelines/

Current state:

• client/src/index.css maps individual Tailwind utilities in html.light, including .bg-gray-800, opacity variants, hover variants, border variants, and !important form overrides.
• This makes light theme fragile because every new utility usage needs a matching override.

Implementation:

• Define semantic CSS variables on :root / html.dark and html.light, for example:
  • --color-app-bg
  • --color-panel
  • --color-surface
  • --color-surface-muted
  • --color-border
  • --color-border-strong
  • --color-text
  • --color-text-muted
  • --color-text-subtle
  • --color-danger, --color-success, --color-warning
• Wire those variables into Tailwind in client/tailwind.config.js as semantic colors, or add an @layer components set of semantic utility classes if a full Tailwind config migration is too large.
• Migrate shared primitives first so new code naturally uses semantic classes:
  • Button
  • Input
  • Modal
  • Layout
  • Skeleton
• Then migrate page hotspots away from raw bg-gray-*, text-gray-*, and border-gray-* utilities where they define surface/text hierarchy rather than literal gray intent.
• Remove the broad html.light .bg-gray-*, html.light .text-gray-*, html.light .border-gray-*, hover, ring-offset, and !important input overrides once migrated.
• Leave literal status colors such as red/green/yellow/blue accents alone unless they are actually surface/text roles.

Important edge cases:

• Opacity utilities such as bg-gray-800/40 need semantic alpha equivalents, not one-off light overrides.
• Hover, disabled, focus-visible, placeholder, code, kbd, badges, and selected/active states need both light and dark coverage.
• Form controls should not depend on !important global selectors after the migration.
• Preserve the dynamic --accent behavior from themeStore.

Suggested tests/verification:

• Add or extend a small frontend regression test around theme class application if the existing frontend test setup can inspect class names or computed styles.
• Run the client test suite.
• Run a visual pass in both html.dark and html.light across Dashboard, Settings, Schedules, Colony list/detail, Chat, Pipelines, Webhooks, MCP servers, and Agent editor.
• Specifically verify inputs, selects, modals, hover states, badges, code snippets, and empty states.

2. Replace remaining window.confirm() / global confirm() calls with accessible modals

Likely files:

• client/src/components/ui/Modal.jsx
• New shared component such as client/src/components/ui/ConfirmDialog.jsx, or reuse/extend client/src/components/agents/DeleteConfirm.jsx
• client/src/pages/WebhooksPage.jsx
• client/src/pages/SkillsPage.jsx
• client/src/pages/staff/components.jsx
• client/src/pages/SettingsPage.jsx
• client/src/pages/colony/useColonyPage.jsx
• client/src/pages/StaffPage.jsx
• client/src/components/mcp/McpServersSection.jsx
• client/src/features/pipelines/HistoryDrawer.jsx
• client/src/components/agents/AgentEditor.jsx

Current state:

• rg "window\\.confirm|confirm\\(" client/src shows confirm calls in Webhooks, Skills, Staff, Settings, Colony, MCP servers, pipeline history, and AgentEditor.
• client/src/components/ui/Modal.jsx already provides focus trapping, Escape handling, focus restoration, and accessible dialog semantics.
• client/src/components/agents/DeleteConfirm.jsx provides typed destructive confirmation for agent-like deletes.

Implementation:

• Add a generic ConfirmDialog component backed by Modal for simple yes/no confirmation.
• Support these props at minimum:
  • open
  • title
  • body or children
  • confirmLabel
  • cancelLabel
  • variant (danger, warning, default)
  • busy
  • onConfirm
  • onCancel
• For high-impact destructive actions, use typed confirmation via DeleteConfirm or add optional typed confirmation to the generic component.
• Replace each confirm call with state-driven dialog flow:
  • Store the pending target/action in local state.
  • Open the modal.
  • Run the existing async operation from onConfirm.
  • Keep the modal open or disable buttons while the operation is pending.
  • Close only after success; show the existing toast/error path on failure.
• Preserve current copy and destructive semantics, especially:
  • Delete webhook
  • Clear webhook inbox events
  • Delete skill
  • Clear staff chat history
  • Clear provider/ngrok secrets
  • Clear shared blackboard
  • Delete pipeline run history
  • Reset schedule run history
  • Delete colony team
  • Delete staff member
  • Delete MCP server
  • Clear pipeline history
  • Reset sandbox
  • Clear agent memory

Important edge cases:

• Avoid stale target state if a user opens a dialog and then changes selection.
• Prevent double-submit while a destructive operation is pending.
• Ensure Escape/backdrop close behaves like cancel and does not run the action.
• Make sure focus returns to the triggering button after close.
• Preserve any current toast messaging and list refresh behavior.

Suggested tests/verification:

• Extend client/src/components/ui/accessibility.test.jsx or add ConfirmDialog.test.jsx for render, keyboard close, focus behavior, cancel, and confirm callbacks.
• Add focused component/page tests where practical for at least one converted simple confirm and one typed/destructive confirm.
• Re-run rg "window\\.confirm|confirm\\(" client/src and verify no production UI confirm calls remain.
• Manually verify each converted destructive action in the UI.

3. Replace Schedules "Run now" 3-second refresh guess with completion-aware polling

Likely files:

• client/src/pages/SchedulesPage.jsx
• client/src/lib/api.js
• server/routes/schedules.js
• server/lib/scheduler.js
• server/tests/scheduleRoutes.test.js

Current state:

• ScheduleCard.handleRunNow calls api.runScheduleNow(schedule.id) and then setTimeout(() => onRefresh(), 3000).
• POST /api/schedules/:id/run-now triggers scheduler.runSchedule(row) and immediately returns { success: true, message: 'Run triggered in background' }.
• server/lib/scheduler.js tracks running schedule ids in a private running set and writes last_run, last_output, last_error, and run_count when the run finishes or fails.

Implementation:

• Expose schedule run state from the backend:
  • Add scheduler.isRunning(id) or include running state in an exported status helper.
  • Add running to GET /api/schedules/:id and optionally to list rows returned by GET /api/schedules.
• Consider returning the current schedule snapshot from POST /api/schedules/:id/run-now, including last_run, run_count, and running.
• In SchedulesPage.jsx, replace the fixed timeout with bounded polling:
  • Capture the pre-run last_run and run_count.
  • Trigger runScheduleNow.
  • Poll api.getSchedule(schedule.id) every 750-1000 ms.
  • Stop when running is false and either run_count changed, last_run changed, or last_error reflects an immediate validation failure.
  • Also stop on timeout, for example after 2-5 minutes, and show a toast that the run is still pending or could not be confirmed.
  • Refresh the parent list with the final schedule state.
• Keep the button disabled/spinning while polling, not just while the trigger request is in flight.

Important edge cases:

• Immediate failures before running.add() currently update last_run and last_error; polling must treat those as terminal.
• Overlapping runs return by setting last_error to "Skipped: previous run still in progress" without incrementing run_count; handle that as terminal.
• last_run has second-level precision, so run_count is the safer completion signal for fast repeated manual runs.
• The schedule may be deleted while polling; handle 404 by stopping polling and refreshing.
• Cancel polling on unmount to avoid state updates after the component leaves the page.

Suggested tests/verification:

• Add server route tests proving GET /api/schedules/:id includes running and POST /run-now reports/starts a run without blocking.
• Add or update scheduler tests around overlap behavior if the test harness can stub runAgentOnce.
• Add a frontend regression test for ScheduleCard with fake timers or mocked API calls: verify no fixed 3-second-only refresh remains and that polling stops when run_count changes.
• Manual verification with one fast schedule and one slow schedule: the card should update when the run actually finishes, not exactly 3 seconds later.

4. Split client/src/pages/colony/components.jsx into focused modules

Likely files:

• client/src/pages/colony/components.jsx
• New files under client/src/pages/colony/components/ or grouped files under client/src/pages/colony/
• client/src/pages/colony/views.jsx
• client/src/pages/colony/useColonyPage.jsx
• client/src/pages/colony/helpers.js
• Existing import sites for colony components

Current state:

• client/src/pages/colony/components.jsx is 2,061 lines.
• The page already has useColonyPage.jsx and views.jsx, so this remaining file should be decomposed without changing behavior.

Implementation:

• First identify exports and call sites from components.jsx.
• Split by responsibility, for example:
  • components/menus.jsx for small action/menu controls
  • components/status.jsx for run/status/progress display
  • components/log.jsx for live log and artifact output views
  • components/teamConfig.jsx for TeamConfigModal and related controls
  • components/artifacts.jsx for ArtifactViewerModal and artifact helpers
  • components/summary.jsx or components/overview.jsx for summary cards/panels
• Keep components.jsx temporarily as a barrel export if that reduces churn, then update imports in a follow-up.
• Move pure helpers into helpers.js only when they have no JSX dependency.
• Avoid refactoring behavior, state shape, or API calls during the split unless a dependency cycle forces a small extraction.

Important edge cases:

• Watch for implicit dependencies on locally defined constants, helper functions, and shared icon imports.
• Avoid circular imports between views.jsx, components.jsx, and new component modules.
• Preserve named exports so existing imports do not all need to change in the same commit.
• Keep modal state, run selection, and live log behavior unchanged.

Suggested tests/verification:

• Run the client test suite and build.
• Manually verify colony list, colony detail, team configuration modal, live run output, stop/delete/export actions, and artifact viewer.
• Use rg or TypeScript/Babel build output to catch missing exports/imports after each extraction.

Suggested order of work

1. Replace confirm dialogs first. This is relatively contained and improves accessibility quickly.
2. Fix schedule run-now polling next because it touches both backend and frontend behavior.
3. Split colony components as a mechanical refactor with careful verification.
4. Do the light-theme token migration last because it has the widest visual blast radius and benefits from the modal/component cleanup already being complete.