I’ve been building Skrewww, a design system that lives across Figma and React.
At first, the goal sounded straightforward:
Keep the Figma library and the React implementation in sync.
In practice, that quickly turned into a much bigger systems problem.
The difficult part wasn’t building more components.
It was deciding:
- What is actually canonical?
- What should be generated?
- What can be checked mechanically?
- What still requires human design judgment?
- How do you know a component that looks correct in the repository will actually work after someone installs it?
These are a few of the lessons I learned while building the system.
1. One source of truth isn’t enough if everything means “truth”
Early on, it’s tempting to put everything into one giant component definition:
- props
- variants
- tokens
- Figma information
- documentation
- accessibility notes
- usage guidance
- distribution metadata
But these things don’t all have the same level of certainty.
Some facts are mechanically verifiable.
For example:
- a component slug exists
- a prop is documented
- a token is referenced
- a component is Beta or Stable
- a component is distributed through the registry
Other things are design intent:
- when Glass should be used
- whether a specific interaction feels right
- whether two surfaces are visually equivalent
- whether a Figma behavior should become a React API
I eventually started treating these as separate layers.
The canonical layer owns facts that can be checked.
Design intent and usage guidance remain guidance.
That distinction turned out to be important because otherwise metadata can become a second implementation that can drift just as easily as the code.
2. Generated files should stay boring
Skrewww has several generated projections.
The simplified flow looks like this:
text
Canonical component sources
↓
Registry metadata
↓
Generated registry
Agent contracts
Consumer facts
Documentation projections
Top comments (0)