How the mistakes are guiding the Harness Design System

A conversation today with Gustavo Navarro, our Engineering Manager, and Diogenes Vanzela, our Group Product Manager, made me see something that had been in front of me since the beginning. The map of what we need to document in the Harness Design System project already existed. It was in the mistakes Claude Code had made in the previous months.

What the tests had already shown

Before this project was formalized, we had already run experiments using Claude Code to build interfaces directly in code. Some results were surprisingly good. Others revealed problems I did not expect.

What worked was the kind of component with a global pattern: tables, headers, menus. Claude Code has already seen these elements in thousands of different codebases. It can infer what a table is and how a menu behaves. It does not need much instruction, because the pattern exists outside our system.

What failed was a different kind of component.

In a project we tested without prototyping in Figma, Claude Code tried to build screens that included drawers and more complex components. In a component that represents a tire diagram, it got some parts right and wrecked others. Information was too small, and spacing too narrow for any readability.

In the lists, it used a checkbox in a format that does not exist in our system. It created grid indicators, splitting information into boxes when a simple list would have worked better. In another case, it generated a fully generic card listing, with colors that made no sense and stacked information boxes with no refinement at all.

The most emblematic case: without finding our specific way of handling status, it invented its own. It created cards with a yellow, red, or green background depending on the situation. That logic does not exist in our design system. It built it from scratch because it found nothing to reference.

The pattern behind the failures

Looking at the set of errors, one pattern became clear: Claude Code invents when it does not find.

When there is an available, documented component, it uses it. When there is not, it creates one. And what it creates reveals exactly what is missing from the documentation.

The checkbox in a list points to the fact that the list pattern needs an explicit rule about when to use it and when not to. The status-colored cards show that our status system is not documented in an accessible way. The information box taking a whole line shows there is no available guidance on optimizing space.

Structural components with a global pattern work because Claude Code has enough reference from the outside world. Product-specific contextual components fail because the only possible reference is our system, and if it does not document things well, the LLM guesses.

How this changes the prioritization

In the previous article I described the logic of prioritizing by the most repeated screen pattern: menu, topbar, header, and table. That anchoring still makes sense as a starting point. Today's conversation added a second layer that was missing.

The first part remains the components of the anchor screen. The menu appears in practically every screen of the system. Claude Code can already build it reasonably well, but it still makes mistakes. Refining the documentation enough to eliminate these mistakes has an immediate impact at full scale. It is the component with the highest proportional return.

The second part goes straight to where the errors are concentrated. Drawers are the most critical case: they replace modals in our system, they are used extensively, and Claude Code has been building them in a completely random way. Sometimes it gets a similar layout right; most of the time it gets it very wrong.

Before assuming the problem is the documentation, we will test more. I need to understand whether Claude Code fails because it did not find the component, because the existing documentation is insufficient, or because the instructions we gave were wrong. Each cause has a different solution.

A recommendation for those starting out

Not every team has two weeks of exclusive dedication to a design system, and not every design system has the specific problem we had with outdated tokens.

What this process suggests as the most practical entry point: start by using an LLM to build real interfaces in code. LLMs that deliver code usable in production, with the developer in the loop. Quick prototyping tools are outside what I am recommending here.

In this process, errors will show up. Each one points to a specific gap in the documentation. You do not need to plan what to document: the LLM shows you where the hole is.

If you already have experiments done and failure cases mapped, as we do now, you can go straight to what is failing and prioritize from there. If you do not have them yet, test first, let the LLM fail, and use the errors as a map.

This does not replace the foundation work when it is needed. Outdated tokens have to be resolved before any AI layer. Order matters. With a reasonably solid foundation, prioritizing by error may be the fastest path to real value in operations.

What comes next

The Harness Design System project is already underway. React and Flutter developers, Glauber Franco, and I are fully focused on it for two weeks. The goal is to come out of this period with tokens applied in the code, the anchor-screen components refined, and a clear understanding of where the drawers are failing and how to fix them.

I do not know yet what results we will reach. I will share the news soon.