Enterprise Design System

02 / Architecture & The Fix

A four-layer structure, not a flat component library.

The system runs on four layers, each with a distinct job, and each publishing into the next:

• Core holds the raw building blocks, spacing tokens, typography, elevation, and base components. Nothing here is used directly in a product screen, it exists so everything built on top of it inherits the same foundation
• Library is where usable components live, buttons, inputs, modals, and shared UI primitives, built from Core and carrying every state a component needs (default, hover, focus, disabled, error)
• Feature-Based is where Library components get combined or customized for a specific product need, a component with a particular state, or several Library pieces assembled into one feature-level pattern
• Sandbox is the final design file, where actual product screens and panels get built using everything the three layers below it provide

A change at the Core level doesn’t update every screen by itself, someone still has to go into Library and Feature-Based and apply it where it’s used. What the four-layer structure actually buys is scope, not magic. A spacing token or color value changes in exactly one place, and from there it’s a known, traceable update through two more layers, not a guessing game across forty scattered instances of the same button with no idea which ones are current. The system doesn’t remove the work of updating. It removes the work of figuring out what needs updating and finding every place it lives.

What happens when a new side project enters the picture.

The four-layer structure isn’t locked to one way of extending. A new project can pull from the existing Library and spin up its own file on top of it, inheriting the foundation without touching the original system, or it can hook directly into the same Variables and update the shared file in place. Which path makes sense depends on the project and the organization: a one-off experiment that shouldn’t risk the core system takes the first route, a project that’s meant to grow into the same product family takes the second. The structure doesn’t force one answer, it leaves the decision open to whoever’s extending it.

The whole system, in one picture.

Three token categories at the top (color, spacing, typography) feed into Core, which then publishes downward through Library, Feature-Based, and Sandbox. Nothing below Core touches a raw value, every layer inherits from the one above it.

Built on atomic design principles, adapted to how the team actually worked.

The structure borrows from atomic design (atoms, molecules, organisms, templates, pages) but isn’t a rigid copy of it. The four-file system is the practical translation of that thinking into something a two-person design team and an external frontend team could both navigate without needing a design theory background to use it correctly.

What’s inside each layer, concretely.

• Core holds spacing tokens, typography styles, elevation values, and base (unstyled) components, the raw material everything else is built from
• Library holds the full set of usable UI primitives, buttons, inputs, modals, and shared patterns, plus the color and spacing definitions applied to them
• Feature-Based holds product-level modules and custom variants, Library components combined or adjusted for a specific feature’s needs
• Sandbox holds the actual product pages and designed experiences, the space where everything from the three layers below gets tested, iterated, and validated before anything merges into the main system

What building one component through all four layers actually looked like.

In Library, that skeleton gets pulled in and multiplied across every dimension the product actually needs:

• Style: Contained, plus Primary / Secondary / Inherit variants
• Size: Large, Medium, Small
• Color intent: Primary, Secondary, Error, Warning, Success
• State: Enabled, Hovered, Focused, Disabled, Loading

Laid out as a grid, that’s dozens of distinct combinations, all generated from the same Core skeleton, all guaranteed to share identical spacing, type, and icon alignment because they’re built from one source, not redrawn per variant. Color never touches a raw hex value here either, the Loading state’s spinner, for instance, is filled with action/primary/text, not a picked purple, so if that token’s underlying value shifts, every loading spinner across every button variant shifts with it without anyone touching this file directly.

Color tokens, never used raw.

Base color values (a full palette, shade 50 through 900, across purple, orange, grey, and more) exist in one layer and are never referenced directly in a design. On top of that sits a semantic naming layer, tokens named for what they do, not what they look like: action/primary/state/hovered, action/error/main, surface/secondary, text/headline/darker. A designer placing a button never picks a shade of purple, they pick “primary button, hover state,” and the system resolves what that means.

That same semantic layer is what makes light and dark mode a non-event instead of a parallel design effort. Each token resolves to a different base value depending on mode, action/primary/main is purple/700 in light mode and purple/200 in dark mode, but the design using the token never changes. Switching mode is a variable swap, not a redesign.

Bilingual by construction, not by patching.

Most components handled Persian and English without extra work, since the token and spacing system was language-agnostic by design. The real friction showed up in components where content length is baked into the layout. Text fields with floating labels, for instance, where the label’s position and the surrounding spacing had to be calculated differently depending on whether the label text was a short English word or a longer Persian phrase, RTL and LTR behaving differently enough that the same component needed distinct handling for each language rather than a simple mirror.

What that actually looks like, side by side.

The same sign-in component, Persian and English, light and dark, all four combinations built from the identical underlying structure. Nothing here is four separate designs, it’s one component resolving four different conditions through the token and layout system described above.

One component, every screen size.

