Open UI community group: In order to add substantial contributions to Open UI you need to join the Open UI CG
We have a weekly telecon on Thursdays at 11AM - 12PM Pacific Time. We post the agenda by end of day (Pacific time) Tuesday on the Discord telecon channel along with the Jitsi video telecon link. See the agenda and minutes archives.
Like many working or community groups in the W3C we leverage IRC. We primarily use it during the telecons to leverage the various bots that have been created through the years for drafting minutes and commenting on related Github bots. Our IRC channel is #openui and you can use the free IRC server on W3C at https://irc.w3.org/ if you don’t have a preferred client.
For useful and common IRC commands, please see this guide or other resources found under the W3C meeting tools section.
The following guide walks you through the process of bringing a Component from idea to either, a standardized Open UI Web Component and/or, an implemented feature in a browser.
Research is a cornerstone of Open UI. Research enables us to not only ensure all use-cases are covered, but also that the best and most inclusive approaches are taken. Research should not only be limited to component libraries or current web technology; although those are very important. Leverage any and all content and perspectives that you may uncover in order to inform the proposal. Some common resources that people utilize are:
We start with a design system review and then build on that. Design systems and component libraries have existed on the web platform for years. Even before the web’s existence; certain terminology (such as tabs) and behaviors (swipe, pop up) are already known and ready to be cemented by the web’s UI industry and the web platform. So we start there:
Look at all the design systems you can find and see how they treat your component. Create a research page using this context and following the workflow documented in the Design Systems Analysis page. For help getting started, you can view the list of design systems we use to conduct research.
Review the concepts that you put on the research page for the component, and begin identifying common ones.
Define terminology for use in your research which identifies all of its “parts” in uniform terms (they might not agree or there might be overlapping concepts) it is important that researchers can share a common understanding.
Sketch out an outline of the component anatomy. The anatomy is the foundation of an Open UI component. From the parts of the anatomy we can define behaviors, and then events.
Review and summarize the characteristics of existing design systems for each piece of the anatomy. Make sure to look at the Aria Practices Guide for prior art overlapping component behavior and assistive technology rendering expectations github.com/w3c/aria-practices. Consider how writing modes, device forms and operating systems affect or impact the component design.
Add relevant design system versions of your component
Optionally: Compatibility research. Do analysis on httparchive about how web developers are doing this. We want to ensure that the design is web compatible (i.e., when implemented in a browser, existing websites continue to work as before). One way to understand this is to imagine the semantics of your component, think about potential ways it could break a web page, then query http archive for that scenario, and report on the results for discussion.
Optionally: Web developer research. Talk to web developers, conduct surveys and/or interviews. Create use cases. Open an issue on GitHub. TODO: discuss research design.
Optionally talk to end users who are most impacted by your topic. Design your research ahead of time and get input from the open ui community, and from the folks you’re discussing your research with. Think about the principles of design justice and try to recruit research participants as paid co-designers who have lived expertise.
Finally, you should take the output of your research, synthesize it, and make a proposal using the Proposal Guide
Once you have your research and proposal together, it needs approval from two Open UI editors or chairs to advance to the next stage. To get this, you should open a pull request. The goal of this process is to allow for asynchronous changes, transparency, and opportunities to ensure consensus from the community. The process is:
needs mergefor review by the community group and editors
We write specifications in order to describe how something is going to work, so we can talk about it, build consensus and harmony, drive additional peer review, and support multi implementations agreeing and interoperating.
Good specifications want to have a mix of clear and unambiguous detail about how a system should work, ambiguity where implementers require flexibility, and clarity for both an implementer and a user.
In the Open UI community, we believe that specifications can be both detailed for implementers, and legible to end users (e.g. web developers).
The goal of writing a spec is to describe the component in terms that we can get feedback on, and that an implementer can implement.
Open UI Components have two potential outcomes in the final stage of this process. They can become standards to be added to the platform (e.g.
<popup>) or they can stay in Open UI as web components (e.g.
In either case, we strive to write our specification prose in a way that is legible to end users of web browsers, web developers, framework authors, and browser implementers.
:hover), or a pseudo-element selector (e.g.
::before) it should also be described.
Note that at this stage, we don’t necessarily know if the Component will be graduated into the web platform or not. However, if you think it might, or if you have ambitions to do so, it’s a good idea to skip ahead to the guidance for Stage #3 “recommendation” to see what your spec will need to look like, and incorporate that guidance into this stage. Doing so will make it easier to advance your Component to stage #4 when that time comes.
Peer review is a building block of consensus. Even though you’ve already gotten alignment internally within the Open UI community, it’s important to drive deeper consensus across web platform stakeholders in other groups.
Good external review takes time, kindness, and empathy. You’ll be reaching out to people who you may or may not have met, asking for input, waiting for them to be available, responding with enthusiasm, incorporating their feedback, and checking if you got it right.
Look up the W3C group you need review from, find the chair or another administrator, email them, and ask for advice. Or, if you don’t feel comfortable doing that, you can ask Greg (firstname.lastname@example.org) or Simon (email@example.com) to determine who to talk with next, and make an introduction. We recommend getting input from the following groups:
ARIA: Add a new issue to the ARIA GitHub repo, and request it be labelled for an agenda topic. Attend the ARIA weekly meeting and share your component accessible interaction model. Request input.
Add some guidance on how to develop the accessibility model of a new control based on prior art in ARIA. Also add information on where to raise issues, e.g: authoring practices task force - raise an issue - tagged in x way.
Privacy, and security: Whenever we design a Component it’s a good idea to get input from the privacy community. We strive to reach out to the Privacy Interest Group (PING), as well as the Design Justice Community for a consentful tech analysis. [TODO: add discussion of consent]
Internationalization: https://github.com/w3c/i18n-activity/issues and https://lists.w3.org/Archives/Public/www-international.
Add more clarity around what to do here
Architectural coherence: After incorporating feedback from other standards groups, we seek high-level input from TAG about how the component fits into the technical architecture of the web platform. You can open a W3C Tag design review issue.
Browser Implementers: It’s a good idea at this point to start getting feedback from folks who might be implementing support for this (either directly or via the runtime), and get their reactions. You can find some guidance on who to talk to at the Web Platform Contribution Guide.
Library authors: TODO
Web Developer Feedback: Check back in with the developers you talked to during your research phase and see if they think we’re still on track. Adjust.
End User Feedback: Check back in with the most impacted end users who you talked to and see if they think we’re still on track. Adjust.
Once you have sign off on the spec from these stakeholders, you can advance your spec to Stage 3.
Define what “sign-off” from means concretely. Disposition of comments, developer feedback on polyfill, etc??
For the purposes of Open UI, we consider a Web Component to be an implementation. We still distinguish between a “Web Component” and a “graduated” component, because of the different work that goes into adding a component to a browser engine.
If you desire to go this route, it’s now time to implement the design you’ve built consensus on using web components.
You can find many good guides for this online. Open UI recommends https://developer.mozilla.org/en-US/docs/Web/Web_Components.
If you have buy in from browser engines, HTML/CSS/ARIA editors to add the component to the web platform, you’ll take these steps:
If you have a need to add a new selector, it should be defined in the selectors spec. If you are adding a pseudo class selector (e.g.
:hover), or a pseudo-element selector (e.g.
::before) it should be added to the pseudo spec, and the HTML semantics for that pseudo-class or pseudo-element selector should be in the HTML spec pseudo-classes section.
For example, the
disabled selector is defined in CSS here: https://drafts.csswg.org/selectors/#enableddisabled and in HTML here: https://html.spec.whatwg.org/multipage/semantics-other.html#selector-disabled .
If you’ve created new HTML, make sure to take a look at the WHATWG/HTML working mode
If you are adding a new element to HTML, that goes into the Elements of HTML section
If the element should participate in form submission, it will also need logic here
Element and attribute indexes:
If you define new events, the Events index is here and you’ll probably add a new “global” event listener attribute for the new event here
If you’re creating a new element you’ll also need to add default rendering rules for the element to the user agent style sheet here: https://html.spec.whatwg.org/multipage/rendering.html#rendering
Every spec should have a consideration for both the browser rendering, and the Assistive Technology (AT) rendering. You should include an example of how to render your new widget. If you can’t represent your widget in ARIA you should extend ARIA with new semantics.
If you have added a new HTML element, it will need to be added to the HTML Accessibility API Mappings (AAM) spec, which indicates the platform mappings for HTML features, and indicates which features are provided implicit ARIA semantics, defined in CORE AAM.
For new HTML features, you’ll also need to consider whether the features’ semantics would be negatively impacted by authors overwriting their implicit ARIA semantics. These requirements would then need to be documented in the conformance requirements (for validators/conformance checkers) in the ARIA in HTML specification.
There are two types of states in the HTML spec, internal and external. Internal states are stored in the browser’s internal data structure (“internal slot” in spec language), whereas external states (e.g. checkbox disabled, select open) are stored in HTML attributes only (e.g. details open).
We write tests for a few different reasons:
Define the testing done within Open UI and link out to other WGs testing definitions
In all cases it’s a nice idea to start with a test plan. This is a high level document or GitHub issue that describes the goals of the test suite and answers questions like:
Once we have a plan, it’s a good idea to start to get familiar with the workflow of the test suite:
Find the owner for the area you’re testing in your test suite, and let them know you are working on this. In WPT for example, ownership happens on a directory level. Then it’s time to write the tests. Then, we need to ping our stakeholders to get review. This can take a while, so don’t worry if it does. It is appropriate to reach out to folks and ask if they have the bandwidth.
Documentation helps web developers understand how to use the technology. A lot of the time, specs get thrown over the wall and technical writers try to decipher them. More over, better docs make standards easier for web developers to deliver feedback on how a feature works.
Good developer documentation has a high level explanation of the feature, specific explanations of each interface and each option, and example code.
Reach out to the MDN project lead to let the know you’re working on docs. Sign up for an MDN Account. Read the MDN style guide. Run through each possible way to use the feature, create examples, describe how they work, and test them to see how they work. Reach out to someone who has never used the feature and ask them to follow your documentation. You can watch them do it and ask them to “outloud think” what they’re experiencing, or ask them to keep a friction journal. If you are able to get funding, this should be paid work.
TODO add ARIA Practice Guide guidance.
That’s it, now you’re done! This process usually takes 12-36 months for a full component. Some smaller changes can happen slightly faster.