Open UIOpen UI GitHub

Add a Design System

Open UI uses design systems as one of its forms of evidence for cataloging emergent UI standards. Design systems are documented in JSON5 format according a JSON schema. This provides us with a consistent and machine readable way of documenting the design system.

Criteria

In order to succeed as an open standard, Open UI must collect the most useful ideas and patterns that exist. Because of this, not all design systems are suitable to use as Open UI sources.

We believe the most useful ideas are those that:

  • support designers and developers
  • support multiple platforms and frameworks
  • support accessible users
  • support small and enterprise projects
  • demonstrate organic adoption in a wide community
  • demonstrate significant real-world usage
  • demonstrate deep thought and debate by many experienced minds

A design system does not need to meet all of these criteria but it should meet many of them. The design systems we've launched with we believe are representative of these criteria. We may not accept PRs contributing design systems that are lacking by these criteria.

Initial information

Create a JSON5 file in /sources for the design system, like /antd.json5. Add the $schema key pointing to our design-system.schema.json5 schema and complete the required fields.

{
$schema: '../schemas/design-system.schema.json5',
name: 'Ant Design',
description: 'A design system with values of Nature and Determinacy for better user experience of enterprise applications.',
url: 'http://ant.design',
by: 'AFX',
}

Components

Every UI component in the design system should be added to the components array:

{
$schema: '../schemas/design-system.schema.json5',
name: 'Ant Design',
description: 'A design system with values of Nature and Determinacy for better user experience of enterprise applications.',
url: 'http://ant.design',
by: 'AFX',
components: [{ name: 'Button' }],
}

Do not document utility components. Only document components which render a user interface that can be experienced either visually, by keyboard, or narration.

Concepts

Component concepts are terms used to described the appearance and behavior of a component. Things like primary for a Button.

Concepts are surfaced in component APIs will vary by framework and platform conventions. Sometimes concepts are grouped into categories. The concepts themselves should be cataloged opposed to the categories the design system puts them in.

Example, the concept of primary for a Button might be surfaced in a design guide under the "Types" heading, in an CSS framework with the HTML class="primary", or in a React component library as the prop type='primary'. Open UI's job is to recognize that the concept primary exists within the scope of a Button component.

When cataloging components in a design system, we record the concept primary. The category type is not a concept but it should be noted that the design system categorized primary as a type.

...
components: [
{
name: 'Button',
concepts: [
{ name: 'primary', category: 'type' },
],
},
],
...

💡 Always use kebab-case for concept names.

TODO:
The below guidance has changed already. Carbon for example has no size concept, just small. Latest thinking says it is useful to know how many sizes are applied to each component, opposed to just "size". The guidance for what should be a concept could be whether or not the component can "be" that concept. No one says a Button can be "size". Example, Carbon says a Button can be "small", AntD says a Button can be "large", and Semantic says a Button can be "massive". Put another way, we would record "is" relationships which denote qualities, like "that button is small". We would ignore "has a" relationships which denote properties, like "that button has a size".


Concepts vs Categories

Above we reasoned to flatten the primary concept from within its type grouping. Do we do this for all enum values, such as flattening small from within the size grouping? No, because size is already a concept with consensus as to its meaning and bounds.

We can find size in an encyclopedia with a definition, "Size is the magnitude or dimensions of a thing." It is a concept that exists on its own. Contrast this with type which is abstract and ambiguous. It leads to a disambiguation page and does not stand on its own. We can only talk about types in the context of some other thing.

Another test is whether or not there is intuition and consensus about what this group contains. If you asked a large diverse group of people to list items in this group, do you expect general consensus? List off sizes, did you think of "small", "medium", or "large"? List off types, can you think of anything that makes sense here?

This table can help you determine if a concept is in fact a concept itself or if it is a group of concepts whose items need to be flattened into many concepts:

Might be a conceptMight be a group of concepts
Well-knownObscure
ConcreteAbstract
Stands aloneRequires specific context
Has consensusLittle to no consensus

Images

An image of the concept should be included with the concept. This allows a visual aid to be shown when the concept might need to be clarified in the specifications.

...
components: [
{
name: 'Button',
concepts: [
{ name: 'primary', group: 'type', image: 'antd-button-primary.png' },
],
},
],
...

You can use a screenshot tool to capture these images directly from the design system. Here's an example image of the primary Button in Ant Design.

Ant Design Primary Button

If the image requires showing motion or interaction, considering using a gif tool.

Semantic UI Animated Button