Maybe you’ve run into this situation before: you’re a young startup needing to move quickly to find product-market fit and gain customers. You grab a third-party UI component library that helps you build your frontend quickly. The customers are happy. The bosses are happy. The engineers are happy. Everything works well…until it doesn’t.

One day you realize you’re spending half your time adding custom style overrides to get the component library to match the design spec; the company’s design language shifted away from what the component library was intended for long ago. Or perhaps the library isn’t as accessible as your evolving customer base requires, so you have to implement hacks to add functionality. Maybe the tradeoffs and API design of the library don’t match what your company needs anymore, or the degree to which you need to reuse patterns and components outpaces the library.

This is exactly where we found ourselves at Cribl.

The “why”

As I mentioned, we were facing considerable difficulties in our frontend codebases. We saw significant visual and behavioral divergence between parts of our products. Without aligned reusable building blocks for designers to use in Figma and engineers to use in code, many new features were built with one-off visual treatments, making development slow and inefficient. Components behaved differently across our platform depending on which team or engineer built them. The third-party UI component library we had relied on for years was becoming more of a liability than an accelerator. Our constant overrides and hacks were making the codebase, particularly the styling, increasingly brittle.

An even larger problem was that our application was also failing our customers from an accessibility perspective. Many interactions were either partially or completely unusable with a keyboard. Color contrast, font sizes and weights, and click target sizes were outside acceptable parameters. Event handlers were attached to non-interactive elements. Items in the browser accessibility tree were missing labels and explanatory text. We knew we had to serve our customers better.

Our application surface had changed drastically over the past few years, too. We now had multiple frontend codebases and design standards that needed to be kept in sync. Historically, this meant copy-and-pasting override styles from one codebase to another to ensure they matched. With the advent of Cribl Apps, we needed to align both our internal products and our customers’ apps against a single north star, one that championed consistent design and accessibility. 

It was time to build our own design system.

The “what”

A design system is more than a suite of UI components. It’s the entire UX repertoire you use to communicate with your customers. Design standards, usually encoded as design tokens, define how the product will look and feel. A frontend component library enforces that by providing healthy guardrails for how the product can be built. Underpinning both of these is a commitment to serving your entire customer base, which means baking accessibility into every decision, from color palettes to animation speeds to keyboard interactions. In this current era of agentic programming, a well-made design system provides documentation and enablement for both humans and agents.

A design system is more than a suite of UI components. It’s the entire UX repertoire you use to communicate with your customers. Design standards, usually encoded as design tokens, define how applications look and feel. A frontend component library enforces that by providing healthy guardrails for how the product is built. Underpinning both of these is a commitment to serving your entire customer base, which means baking accessibility into every decision, from color palettes and animation speeds to keyboard interactions. 

This is especially vital in the era of agentic programming. A well-made design system provides documentation and enablement for both humans and agents.

The “how”

Cribl’s Platform UI team started with our design standards and partnered with the Design team to define the final state of our UX. This required reassessing every aspect of the user experience. A few changes that came out of this work included a new color palette, a recalibrated semantic use of color, and removing existing patterns and interactions that were inherently inaccessible. These newly refreshed design standards were documented in Figma and the documentation site, and we encoded the nuts and bolts of the standards (colors, spacing, typography, etc.) using the latest Design Token Community Group spec. Our design tokens now serve as the source of truth for both Figma and components, and are redistributed using the excellent Style Dictionary library. 

Our next step was to utilize those design tokens in code. After assessing a few options in the problem space, we chose the battle-tested, accessibility-first headless UI component library React Aria Components as our foundation. Using an off-the-shelf library may seem counterintuitive considering the pain points we mentioned earlier, but there are a few key differences. React Aria Components ships without any styles, which means we can customize the look and feel as we see fit without having to wrangle or override default styles. We also treat the library as an implementation detail and don’t expose it directly in our public APIs. We then layered our custom styles and additional behavior on top of React Aria Components. This resulted in components that were attuned to our specific needs while still providing rich, interactive experiences to all our customers.

The final step was to document our design system so it could be used effectively. We use Storybook for that, co-locating both component documentation and “stories,” which are live examples of how our components work. This worked well for humans, but we found that agents couldn’t consume Storybook effectively, since most of its functionality requires JavaScript in the browser. To solve this, we wrote a custom rendering pipeline that converted all of our Storybook content into plain Markdown, which we expose via an /llms.txt route on our documentation site. We went further and embedded that plain-text documentation in our published packages as well. This way, whether human or LLM, our design system documentation is available right where it’s needed.

There are many more details that go into the “how” of building Capra, and we will explore those in future blog posts. Stay tuned.

How is it going?

We’re still in the midst of rolling Capra out fully across our products. As you can imagine, replacing years of hird-party library tech debt takes time. But we’ve already seen significant progress. Our internal dashboard tracking the migration shows we’ve already passed the 25% mark. More of the work is being planned as you’re reading this.

We’ve learned many lessons along the way, and I’m sure we will continue to do so. One lesson of note was finding the right balance between getting components to their final state versus finding a pragmatic middle ground. We introduced too much change early on, both visually and API contracts, compared to the previous third-party library. For example, our new text inputs originally used a different border/background color scheme, which looked strange when it was on the screen adjacent to an old text input that wasn’t yet migrated. While this was well-intentioned, it missed the mark on empowering our engineers to quickly and safely migrate to Capra. We took a step back, adjusted how we built components, and provided more gradual stepping stones to adoption.

It’s also exciting to see Capra used in Cribl Apps. While we originally published our packages privately, we’ve since moved Capra to NPM so our customers can build apps that match the Cribl’s design aesthetics and behavior. The download numbers keep climbing, and we can’t wait to see what our customers build!

What’s next?

We’re continuing to build out Capra. As adoption increases, we’re finding more opportunities to leverage Capra for ourselves and our customers. Our roadmap includes a more robust set of base components in the coming months. We’re also exploring different mechanisms to support higher-level components (like “organisms,” if you’re familiar with atomic design principles), which should make it easier to scaffold out entire sections or pages.

Our investment in Capra is already paying dividends by driving design and behavior consistency, accessibility, and improved code health across our entire platform. We look forward to its continued use and adoption in order to serve our customers well.

Interested in using Capra with Cribl? Read more about Cribl Apps and check out the Capra documentation at capra.cribl.io.