WorkDS is the design system that powers WorkOS user interfaces.
WorkDS is built and maintained by the design and engineering teams at WorkOS. We also maintain the open source project Radix UI, which is used as low-level React component primitives in this design system. While Radix is collection of unstyled and unopinionated React components, WorkDS is built with our own design principles, opinions on styling, and visual aesthetic.
We intentionally provide a limited set of APIs per component based on the design constraints defined for a component’s intended use. Because we start designing components by defining its constraints first, we do not offer utility-based CSS classes (like Tailwind CSS or text-sm-type classes) to override styling. For more information about overriding a component’s styling, see: Overriding with the style prop
It’s tempting to try to make a component that solves every usecase that might exist. This can lead to many different variations and one-off deviations. Instead, we strive to let our product challenges dictate the first iteration of a component and then create abstractions to solve use cases as they arise.
We create components composed of other child components rather than baking in a robust set of configurable options. This leads to a set of constraints that can be applied more consistently across component types, while still giving developers the ability to use components in different scenarios.
Our APIs are predictably applied across different component types, but not necessarily consistantly applied. For example, the size prop is always a number value, but it may correspond to either a type scale or spacing scale depending on the context.
When implementing a design with WorkDS, the developer should not have to do extra work to make the design responsive, accessible, or themed correctly for light/dark modes. These are all built-in at the component level.
This artifact exists as a means to document our components’ individual design constraints and provide patterns for achieving commonly desired outcomes. This documentation is written for our own design and engineering teams to create fully composed interfaces within our product. We have made it publicly available in the hopes that it can be useful to other design and engineering teams creating their own design systems.