Home

Welcome to the Red Hat Design System wiki! This is meant to be a scratchpad for putting together best practices guides for creating components in this repo. This will not be the final destination for this information, we'll most likely transfer them to ux.redhat.com.

Feel free to update this wiki, no pull requests necessary. Optimally, we would discuss best practices in a discussion thread and document the outcome of those discussions in the wiki.

The structure of Red Hat Design System

Our design system is composed of three kinds. Arranged from smallest-and-lowest-level to largest-and-highest-level, they are:

1. Design Tokens
2. Custom Elements
3. Design Patterns

Design tokens

The smallest, lowest level, and most fundamental kind in our design system are Design Tokens. A design token is a well-known style value, and it has at the very least a name and a value. The primary advantage of design tokens is in the assignment of those names to values.

For example, the design token which represents the background colour for a surface with the lightest color palette has the name --rh-color-surface-lightest and the value #ffffff.

Design tokens may include other information like attributes which describe the categories and uses of the token, documentation like a short description, and references to other design tokens. Tokens whose value is defined by reference to other tokens are sometimes called "semantic" tokens, because they represent a particular usage in design, rather than a given value.

Design tokens are available as part of the RHDS figma library, as well as in the @rhds/tokens npm package.

Custom elements

The next most fundamental kind in our design system are custom elements. These are HTML elements defined by the design system authors, which accessibly express the intended designs, and enable design system users to implement patterns. Custom elements use design tokens (in the form of CSS variables), and combine them with Shadow DOM templates, slots, CSS Shadow Parts, custom HTML attributes, and custom DOM APIs like element properties, methods, and events.

In Red Hat's design system, some elements have variants, which modify their appearance, behaviour, or semantics depending on the specific, pre-defined variant attribute value. Elements, particularly those which contain other elements (e.g. <rh-card> or <rh-surface>) may also have a color palette controlled by the color-palette attribute, which accepts one or more of our color palette names as its value: darkest, darker, dark, light, lighter, or lightest.

Custom elements are available as part of the RHDS figma library, as well as in the @rhds/elements npm package.

Patterns

The highest level and most complex kind in Red Hat's design system are Patterns. These compose tokens and elements together along with HTML templates, guidelines, and accessibility requirements into complex user experiences.

An example of a Pattern would be the quote card, which composes the <rh-blockquote> and <rh-card> elements. That pattern also specifies which slots and parts to use in each element and what type of content to apply.

Patterns are available as part of the RHDS figma library, as well as in documentation on the RHDS website's patterns section.