Design System

Source of truth: https://zeroheight.com/239aea73f

Conventions

Implementation

A component should either

• Render a native HTML element, or
• Render a component provided by BaseUI

All components support the render prop from BaseUI. This prop is either forwarded to the root component, when rendering a BaseUI component, or used through the useRender hook when rendering a native HTML element, allowing further customization.

All components support a set of common properties:

• id
• className
• style
• ref (a React ref)

When implementing a new component, you should

• Write a TypeScript interface for the component props, extending the common properties and HTMLAttributes<T> (or a sub-interface) to inherit default HTML props.
• Use the useMergeProps to merge default properties coming from the theme with the properties passed to the component.
• Add a section to the Theme interface for the default props of your new component, and choose default values.

Props

Except for component-specific props (like variant, size, etc.), all components should support spread props on the root element.
This is automatically handled by useRender when rendering a native HTML element, but needs to be manually done for BaseUI components.
This allows all native HTML props (like style, onClick, etc.) to be forwarded.

Refs

All components accept a ref that should always be used. Either

• Forwarded to a BaseUI component (all of them accept refs), or
• Given to useRender hook when rendering a native HTML element. See https://base-ui.com/react/utils/use-render#merging-refs

Styling

Styling is done using a CSS module per component.
All CSS modules should always start with a root class, typically .<component name> that is applied to the root element of the component.

When typing common styling properties, such as color or size, please always define a TypeScript type for the property, and use it in the component props interface. If the same set of values as the common ones is supported, you can use a type alias.

For instance

export type DSMyComponentSize = ComponentSize;

Sizing

When applicable, components should support a size property that can be set to small, medium or large. The default size is medium.
In the component's CSS module, .small, .medium and .large classes should be defined to apply the appropriate styles for each size.
When rendering the component, use the classNames utility to apply the appropriate size class based on the size property.

:bulb: It's OK to only support a subset of the available sizes.

Variants

When applicable, components should support a variant property that can be set to primary, secondary or tertiary. The default variant is primary.
In the component's CSS module, .primary, .secondary and .tertiary classes should be defined to apply the appropriate styles for each variant.
When rendering the component, use the classNames utility to apply the appropriate variant class based on the variant property.

:bulb: It's OK to only support a subset of the available variants.

Line height

As a general rule, don't override the line-height CSS property. It makes vertical alignment difficult, especially with icons next to text.
Whenever required, use an override in DSTypography to set a custom line-height on a variant.

Testing

To run the tests, make sure you have Docker installed first.
Run docker compose up -d to start the required containers, and then npm test to run the Vitest tests.