Design systems, Mamo, 2021–2024

Mamo’s design system in code, from SCSS to MUI

When I joined Mamo in July 2021, the merchant dashboard was Rails views, HTML with Ruby in it, with no shared components and no design tokens. Over the next three years its design system took three shapes in code, each one what the stack allowed at the time: an SCSS library that worked like Tailwind before we could use Tailwind, a move to Tailwind once we could, and React components on MUI with a theme typed in TypeScript.

Stack
Rails views, SCSS, Tailwind, React, TypeScript, MUI, Storybook
My part
Built the SCSS library, moved it to Tailwind, then built the React components on MUI with a typed theme

Where it started

The dashboard was server-rendered Rails. Each page was an ERB template, HTML with Ruby in it, with its own styles. There was nothing shared, so every page styled its own buttons, cards and spacing, and values were typed in by hand and drifted.

I built the components as plain HTML and SCSS first, in their own repo, so the Rails views could take the markup and the stylesheet as they were.

Why not Tailwind?

Tailwind was the obvious answer, and we couldn’t use it. The dashboard’s stylesheets went through Rails’ asset pipeline, Sprockets, and from December 2021 through Webpacker 5. Neither ran PostCSS 8, which Tailwind needed. The only way in was a separate compatibility build, and it didn’t work with our Rails setup.

So I wrote the parts of Tailwind we needed, in SCSS.

A Tailwind of our own

The library had four layers. Variables held the raw values: a type scale from 10 to 80, spacing from 0 to 128, and colors in seven shades each. Maps grouped them so a loop could walk them. Mixins held the logic: respond for breakpoints, plus tooltips, cards and dropdown menus. And the utilities file looped over the maps to write the classes: bg-blue-500, hover:bg-blue-500, p-24, -mt-24, md:p-24.

The names followed Tailwind’s, so anyone who knew Tailwind could read the markup. The utilities file was 560 lines, and it compiled to about 6,000 classes, 5,000 of them responsive versions. That was also its cost: the purge step that strips unused classes threw bugs in our build and stayed switched off, so the compiled stylesheet carried every class.

Property
Token
Breakpoint

In the markup: class="md:p-24"

_utilities.scss
// wrapped once more in @each $bp in $breakpoints// and @include respond($bp)@each $name, $size in $spacings {  .p-#{$name} { padding: $size; }}
main.css, compiled
@media only screen and (min-width: 48em) {  .md\:p-24 { padding: 2.4rem; }}
The generator, rebuilt from the library’s own loops and values. Pick a property, a token and a breakpoint.

Moving to Tailwind in one pull request

In March 2023 we brought Tailwind in, through the PostCSS 7 compatibility build. Because the class names already matched, the move was one pull request. I set Tailwind’s config to our scale, with spacing and type named in pixels and the same color names, deleted the utilities, maps and grid files, and renamed the few classes that differed: justify-space-between became justify-between, align-center became items-center, none became hidden.

It touched 112 files, and the codebase came out 788 lines smaller.

Migrate in-house CSS utility library to TailwindCSS112 files
Removed: <div className="flex justify-space-between align-center">Added: <div className="flex justify-between items-center">Removed:   <nav className="none lg:block">Added:   <nav className="hidden lg:block">Unchanged:   <p className="-mt-24 text-12 text-black-300">Unchanged:   <div className="p-16 md:p-24 bg-blue-500">
The kind of change the files got. Classes that already matched Tailwind’s names stayed as they were.

React, MUI and a typed theme

From late 2023 the design system moved into React components. Our designers referenced MUI a lot, so rather than build every input, menu and date picker from scratch, I used MUI’s components and restyled them to Mamo’s brand in one theme file. It came to override 25 MUI components, from inputs and menus to tabs, switches and the date picker.

The tokens moved to TypeScript in two layers: a raw palette, then named roles that components use, like primary, surface, border and text. The old color object stayed, marked deprecated, so files could move over one at a time. Tailwind got the same colors in the same pull request.

primary[1] points at
constants/colors.ts
const palette = {  blue: { 600: '#3333FF', 700: '#222BE2', 900: '#20388D' },} export const colorsV2 = {  primary: { 1: palette.blue[600] },}
Point the primary role at another shade and every component that reads it follows. Mamo’s palette values; the components are drawn here.

Storybook, once we could run it

Storybook had to share the app’s build setup, and the old asset pipeline couldn’t give it one. It was wired into Webpacker in April 2022 with one example story, and that was all it had for the next 19 months.

In November 2023 I started the library for real: cards, tooltips and charts first, then colors, typography and icons, then checkboxes, text inputs, tags, dropdowns, buttons and tabs by the end of December. The stories showed each component’s variants and states, and they were the check that the code matched Figma. Other engineers added their own stories as they built components. I wrote 27 of the 40.

Controls

variant
size
disabled
A small Storybook in this site’s style, with the names of the first stories I wrote. The components are simplified drawings in Mamo’s colors.

What would have come next

In hindsight, MUI wasn’t perfect. It was designer friendly: our designers knew its components and referenced them in their work. For developers it meant restyling from the outside, and a good part of the theme file undoes Material’s own look (all: unset, !important, hiding the outline MUI draws) before adding ours.

The next iteration would have been friendly to both. Radix for the behavior and accessibility, and shadcn’s approach on top: the component copied into our codebase and styled with Tailwind, so the code is ours to read and change. That is where the frontend world was heading, and by 2025 Mamo’s team was building new pieces that way: Radix primitives, variants written with class-variance-authority, and a shadcn-style sidebar.

theme.ts, MUI: restyle it from outside
MuiOutlinedInput: {  styleOverrides: {    root: {      border: `1px solid ${colorsV2.border[2]}`,      '&:before': { all: 'unset' },   // undo Material      '&:after': { all: 'unset' },    // undo Material      '&.Mui-focused': { borderColor: colorsV2.border[4] },    },    input: { padding: 'unset !important' },    notchedOutline: { display: 'none' },  // undo Material  },},
input.tsx, the shadcn way: the component is ours
const input = cva('h-14 rounded-lg border px-3 text-body', {  variants: {    tone: {      default: 'border-border-2 focus:border-border-4',      warning: 'border-yellow-1 bg-yellow-3',    },  },}) export function Input({ tone, ...props }: InputProps) {  return <input className={input({ tone })} {...props} />}
The same input, styled two ways. Both simplified: the first is the shape of Mamo’s MUI theme, the second the shadcn approach.