Open UIOpen UI GitHub

Contribute

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.

What's a Design System?

A design system is a collection of assets and components used to create and maintain UIs on multiple platforms. Examples:

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.

Create Source JSON

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.

A term is a concept if the component can "be" that concept. For example, no one says a Button can be size but it can be small. Put another way, record "is" relationships which denote qualities, like "that button is small". Ignore "has a" relationships which denote properties, like "that button has a size".

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

💡 Always use kebab-case for concept names.

Images

An image of the concept should be included with each 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', category: '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

Create Component Page

Adding a component to Open UI is a research process. Because of this, two pages are created for each component; a research page and a proposal page. Create your component pages like so:

/src
/components
your-component.proposal.mdx
your-component.research.mdx

💡 These will be displayed as a single page on Open UI.

Proposal Page

The proposal page will summarize your findings, conclusions, and unresolved points.

Define your proposal page front matter. The pathToResearch key tells your proposal page where its research page is hosted.

---
menu: Components
name: Your Component
path: /components/your-component
pathToResearch: /components/your-component.research
---

Research Page

The research page is a place to collect, analyse, and deeply understand the data available on the component.

Define your research page front matter. The pathToProposal key tells your research page where its proposal page is hosted.

---
name: Test
path: /components/test.research
pathToProposal: /components/test
---

There are some MDX components available in Open UI's docs to help analyze and understand the data collected. You can reference some other component doc pages for usage examples. Otherwise, you can collect and analyze your data more manually.

Try it out

You should now be able to yarn start the docs and see your component in the menu. You should also have a toggle on the component page to switch between the proposal page and research page.

😄 You're all set! We're looking forward to your contribution to Open UI!