A Design System in Practice
Sirius2 has been in production across our products for about nine months now. Long enough that the initial excitement of “everything looks consistent” has given way to the practical realities of maintaining a shared component library across multiple applications. Some things worked exactly as planned. Others taught us things we didn’t expect.
Components age differently in different products
A Button is a Button everywhere. The Card component works the same in Meera as it does in Journey. These foundational components stabilized early and haven’t needed much attention.
The interesting ones are the components that get used in ways we didn’t anticipate. IndexTable was built for Meera’s board views: a data table with selectable rows, sortable columns, and inline actions. When Wave CI started using it for build lists, the interaction model was slightly different: rows needed to link to detail pages, not toggle selection. We had to add navigation support without breaking Meera’s selection behavior.
ResourceList has a similar story. It was designed for vertical lists of items with actions. Then someone put a ResourceList inside a Card and the borders doubled up. Then someone put a ResourceList inside a Modal and the scrolling behavior was wrong. Each product found edge cases that the documentation app, where components are rendered in isolation, never exposed.
The documentation gap is real
This is the thing I flagged in August and it’s still true. We know how the components work because we built them. But explaining “use the :subdued prop on a Card section when the content is secondary to the section above it” requires context that isn’t written down anywhere.
I’ve been adding documentation incrementally. Primary colors for the Badge component this week, better examples for a few others. But the fundamental problem is that component documentation lives in code comments and in people’s heads, not in a structured format that’s browsable and searchable.
What I want is a documentation system where each component carries its own docs as structured metadata: props, slots, examples, and best-practice notes in a format that can be rendered into a browsable reference site. Something where adding a new prop means updating the metadata in the same commit, not remembering to update a separate doc file later.
That’s a project for when things are less busy. But it’s becoming more important as more people work with the components.
Token discipline
The semantic token architecture is the thing that’s held up best. Nine months in, I haven’t found a single case where a product needed to bypass the token system and use raw color values. Every background, every text color, every border, every shadow goes through semantic tokens. The three-layer indirection (component → semantic token → palette value) that felt over-engineered in March is now the most reliable part of the system.
The discipline it enforces is real. When someone wants to add a colored element, they have to think about what it means (is it success, warning, critical, info?) rather than what color it should be. That forced semantic thinking prevents the visual drift that we built Sirius2 to solve.
What’s working, what needs attention
Working well: Token system, foundational components (Button, Card, Banner, Badge, Text, Icon), the HERB template integration, consistent visual language across products.
Needs attention: Documentation (biggest gap), edge cases in composed components (ResourceList in Card, IndexTable navigation mode), the Popover component’s interaction with Turbo page transitions, and the overall size of the CSS bundle which has been growing as we add components.
Nine months is long enough to be confident the architecture is right. The token system works. The component model works. HERB makes everything more pleasant to build. The gaps are in documentation and edge cases, which are solvable problems, not architectural ones.