Avila Design System
A production-grade design-to-code pipeline. Token architecture, component library, dark mode theming, and documentation. Built solo to prove the thinking before selling it to a team.
Project Details
Avila isn't just a project name — it's a tribute. A nod to Hispanic heritage, to the culture, the color, the craft that's always been part of who I am. Building something and naming it after that lineage felt like a small act of honoring where I come from.
But the reason it exists goes beyond the name. Most design systems get built after the pain is already visible — after the inconsistency, after the drift, after the team is already frustrated. I wanted to build one where the connection between design and code was the foundation from the start. Not a patch. An architecture.
Avila DS is that architecture. And building it solo was the point — because you can't sell a system to a team until you've proven it to yourself.
Role: Staff Design Systems Engineer — Solo Build
Platform: Figma, Storybook, Vercel
Industry: Design Systems / UI Engineering
Scope: Design Token Pipeline · Component Library · Dark Mode Theming · Documentation Site
The Name
Avila isn't a project name. It's a tribute, to Hispanic heritage, to the culture and color and craft that's always been part of who I am. Naming something you built from scratch after that lineage is a small act of honoring where you come from.
It also sets the stakes. This isn't a throwaway experiment. It's a system with a point of view, named after something that matters.
The Problem
Design systems fail for one reason before they fail for any other: design and code don't share a source of truth.
A designer names a color Ink 100 in Figma. A developer hardcodes #1a1208 in a stylesheet. Those two things represent the same decision. Nothing connects them. Every time something changes, someone has to manually sync the gap — and eventually, someone doesn't.
That gap shows up as components that look right in Figma and drift in production. It shows up as a team moving fast but never quite in sync. It shows up as the quiet accumulation of small inconsistencies that erode trust in the system itself.
Most design systems try to patch this after it's already painful. I wanted to build one where the connection was the foundation. Not a handoff. A pipeline.
What I Built
The Avila Design System is a fully connected design-to-code pipeline. Tokens defined once in Figma flow through as structured data, transform into CSS variables, and land directly in components. Change a value in Figma — it propagates. No copy-paste. No guessing. No drift.
The token layer
Every color, spacing value, and typography decision lives as a named token. A button's background isn't #e8195a — it's --avila-color-action-primary. That distinction is the whole point. Hardcoded values are implementation details. Named tokens are design decisions. Only one of those two things can be referenced, audited, and changed in one place.
The component library
Components live in Storybook. Every one has live rendered examples, usage guidelines, and the actual code — not a static mockup. Developers can inspect a component in isolation, copy the implementation, and trust that what they see is what ships.
Dark mode
Full dark mode support, built as a proper semantic token layer — not a color inversion. Each token carries meaning in both contexts. --avila-color-surface-primary isn't just a hex value; it's a named role that resolves correctly whether the system is in light or dark. Switching themes doesn't just change colors. It switches intent.
This took longer than expected. It was worth it. Getting the semantic layer right from the start means you're not patching theme logic across every component forever.
Documentation site
A dedicated site alongside Storybook — the public face of the system. The place anyone on a team could land and immediately understand what Avila DS is, what it includes, and how to use it. Systems without documentation aren't systems. They're libraries waiting to be misused.
Key Architecture Decisions
The thinking behind the system, not just the output.
Token naming as contract
Every token in Avila DS has a semantic name, not a raw value. A button's background isn't #e8195a — it's --avila-color-action-primary. That distinction isn't cosmetic. The name is the contract between design and engineering. When a value changes, the contract stays intact. When a team scales, the vocabulary stays shared. Raw values create drift. Named tokens create alignment.
Semantic layer over raw values for dark mode.
Dark mode done wrong is a color inversion. Dark mode done right is a meaning swap. I built a semantic token layer from the start — each token carries intent in both light and dark contexts, not just a different hex. That means switching themes is a configuration, not a rebuild. Get the structure right once and theming becomes a solved problem instead of a recurring one.
Storybook as the proof, not Figma.
Figma is where decisions get made. Storybook is where they get proven. If a component doesn't run in Storybook it doesn't exist — it's a sketch. Every component in Avila DS has live rendered examples, usage guidelines, and the actual code behind it. Nothing is a static mockup. This distinction matters because the gap between "designed" and "shipped" is where most systems quietly fall apart.
In Closing
This project started as a personal challenge and became the clearest proof of how I think about systems work.
Not because it's perfect — it isn't. But because every decision in it was made deliberately, documented honestly, and shipped into production. The token naming conventions, the semantic dark mode layer, the Storybook-first documentation approach — none of those were obvious choices. They were architectural bets made early that paid off later.
That's what design system work actually is. Not a component library. Not a Figma file. A set of decisions that either scale or don't — and you find out which one when a team starts building on top of them.
Avila DS isn't a portfolio piece. It's the infrastructure I use to build everything else. That's the difference between a design system and a component library — one is a deliverable, the other is a decision.