Contribute

We welcome any contributions that you're willing to make, whether it be in the research of a component
or in defining specific behaviors or parts of a component. Below are ways in which you can help contribute,
if you have any questions then that means that our documentation can be improved - please file an issue 🐛

Design Systems

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:

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.

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.

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!

Creating a component spec

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

Research Page

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.

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>

Definitions

Since Open UI is about doing research across design systems to understand their components
and controls it's important to have clear definitions. For the purposes of Open UI here are
some common terms used in specifications and their definitions.

Component

The dictionary defines a component as, "a part or element of a larger whole" and this is
true for components in a design system's component library. Components normally have a meaning,
although this meaning may not be presented to the user (such as a utility component). The meaning is
defined by the component's model, defined parts and
slots, and states.

Control

A control is a type of component that allows some form of user interaction. The control has controller code
that manages the transition of the component's states and the model based on end user interaction with the
defined parts.

Composite Component

It is often necessary to produce a component that contains other components. For example, the <file>
control is a component that normally contains an <input> component and a <button> component.
These types of components are commonly referred to as composite components.