A Design System with Judgment

Everyone was building their own design system

By the time I joined Brain Co., designers and engineers were quietly rebuilding our design system on their own. One engineer, Jared, started a week before me and went looking for Pearl, our existing system. The Figma library and the code had drifted apart, Storybook had been offline for months after an incident, and forked copies of Pearl lived in various repos across teams. He eventually found a single 5,000-line file holding a handful of components, copied it, and wrote his own frontend documentation so his coding agent had something to follow.

He wasn’t the only one. Alex, the engineer maintaining our platform UI library, spent weeks rebuilding every Figma component in code so his agent could compare the two and report where they disagreed. The list was too long to act on. Kanav, one of our founding engineers in MENA, told me candidly that customer work always came first and the design system sat on the back burner. None of this was carelessness. It’s what happens when a team ships fast for its customers and the system can’t keep up.

Designers were working around it too. Mia, who leads design on our insurance vertical, had started her own library for the citations, forms, and cards Pearl didn’t have. Even the components Pearl did have caused friction, and nothing annoyed people more than the buttons. They were oversized for dense interfaces, and their generous radius clashed with the square inputs beside them. Primary buttons were purple in some products and blue 500 in others, or blue 200 wherever a designer found 500 too saturated, and an agent might reach for any of them.

With no rules to follow, every team and every agent made its own calls. We needed a shared implementation teams could rely on, and guidance for the decisions the components couldn’t make.

Components are free now

For years, building the component library consumed much of the work of a design system. Tables, comboboxes, and accessible dialogs took real design and engineering time to get right. A well-made library was an achievement.

Today, teams can start with much of that work already done. Mantine offers more than 100 customizable components. Adobe’s React Aria handles complex keyboard and screen reader interactions. shadcn provides component source code and documentation that agents can read, install, and adapt in an afternoon. The cost of getting started has collapsed.

The value has moved into what the parts can’t tell you: Which pattern fits the surface. What has to stay visible while someone works. What an operator needs to see before acting. Many teams still rely on design review to resolve those questions. At Brain Co., coding agents now build most of our interfaces alongside forward-deployed engineers on tight customer timelines. Some surfaces get built without a designer in the room.

Without that guidance, an agent falls back on familiar patterns. Eyebrow labels over every heading, decorative gradients and border accents, dashboards that give every metric equal weight. Most designers recognize the “vibe-coded” look. But the problem goes beyond appearance. The components can all be correct while the screen gives an operator no clear sense of what matters or what to do next.

The judgment has to ship inside the system, which is the premise of Synapse. This moves more of the design work upstream. Designers define the patterns, explain the decisions behind them, and specify when each applies. That guidance needs to be precise enough for an agent to act on without a designer reviewing every screen.

Judgment ships in two places

Brain Co. builds software for insurance, government, finance, and healthcare. The people using our applications are operators and decision-makers working through long, consequential workflows. A claims reviewer needs to keep their place and understand where a finding came from before acting on it. Guidance like “make the hierarchy clear” doesn’t tell an agent which findings must stay visible during a review. Synapse builds recurring decisions into components and interaction patterns, and uses skills to guide decisions that depend on the workflow.

I started by writing skills: tightly scoped, reusable instructions an agent loads during a build. dense-ui guides the agent in deciding what the operator is trying to accomplish and which information has to stay in view. Exceptions and information that could change a decision stay visible, while supporting detail opens when needed. A detail panel lets the operator inspect a finding without losing the surrounding context, and returning to a list restores the operator’s position. Component code alone doesn’t tell an agent how to apply these patterns to a particular workflow. Writing them down gives an agent guidance that would otherwise have to come from a designer during review.

Other decisions are built into the components. In Synapse’s data table, a column marked numeric right-aligns and uses tabular figures, so amounts and counts line up automatically. Density is a prop, with compact, default, and comfortable settings that change only the space around the information, never the text size. The guidance says when to reach for each, so an agent building for someone scanning deal health makes different choices than one building for someone reading long descriptions.

A rule is only as good as its evidence

