Making Engineer and Designer Speak the Same Language
Lead Product Designer
"Design system quality lies in the invisible."
The problem
When I joined SmartNews in 2021, the company was scaling fast. The design team was small, there was no dedicated design system owner, and the brand guideline was our only shared reference. It was enough to keep things roughly aligned — until it wasn't.
Two designers on my team shipped the same component for the different feature, in two completely different styles. Neither was wrong. Both followed the brand guideline. That was the problem.
Without a shared system, the same UI was being rebuilt in slightly different ways across files. On the surface, the inconsistencies looked normal, a slightly different radius here, a different shade of gray there. But underneath, there was a gap. The team was moving fast, but the surface was drifting.
Can you tell the differences?
That inconsistency cascaded into engineering. Without shared components, engineers recreated patterns from scratch, often duplicating the same color hex or text style in slightly different ways. The codebase became a patchwork.
As the product grew, so did the friction. Every new feature meant re-negotiating the same decisions. Reviews slowed down. Rework increased. Design and engineering weren't just inconsistent, we were speaking different languages.
The approach
Before building anything, I needed to answer one question: where do you start a design system when nothing exists?
Components without shared foundations just recreate the same problem at a higher level. So Phase 1 focused entirely on building a shared language, with slow start on a component library as well.
This was shaped by talking to the engineering team. Engineers already work with systems. Type systems, naming conventions, dependency trees. But design just wasn't giving them one.
"Engineers used to work with system, everyday."
From that conversation, the framework took shape as three layers — each one solving a different kind of friction, stacked so the lower layers carry the upper ones.
Shared naming
CommunicationThe foundation of everything. If design calls it "brand blue" and engineering calls it #0099EB, we already lost. The first thing I established was a naming convention both sides could use.
Shared specs
SpecificationsWith names aligned, the next step was making the actual values unambiguous. A single source of truth for type scales, color palettes, and spacing. Defined once, referenced everywhere. No more "which gray did you mean?"
Shared process
WorkflowLanguage and specs reduce ambiguity, but the real friction is in handoff. The third layer aligned how design decisions flow into engineering implementation — minimizing back-and-forth and making the system self-documenting.
The system
With the strategy set — language first, components later — the work focused on three foundations: typography, color, and the token architecture that ties them together.
Typography
SmartNews runs in two languages. Japanese and English don't just use different characters, they have different density, different rhythm, and different readability thresholds. A type scale that works for English body text can feel cramped in Japanese. Getting this wrong means every screen in the product feels slightly off.
The type system needed to feel like one unified scale, while handling two very different languages underneath.
The solution was a mirrored type scale: shared hierarchy and sizing across both languages, but language-specific font families and weight mappings. Hiragino Sans for Japanese. SF Pro and Roboto for English. Same structure, adapted execution.
Same scale, different rhythm. Toggle metrics to see it literally.
Color
The old color system was a flat list of 53 hex values with names like random. No scale, no grouping, no rules for when to use what. Picking a color meant guessing, or asking someone who'd been around long enough to know.
The new system introduces two layers: primitives (the raw palette) and tokens (what they mean).
Each color family follows a consistent scale: 100 through 900 for grays, 100 through 300 for brand colors. A shared scale means a designer can say Gray-600 and an engineer knows exactly which value that is, on any platform.
The naming convention wasn't arbitrary — it followed a deliberate hierarchy that maps directly to how both designers and engineers think about values.
Just a hex. No name, no context, no meaning. If an engineer sees this value in a spec, they have no idea what it's for.
Now it has a name and a position. But it still doesn't say what it's for.
Now anyone — designer or engineer — knows exactly what this color is for. This is where both sides meet.
Same meaning, platform-native naming. Designers stop at the design token. Engineers pick it up from there. That's the bridge.
To make the layered naming tangible, here's a small token name builder. Pick a foundation, a property, and a modifier — the composed token updates live, alongside how the same name appears on Figma, Android, and iOS.
Try different combinations to see how the naming system maps across platforms.
The Demo
To make the system tangible, here's a live inspector built directly from the tokens above. Toggle Inspector on, then click any element on the SmartNews home feed — the panel reveals exactly which token, primitive, and value powers it. Switch between light and dark to see the same tokens resolve to different primitives.
Hover and click any element to reveal its design tokens.
From 53 unnamed colors to 25 structured tokens. One naming convention. Every platform.
From the team
The real test of a design system isn't only the documentation, but also how the team uses and interacts with it. The shared language had simply become the way we talked about color.
Realized the search screen uses
background-elevation
as its background color, instead of
surface-primary
like in home screen or profile screen. All of those screens are
accessed from GNB, so I was expecting the search screen to have the
same background. Just want to know if it's expected to use
background-elevation?
@Janice Kartika would it
make things easier if all of the background pages were
surface-primary
instead of using different background colors for different pages?
If so, @Raufan I think I'd
be ok with using
surface-primary
for all background — but happy to discuss / we should take a look
at the designs.
Btw: it's very comfortable to use the design tokens for discussing this instead of talking with the hex color. Kudos minna san — so happy with CL.
Thank you so much @Raufan, for the clear updates, it makes it very easy to get up to speed at a glance 🚄
Results & Reflection
Phase 1 set out to build a shared language. Here's what that language made possible.
Designers stopped asking "which gray." Engineers stopped guessing hex values from screenshots. Handoff conversations shifted from pixel-checking to token references — and the Slack thread above wasn't a one-off. Within two weeks, token names had become the default vocabulary across the team.
With the language in place, the team could start building on top of it.
- Color primitives & semantic tokens A two-layer palette — raw values underneath, named roles on top.
- Typography scales for JP & EN One scale, tuned per language so vertical rhythm stays consistent.
- Naming convention across the stack Same token names in Figma, Android, and iOS — no translation layer.
- Token architecture Raw → primitive → design → component, so every value has a home.
- Core component library Buttons, inputs, cards — built on the tokens already in place.
- Documentation site A single source of truth for tokens, patterns, and usage guidance.
- Figma library governance A contribution model so the system grows without fragmenting.
Starting with language instead of components felt counterintuitive, but it was actually the fast path.
The team wanted buttons and cards and all the tangible things they could use tomorrow. But with this, by the time the first component shipped, adoption was instant because everyone already understood the naming. We all speak the same language now.