Shade UI Case Study

Developer Tools, Design Systems | 2024 | Product Designer, Developer

Overview

Design systems rarely become inconsistent overnight. Components evolve independently in Figma and code until neither reflects the other with complete confidence. Designers begin guessing what's implemented, developers make small adjustments in code, and over time the system loses its reliability.

Shade UI was built around a simple constraint: if a component exists in Figma, it exists in code in the same form. That principle shaped everything from component architecture and naming conventions to documentation and theming.

Built in collaboration with Tunde Adekoya, I led the design system architecture, the full component library, Storybook documentation, and the Shade UI website. We worked closely throughout the project, but I was responsible for ensuring the system remained coherent as it expanded — from individual components to templates developers could install from the CLI.

Problem

Most design systems fail quietly. They don't break all at once — they drift. A component updates in code, the Figma library lags behind, and suddenly designers are guessing again. For designers learning to code, this erodes confidence. For teams moving fast, it introduces rework and friction. Working at the intersection of design and development, my collaborator and I had experienced this repeatedly. Instead of solving it with process ("remember to update Figma"), we asked whether the system itself could enforce consistency.

Constraints

From the beginning, we treated parity between Figma and code as a product requirement rather than a maintenance task.

That meant every component had to work equally well in both environments. Visual variants that couldn't be represented cleanly in code were redesigned, and implementation patterns that couldn't be reflected accurately in Figma weren't introduced. Instead of maintaining separate versions of the same component, tokens became the mechanism for theming while the underlying component model remained consistent.

Documentation became part of the system rather than something produced afterwards. Components, naming, usage guidance, and implementation patterns were designed together so designers and developers could work from the same source of truth.

Role and collaboration

I owned the design system architecture from the design side, with a focus on how design decisions translate into production constraints.

My responsibilities included:

• Defining component structure, states, and variants across the full library in Figma • Ensuring Storybook documentation matched Figma — shipping 200+ production-ready components • Establishing design tokens aligned with implementation realities • Building data visualisation components (line charts, bar charts, and more) • Introducing CLI templates (`npx @shadeui/ui add dashboard-01`) and AI deeplinking for Cursor, Claude, DeepSeek, and Kimi • Creating documentation to explain not just what components exist, but how they're intended to be used • Designing and building the Shade UI website

I worked closely with a designer-developer partner responsible for implementation and npm distribution. Decisions were made collaboratively, but I was accountable for design consistency and system coherence.

System view

One of the biggest decisions we made was slowing down.

Early in development, our button component had accumulated more visual variations than could be represented cleanly through a consistent prop model. We could have continued building new components, but every new addition would have inherited the same inconsistency.

Instead, we paused work on the library and redesigned the variant model first. That decision delayed visible progress, but it established patterns that every component could follow afterwards. It also made later components significantly easier to design, implement, and maintain because the underlying architecture had already been resolved.

The same thinking influenced our first release. Although more than one hundred components had already been designed, we shipped only a small set of production-ready components to validate the architecture, documentation, and developer experience before expanding the library further.

Once that foundation held, I worked across the entire component library — designing in Figma, documenting in Storybook, and shipping over 200 production-ready components. Each one followed the same pipeline, from design through documentation to npm. Alert was a useful test case: status, variant, optional actions, and dismiss behaviour all had to work the same way everywhere. We extended that same approach to data visualisation, adding line charts, bar charts, and other chart types so teams could build dashboards without reaching for a separate library.

Key decisions

Once people outside our workflow started using Shade UI, the gaps became obvious. [Univelcity](https://univelcity.com/) adopted it into their curriculum, giving us a view of how designers and developers used the library on real projects rather than internal examples. Students consistently built marketing sites rather than dashboards, exposing gaps in [marketing components](https://www.figma.com/community/file/1526330056211572612) — hero sections, feature grids, testimonials — we hadn't prioritised during development. That feedback shaped the roadmap and helped us expand the system without introducing parallel patterns or unnecessary complexity.

Customer conversations surfaced a similar pattern. Many designers discovered Shade UI through developer colleagues rather than finding it themselves, and several joined our beta programme to test components before release. Designers wanted confidence that what they specified in Figma would ship as built; developers wanted the same confidence in reverse.

To shorten the path from discovery to implementation, we introduced CLI templates — for example, [npx @shadeui/ui add dashboard-01](https://www.shadeui.dev/?path=/docs/guides-templates--docs) — so developers could scaffold full pages rather than assembling every component by hand. We also added AI deeplinking for Cursor, Claude, DeepSeek, and Kimi, and began rolling out a dedicated set of components for building AI products, expanding the library week by week.

Goals

Deterministic parity - Every Figma component maps 1:1 to a production component. No approximations.
Designer-first usability - Designers should understand how components work without needing deep framework knowledge.
Scalability - The system should support future theming, dark mode, and token overrides without re-architecting core components.

Challenges

The first real failure surfaced with buttons. Visually, it was easy to create multiple button styles in Figma. In code, those same variants needed to be expressed as a small, composable set of props. Our initial approach allowed too many visual permutations, which broke when translated to code. Rather than patching the symptoms, I paused new component design and revisited the underlying model.
[object Object]
[object Object]
Shade UI was our first public npm package, which introduced unfamiliar problems beyond design: • Versioning and distribution • Documentation clarity • Storybook configuration • Maintaining trust as the system evolved When we hit blockers we couldn't resolve internally, we reached out to peers with more experience. This reinforced an important lesson: shipping a system is as much about collaboration and humility as it is about technical skill.

Solution

To move beyond internal assumptions, we partnered with Univelcity and gave early access to students learning design systems and front-end development. These users weren't building internal dashboards — they were building landing pages and marketing sites. That insight exposed a blind spot in our roadmap. The system was functionally solid but incomplete for real-world product building.
[object Object]
[object Object]
While over 100 components were designed, we intentionally shipped a small beta: • Button • Input • Badge • Banner • TextArea Shipping fewer components allowed us to validate the architecture without committing to a large, unstable surface area. Despite the limited scope, early adoption validated the core premise.
[object Object]
[object Object]

Impact

Shade UI has been adopted by more than 5k users through its Figma library and npm package, with weekly downloads for @shadeui/ui growing 46x as the component library expanded. It has also been incorporated into Univelcity's curriculum.
46 x Growth in weekly npm downloads for @shadeui/ui
5k + Users building with Shade UI across the Figma library and npm package
200 + Production-ready components in Storybook, matched to Figma
1 Leading training school (Univelcity) adopted Shade UI into their curriculum

Reflection

Working as both designer and developer on this project evolved my approach to design. Because we were working across multiple components, including APIs, variants, naming, documentation, and accessibility, those constraints shaped decisions from the start. Accessibility and parity were also a focal point; when they broke, we paused work until the constraints were fixed. This improved my thinking around systems and implementation.