case-study May 20, 2026 6 min read

From design system to product platform

#design-systems#product#frontend#tooling#operations

For some time now, a very specific idea had been resonating with me: a design system should not depend on a specific tool to exist, nor on a closed workflow to remain useful. The governance I had seen in other large teams already pointed in that direction: more contract, more shared criteria, and less dependency on a single interface or a single visual source of truth.

I also started to see the same movement in different large-scale product environments. Some teams were rethinking their systems to be accessible, consistent, and consumable by LLMs; others were already working with directly code-ready systems, closer to infrastructure than a visual showcase.

In parallel, something happened to me that anyone who has worked with third-party design tooling will surely recognize: an update made me realize how fragile it can be to build on a platform you do not fully control. In the end, it was resolved, but the intuition remained clear: if the tool changes, the system cannot be trapped in it.

So I decided to build something with what we already have today —LLMs, documentation, experimentation, and close experience— to create a base of work that does not depend on a single interface, but on a system contract capable of evolving with us.

The real problem

Many design systems have components, libraries, documentation, and even a fairly solid visual language. But when it comes to building real product, launching a new page, or adapting an experience to another context, too many times the system falls short.

It usually doesn’t fail due to a lack of parts. It usually fails because it never becomes infrastructure. That is, because it does not end up being the real foundation upon which design, frontend, and tooling can work without re-interpreting the same problem over and over again.

More than a catalog

In Code Ready, the architecture is already quite far from the classic idea of a “collection of components”.

The system uses Astro as the catalog and page shell, React for interactive components, and Base UI as an accessible headless primitives layer when it fits the problem to be solved.

That alone could still describe a well-built library. What really changes the nature of the system is something else: the JSON registry acts as a central contract and the current documentation explicitly separates the operational, canonical, and referential.

That nuance matters. It means the system no longer lives scattered between code, screens, and the team’s tacit knowledge. There is a clear structure regarding where each truth is, which layer rules over another, and how each part is edited without introducing noise or duplication.

The registry as a contract

The most powerful idea in all this is that the registry stops being an inventory and becomes a contract. It not only says that a Button, a Dialog, or a HeroLeadForm exists; it also establishes how it is described, what props and states are part of its API, what example represents it, and what documentation accompanies it.

But the most interesting evolution is that this contract no longer covers only the technical implementation. The new canonical documentation adds specific layers to model decision, quality, criticality, business, brand, and locale directly in the registry entries.

That changes the conversation quite a bit. The system can no longer just answer ‘which component do I use’, but also ‘what level of abstraction does it have’, ‘what happens if it fails’, ‘in which context should it appear’, or ‘which part of the product does it affect’.

From parts to decisions

For years we have thought of design systems as boxes of parts. Buttons, inputs, modals, menus, tabs. All of that is still necessary, of course. But it is not enough to speed up real work if every time a new page or flow appears, the team has to re-interpret from scratch how to compose, which pattern fits, and what decisions were already resolved.

That’s why I think it’s so important that Code Ready doesn’t stop at primitives. The system already contemplates sections as page-level reusable compositions, registered and documented within the same framework as the rest of the catalog.

There is a major shift in mindset here. A section is not a flashy demo or an informal template. It is a composition that the system considers stable and reusable enough to turn it into a shared asset.

A concrete example

HeroLeadForm summarizes that evolution quite well. It does not try to solve every hero or every form: it is designed as a specific composition for acquisition pages with a primary goal of conversion and a fairly recognizable structure.

Documented interface of HeroLeadForm as a system section

The interesting thing is that the system does not stop at the visual layer. It also begins to place components and sections in their real context: where they are used, what objective they help achieve, and what care is required to change them.

The documentation itself describes it as a section designed for high-intent contexts, where the form is a direct part of the conversion goal.

The system now models more than UI

