Before AI-first, human-first

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

The natural question after that text would be which components to start with. That was the question I brought to this week. When I went to answer it, I found there was an earlier question. 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.

Applying a layer of AI on top of a flow that still has friction between designer and developer does not remove 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 this system will be working with two sources of truth at once. The problem that already exists will become 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 correcting 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 foundation stands today

In 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 with no token. A background that needed a new variant. Shadows that were not mapped. Each gap became an adjustment to the corresponding variable.

An interesting side effect showed up in this process: dark mode, almost for free. When you work with tokens and variables properly, dark mode stops being a future project and becomes something you can switch on. It was not a priority in scope, but we reached a point where testing dark mode was almost trivial. The team got excited, and so did the stakeholders. This kind of unexpected return is what happens when the foundation work is done right. You fix the base and gain 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, it would create a worse problem than the current one. Designers would start delivering handoffs with colors and typography that the developer has no way to apply. Each screen used in a stakeholder discussion would look like a decision had been made, but what reached production would be different. The noise between Figma and code would show up in every conversation, and nobody gains time from that.

This is the kind of problem that looks small on a slide and becomes big when it hits a whole sprint. I will 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 the 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 painstaking, sifting work. Only after that can the design system be published in Figma, and the human-first flow becomes coherent again.

In parallel, we started investigating a question I do not yet know how to answer: how to make the tokens consumable by an LLM. A distinction here has become important in the Harness Design System project. 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 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 not yet clear how much work that will require. It could be small, it could be big. I will find out next week.

Then, the components. And the initial question comes back

Once this first layer is closed, the question of which components to start with returns with more 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 an activity with no feedback. You improve the documentation, move on to the next component, and never know whether what you did produced results. To test, you need a concrete scenario.

The decision: anchoring 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 will start there. This 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 working.

Third: we already have several versions of this screen built by hand, 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 reaches the same level, falls short, or needs so much adjustment that it is not worth it.

What the experiment will actually test

After the tokens are applied in the code and these four components have their LLM-readiness documentation, I will ask Claude Code to build a screen with 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 be scaled. 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 yet seen. Partially is the most likely scenario and the most interesting one 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 the code first. Design system published in Figma next. LLM-readiness of tokens investigated in parallel. After that, components of 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 this order. The next ones will tell what happened when I left it and went into practice, with the surprises that show up along the way.