| name | path |
|---|---|
Contribute |
/contribute |
import Image from '../components/image'
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
- Creating a component spec
- Definitions
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.
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: 'An enterprise-class UI design language and React UI library.',
url: 'http://ant.design',
by: 'AFX',
}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: 'An enterprise-class UI design language and React UI library.',
url: 'http://ant.design',
by: 'AFX',
components: [{ name: 'Button' }],
}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.
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.
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!
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.
/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.
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.
Example:
---
name: Test
path: /components/test.research
pathToProposal: /components/test
---After this front matter, copy in the content from the Component Research Template.
This template includes a few optional partials you can import into the research page.
Each of these walks through the design system JSON5 files in /sources to finds components where the openUIName value matches the Name value of your research page front matter.
- Anatomy: lists out component anatomy by part, if any matching components have defined an anatomy.
- Concept Coverage: lists matching components according to unique names, as well as which design systems use that name.
- Concepts: for each unique concept defined for matching components (per the concepts section of this documentation) the research page will display: this concept name, the various names used by different design systems for this concept, and examples of this concept from the design systems.
You may also collect and add research manually to this page.
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.
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: Proposals
name: Your Component
path: /components/your-component
pathToResearch: /components/your-component.research
---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.
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.
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
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>
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.
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.
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.
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.