Too many one-off patterns
Similar interactions were being solved differently across screens, which created extra review time and avoidable design debate.
Portfolio Case Study · Design Systems
Building design systems from messy product reality.
This page shows how I organize foundations, elements, components, variants, documentation, and handoff rules so product teams can stop rebuilding the same UI decisions from scratch.
The Problem
The product looked consistent at a glance, but the system underneath was not.
When I audited the screens, I found multiple versions of the same buttons, forms, cards, alerts, and spacing rules. Some differences were intentional, but many came from one-off decisions made during fast delivery cycles. That made the UI harder to maintain and harder for engineering to translate cleanly.
Unclear component ownership
Teams were not always sure what was reusable, what was local to a feature, and what needed to become part of the system.
Handoff needed more detail
States, behavior, accessibility notes, and responsive rules were not always documented in a way developers could use.
The main design decision was to treat the system like a product, not a folder of components.That meant defining rules, usage, edge cases, and adoption paths, not just building clean Figma assets.
Audit & Inventory
I started by finding the repeated decisions hiding across screens.
Before building anything new, I grouped what already existed. The goal was to separate real product needs from accidental inconsistency. That gave the team a practical backlog for what needed to be standardized first.
- Buttons and actionsPrimary, secondary, destructive, disabled, loading, icon placement, mobile tap targets.
- Forms and inputsLabels, helper text, validation, error states, required fields, stacked mobile behavior.
- Cards and containersContent density, elevation, borders, section headers, empty states, layout rules.
- Alerts and status messagesSuccess, warning, error, info, dismiss behavior, priority, accessibility messaging.
- Spacing and layoutGrid rules, responsive padding, content width, section rhythm, card spacing.
- Content patternsCTA wording, field instructions, error tone, confirmation copy, progressive guidance.
System Structure
How I organized the design system.
I broke the system into layers so every design decision had a place. Foundations controlled the visual language. Elements handled small building blocks. Components handled reusable product patterns. Variants handled states and options. Examples showed how everything worked in real screens.
Design system structureFrom raw tokens to real product usage
Foundations
Design tokens and base rulesColorSpacing
481624
Elements
Small reusable piecesButton baseInput baseIconsSearch · Alert · Check · More
Components
Reusable product patterns
Variants
States, sizes, intent
Examples
Patterns in contextForm pattern
Components
Each component needed anatomy, rules, and a reason to exist.
I avoided turning every visual variation into a new component. Instead, I documented what each component was responsible for, what parts were optional, and when a team should use an existing pattern instead of inventing a new one.
Component anatomy
Named required and optional parts such as label, helper text, icon, action area, status message, container, and supporting content.
State coverage
Defined default, hover, focus, pressed, disabled, loading, error, success, empty, and read-only states so edge cases were not left to interpretation.
Responsive behavior
Documented how components stack, resize, truncate, wrap, or collapse across desktop, tablet, and mobile breakpoints.
Variants
Variant logic had to match real product decisions.
I did not create variants just to show options. Each variant needed a reason: hierarchy, state, destructive action, loading, size, responsive behavior, or accessibility. This helped reduce component bloat and made the library easier to maintain.
| Variant | Use it when | Example |
|---|---|---|
| Primary | The action moves the user forward or completes the main task. Rule: one primary action per decision area. | |
| Secondary | The action supports the main path but should not compete visually. Rule: pair with primary when there is a clear hierarchy. | |
| Destructive | The action removes, cancels, or creates risk. Rule: pair with confirmation when the action cannot be easily reversed. | |
| Disabled | The action is unavailable because a requirement has not been met. Rule: explain what the user needs to do when possible. |
Documentation & Handoff
The system needed to answer the questions people ask during real work.
For each component, I documented when to use it, when not to use it, anatomy, variants, states, accessibility expectations, responsive behavior, content rules, and development notes. That made the system easier to adopt because people did not have to guess.
Usage rulesAnatomyStatesAccessibilityResponsive behaviorEngineering notesFigma variablesAuto layout rules
Impact
What changed after the system was in place.
The strongest impact was alignment. Designers had reusable patterns. Engineers had clearer specs. Product teams had a better way to make decisions across screens without creating a new UI every time.
FewerDuplicate components and one-off UI decisions across the product area.
ClearerHandoff between design and engineering, especially around states and behavior.
FasterDesign reviews because teams could point to documented patterns and rules.
A design system only works when it fits how teams actually build products.
The library matters, but the bigger value comes from the decisions behind it: what gets standardized, what stays flexible, how patterns are documented, and how the system keeps improving after launch.