UI Collective just released a video on design systems and AI, and it nails a problem I run into a lot on client work: you connect your design system to an AI, it sees your components and your variables, but it doesn't know which one to use when. So it guesses.
A list with no instructions
Everyone has seen the result: it uses three variables out of thirty, it overrides a button's color with a gradient out of nowhere, it ignores half your text styles. You tell yourself the AI isn't ready. In reality, it was handed a list with no instructions.
The method in the video is simple: you split your design system into groups (form components, navigation, data display) and you write one sheet per group explaining what to use when.
The two documents the AI can't write for you
Where the video gets really interesting is this: there are still two documents no AI can produce, because their raw material exists nowhere except in the team's heads.
The first lists the flaws the team knows about and won't fix, the ones whose fix isn't in the design system. Your brand color fails contrast as text on a white background. It's not one token to change, it's several files to update. As long as that trade-off isn't written down anywhere, every audit run with an AI flags it, and the team spends time all over again re-explaining a decision that's already been made.
The second lists what nobody writes down because everybody knows it. Three card components that look alike, only one allowed on the dashboard. A table that switches to a list below a certain width, except on one specific page. The AI picks the component whose name speaks to it. A designer who just joined does exactly the same, except someone ends up telling them in review.
Admissions, and the first two pages that are missing
These two documents are admissions, and that's exactly why they never get written: nobody likes documenting their compromises. Yet they should be the first two pages of your documentation, because they're the only two that neither an AI nor a new designer can guess.