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:

• Google's Material Design
• IBM's Carbon Design
• Read more here

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.

Adding a design system

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',
}

Adding your design system's component

After you create the base schema file, add in each component for your design system into a components array that resides in the schema document. This information will populate the Component Name Matrix.

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

{
  $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' }],
}

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.

Adding images to a component

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.

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

Document a component using research and proposal pages

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. You'll want to create both at the same time as Open UI leverages the research page to document anything for

• Anatomy
• States
• Behaviors

Utilize the Component Spec Template to begin to tease the component apart.

Create your component pages like so:

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

Copy the content from the Component Spec Template and paste it into your proposal document.

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

Research Page

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

Copy in the content from the Component Research Template

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.

For any other research that you believe will make more sense on its own, create a seperate research documents following <component-name.research.<research-topic>.mdx.

Link to these documents within your research page under a section title accordingly. For example, the <select> control has research pages for behaviors.

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
---

Working through the proposal template

Beginning to spec a control can feel daunting and it's hard to know where to start. The spec template headings should be used as a guide to ensure that all aspects of creating a high quality control that is inclusive for all users is covered. Not all sections are required for every control. If you remove them, make sure to denote that you removed them and why in a PR.

Gaining consensus on a change

Of course, merely documenting what exists does not necessarily make something a good design. For each normative change that you make to your spec proposal, open an issue to outline the change that you're proposing. You should provide any research to support the change(s) that you're proposing.

Do NOT deviate from already standardized content

Open UI is trying to define an entire control in a single location. Currently, in order to build a complete control you'll need to refer to specifications in WHATWG, CSSWG, and WIA-ARIA. Open UI will enable an author to build a control referencing a single location.

While this will be helpful, Open UI should not re-define aspects of other specifications. If you identity an aspect of a control that exists in the majority of design systems but is not currently in a web platform specification, you should define it in the Open UI spec proposal. Upon getting resolution of this proposal a subsequent issue should be filed against the necessary specification to get its addition. To make it a bit more clear, let's take a concrete example:

The Open UI <select> proposal has a definition for an open state. This is currently not defined in a web platform specification. In order for this to make it into the web platform an issue will need to be filed again the WHATWG HTML specification.

Note: In order to understand how Open UI achieves consensus, please review to our charter

Denoting Questions

There is an expectation that your proposal will have open questions. Leverage the following HTML to denote them, they'll be incremented automatically and pre-pended with 'Question'.

<p class="question">QUESTION</p>

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!