New screens now take 50% less time to design, and 70% of them are built only from library parts.
Swivl is a field service platform. Office teams run jobs, estimates, invoices and schedules on desktop, and technicians use it on their phones. In June 2025, three of us started building the design system behind every one of those screens: the parts in Figma, the rules in Notion, and the same scales the code uses. This is the story of what we decided, and what it changed.
Swivl is a field service platform. Office teams run jobs, estimates, invoices and schedules on desktop, and technicians use it on their phones. Three of us built the design system behind every screen: the parts in Figma, the rules in Notion, and the same scales the code uses.
50%
Less time to design a new screen
Was about 30 min, now about 15 min
1–2
Design QA issues per feature
Down from double digits
70%
New screens built only from library parts
Up from about 40%
95%
Colours on core components come from tokens
Counted on 12 core component pages
Light
Dark
Impact on our workflow
50%
Less time to design a new screen
1–2
Design QA issues per feature, down from double digits
70%
New screens built only from library parts, up from about 40%
95%
Colours on core components come from tokens
97.7%
Colour bindings on the top tier
93
Components in Storybook on every push
5
Named pop-up sizes, down from about ten
95%
Colours on core components come from tokens
⟨42%⟩
Less time to design a new screen
⟨57%⟩
Fewer design QA issues per feature
⟨85%⟩
New screens built from library parts
95%
Colours on core components come from tokens
⟨42%⟩
less time to design a new screen
⟨57%⟩
fewer design QA issues per feature
⟨85%⟩
of new screens built from library parts
95%
of colours on core components come from tokens
Swivl had grown fast, and nothing was written down. Designers copied hex codes from old frames, and the same job got a different answer depending on who drew it. Then the ask landed: revamp the whole product and ship a run of big new features, on a deadline counted in weeks, not months.
We built the system first, so every part made once would serve the revamp and every feature after it. Colours sit in three layers, so a rebrand or dark mode is one change, and one rule with five named sizes replaced about ten pop-up widths. The revamp took six weeks.
We didn't need more components. We needed decisions: which button, which pop-up, which colour, and why. A design system is a decision system, not a component library.
Feature work couldn't stop while we built the system.
Engineers already built with both.
Every screen had to work on a phone.
Swivl added modules fast: jobs, estimates, invoices, scheduling, inventory and AI features. The design rules didn't keep up. Nothing was written down, so designers copied hex codes from old frames and guessed icon sizes. Six button styles did three jobs, and pop-ups came in about ten widths.
Feature work couldn't stop while we built the system.
Engineers already built with both.
Every screen had to work on a phone.
Swivl had grown fast. Jobs, estimates, invoices, scheduling, inventory, then the AI features, and each module was designed a little differently from the last, because nothing was written down. Designers copied hex codes from old frames and guessed icon sizes. Pop-ups came in about ten widths. The same job got a different answer depending on who drew it.
Then the ask landed: revamp the whole product, ship a run of big new features on top of it, and keep every screen working on a technician's phone, all on a deadline counted in weeks, not months. Three designers. And the feature work already on our plates could not stop.
It felt like a chicken-and-egg problem:
Keep shipping on the old UI, and redraw all of it later?
Or build the new UI first, and let the roadmap wait while we did?
We took a third path. Build the system first, and let it carry both. Every part made once would serve the revamp and every feature after it. The rest of this page is what that took.
Swivl had grown fast. Jobs, estimates, invoices, scheduling, inventory, then the AI features, and each module was designed a little differently from the last, because nothing was written down. Designers copied hex codes from old frames and guessed icon sizes. Pop-ups came in about ten widths. The same job got a different answer depending on who drew it.
Then the ask landed: revamp the whole product, ship a run of big new features on top of it, and keep every screen working on a technician's phone, all on a deadline counted in weeks, not months. Three designers. And the feature work already on our plates could not stop.
It felt like a chicken-and-egg problem:
Keep shipping on the old UI, and redraw all of it later? Or build the new UI first, and let the roadmap wait while we did?
We took a third path. Build the system first, and let it carry both. Every part made once would serve the revamp and every feature after it. The rest of this page is what that took.
Then the ask changed. Swivl wanted a full product revamp, a run of big new features, and every screen working on a technician's phone, all inside ⟨2–3 months⟩. There were three of us to design it, and the feature work already on our plates could not stop.
Do we keep shipping features on the old UI and redesign them later? Or build the new UI first, knowing every feature drawn on the old one would have to be drawn twice?
We took a third path. Build the system first, and let it carry both.
One picture of the whole story before the detail. Read it top to bottom: why we needed a system (modules grew fast, the rules were never written down, and the same job got different answers), the six principles behind every call, the insight that changed how we worked, and then what we built: foundations, components, the pop-up rule, docs and rollout, ending in the result. The band at the bottom is what happened after launch.
One map, the whole story. The two numbered boxes are the decisions everything else hangs on. Decision 1 puts every colour in three tiers, so a rebrand or dark mode is one change instead of a redraw. Decision 2 swaps about ten pop-up widths for one rule and five named sizes. If you read only two things on this page, read those.
The two numbered boxes are the key decisions. Decision 1 puts every colour in three tiers, so a rebrand or dark mode is one change instead of a redraw. Decision 2 replaces about ten pop-up widths with one rule and five named sizes. Most of what follows on this page comes from those two.
1Key decision
73 colours. Screens use only Mode.
The result
50% less time per new screen · 95% of colours come from tokens
Why we needed it
Six principles
Foundations
After launch
1Key decision
Before the system, we listed what already existed in Figma and in code. In our own words at the time, designers "were referring directly to Figma for values without naming or usage guidance", and icon sizes were a guess.
We didn't need more components. We needed decisions: which button, which pop-up, which colour, and why.
A design system is a decision system, not a component library.
With three designers and no time to argue, we needed a way to say no quickly. So before we drew a single component, we agreed on four principles. Every decision on this page traces back to them, and they are the reason two of us, working alone, reach the same answer.
Every decision in the system traces back to Swivl's design principles. They let three people say no quickly, and they're why two designers reach the same answer on their own.
Design for scale,
not for today
Reuse instead
of reinventing
<Button size="icon" />
AI speeds up thinking,
people decide
Use the primary token, not #0E7490
AppliedMake a new component for this
DismissedA short film about the four principles. With three designers and no time to argue, every decision goes through four filters. One request, adding “Assign technician” to the job page, on phones too, drops through them. Scalable reshapes the menu: it scrolls after 8 items and adds search. Familiar and reusable stops a new IconButton component: icon-only is a switch on the Button. Mobile-first turns the menu into a bottom sheet with 44px touch targets. AI-assisted: AI suggests three changes and a designer keeps two and turns one down. Then two designers, working alone, reach the same answer.
Design for scale, not for today
Built for 10× the data: menus scroll after 8 items and add search for long lists.
Reuse instead of reinventing
Built on Tailwind scales and shadcn/ui parts, named the same as the code. A new need becomes a variant, not a new component: icon-only is a switch on the Button.
Reuse instead of reinventing
Built on Tailwind scales and shadcn/ui parts, named the same as the code.
Systems, not one-offs
A new need becomes a variant, not a new component: icon-only is a switch on the Button.
Smallest screen first
Every part has a phone version with 44px touch targets, and menus become bottom sheets.
Ship, then improve
v1 ships when it's useful, and known gaps are written down, not hidden.
AI speeds up thinking, people decide
AI checks and drafts; a designer makes every call. ⟨How you used AI, e.g. scanning the library for gaps⟩
We didn't build what we could borrow. Tailwind gave us spacing, radius and breakpoints, shadcn/ui gave us the components and their names, Lucide the icons, Geist the type. Borrowing meant design and code spoke one language from day one.
We borrowed where it saved time, so design and code share one vocabulary.
We built the tokens, the 73 component pages, the docs and the pop-up rule ourselves. We borrowed where it saved everyone time.
That's the Familiar principle at work: nobody had to learn a second vocabulary.
One system in three layers (foundations, components and patterns) with two homes. Figma shows how things look; Notion explains when and why. Every scale matches the code, and every rule carries its reason.
Swipe sideways to see the whole map.
Screens touch only the top token layer, so a brand or dark-mode change flows down to every component and pattern. Notion sits beside each layer with the reasons, and the code uses the same names and scales.
One of three designers on the system. I owned:
Team. Victoria (Lead Product Designer) ⟨one line on what she led, e.g. set the direction and reviewed every rule⟩. Aashish (Product Designer) designed the mobile card pattern ⟨and anything else he owned⟩. We worked with the Swivl engineering team.
FoundationsKey decision 1
Colour came first, because it was about to bite us twice. The brand had already moved once, from magenta to cyan, and dark mode was coming. We wanted one change to reach every screen. So colours sit in three tiers: Mode (light or dark), Theme (the brand) and TailwindCSS (the raw palette). Designers and screens only ever touch Mode, where each colour is named by its job, primary, card, warning, not by its shade: 73 colours, each with a light and a dark value.
Colours sit in three tiers: Mode (light or dark), Theme (the brand colours) and TailwindCSS (the raw palette). Designers and screens use only Mode. Each colour is named by its job (primary, card, warning), not by its shade: 73 colours, each with a light and a dark value.
WhyThe brand had already moved once, and dark mode was next. One change had to reach every screen.
CostMore setup up front, and designers had to learn which tier to pick.
What it changedA brand or dark-mode change is now a variable switch, not a redraw. 97.7% of colour bindings sit on the top tier.
Built on the shadcn/ui Kit for Figma, which mirrors how shadcn/ui themes its code. The tier names and the rule come from our Color doc in Notion.
The API everyone uses
Brand colours, edited only by the design system team
Raw palette, never used directly
22 Tailwind families + Byzantium and Seablue, 11 steps each
The rule: Always reference Mode. Mode is the only contract that survives a theme shift.
Theme and TailwindCSS colours are hidden from the library, so designers only ever see the 73 Mode colours.
One token, three tiers
NEW 2025OLD MagentaSwitch the theme to OLD Magenta and base/primary/primary becomes Byzantium/600 #AB2184 on every screen.
1A button doesn't know its colour. It only knows its name: Primary.
2Flip to dark. Every Primary on every screen changes. Nobody touched the button.
3New brand? Flip once more. Every Primary follows.
4Why it works: the name passes through three questions. The last one hands back the colour.
5Designers never see the questions. They pick from 73 names, and the system does the rest.
One colour goes through three questions before it lands on a screen.
1A button asks for a colour by its job: primary. Not by its shade.
2Three tiers answer, one after another. Then the button gets its colour.
3Dark mode? Only the first tier changes its answer.
4New brand? Only the middle tier changes its answer.
5Designers only ever see the first tier: 73 colours, named by their job.
5 steps · 36 s · loopsLight or dark?
Which brand?
The real colour
One colour change updates every screen.
Foundations
Colour was the hard tier. The other foundations were easier, because of one rule: design uses the code's scales, not its own. Spacing, radius and breakpoints follow Tailwind, so spacing 4 in Figma is p-4 in code and nothing needs translating at handoff. The tokens cover the product only; marketing pages use Untitled UI's Pro Variables instead, which keeps the product set small and stable.
Spacing, radius and breakpoints follow Tailwind, so spacing 4 in Figma is p-4 in code, and handoff needs less translation. The tokens cover the product only: marketing pages use Untitled UI's Pro Variables library instead, which keeps the product tokens small and stable.
Foundations
Then everything got a name by its job, not its size. Type is Geist, with 12 roles from page title to table cell, built on 41 text styles that are all bound to variables. Spacing steps by 4, 35 steps from 0 to 384, so if a design wants 18px, the answer is 16 or 20. Six named radii sit on top of Tailwind's ten, so a designer chooses from six, not ten.
Type is Geist, with 12 roles from page titles to table cells, built on 41 text styles that are all bound to variables. Spacing multiplies by 4: 35 steps from 0 to 384, so if a design needs 18px, the answer is 16 or 20. Six named radii sit on top of Tailwind's ten, so designers choose from six.
Icons come from Lucide, in six sizes from 16 to 64px, with 10 custom icons kept for real AI features.
Icons come from Lucide, which covers the product with 1,477 icons, and 10 custom icons are kept for real AI features. There are six sizes from 16 to 64px, and strokes thicken as icons grow (1.25 to 2.5) so they look balanced at every size.
ComponentsKey decision 2
Secondary-Grey and Secondary-White differed only by fill, Outline repeated Secondary, and Ghost was close to Link. We merged them into Primary, Secondary and Tertiary, based on how important the action is rather than what kind it is. There are three sizes instead of four, and icon-only became a setting instead of its own row.
WhySix styles were doing three jobs, and some differed only by fill.
CostEvery old button in every file had to move, so we kept the old ones, marked Deprecated, with a swap guide.
What it changedAbout 116 variants became about 48. There's one Primary per view, and a 73-row table answers "which button do I use?".
Three styles, ranked by how important the action is.
~116 → ~48 variants · 4 → 3 sizes
Components
Wide tables don't fit a phone. Aashish designed one card pattern (header, body, footer) that each module fills in its own way, giving 20 module cards, from customers and jobs to invoices and the price book. Cards open with the key fields and expand on "View more".
Components
The complex parts, such as inputs, selects, filters, date pickers, the top bar and pop-ups, each have a mobile web version. Newer parts follow shadcn/ui's names and structure (Sidebar, Command, Navigation Menu, Input OTP, Charts), so they map one to one to the code.
Components
With the foundations in place, components could be built to be set up, never detached. In the Button, every part is a switch, a swap or a token: one component covers 3 types, 4 states and 3 sizes, 36 variants, and icon-only is just Show Text turned off. The Popover works the same way. Its middle is a native Figma slot, so one component holds any content, and nobody has to break it apart to use it.
We build components to be set up, not detached. In the Button, each part is a switch, a swap or a token: one component covers 3 types, 4 states and 3 sizes (36 variants), and icon-only is just Show Text turned off. The Popover works the same way: its middle is a native Figma slot, so one component holds any content.
Bound variables
NEW Swivl Component Lib
Docs link: shadcn/ui Button
NEW Swivl Component Lib
Swipe sideways to see the whole Popover.
Bound variables
Styles
NEW Swivl Component Lib
Components
This is what that looks like in use. Eight parts from the library doing everyday jobs: saving an invoice, typing an amount, sending a reminder, marking an invoice paid. They all run on the same tokens, so one switch turns the whole grid from light to dark.
Eight parts from the library doing everyday jobs: saving an invoice, typing an amount, sending a reminder and marking an invoice paid. They all run on the same tokens, so one switch turns the whole grid from light to dark.
Amount
Deposit at 50%: $625.00
Auto-send reminders
3 days before the due date
Next reminder: Sep 27, 9:00 AM
Customer
Invoices
Search invoices New invoicePatternsKey decision 2
Parts were only half the problem. We also had nine kinds of overlay and no rule for choosing between them, so the same task opened in different ways depending on who designed it. I wrote one rule, pick the pop-up by the task, then checked it against the code.
We had nine kinds of overlay and no rule for choosing, so similar tasks opened in different ways. I wrote one decision rule, then checked it against the code.
WhySimilar tasks opened in different ways, and the code had 394 one-off widths.
Cost14 record forms have to move from centred pop-ups to side panels.
What it changedCreating or editing a record opens a side panel, deleting asks in a small dialog, and multi-step flows get a large dialog. Five named sizes replace about ten widths.
Pick the pop-up by the task.
01
Pick the pop-up by the task.
The decision: five named sizes (400, 512, 672 and 896px, plus full screen), chosen by name and never by pixel. Every overlay also has a phone form: menus and popovers become bottom sheets, and dialogs go full screen. The guide mirrors the engineering code standard, so design and code follow the same rule.
Drawn to scale on a 1280px screen. Picked by name, never by pixel.
Create or edit a record: a side panel, with the list still in view
This can't be undone.
Delete: a small dialog
Docs and governance
A system nobody trusts gets copied around instead of used. So every part got a page. Figma shows how it looks, Notion explains when and why, and each Notion page links to its Figma frame.
A system people don't trust gets copied around instead of used. Figma shows how things look, and Notion explains when and why. Every Notion page links to its Figma frame.
What it's for, its parts, variants and states, light and dark, and do's and don'ts.
Every change gets a changelog entry: the date, what changed, why, and who.
For example, a colour token named "brand-blue" that is actually purple. Written-down quirks are harmless; hidden ones break trust.
Most doc pages link their own Linear ticket, so the work is visible and easy to track.
Docs and governance
Nobody was forced over on day one. Old components stay in the library marked Deprecated, with a short swap guide, and move to a separate file once nobody uses them.
Old components stay in the library marked Deprecated, with a short swap guide, and move to a separate file once nobody uses them.
Deprecated. Use Button 2.0 instead.
Swap guide
1
2
3
4
5
Design ↔ Dev
The names travel all the way into code. There is no export file in the middle: Figma variables use the same Tailwind and shadcn/ui names as the code, so base/border/border in Figma is --border in globals.css and border-border in a component. Every push to main rebuilds the Storybook, 93 components today, and every pull request is checked for raw hex.
There's no export file in the middle. Figma variables use the same Tailwind and shadcn/ui names as the code, so base/border/border in Figma is --border in globals.css and border-border in a component. Every push to main rebuilds the Storybook, 93 components today, and every pull request is checked for raw hex.
same names
classes
push to main
base/border/borderFigma · Mode--borderglobals.cssborder-borderTailwind classPrimitives/CardStorybookcolorBorderMobile appbase/border/borderFigma · Mode--borderglobals.cssborder-borderTailwind classPrimitives/CardStorybookcolorBorderMobile appA few screens built from library parts: ⟨Jobs⟩, ⟨Invoice builder⟩, ⟨Scheduler⟩ and one mobile web view.
Jobs
Invoice builder
Scheduler
Mobile web
Then the revamp came, and it took six weeks. Adding a big new feature stopped being a project, handoff got cleaner, and the library became the default way to build.
Then the revamp came, and it took six weeks. Adding a big new feature stopped being a project, handoff got cleaner, and the library became the default way to build.
Design got faster, handoff got cleaner, and the system became the default way to build.
50%
less time to design a new screen
Typical for a new screen built from library parts. A full flow now takes a day or two.
1–2
design QA issues per big feature
Counted on each big feature shipped after June 2025. Before the system, a feature came back with ten or more.
70%
of new screens built only from library parts
Share of new screens with nothing detached or drawn one-off, before and after the system started in June 2025.
97.7%
of colour bindings sit on the top tier
Counted across the Theme file: 759 variables in 4 collections, and screens touch only the 73 Mode colours.
93
components build in Storybook on every push
One set of names from Figma to code, and every pull request is checked for raw hex.
5
named pop-up sizes replaced about ten widths
From the code audit: 394 one-off widths beside 121 named ones, and 14 record forms moved to side panels.
⟨42%⟩
less time to design a new screen
Median of ⟨8⟩ comparable screens, using Linear dates from design start to ready for dev
⟨57%⟩
fewer design QA issues per feature
Issues tagged design QA in Linear, for ⟨5⟩ features before and after
⟨85%⟩
of new screens built from library parts
Share of new screens with no detached or one-off parts
⟨A real line from an engineer or PM about handoff. A teammate's words carry more weight than yours.⟩
A system drifts the moment you stop looking. Three months after launch, I checked all 79 Figma pages against the docs and the code, to catch the drift before it spread. Here is what it found, and the three decisions it forced.
Three months after launch, I checked all 79 Figma pages against the docs and the code, to catch drift before it spread.
Three months after the docs went live, I audited the whole system: all 79 Figma pages, the token file, the Notion docs and the Linear history. The goal was to catch drift before it spread.
Components with a Notion page
14 of 73Component sets with a Figma description
3 of 266Component sets with a focus state
12 of 266Variables with a code name for developers
0 of 759Places where two docs disagree
10The code already used red, so the docs now do too: a Destructive style, with the verb label and confirm step kept.
Buttons v1 said no red, but the engineering standard and our Menu docs already used red. We keep the safety net, a verb label and a confirm step, and add a Destructive style so the doc matches the product.
Three docs had three scales. We kept the engineering one: 400, 512, 672, 896px and full screen.
Three docs listed three different width scales. We picked the one the engineering standard recommends: 400, 512, 672 and 896px, plus full screen.
"Closed" was grey in Tasks and blue in Leads. Now each status word has one colour.
The same word had different colours in different modules: "Closed" was grey for Tasks but blue for Leads. One table will map every status to one meaning.
Fix what disagrees first, because every new page would copy it. Restructure only once the docs and states are good enough to guide the move.
Done whenNo two pages or files disagree on a rule
Done whenTop components have states, docs and code names
People follow a rule when they know the reason, so the why sits next to every rule. The pop-up rule did more for consistency than any single component.
We shipped parts without focus and disabled states, and designers filled the gaps by hand. Next time, a component isn't done until every state exists.
Building on Tailwind scales and shadcn/ui names removed a whole layer of back-and-forth.
Three months was enough for ten contradictions to creep in, a few of them in my own pages. A check every quarter keeps the system honest.
Screens
This is what it all adds up to. Five live Swivl screens, built from the same parts. The sidebar, the page header, the cards, the tables and the buttons come straight from the library, so a new screen looks like it belongs on day one.
Five live Swivl screens, all built from the same parts. The sidebar, the page header, the cards, the tables and the buttons come straight from the library, so a new screen looks like it belongs from day one.
Victoria, Lead Product Designer · Aashish, Product Designer · Abhijeet Patil, Product Designer · with the Swivl engineering team
Next case study