When Documentation Becomes a Contract Your AI Must Follow

Somewhere along the line of a big refactor, I broke our custom theme system.

Wasn’t obvious at first. The layout still rendered. Tailwind classes were there. No error messages. But the app looked… off. Dull. Unstyled. Like the soul had been drained.

Turns out our EnvironmentThemeProvider—which dynamically injects environment-based themes (indoor, evening, outdoor, etc.) using CSS variables—was silently being overridden by leftover hardcoded defaults in index.css.

What Actually Happened

• The provider correctly injected data-theme="soft-dark" and runtime variables like --background
• But our global CSS still had a :root block with static fallbacks
• CSS precedence rules did their thing: the old vars won, and our theme engine lost

This is the kind of bug that’s invisible to most linters. It’s not a broken build—it’s a broken contract.

The Fix Wasn’t Just Code

I used Kilo to audit tailwind.config.ts, global CSS, and layout wrappers. But what I got back wasn’t just “here’s the problem.” It was a reproducible failure mode and a fix plan aligned with our coding standards. It explained why dynamic CSS vars were being ignored and justified why we weren’t using DaisyUI or plugin-based theming.

That distinction matters.

We baked the fix into a new THEMING.md and added dev-only debug overlays to verify active theme tokens. All in code. All source-controlled. All enforceable.

The Mindset Shift

This wasn’t just a styling bug. It was a mindset bug.

In AI-assisted development, I have to treat intent as a system. If the theme logic is dynamic, the docs, tests, and CSS structure must be too. Otherwise I’ll build infrastructure that’s technically correct but operationally misleading.

I used to think “docs-as-code” meant keeping documentation version-controlled. Now I see it differently. Docs-as-contracts means the documentation defines what the system must do—and the AI uses it as a constraint, not just context.

When the app’s assumptions are documented, enforced, and testable, AI agents don’t just help. They accelerate the right direction. When those assumptions are implicit or scattered? The AI just generates faster in the wrong direction.

Theme system restored. Intent made explicit. The AI reinforced the design contract, not just the syntax.

That’s the game now, I think. Or at least, that’s how I’m playing it.