Before AI-first, human-first

In the previous article I described how we are building the Harness Design System Project. The plan was clear: start with a few components, test with Claude Code, learn before scaling.

The natural question after that text would be which components to start with. That was the question I brought into this week. And when I went to answer it, I found there was a question before it. Before deciding which component comes first, I had to decide what comes before the components. That is what this article is about.

The order that became clear this week

The rule I arrived at is simple to state and harder to follow: before AI-first, human-first.

Putting an AI layer on top of a flow that still has friction between designer and developer does not solve the friction. It multiplies it. If the design system is not in sync between Figma and code today, in the traditional flow, any agent that tries to consume that system will be working with two sources of truth at once. The problem that already exists will get more opaque, not more visible.

Even in a scenario where AI produces more and more, there will always be a human operating at some point. A designer reviewing. A developer refactoring. A stakeholder validating. If that human cannot trust the foundation, they will end up fixing things the AI generated, and the result will look random. The order is to fix the base first, then build on top of it.

Where the base stands today

Over the last two weeks, Glauber Franco and I finished the complete tokenization in Figma. We applied the tokens to components that already existed, starting with the simplest ones, like buttons and inputs. While applying them, we kept finding semantic gaps. A border color that had no token. A background that needed a new variant. Shadows that had not been mapped. Each gap became an adjustment to the corresponding variable.

An interesting side effect showed up in the process: dark mode almost for free. When you work properly with tokens and variables, dark mode stops being a future project and becomes something you can switch on. It was not a priority in the scope, but we reached a point where testing dark mode was almost trivial. The people on the team were excited, and so were stakeholders. That kind of unexpected return is what happens when foundation work is done right. You fix the base and get things you had not asked for.

The problem that still needs solving

The tokens are ready in Figma. In code, they are not.

If I published the design system now, with the new tokens in Figma and the old ones running in production, I would create a problem worse than the current one. Designers would start delivering handoffs with colors and typography that the developer has no way to apply. Every screen used in a discussion with a stakeholder would look like a decision already made, but what shipped to production would be different. The noise between Figma and code would show up in every conversation, and nobody saves time on that.

This is the kind of problem that looks small on a slide and becomes big when it hits a whole sprint. I am going to be careful to avoid it.

What comes next week

Next week is dedicated to aligning with the React and Flutter developers on how they will apply tokenization to the code that is already in production. This work is not small. Every hardcoded color, every direct reference to a value that should be a token, needs to be reviewed. It is prospecting work. Only after that can the design system be published in Figma and the human-first flow be coherent again.

In parallel, we are starting to investigate a question I still do not know how to answer: how to make tokens consumable by an LLM. A distinction that has become important in the Harness Design System Project belongs here. Harness Design is the broader discipline, the design of the whole system so that AI can produce with direction. LLM-readiness is a specific practice within it: documenting and structuring artifacts so that an LLM can read them and use them correctly. Making components LLM-ready is part of Harness Design. Making tokens LLM-ready is too, and it is still unclear how much work that will take. It might be small, it might be big. I will find out next week.

After that, the components. And then the original question comes back

When this first layer is closed, the question of which components to start with comes back with weight. And the intuitive answer of picking the most used ones is not enough on its own. Applying LLM-readiness to components without a way to test whether the application is working becomes activity without feedback. You improve documentation, move on to the next component, and never know whether what you did produced a result. To test, you need a concrete scenario.

The decision: anchor on a screen pattern

I looked at our system and identified the screen pattern that repeats the most. It has four main components: menu, topbar, header, and table. It is the most basic pattern we have, and also the most frequent. I am going to start there. The decision solves three things at once.

First: the components in this pattern are among the most used in the system. Working on them first has a high return even if the AI experiment does not give the expected result, because better documentation for them also serves the human-first flow.

Second: if Claude Code cannot reproduce this screen well, which is the simplest and most standardized one we have, it will hardly be able to reproduce anything more complex. That gives me a clear failure criterion, instead of a vague feeling that it is more or less okay.

Third: we already have several versions of this screen built manually, in the traditional flow. That becomes a control case. I can compare what Claude Code generates with what the team produced without AI, and see whether it is at the same level, below it, or needs so much adjustment that it is not worth it.

What the experiment will actually test

After the tokens are applied in code and these four components have their LLM-readiness documentation, I will ask Claude Code to build a screen of this pattern. The question is whether the result has quality close to the manual version, without needing much adjustment.

The answer will be yes, no, or partially. Any of the three is useful information. Yes means the path works and can scale. No means something is wrong somewhere, and part of the work will be finding out whether it is in the documentation, in the method, or in an assumption I have not seen yet. Partially is the most likely scenario and the most interesting to document, because it will show where it works, where it breaks, and where it needs refining.

The order of the Harness Design System Project

To sum up the order that became clear this week. Tokens in code first. Design system published in Figma next. LLM-readiness of tokens investigated in parallel. After that, components from the most repeated screen pattern, anchored in an experiment with a control case.

Each layer has to work before the next one can be trusted. This article is about how I arrived at that order. The next ones will tell what happened when I took it from there into practice, with the surprises that show up along the way.