Overview
- Role
- Design Engineer
- Team
- Solo, embedded with the engineering team
- Organization
- Code the Dream, Learns App
- Timeline
- 2025 to 2026
- Live app
- learns-design-system.vercel.app
- Tools
- Next.js 16, MUI v7, React, Vercel
The Problem
Design and dev were drifting apart.
The app was growing, the team was not aligned.
The CTD Learns App had been built piece by piece over months. Tokens lived only in the codebase. Designers worked from outdated Figma files. Engineers reimplemented the same components with slight variations because there was no canonical reference. Every new feature added a small amount of drift, and the drift was starting to show in the product.
I interviewed three engineers and reviewed twelve recent pull requests. Three patterns came up in every conversation:
- Engineers were guessing at color and spacing values because the theme file was hard to scan
- Designers were reverse-engineering specs from screenshots
- Both groups were filing the same questions in Slack week after week
"I just want one place to copy a hex code without opening eight files."
— Senior Engineer, CTD Learns App
What I Learned From Research
A short audit of the existing codebase showed how much was already there, just not documented.
Critical insight: the code was already a design system. It just had no surface. The work was not to invent tokens or components. The work was to make what existed visible, browsable, and trustworthy enough to use as the source of truth.
The Solution
I built a documentation site that mirrors the codebase exactly. Every page lives at the same URL pattern as the sidebar. Every component has the same structure: interactive preview, specs, code. Every token auto-generates from the theme file so it never drifts.
Auto-generated tokens
The Token Library reads theme.js directly. Adding a token to the code makes it appear in the docs on the next deploy. No hand-curating.
Interactive previews
Every component page has a live MUI playground. Flip props, see the result, inspect the specs, copy the code. No guessing what a prop does.
End-to-end pattern docs
Patterns like the Workflow Editor are documented end to end with React Flow code, custom handles, edge styling, and a working interactive canvas.
How It Works
- Browse. Open the homepage. Find the token, component, or pattern through the sidebar, search, or directory grid.
- Inspect. Click to open. Every page shows a live preview, specs, and a code block.
- Copy. Use the copy button on any token, hex value, or code sample.
- Build. Paste into your component. The code matches the theme exactly.
Highlights
Token Library
A central glossary of every design token in the app. Search by name, value, or path. Filter by category. Switch between grid and list view. Click any token to jump to its anchored row in the foundation docs. The library auto-generates from theme.js, so it stays in sync without maintenance.
Interactive component playgrounds
Every component page has a live MUI playground with prop controls, dark mode toggle, an inspect button that shows computed specs, and a copyable code panel. The same controls that change the rendered preview also update the spec sheet, so engineers see exactly which value comes from which prop.
Workflow editor pattern
The most ambitious section. It contains a fully interactive React Flow canvas with infinite pan, wheel zoom, click-to-select nodes, and a live properties panel. The page also documents node types, palette items, custom handles, multi-handle decision branches, and styled edges with copy-pasteable React Flow code for every visual element.
Feedback flow built in
A feedback modal in the sidebar lets anyone on the team report bugs, request features, or submit ideas without leaving the site. Submissions land in my inbox via mailto: with a structured subject and body. No infrastructure needed.
The Methodology Behind the Build
Theme as source of truth
Every value lives in theme.js. Docs read from it. No duplication.
Spartan writing style
Direct, plain language. No marketing voice. No em dashes. A banned word list kept copy honest across every page.
Mobile-first responsive
Every page collapses cleanly to phone width. Tables stack, panels hide, canvases scroll.
Built on the production stack
Same Next.js and MUI versions as production. The code in the docs is the code engineers run.
Results
- 3rd largest content surface built in two weeks
- 56 tokens indexed and searchable
- 17 doc pages covering every foundation, component, pattern, and guideline
- 100% of components in the app are now documented and previewable
The handoff to the dev team is scheduled for the week after the sprint closed. The site is live, mobile responsive, dark mode supported, and seeded with the team's actual node types and example workflows so engineers see real data, not lorem ipsum.
Growth Path
MVP. Live for the CTD Learns App engineering team. Token glossary, every component documented, every pattern walkable end to end. Feedback flow in place to capture what is missing.
Next. Designer playground for generating components and wireframes. A no-code surface where designers can compose layouts using the same tokens engineers ship with. Currently in design.
Scale. Open the system to other Code The Dream projects. The architecture is project-agnostic. Any app built on MUI can swap in its own theme file and inherit the entire docs surface for free.
What I Learned
This sprint changed how I think about documentation work. The instinct is to write more, but the real value is in showing less and letting the source code speak. The auto-generated token library is a thirty-line component. It does more for engineers than three pages of hand-curated tables would have.
Working across both design and engineering forced shortcuts I would not normally take. I shipped the Workflow Editor's interactive canvas in a single day because I had already built every primitive (the Box, the Stack, the SpecTable) the day before. Doing the design and the implementation in the same head removed an entire round of handoff translation.
The hardest decision was what not to build. The team asked for a contribution flow, a changelog feed, and a Figma export. I shipped the feedback modal instead and decided everything else would wait until the team actually used the site. Two weeks of feedback will tell me more than two weeks of speculation.
The most useful thing I built was not a token, a component, or a pattern. It was the writing style memory. Every page reads the same because every page was written against the same direct, spartan rules. That consistency does more for trust than any visual polish.