Every design system has type, color, space, and accessibility at its foundation. Those decisions repeat across screens, so a weak choice can affect every product surface that uses the system. I built prototypes to compare them on real interfaces.

The first compared surface treatments on some of our most complex screens. It let me switch treatments in light and dark while content and layout stayed fixed. I went in expecting to give cards and panels their own surface colors. On a screen that’s already full, though, distinct fills can make every region compete for attention. I used fewer surface colors to separate regions while keeping the content prominent. In the permitting workspace, documents sit in a recessed neutral well with the checklist and intake review around it.

Color got the same treatment. I built a chart exercise to examine the palette under simulated deuteranopia, protanopia, and grayscale, with a contrast audit alongside it for both themes. It also tested what happens beyond five series, comparing repeated colors against small multiples. Without guidance for larger datasets, an agent can keep adding colors. The system needs to explain when to use a different chart layout.

Name the job, not the value

When teams choose directly from traditional color ramps, every shade becomes another decision. Nothing in a name like gray 100 says whether it’s a border or a background, so teams can use different values for the same job. That’s how Pearl ended up with blue 500 in one product and blue 200 in the next.

Synapse keeps the vocabulary small and names semantic tokens for their purpose. The whole semantic layer is a single file of under 300 lines, with names such as --bc-surface-page, --bc-border-control, and --bc-font-machine. A name holds across themes while the value underneath changes, and every dark value was chosen by hand instead of derived from light. An agent building an input doesn’t pick from a ramp of grays. It reaches for the control border, the token named for exactly that job.

Depth and shape follow the same logic, reduced to rules an agent can check. In Synapse, shadows are reserved for dismissible overlays. Menus and popovers take --bc-shadow-float, dialogs take --bc-shadow-modal, and panels, navigation, and tables cast nothing. Radius follows depth: core surfaces and layout stay square, anything that casts a shadow gets one small radius, and only objects that are geometrically round are fully round. An agent can apply these decisions without choosing a new treatment for each screen.

--bc-font-machine distinguishes machine output from the surrounding interface. Brain Co. Monument Grotesk is used for interface text, while its semi-mono variant is used for agent traces and machine values. The shared type family keeps the two visually related, while semi-mono’s narrower proportions save space in dense cells compared with full monospace.

Keeping the system and its guidance together

Synapse’s documentation pulls updates directly from the component packages. When a component is added or a token changes, a package sync brings the update into the site automatically; there is no separate copy of the implementation to maintain. The site is a go/synapse link away for anyone at Brain Co.

A designer can inspect any component state or variant in either theme. An engineer can see the implementation and pull it into their repo. A Copy Markdown button on every page exports the API, usage rules, and accessibility notes, so people and agents work from the same source.

A component export missing its API section, accessibility notes, or documented properties fails the build before it reaches a team. The changelog tracks changes to components, foundations, skills, and agent instructions together, so teams adopting an update can see what changed in the implementation and how it should be used.

The system at work

Brain Co.’s permitting software checks site plans against local regulations, so permit seekers get answers in minutes instead of months. A residential construction intake runs through a series of checks, and when the model flags one, the operator sees a summary of why it needs attention. The flag might concern floor elevations or proximity to a body of water. Opening it reveals what the agent found.

The workbench shows the principle in practice. The top level shows the number of checks and the flags that need attention, so the need for review stays visible while the supporting evidence waits until the operator goes looking for it. Justin, the designer on U.S. Permitting, describes the workbench as denser and clearer at the same time, with better organization and clearer places to make decisions.

Jared, who opened this piece hunting for a usable copy of Pearl, now builds on Synapse’s data tables, denser drawers, thinking states, and selection actions. He says he spends less time adjusting components and prompting agents to correct the same component and layout decisions.

Next, we’re turning our strongest product surfaces into references agents can build from. I’m asking everyone on our team for the surfaces they’re proudest of, so the next agent building a permitting screen or a claims review can start with patterns we’ve designed specifically for that work. That’s the part of a design system nobody can download.