Improving a low readiness score

Most low scores come from the same four gaps, in the same order. Fixing them is writing, not refactoring, which is why the work is usually faster than teams expect.

1. Say what each component is for#

Highest weight, most commonly missing. "Modal component" tells an agent nothing. Write the sentence a new colleague would need:

Use Modal for short interruptive tasks that need an explicit decision before the user continues. It traps focus and blocks the page behind it.

One sentence per component, in the place your team already documents them: the JSDoc block above the export, the Storybook docs page, or the Figma component description. Onefold reads all three. About ten minutes per component, and it is the single highest return change available.

2. Say when not to use it#

The most missing thing in design systems, and the thing agents need most. An agent choosing between Button, Link and IconButton has no way to pick correctly unless something rules the wrong options out.

Do not use Modal for confirmations that can be undone, use Toast. Do not nest a Modal inside another Modal.

Negative guidance is worth 10% of the score and close to nothing is usually written. Two lines per component.

3. Replace literal values with tokens#

Every stray hex value, pixel radius and hardcoded shadow is a rule an agent will copy. It reads your implementation as the example of how this system is built, so a component with #3b82f6 in it teaches the agent that literal colours are acceptable here.

Find them, replace them with the token that already exists, and if no token exists, that is the finding. This is the one item on the list that is a code change rather than a writing task, and it is worth doing with a codemod rather than by hand.

4. Give each component one canonical example#

Agents pattern match. Whatever example they find first becomes the template for everything they generate. One correct, complete, idiomatic usage per component, in a story or in the documentation, is enough. An outdated example is worse than none, because it will be copied faithfully.

Then, the structural ones#

These take longer and are worth planning rather than doing in an afternoon.

• Make components discoverable. Predictable exports from a single entry point, one name per component, no component reachable only through a deep import path. If Onefold cannot find it reliably, neither can an agent.
• Close the design to code gaps. A Figma component with no implementation, or an implementation with variants Figma does not have, is drift. Every instance is a place where design and code disagree and the agent picks one at random.
• Document the accessibility contract. Which element receives focus, what the label is, which role applies, what keyboard interaction is expected. Generated UI silently drops all of it unless it is written down.

What not to do#

Do not generate documentation with a model and commit it unread. It raises the score, because the score measures whether documentation exists, and it lowers the thing the score is a proxy for, because an agent will follow a confident description of behaviour the component does not have. Onefold measures what is written. It cannot tell you it is true.