← Back to articles

November 18, 2026

Before the First Component: Lessons from Building a Design System from Scratch

Capa do artigo sobre a construção de um design system do zero

Introduction

From the outside, building a design system from scratch looks like making beautiful components. In practice, most of the effort goes elsewhere: deciding what goes in, organizing it so people can find things, documenting it so they use it the right way, and handing it off to development without noise.

Over the past few months I built a design system almost from scratch, at a healthcare company with several digital products running at the same time. The starting point was a product that already existed and teams that were already designing screens without a system. Today, the first version has 49 components.

This article brings together what I learned along the way, across four areas: organization, documentation, handoff and the use of AI (mainly Claude) to speed up the work. If you're starting a design system on your own or with a small team, I hope it helps you streamline your work, even if just a little.

1. Before the first component: inventory and scope

The natural urge is to open Figma and start with the button. Resist it. The first deliverable of a design system is an inventory of what already exists, because that's what shows where the inconsistencies the system is meant to fix actually are.

In my case, the foundation was a real product in active use: our users' main portal. Instead of inventing ideal components, I started from what people were already using and asked three questions about each element:

  • Does it appear on more than one screen or product?
  • Are there variations that should really be one thing?
  • Can the developer build it on our platform? In our case that was OutSystems, a low-code platform with its own limitations. We worked around all of them, but only because we asked this question before the component was finished, not after.

The second lesson was to name the scope of the first version. Calling it V0 and separating out the foundations was an important decision: it made clear to the team that this wasn't the complete system, but the first stable layer. That takes away the pressure to solve everything before launch and gives you permission to evolve.

💡 Practical tip: build the inventory with screenshots side by side, grouped by element type. Seeing twelve different buttons on one screen convinces stakeholders faster than any argument.

2. Foundations first, components second

A component without foundations is just a reusable drawing. What makes a component part of a system is that it consumes decisions made somewhere else: color, typography, spacing, radius, shadow.

That's why the order that worked for me was:

  • Primitives from the brand guidelines. I took the main colors from the company's brand manual and expanded each one into a scale from 100 to 900. In most cases, 500 is the base value, matching the official brand color.
  • Semantic tokens built on the primitives. On top of that scale I created tokens with meaning: background, text, stroke and so on. Each one comes with its default, hover and pressed states already defined.
  • Components that only consume semantic tokens, never raw values.

Defining states at the token level, not the component level, was the decision that sped up the work the most later on. Whoever designs a new interface doesn't have to pick which shade to use on hover: the answer is already in the system.

The same logic applied to grids, spacing and typography, split between desktop and mobile. In Figma, I organized them into variable modes, so that switching a frame's mode automatically adjusts text sizes, spacing and grid to the standard we defined. The rule I started following is simple: if a component has a hand-typed value, it's wrong.

The payoff comes later. When a color changes, it changes in one place. And when you talk to the developer, you both speak the same language: “use the background-base-hover token” instead of “use that light gray.”

3. Organization: the new has to live alongside the old

No design system is born in a vacuum. While you're building it, the team keeps shipping screens with the old components. If the new file simply replaces the old one, you break everyone's work.

The solution I adopted was to keep both side by side, with an explicit label in the name:

  • (new): design system components, linked to the foundations, to be used in new projects.
  • (old): legacy components, kept for those who haven't migrated yet.

It sounds simple, but it solves three problems: nobody loses what they already use, the recommended path is obvious, and migration becomes visible and measurable.

The team responded well. At times, though, the eagerness to switch components and variables to the new ones was so strong that it caused friction with developers of products that hadn't been migrated yet. The result was rework to go back to the (old) components until the migration to the new system was approved.

The lesson: keeping both in the file isn't enough. You need to make clear which products can already use the new one. To do that, I kept talking with the teams and aligning regularly with management, which let us prioritize adoption and gave me room to handle knowledge transfer one on one.

Other organization rules that paid off:

  • One section per maturity stage, not just per component type. What's ready is kept apart from what's still in progress.
  • Names the developer recognizes. If the component is called Modal Dialog in code, it's called that in Figma too. Every name should be identical.
  • Properties instead of endless variants. Boolean and text properties reduce the number of variants and keep the designer's panel cleaner.
  • A cover page with instructions. The first contact with the file should say what to use and what to ignore.

In practice, this also meant leveraging Figma's slot functionality so designers could nest different components within cards while keeping spacing, corners and colors consistent across the Design System.

4. Documentation people actually use

Design system documentation usually dies from excess, not from lack. Long, beautiful pages that nobody opens. What I learned is that each component needs to answer a few questions, always in the same order.