Responsive behavior was built into each component itself rather than maintained as separate mobile and desktop versions. A single button, card, or input adapts its sizing and layout logic across breakpoints, so a design change at the component level holds across the full device range instead of needing to be repeated per layout.

Naming conventions aligned with engineering, not decided in isolation.

Component and property names were set collaboratively with the frontend team early on, in a working session, then maintained consistently from there. Once engineering saw the naming held up and made their implementation faster, they followed the convention without needing to be asked twice, which meant handoff stopped being a translation step between design language and code language, it was the same language.

Error handling and system feedback as first-class components, not an afterthought.

Error states, validation feedback, and system messaging were designed as part of the core component set from the start, not bolted onto individual screens as problems came up. Every input, form, and action carried a defined feedback pattern it could fall back to.

Design and UX principles applied as process, not as a slogan.

A working checklist guided every component through a consistent set of checks before it was considered done, covering things like contrast and legibility, touch target sizing for interactive elements, consistent spacing against the base grid, and state coverage (default, hover, focus, disabled, error) for anything interactive. The point wasn’t a single audit at the end, it was a standard every component had to clear before it entered the Library layer, so nothing inconsistent made it downstream into Feature-Based or Sandbox.

What the Variables setup actually looked like underneath.

Beyond the visible component structure, the system ran on a layered Variables setup in Figma itself, Layout Spacing and the full color Palette defined once at the Core level, then separately referenced inside the component Library rather than redefined there. A component in Library doesn’t carry its own copy of a spacing or color value, it points back to the same shared variable Core already defined, alongside typography set by family, size, and typeface as their own linked variable groups. That’s what made the propagation described earlier actually hold up in practice, the dependency isn’t a convention designers agreed to follow, it’s wired into the file structure itself.

Documentation lived inside the components, not in a separate guide.

Rather than maintaining a standalone documentation site that could drift out of sync with the actual files, every component carried its own short usage note directly in the layer structure, what it is, when to use it, right next to the component itself. A designer opening the Button layer sees its description before they even open the variant panel. That kept the documentation from going stale the way a separate wiki tends to, it lived exactly where it would be read, updated in the same breath as the component it described.

How a change actually got approved before it touched the system.

Nothing got added on instinct. A proposed change started with root-cause work, making sure the actual problem was understood before touching anything, then moved through research and alignment across design and the relevant teams. Only after that did a new design get built, tested on a limited part of the product first, and reviewed against real feedback. If it held up, it rolled out to the full system and went to engineering for implementation. A four-step gate (diagnose, design, pilot, roll out) stood between “this would be nice” and “this is now part of the system,” which is what kept the library from accumulating one-off exceptions no one remembered approving.

The icon system, at a scale most component libraries never reach.

Over 40,000 distinct icons, including regional flag variants, lived inside the system. Every icon shared the same base size, but the surrounding structure was built so each one resized automatically to fit whatever card, button, or container it landed in, rather than needing a manually resized version per context. At that volume, manual resizing per instance wasn’t a realistic option, the system had to handle it structurally or the icon set would have been unmanageable within weeks.

03 / Impact & Outcome

What the numbers actually show.

• 100+ components across Core, Library, and Feature-Based, plus a full icon set, organized across 4 structured files
• One token system covering two languages, two color modes, and the full responsive range, with zero component duplication per condition
• Roughly 3 months to a working v1, then continuous growth alongside the product for close to a year
• Adopted beyond the core two-person design team, by frontend engineers and outside designers who referenced or built on its conventions

Where this sits against the industry.

What consistency at this scale actually bought the team.

The clearest signal wasn’t a metric, it was behavior. Designers and frontend engineers outside the core team started adopting the system’s conventions without being told to. People who worked alongside the project independently described it as the most cleanly systemized design work they’d seen on a team that size, unprompted, not solicited as a testimonial. That’s a harder thing to earn than a usage number, because it only happens when a system actually removes friction instead of adding process for its own sake.

What it meant to own a system at this scale.

Most teams running a system at this scope have a dedicated design-ops function, sometimes a full team, just to keep tokens, documentation, and governance from drifting. Here, it was built and maintained inside a two-person design team, alongside actual product design work, not instead of it. Hanie Mansour Kiai joined partway through and carried changes forward alongside me from then on, which is part of why the system held up past the point where one person’s attention would have started to crack under it. A system loose enough to need constant babysitting doesn’t survive being run by two people on the side of their actual design work. This one had to be tight enough to mostly run itself, which is exactly what the four-layer propagation and the semantic token layer were for.

What this project actually proved.

That a two-person design team can build and maintain a system robust enough for a full product, two languages, two color modes, and a growing frontend team, without it ever needing a dedicated design-ops hire to hold it together. The system is still in active use. Some of the people who built alongside it moved to other teams or, in my case, left the company; the system didn’t. That’s the actual test of whether a design system was built right: whether it keeps working once the person who built it is no longer in the room.