Engineering the Frontend Platform behind the CUPRA Design System

Photo by Raphaël Biscaldi on Unsplash

Design Systems are often discussed in terms of visuals, components, and guidelines. Less attention is usually paid to the frontend infrastructure that turns those definitions into something teams can actually build with, maintain, and evolve over time.

This article focuses on that layer: the frontend platform that materializes design intent into production-ready components and allows it to exist consistently across applications, teams, and brands. Not the Design System itself, but the system that makes it real in code.

Source: Cupra Diagonal Design System

How It Started

This work began as part of a new product initiative.

We were building a long-lived, public-facing product with direct business impact. From the outset, it was clear that the frontend layer would need to be reliable, reusable, and able to evolve as both the product and its design matured.

We were provided with design assets and a component library intended to serve as the UI foundation. While the visual design was clear and functional, the library’s technical implementation was not production-ready. It lacked the reliability and structural guarantees required for a long-lived, production-critical product, making it necessary to rethink the engineering layer while preserving the original visual intent.

Rather than treating the components as a one-off implementation, we approached the problem with a broader goal in mind: to build a component foundation that could support the immediate product while also being reusable and extensible for other teams and future use cases.

The work started with a small set of widely used, structurally simple components, allowing early validation of architectural decisions before moving on to more complex and interdependent pieces.

Designing for Evolution, Not Just Delivery

The objective was not to redefine the visual language or to replace existing design work. The challenge was technical rather than aesthetic: how to implement that design in a way that would remain stable under change.

The platform needed to handle delivery pressure without becoming brittle. It had to absorb design changes, new requirements, and future extensions without forcing repeated rewrites. From early on, it was also clear that the solution should not be tied too tightly to a single product or a single team.

One of the first real stress tests for the platform was theming. Supporting multiple themes was not simply a matter of swapping colors or typography. One early assumption did not fully hold as the platform evolved: we initially leaned heavily on design tokens as the primary mechanism for theming.

In practice, however, the second theme introduced significantly different structural requirements where token parity could not be guaranteed. Trying to force disparate structures to share the same tokens led to specificity wars and brittle CSS.

This realization forced us to pivot: tokens alone were not sufficient when component structure diverged. We had to enforce a stricter boundary, ensuring that visual variations didn’t leak into the core component logic. This meant treating the separation between structural CSS and theme-specific layers as a hard architectural constraint.

Many of these decisions evolved over time through iteration and adjustment, as the platform matured and real usage revealed which approaches held up and which needed refinement.

Choosing a Foundation That Could Outlive Frameworks

Before this project, I had attended a workshop at React Finland 2022 titled “Web Components — Write Once, Run Anywhere”, led by Matias Huhta, focused on Lit and Web Components and had started a small experimental library as a personal project. That experimentation provided a concrete technical starting point when the need arose.

Web Components offered a way to build UI primitives that were based on web standards, portable across environments, and decoupled from the lifecycle of any specific framework. For a platform expected to live for many years and support multiple products and teams, this was a critical property.

The components themselves were not invented in isolation. They were concrete implementations of existing designs, translated into a reusable frontend layer with evolution in mind from the start.

“They can be considered the standard way to create reusable and interoperable UI components.” — Andrea Chiarelli, Exploring Web Components

From Components to a Platform

Over time, what started as a small set of components evolved into something more structured.

As adoption grew and more teams became involved, the focus shifted from individual implementations toward shared conventions, explicit contracts, and architectural boundaries. This shift proved essential when the visual language evolved later on. Designs changed, tokens were redefined, and component visuals were refined, but the underlying structure remained intact.

This meant that components could evolve visually without forcing changes in how teams consumed them or integrated them into applications.

The same foundation allows new themes and design systems for different brands, such as SEAT, to be layered on top without breaking behavior or structure. What mattered most was no longer how a single component looked in isolation, but how coherence was preserved as the platform evolved.

A High-Level View of the Platform

That evolution resulted in a frontend platform designed to be consumed in different contexts without fragmenting behavior or duplicating logic.

The platform is organized as a single system composed of two complementary public libraries, developed and maintained together. One provides the core component implementation, and the other focuses on framework integration. This separation makes it possible to serve different teams and technical stacks while keeping a single source of truth for behavior and design contracts.

Source: @cupra/ui-kit and @cupra/ui-react

At the core sits a framework-agnostic component library built with Web Components, using Lit and TypeScript. This layer contains the actual components: their structure, behavior, styling boundaries, and theming capabilities. Because it is based on web standards, it can be consumed directly from plain HTML or integrated into any modern frontend stack.

This separation was not only a matter of cleanliness, but of adoption. While the core was intentionally framework-agnostic, most teams worked day to day in React. Expecting each team to solve the integration details independently would have introduced friction, inconsistency, and subtle bugs over time.

Providing a dedicated React integration layer allowed teams to work with familiar patterns and tooling, while keeping all behavior, structure, and design contracts centralized in a single core implementation.

With the structural foundation secured in the core and accessible via React, the next challenge was orchestrating the visual layer across different brands.

A key part of the platform is the theme provider. Applications select a theme declaratively, and the provider applies the corresponding styles, tokens, and assets. This makes it possible to support multiple brands and visual identities using the same components, without changing public APIs or duplicating implementation.

Source: @cupra/ui-kit and @cupra/ui-react

Component documentation and exploration are handled through Storybook, where components are presented as interactive examples. This allows teams to explore variants, states, and behaviors in isolation, and serves both as developer documentation and as a validation tool to ensure consistency as the system evolves.

Accessibility, performance, and developer experience were treated as architectural constraints rather than optional enhancements. This focus became increasingly critical as regulatory requirements evolved during the project’s lifetime, requiring us to adapt continuously.

Components were designed to support proper semantics and keyboard interaction from day one. To ensure compliance, accessibility was continuously validated through a combination of manual audits, Lighthouse checks, and automated tooling integrated into Storybook.

SEO also presented a specific technical challenge. Since not all consuming applications used Server-Side Rendering (SSR), we implemented content projection patterns (slots). This allowed components to enhance existing markup instead of replacing it, ensuring that core content remained meaningful and discoverable regardless of the tech stack.

Together, these elements form a component platform that is portable, extensible, and designed for long-term evolution.

Conclusions

Working on this platform clarified, for me, what a Design System represents in practice.

A Design System is not just a collection of components or a set of visual guidelines. It is a shared reference that defines how products look, behave, and evolve over time. It helps teams align by turning design decisions into something concrete, reusable, and reliable.

The component platform is not the Design System itself, but it is one of its most tangible and operational expressions. It is where design decisions become executable and testable, and where visual rules and interaction patterns turn into software teams can actually build with.

From this experience, one conclusion stands out: Design Systems only work when they are treated as long-term infrastructure. That requires deliberate architectural choices, an acceptance of constraints, and a commitment to consistency over short-term convenience.

The real achievement is not any individual component or technical decision. It is the platform that allows many components, and many teams, to move in the same direction over time.

Looking back, the hardest part was not building components, but deciding what the platform should refuse to support in order to stay coherent over time.

Resources

@cupra/ui-kit (Web Components)

https://www.npmjs.com/package/@cupra/ui-kit

https://diagonal.cupra.com/ui-kit/index.html

@cupra/ui-react (React wrappers)

https://www.npmjs.com/package/@cupra/ui-react

https://diagonal.cupra.com/ui-react/index.html