The “when not to use it” row is the most valuable and the most often forgotten. It's what prevents a modal being used as a page or a tag being used as a button.

Two decisions that saved me time:

  • Two levels of documentation. In Figma, next to each component, lives the essentials for whoever is designing. In zeroheight lives the full documentation, the official reference for designers, developers and other teams. Anyone with a quick question doesn't have to leave Figma. Anyone who needs to understand the system has one place to look.
  • Write with the product in mind. Generic examples (“use for primary actions”) give little context. Product examples (“use to confirm submitting a request”) show how to use it for real.

5. Handoff is a partnership, not a delivery

My biggest handoff lesson was to stop thinking of it as a moment. Good handoff is an ongoing conversation with whoever is going to code. In my case, I worked with a very experienced developer from the start, and that changed the project. OutSystems had limitations, but we managed to work around all of them, because they came up in conversation while the component was still being designed.

What worked:

  • Involve the developer before the component is finished. A 15-minute review of the draft prevents a component that's impossible to build on the platform.
  • Agree on naming once. Component, property and token names are the same in Figma and in code.
  • Deadlines per component, not for the whole system. Shipping in batches gets the design system into use sooner and brings real feedback.
  • Specify states, not just the default look. Focus, error, loading and empty states are where rework lives.

A simple checklist I use before calling a component ready for development:

  • Uses only semantic tokens
  • All states designed
  • Name matches the code
  • Responsive behavior described
  • Accessibility criteria noted
  • Reviewed with the developer

6. Where AI came in (and where it didn't)

I used AI, mainly Claude, as a working partner for the repetitive parts and for the moments when I needed a second pair of eyes. The design decisions stayed mine. What changed was the time spent on everything around them.

One AI to write the request, another to carry it out. I used ChatGPT to structure the prompts I then took to Claude. Separating “thinking about the request” from “executing the request” made the answers much more precise, especially for long tasks full of rules.

Building and documenting tokens. This is where Claude helped me the most. Tokens are work that demands a lot of consistency and little creativity: naming, organizing into collections, describing when to use each one. With a well-structured prompt, it proposed the structure and the copy, and I reviewed and adjusted.

Testing components on screen. I used Figma Make, Google's Stitch and Claude, connected to Figma through MCP, to build screens with the components I had just made. It's a stress test: when a screen calls for something the system doesn't have, or a component behaves badly outside the context it was designed for, the problem shows up before it reaches the team.

Writing the documentation in zeroheight. Claude also helped me put together the documentation pages, following the fixed structure from the previous section. Getting past the blank page stopped being the bottleneck.

What I learned about using AI in this context:

  • Context is everything. Instructions like “use only the (new) components, ignore the (old) ones” completely change the result. The more of your design system's rules you spell out, the better the answer.
  • Use it to read and draft, not to decide. AI is great at gathering, organizing and proposing. You're the one who knows the user, the product and the technical constraints.
  • Review everything. Generated values, names and specs need to be checked against the file. A wrong token in the documentation is worse than none.
  • Be careful with sensitive data. Check what your company allows you to share with AI tools before connecting internal files.

7. What I'd do differently

Looking back, I'd change two things. Neither is about components.

Use AI even more, and from the start. I brought AI into the process gradually, as I discovered where it helped. If I were starting today, I'd use it from the inventory all the way to the documentation, instead of saving it for the most repetitive steps, and I'd test everything it can help with faster and more thoroughly. At the same time, all that exploration was a huge learning experience. In a setting where I couldn't dedicate myself fully to it, I believe the pace was the best it could be.

💡 Don't blame yourself for not knowing everything. Research, take notes, understand and put it into practice: it's the best way to keep up with changes as fast as the ones happening in AI.

Communicate beyond designers. I kept the other designers updated on every new release, but talked less with stakeholders and managers. They're the audience that decides whether the design system keeps getting time and priority. Today I'd share every improvement with them too, in a short, clear and regular way.

A design system is work that happens behind the scenes. If nobody sees what's being done, it easily loses ground to more urgent demands. Showing your work clearly and objectively isn't vanity: it's what keeps it going.

Wrapping up

A design system isn't a file of components. It's an agreement between people about how to build product, and that agreement only holds if it's easy to find, easy to understand and easy to implement.

If I had to sum it up for someone starting out: start with the inventory, not the button. Treat the developer as a co-author, not a recipient. Use AI to clear the repetitive work out of the way, so there's time left for the decisions only you can make. And show what you're doing beyond the design team.

If you'd like the prompts I used to build and document tokens and components, reach out and let's talk. :)

Originally published on Medium: medium.com/@vitoriaasimon