Contrast Fixes and Module Audits: Two Small Tasks That Matter
The Docs Readability Problem
Had been bugging me for a while. The documentation pages (/docs/) and admin docs hub (/admin/docs-hub/) had text that was hard to read. Not broken, exactly. Just... dim.
The root: using var(--text-tertiary) which resolves to #64748b (Tailwind slate-500) on the cosmic background. At small font sizes (0.7–0.82rem), that produces a contrast ratio of roughly 3.6:1. WCAG AA requires 4.5:1 for normal text. We were below spec.
Affected:
- TOC sidebar links
- Sidebar nav numbers
- "Other Sections" links
- Breadcrumbs
- Doc meta (dates, edit links)
- Hub index card descriptions
Additionally, doc body used #cbd5e1 for paragraphs—readable on desktop in bright light, but on a phone screen in normal indoor lighting? Dim. Squinting dim.
The Fix
Systematic brightness bump across the affected elements:
| Element | Before | After | Improvement |
|---|---|---|---|
| TOC links | #64748b |
#8a95a5 |
+38 brightness |
| Nav numbers | #64748b |
#7d8898 |
+25 brightness |
| "Other Sections" | #64748b |
#8a95a5 |
+38 brightness |
| Body paragraphs | #cbd5e1 |
#d1d9e3 |
+6 brightness |
| Body h5/h6 | #94a3b8 |
#b0bcc8 |
+28 brightness |
On mobile specifically (added @media (max-width: 900px) blocks):
- Sidebar nav items: larger font (0.88rem), lighter color (
#c8d1db), subtle background highlight - Body text: lighter (
#dbe2ea), slightly larger (0.95rem), better line-height (1.75) - Headings: proportionally lighter
Desktop visual changes were minimal—just a subtle brightness bump on secondary elements. Mobile got much more readable without destroying the cosmic aesthetic.
Four files changed: public docs page, public docs index, admin docs reader, admin docs hub. +247/-39 lines. Tested on a real phone. Much better.
The Module Audit
Then I did something I'd been postponing: looked at the entire module structure.
ArgoBox has 28 admin feature modules. I built the module system weeks ago, but hadn't done full validation. Turns out there were orphaned pages—admin pages that existed but weren't registered to any module.
What I Found
/admin/settings— Created but never assigned to a module/admin/buildand/admin/swarm— Existed but not claimed/admin/site-test— Health monitoring page, orphaned
Created a settings.ts module to claim /admin/settings and the group "system". Updated build-swarm.ts and health-monitor.ts to claim their respective pages.
Also did component ownership claims—documenting which components belong to which modules:
| Module | New Components |
|---|---|
| security | AdminSidebar, CommandPalette, NotificationSystem, AdminModeIndicator, TroubleshootingNotes |
| pentest | ScanOutput |
| build-swarm | FleetStatusGrid, SwarmHero |
| homelab | HeroSection, ProjectsSection, ServiceCategory, ServicesSection |
| chat | ChatWidget |
The Sandbox Cleanup
The sandbox page at /admin/sandbox was serving two purposes: showing module nav duplicates AND showing unique pages not reachable elsewhere. Confusing.
Removed 5 sections that duplicated module nav (Recovered Admin Routes, Argonaut, Content & Editing, Proxmox, MasaiMara). Kept 4 unique sections (Demo, Command Center, Playground, Ansible—pages that don't belong in any main module). Added "Legacy & Orphaned Pages" section and placeholder for "OpenClaw Generated" content.
The Result
- 28 modules
- 0 orphaned admin pages
- 67 admin pages total, all claimed
- 152 pages site-wide
- Everything validated and coherent
Takes maybe 30 minutes to verify 28 modules. Worth it to know the structure is consistent and nothing is hidden.
Why These Tasks Matter
These aren't flashy features. Readable documentation and clean module architecture don't show up in commit messages that excite people. But:
Readable docs = people can actually use the platform. Dim text doesn't stop you from functionality, but it stops you from understanding. Swap one for slightly-lighter text and suddenly the cognitive load drops. Mobile users specifically—they're often in different lighting, on smaller screens. The contrast fix was essential.
Clean modules = the next person (or future me) opening this codebase doesn't spend an hour figuring out where things live. It's documented. It's validated. It's coherent. Saves hours of exploration on the next task.
Both are maintenance work. Both feel minor in isolation. Together, they're the foundation that keeps a complex codebase from becoming a mess.
The Pattern
Start of the week: big architectural features (settings system, module system). Middle of the week: bug fixes and identity work. End of the week: polish and maintenance.
The maintenance work doesn't generate excitement. But it enables the exciting work to happen faster next week.
Status: Docs contrast improved for mobile readability. All 28 modules validated, 3 orphaned pages resolved. Sandbox cleaned up. Module structure coherent and documented.