Como construir um sistema de design quando você é uma equipe de três

When you are a team of three handling dozens of client projects simultaneously, inconsistency becomes your most expensive problem. We noticed the same pattern repeating across our website design engagements at GRADAX: a button styled one way on the homepage, another way on the pricing page, and a third way inside the dashboard. Each deviation cost us time in QA, introduced visual bugs, and eroded the polished feel our clients expected. Something had to change.

The decision to invest in a design system was not driven by ambition or trend-chasing. It was driven by pain. We were spending roughly 30% of every new project recreating components that already existed in some form elsewhere in our codebase. A design system would let us codify our decisions once and reuse them everywhere, turning repetitive work into a competitive advantage.

But the literature on design systems is dominated by stories from companies with dedicated platform teams of twenty or more engineers. We needed a pragmatic approach that a three-person team could build, maintain, and actually use without grinding feature work to a halt. What follows is the framework we landed on after months of iteration.

Every design system tutorial tells you to start with tokens, and for good reason. Design tokens are the atomic values, colors, spacing, typography scales, border radii, that everything else is built from. They are the foundation of any cohesive brand identity, ensuring visual consistency across every touchpoint. We defined ours as CSS custom properties in a single file, mapped to semantic names like --color-primary, --color-muted-foreground, and --radius-lg. This meant any component referencing these tokens would automatically adapt when we changed the underlying values.

The key insight for a small team is to keep the token set ruthlessly small. We started with fewer than forty tokens covering color, spacing, typography, and shadows. Large organizations might need hundreds, but we found that a compact set forced consistency instead of enabling a thousand subtle variations. When a developer reaches for a spacing value and only has eight options, they naturally land on the right one.

We also established a naming convention early, semantic over descriptive. Instead of --blue-600 or --spacing-16, we used --color-primary and --space-md. This decoupled the intent from the implementation and made future redesigns trivial. When a client wanted to shift from blue to violet, we changed six lines in the token file and the entire system updated.

With tokens in place, we turned to components. We adopted shadcn/ui as our foundation, which gave us beautifully crafted, accessible primitives built on Radix UI. Rather than building everything from scratch, we extended these primitives with our token layer and project-specific variants. A Button, for example, inherited shadcn's accessibility and keyboard handling while using our token-driven color palette and spacing.

Our component architecture follows a strict hierarchy. At the bottom sit UI primitives, buttons, inputs, badges, tooltips, that have no business logic and accept styling through props and className merging via the cn() utility. Above them sit composed components, search bars, data table toolbars, stat cards — that combine multiple primitives into reusable patterns. At the top sit page-level sections that are specific to a single view and colocated next to the page that uses them.

This three-tier model prevents the two most common design system failures: components that are too abstract to be useful and components that are too specific to be reusable. When a developer needs to build a new feature, they assemble it from the middle tier. When the middle tier does not have what they need, they compose it from primitives and, if it proves reusable, promote it.

Documentation is where most small-team design systems go to die. The team builds beautiful components but never writes down how to use them, so new contributors (or the original authors three months later) reinvent patterns that already exist. We solved this by making documentation a byproduct of development, not a separate task.

Every component file includes a JSDoc block describing its purpose, its props interface, and a usage example. We also maintain a living Storybook instance where each component is rendered in isolation with its variants. The critical rule is that no pull request merges without the corresponding story. This sounds strict, but it takes less than five minutes per component and saves hours of future confusion.

We also keep a lightweight decision log, a simple markdown file that records why we made specific choices. Why did we pick 0.5rem as the base radius? Why does our primary color use oklch instead of hex? These notes are invaluable when revisiting decisions six months later, and they help onboard freelancers or contractors who join temporarily.

Functional tests tell you whether a button fires its onClick handler. Visual regression tests tell you whether it still looks right. For a design system, the latter matters just as much as the former. We integrated Playwright screenshot comparisons into our CI pipeline so that every pull request generates a visual diff of affected components.

The setup was simpler than we expected. Each Storybook story doubles as a visual test case. Our CI job launches a headless browser, captures screenshots of every story, and compares them against committed baselines. If a component's appearance changes, even by a single pixel, the PR is flagged for review. This caught dozens of subtle regressions that would have shipped unnoticed, like a border color changing because someone updated a token without realizing the downstream impact.

We also run visual tests in both light and dark mode. Since our tokens define separate values for each mode, a change that looks fine in light mode can break dark mode entirely. Automated screenshots in both modes eliminated an entire category of bugs that used to reach production.

After six months of use across a dozen client projects, our design system had grown from forty tokens and twelve components to roughly eighty tokens and forty-five components. The question was no longer whether to scale but how to scale without losing the simplicity that made the system valuable in the first place.

We introduced a contribution checklist that every new component must pass before joining the library: it must use only existing tokens, it must be accessible out of the box, it must include at least one Storybook story, and it must work in both light and dark mode. Components that fail any criterion stay in the project-specific codebase until they are hardened. This gatekeeping keeps the shared library trustworthy.

We also started versioning the system with semantic releases. Breaking changes to a token or a component prop surface as major version bumps, so projects pinned to an older version do not break unexpectedly. This was overkill for a team of three at first, but it paid dividends as we began sharing the system with freelance collaborators and dedicated development teams who needed stability guarantees.

The single most important lesson is that a design system does not need to be enormous to be valuable. Our system is small by enterprise standards, but it saves us an estimated ten hours per project in reduced duplication, fewer visual bugs, and faster onboarding. For a three-person team billing by the project, those hours translate directly into profitability.

The second lesson is to optimize for adoption, not completeness. A design system that your team does not use is worse than no design system at all because it creates the illusion of consistency while the codebase diverges underneath. Every decision we made, from choosing shadcn/ui as a foundation to mandating Storybook stories, was aimed at making the system the path of least resistance rather than an extra burden.

Finally, treat your design system as a product with its own roadmap, even if the only users are your own team. Prioritize the components and tokens that will eliminate the most duplication. Track which components are used most frequently and invest in their quality. A design system is never finished, but with the right priorities, even a small team can maintain one that punches well above its weight. If you are considering building a design system for your product and want guidance on where to start, get in touch with our team, we have been through the process and can help you avoid the most common pitfalls.