Your AI design context is infrastructure, not a document

I have been maintaining ours for about a year. During that time, it has been renamed, restructured, compared against competing documentation, and updated as entire product patterns disappeared.

That work changed how I think about the spec. It is not a document you finish and file away. It behaves more like infrastructure.

Drift is quiet

When a component breaks, someone notices. The problem appears on screen and eventually becomes a bug.

When a design spec becomes outdated, nothing visibly breaks. AI continues producing confident and consistent output, but it follows last quarter's decisions.

We experienced this with two sources of truth. A written design document was maintained alongside the machine-readable spec. Both looked reasonable, but they had diverged on details such as border treatments and hover behavior.

I compared them line by line, decided which rule was current, and removed the duplicate source.

Two sources of truth do not provide extra safety. They create uncertainty about which one should win.

Removing a pattern takes more than deleting its section

At one point, the product direction changed and a complete pattern family had to disappear. The main section was easy to remove.

Then I found references to the pattern in the color rules. It appeared again in typography guidance and inside unrelated component examples.

Any leftover reference could bring the retired pattern back because AI reads every instruction as current.

Now, when removing something, I search for the idea itself and every name used for it. Deleting the obvious section is only the first pass.

Each revision needs a version

I treat significant changes as releases. The current spec is packaged as one artifact, and the previous version stays available until the new one has been tested on real screens.

This has saved time more than once. A tighter rule improved one pattern but unintentionally removed color from another component that needed it. Comparing the two versions made the cause easy to find.

Changing one thing at a time also helps. When several rules move together, it becomes difficult to understand which change caused the output to improve or regress.

Design-tool handoff will not always be perfect

A direct connection to the design source is ideal, but access and tooling are not always reliable.

The fallback that worked consistently was simple: a screenshot of the full component matrix together with the values from the inspector.

The important part was capturing the whole component at once. For an input, that meant every size and every meaningful state. A partial specification only created another round of clarification later.

I also documented what each state meant, not only how it looked. A statement such as “focus uses the accent because it represents an active interaction” survives a token rename. A raw color value does not.

One system can support different outputs

Our design language eventually needed to produce framework components and standalone pages with plain CSS.

Forking the entire spec would have created another drift problem. Instead, the shared rules remained in one place, while each output target received a smaller section describing its implementation patterns.

The language stayed the same. Only the dialect changed.

Maintenance needs to happen with the design work

The most reliable cadence has been straightforward: when the design changes, update the spec during the same work.

Waiting for a quarterly review allows the product and its instructions to separate. By the time the output looks wrong, the team has already spent time correcting the same outdated decision in several places.

A stale spec is not passive. It continues arguing for the wrong design and can repeat that decision at scale.

That is why I now treat AI design context as infrastructure. It needs ownership, versions, and maintenance. Without those, even a very good spec gradually becomes a confident description of a product that no longer exists.