/specs
COMPANY
ROLE
OWNED
PROJECT TEAM
TIMELINE
STAKEHOLDERS
/problem
We have adopted building fast with AI. However, designers know this puts a spotlight on the speed <> quality dilema.
Knowing speed wasn't negotiable in an engineering led-company, my goal was to achieve the highest quality AI output possible. With Claude Code in the codebase, Figma through MCP, Claude design and other tools for prototyping on the side, we had good bases to build a good workflow.
However, our design system didn't have enough context for the LLMs to know how to behave around them.
Semantic layer for tokens
Primitive layers were often linked to our components.
Allowing for miss-alignment.
Rules and guardrails
We needed usage rules to be taken as context for whatever AI to understand our opportunities and limitations.
UX pattern library
Similar as with our rules, a UX pattern library prevents hallucinations from the LLMs in regards to surface solutions.
Component library
Our components, still carried some low-quality properties and building styles typical of a start-up.
Not ideal as pillar base for AI to create from.
/component-library
I decided the old component library wasn't worth restyling. Instead, it was worth replacing.
The strategy chosen was usign a headless component library, rolled out one component at a time. Headless, because construction quality, behavior, keyboard handling, accessibility, comes solid from the primitives and we only own the skin.
And deliberate in one more way: clean, predictable component code is exactly the context an LLM needs to build new components correctly, remapping the new semantic token layer to it.
shadcn-svelte was the obvious candidate for Doinstruct. However, this wasn't headless option, so we decided to use bits-ui, which is the underlaying layer of schadcn, but with our own CSS instead of adopting Tailwind as shadcn proposed.
PATH A - REJECTED
Adopt schadn as is
Take the components and take Tailwind with them. Fastest to start, and it puts a CSS framework migration on top of a component migration, and throws away years of working SCSS foundations against the preference of the engineers.
PATH B - CHOSEN
Adopt the model, keep our CSS
Own-your-code, headless bits-ui primitives, CLI distribution, on our SCSS system. Components become skeletons we reskin. More work per component, one migration instead of two.
/token-architecture
Two brand palettes feed one semantic role set through component variants.
Underneath every component sit bits-ui's headless primitives, which is where keyboard behavior, focus management, and ARIA live, so accessibility is inherited.
The idea is to mimic the token usage of shadcn so we can still use whatever documentation from both libraries to AI generate further needs.
Distribution runs through a custom registry: every repo pulls component source and owns its copy, updates are deliberate. Migration follows the strangler pattern, low-risk components first, all new work on the new library from day one.
Primitive
Raw values. Colors, sizes, type scales. No opinions.
Semantic
Roles: surface, border, input, focus ring, destructive. The layer AI and humans reason with.
Component
Per-component decisions, only where a component genuinely differs.
