Ten years of app, two platforms and no shared language. The system started by counting what was there before deciding anything.
text+ is a messaging and calling app with more than ten years on iOS and Android. It never had a formal design system: styles lived in the code, each platform did its own thing, and the inconsistencies grew with every release. The Flutter rewrite of the app was already under way when I joined.
Before defining a single token I ran a full inventory of the interface: eight flows, 216 screens across both platforms, 571 elements classified by what they do rather than how they look. Grouping by function instead of colour was the decision that made everything else make sense: two “Continue” buttons, one yellow and one green, are the same button implemented badly twice, not two components.
I was the only designer on the project, in a team of three: the CEO, who set priorities; a Flutter developer, my technical counterpart on every decision; and me. Two constraints: a team that size cannot maintain a complex system, and the developer was going to build screens from it without me reviewing each one, so nothing could stay implicit.
A system for a team of three forces you to decide few things and write them down. These six are the system’s governance; each one is documented with its rationale, so the team can argue with it instead of reinventing it.
brand/action, not brand/tangerine. If the name is a colour, the name is wrong. The brand group has exactly two tokens, action and emphasis, and does not accept a third.
A colour changes in one place and no name goes stale.
Primitives and semantics. Component tokens add maintenance a small team cannot afford. Instead, every component carries a description with its intent and the tokens it consumes.
The system grows without its upkeep growing.
Eight palettes in a perceptually uniform colour space: the same lightness reads the same in any hue. Dark mode stops being a design project and becomes a mode change on a variable. AA contrast is checked on the token pair and fixed in the variable.
Three modes from the same 67 tokens, nothing repainted.
They never compete on the same screen. In dark modes yellow is replaced by lime automatically, because the action token resolves to a different value. Everything that is not the main action is secondary or a link.
One primary action per screen, in dark modes too.
The contract is simple: ThemeData and ThemeExtension, no custom widget classes. So the system leans on native Material 3 widgets, and hover and pressed states are not exported: Flutter handles them, not Figma.
The developer consumes tokens from the theme, with no translation.
Minimum width of 360 dp, from Android data; minimum height of 667 pt, from real traffic on iPhone 7 and 8. Below it a Flutter breakpoint hides or reflows, by design. Tablet and desktop wait for data.
Every component fits 360 × 667 and everything else stays out of scope.
Five layers, bottom up. Each one rests on the previous one and none skips ahead: a component never touches a primitive, and a rule never names a colour.
Tokens. 277 variables in Figma, the single source of truth of the system. Spacing works in bands: 4 to 8 inside a component, 12 to 20 as padding, 24 to 40 between sections. Crossing a band breaks the rhythm, and that is written down.
Component kit. Fifteen sets built on the tokens: button, social button, list row, text field, switch, radio, checkbox, segmented control, action card, avatar, badge, plan selector, tabs, bottom bar and top app bar. Each set carries its description with the layer architecture, the tokens it consumes and the handoff notes for Flutter.
The list row as a contract. It is the component that unlocks the most screens, so it has a closed contract that works as its API: the leading slot can be nothing, an icon or an avatar; the trailing slot is a fixed list of nine options, from chevron to switch, badge or value. No new type ships without updating the spec first. In Flutter that contract is an enum, not a free widget.
One-click theme switch. The reference screens are duplicated by changing only the variable mode on the section. Nothing repainted.
Iconography. The app mixed icons from several eras and weights. Instead of buying a new set, I consolidated the one the company already owned: a single library, 1.5 stroke, line style, 24 px base, and the rule that no icon is ever hand-drawn.
Audit before you tokenise.
The inventory was not preliminary work: it was the most important design decision of the project. It surfaced the component that resolved the most screens and that nobody had asked for.
Rules are worth more than pieces.
A kit without rules produces eyeballed decisions on every screen. Writing down when each thing is used, and why, is what turns a library into a system, and what lets others decide without asking me.
Design for a machine to read it.
Names by role, documented intent, closed contracts. That is what lets the developer, or whoever joins next, build a screen and have it come out close to what the system intends.
A design system is not a deliverable. It is a decision about who can change what without asking permission.
Do you have a product that needs to scale with purpose?
Let's talk. hola@franmarrero.com