How 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 us from the start. 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 over 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 didn't 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, how a menu behaves. It doesn't need much instruction because the pattern exists outside our system.

What failed was a different kind of component.

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

In the lists, it used a checkbox inside a format that doesn't exist in our system. It created indicators in a grid, segregating information into boxes when a simple list would have worked better. In another case, it generated a completely generic card list, with colors that made no sense and information boxes stacked 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 doesn't 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 mistakes, a pattern became clear: Claude Code invents when it doesn't find.

When a documented component is available, it uses it. When there isn't one, it creates one. And what it creates reveals exactly what is missing from the documentation.

The checkbox in a list points out that the list pattern needs an explicit rule for when to use it and when not to. The cards colored by status show that our status system isn't documented in an accessible way. The little information box taking up a whole row indicates that there is no guidance on space optimization available to consult.

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 doesn't document well, the LLM guesses.

How this changes 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. Menu appears on practically one hundred percent of the system's screens. Claude Code can already build it reasonably well, but still makes mistakes. Refining the documentation enough to eliminate those mistakes has 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, are used extensively, and Claude Code has been building them completely at random. Sometimes it gets a similar layout, most of the time it gets it very wrong.

Before assuming the problem is in the documentation, we are going to test more. I need to understand whether Claude Code fails because it didn't find the component, because the existing documentation is insufficient, or because the instructions we gave were incorrect. Each cause has a different solution.

A recommendation for those just starting

Not every team has two weeks of dedicated, exclusive time on a design system, and not every design system has the specific problem ours had with outdated tokens.

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

In this process, mistakes will show up. Each one points to a specific gap in the documentation. You don't need to plan what to document: the LLM shows where the hole is.

If you already have experiments done and failure cases mapped, as is our case now, you can go straight to what is failing and prioritize from there. If you don't yet, test first, let the LLM fail, and use the errors as a map.

This doesn't replace foundation work when it is needed. Outdated tokens need to be resolved before any AI layer. Order matters. With a reasonably solid foundation, prioritizing by error can be the fastest path to real value in operations.

What lies ahead

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

I don't know the results we will reach. I'll bring news soon.