Skip to content

API Guidelines

Guiding principles for designing component APIs.

General Guidelines

To keep RADES consistent and predictable the following guidelines should be observed:

  1. If a component accepts the children prop it should be either required, or the element should return null when no children are provided.

  2. When forwarding HTML attributes to the component the following rules should be observed:

    1. If the component internally instantiates one or more interactive (clickable/editable) elements, the attributes should be forwarded to all of them.
    2. If the component does not internally instantiate an interactive (clickable/editable) element, the attributes should be forwarded to the root element of the component.

  3. Every prop of type string has a defined maximum recommended length and a clear description of how it behaves if that length is surpassed.

See Composition for more.

Visual Props: API vs. Theme

While a custom theme is intended to define visual and interaction settings, component API can be designed to allow customization of many kinds, including the visual properties. This may be confusing during the design process of a component. So how do you reliably know which approach you need?

The key difference is whether you want to enable overriding the default value in the component instance:

Do I want to allow overriding this particular visual setting in a component instance?

  • If yes, put it into the API of the component. Developers can adjust their defaults through the global props provider (withGlobalProps / GlobalPropsProvider), but the option value can still be overridden per component instance.
  • If not, put it into the theme (src/styles/themes/). It will then be the same for all component instances.

Measures

Always use the shared spacing values (src/styles/settings/_spacing.scss) for all kinds of measures like offsets, gaps, or spacings. This helps keep the design consistent across components.