One of the things that changes the most with the updated documentation is that the registry no longer describes just the interface. It also describes context. There is a layer to decide if something should be a primitive, section, or manual composition; another to model criticality and impact; another to locate pieces within the funnel; and another to declare brand compatibility, i18n keys, and contexts of use.

Hierarchy and abstraction layers within the Registry

This makes the design system a much more useful tool for senior teams. It is no longer just for aligning UI, but also for making better product and maintenance decisions. You can discuss whether a piece deserves to be promoted to the system, how much it costs to break it, where it is used well, and where it is better not to force it.

And all that without mixing layers. The documentation is designed precisely to prevent the system from drifting into an unstructured metadata soup: each dimension has its canonical doc, its semantics, and its editing location.

Brand and locale without contaminating components

Another clear sign of maturity is how brand and internationalization are resolved. The current guide makes it very clear: React components should not know either the active brand or the active locale. They receive props, consume semantic tokens, and render; visual variation is resolved in the token layer, and language variation in the integration layer before reaching the component.

It seems like a small rule, but it has a significant impact. When brand logic or copy enters shared components, the system becomes more fragile, harder to maintain, and more prone to local exceptions.

Here, the approach is the opposite. Tokens are the visual source of truth, with an explicit cascade between core, brand collections, and modes, and components only consume semantic names like --color-primary or --color-bg, never hardcoded values or specific brand tokens. This allows the same component to adapt to different brands or modes without having to know anything about them.

Publishing for reuse

All of this makes even more sense because the system does not remain locked inside its own catalog. Code Ready is already published as an npm package consumable by other projects and exposes separate entrypoints for components, sections, styles, base, brands, and types.

Packaging architecture and independent entrypoints

This changes the nature of the design system in an important way. It is no longer just something the team references to implement, but something other projects can import as a real foundation. The difference between ‘looking at the documentation’ and ‘consuming the system’ is huge.

I also like that this publication does not mix different things under the same label. The entrypoints for styles and base, for example, separate the definition of the visual system from its application to the DOM, making it clearer which part contributes tokens and which part contributes base behavior.

Designed for design, engineering, and LLMs

There is another detail that I think is key and will likely shape more systems in the coming years: the documentation is not written only for humans. The README and the workflow make it clear that this base is designed for design, engineering, and LLM-assisted workflows, with editing routes, contracts and rules explicit enough so that a machine can also operate on them without inventing semantics along the way.

It’s not about eliminating design tools. It’s about the system surviving them.

Towards new projects

And perhaps that is the part that interests me most about all this. Once you have a published design system, with a clear contract, useful metadata layers, reusable sections, and explicit support for brands and contexts, you are not that far from using it as a base to start new projects.

Complete workflow from the initial Briefing to the generated page

In this scenario, the input is no longer ‘let’s draw a page from scratch’, but something much more structured: what is the goal, what content do we have, what languages does it support, what brand context applies, and what level of composition fits best.

This does not replace design work. But it does change where it starts. Instead of starting by rebuilding the infrastructure, you start by making decisions on a foundation that already exists.

Composing in the consumer

And this opens up a particularly interesting possibility: each new page does not need to exist beforehand as a closed template. In many cases, a consumer could assemble it dynamically from system components, as long as the briefing includes structure, content, goal, languages, and brand context.

The key point here is that the LLM would not have to invent the interface from scratch. It would have to compose based on an already defined contract: what pieces exist, what level of abstraction they have, when it is appropriate to use a section, and when it is appropriate to assemble the page manually in the consumer.

This shifts the value of the design system. It stops being just a UI library and becomes a structured foundation for teams and LLMs to build products with more speed and less ambiguity.

What we are really building

So, if I had to summarize it in a single idea, I would say this: Code Ready does not want to be the visual source of truth. It wants to be the operational foundation to build products without depending on a single tool.

And to me, that is precisely the point where a design system stops being a library and starts to become a platform.

The natural next step in this series is to dive into the core of that idea: why the registry matters so much and how it stops being an inventory to become a contract and decision layer.