The visible problem may look like one API or tuning value, but reliability is decided by state ownership, resource bounds, and recovery after failure. Simple inversion breaks brand, status, and hierarchy. Tokens describe surface, text, border, accent, and danger roles, with theme values chosen separately.
Frontend architecture is about state ownership, repeatable events, invalidation of stale async work, and cleanup after unmount—not the shape of the source directory.
Make the implementation decisions explicit
Start from facts the data and protocol can guarantee, then decide what the interface may promise. Each rule below needs an owner, a bound, and a compatibility policy rather than an oral convention from one review.
- Separate primitive scales from semantic tokens and let components consume semantic roles.
- Resolve system and local preference before app mount to prevent a theme flash.
- Validate hover, disabled, focus, and chart series contrast independently in each theme.
A theme system centralizes visual decisions. Stable semantic tokens make dark mode, brand changes, and accessibility fixes systematic.
Failure paths that are easy to miss
Boundaries turn hidden assumptions into incidents. Weak networks, refresh, concurrency, and capacity need combined coverage because retries can hide each one in isolation.
- Light-theme shadows are reused and either disappear or glow badly on dark surfaces.
- Hard-coded component colors require repository-wide replacement for every theme.
- The initial page ignores preference and flashes light before switching dark.
How to verify it before release
Write the expected state trace before injecting faults. At every phase, reconcile user-visible outcome, both protocol endpoints, persistent records, and resource counts to prove the loop.
- Statically audit token use and reject new unapproved raw color values.
- Test contrast, keyboard focus, system changes, and flash-free first paint on primary pages.
- Check state recognition on OLED, low brightness, and high-contrast modes rather than screenshots alone.
A capability becomes maintainable when it degrades safely, repetition adds no side effects, and its signals reveal a fault before user reports do.