Add styles and index support for experimental content

[mcking65]

Develop support for example pages that include a draft ARIA feature that is still a work in progress. These pages will enable the accessibility community to develop support for the experimental feature but will clearly indicate their content is intended to be used only for that purpose.

Design Objectives

1. Typical users will:
   • not unintentionally discover experimental content.
   • Not mistake experimental content for normal content
2. Anyone who needs to locate experimental content will be able to do so.

Overview of Implementation proposal

There are two types of changes included in this implementation: editorial and infrastructure. Editors are responsible for ensuring the editorial changes are made to any example page that includes experimental content. The infrastructure changes will be baked into the build process.

Together, the infra and editorial changes will satisfy the design objectives by:

1. Providing a different example usage warning that is open by default under "Read This First". Both content and styling could be different.
2. Including the word "Experimental" in the page title and several headings.
3. Excluding the experimental content from the normal index tables and instead listing it separately at the bottom of the index page.
4. Not providing links to experimental example pages from pattern pages or normal example pages.

Editorial changes

1. On any page with experimental content, add the attribute data-content-phase="experimental" to the main element.
2. Use the word "Experimental" in the page title tag and H1 element.
3. Change the heading "About This Example" to "About This Experimental Example".
4. In the about this example section, lead with the objectives of the experimental content and estimated high-level timeline for maturity of the feature, if successful.
5. Change the "Example" heading to "Experimental Example".

Infrastructure changes

1. In the "Read This First" section of example pages, replace the standard example usage warning with one that is open by default and warns users about the nature and purpose of experimental content by making the following changes:
   • Write an experimental-example-usage-warning.html that is similar to content/shared/templates/example-usage-warning.html. In Include the open attribute on the details element.
   • Modify the addExampleUsageWarning function in content/shared/js/app.js to use the experimental-example-usage-warning.html content instead of example-usage-warning.html on pages that have data-content-phase="experimental.
   • Possibly modify CSS to make the warning even more prominent?
2. Modify scripts/reference-tables.js to:
   • Exclude any pages that include data-content-phase="experimental" from the index tables that list examples by role, state, and property.
   • At the bottom of the index page, add a section labeled "Experimental Content" that provides a list of links to the pages that include experimental content.

[mcking65]

@daniel-montalvo, mentioning you and @shawna-slh for review of the above spec. Please review both design objectives and implementation details.

Here is a little more context that may help as you review it.

Note: I'm targeting having this capability ready before end of year so we can start work on an example of tree, listbox, or tabs that uses the new aria-actions feature. Moving aria-actions forward is a 2024 priority for ARIA.

In this spec, experimental means content that the ARIA WG needs in APG as a prerequisite for finalizing an ARIA feature so it can be merged into the editor's draft of the ARIA spec. The APG example of a new ARIA feature provides a live example, as opposed to a WPT test, that stakeholders can use to observe how browser implementations, which may be behind a flag, are working. The experimental example implementation also enables the ARIA-AT CG to draft tests of proposed AT behaviors to ensure that AT developers have the same understanding of what is expected from AT for the new feature.

The purpose and nature of the experimental content would be explained in the "Read This First" disclosure, that would be expanded by default on these pages. In normal example pages, e.g., accordion example read this first, the read this first is collapsed by default.

[a11ydoer]

also tagging ARIA Chairs, @jnurthen @spectranaut

[lolaodelola]

@mcking65 this is a great idea and is similar to how other doc sites such as MDN show experimental features, although this implementation design seems a little more thorough.

I have a question regarding the proposal.

Modify WAI site search to exclude pages that include data-content-phase="experimental" from site search results.

While I understand the need not to be lax with presenting this information so that only those who really want it, find it; will hiding it from search results prevent those users who want to experiment with the feature from finding the information? I know on MDN experimental features are included in search results but labelled as experimental on index/reference pages.

[alflennik]

Hi @mcking65, first of all this seems like a great idea - I never thought of this before but it makes sense.

I was wondering if you have any experimental content authored yet. If not I think I would advocate to hold off implementing this feature until at least one piece of content is ready. If we develop the feature using placeholder content I'm concerned the work would either get stuck in a branch or need to be overhauled once the real content is ready.

I also wanted to weigh in on the search indexing question. The good news is that we recently figured out how to control the search indexes on the WAI website, but the bad news is that this needs to be controlled at the level of the WAI website and can't be directly configured from the wai-aria-practices repo. In effect we would need to make PRs against the wai-website repo for every new piece of experimental content. For this reason I find myself hoping that including the content in the search is a viable solution, assuming the fact that it's experimental is clearly communicated.

[mcking65]

@alflennik asked:

I was wondering if you have any experimental content authored yet.

None is ready yet. I am going to pursue getting an example for aria-actions in the works. I am thinking about using a copy of one of the file tree examples as starting content for that.

If not I think I would advocate to hold off implementing this feature until at least one piece of content is ready. If we develop the feature using placeholder content I'm concerned the work would either get stuck in a branch or need to be overhauled once the real content is ready.

I don't understand this concern. We should be able to use any existing example as a placeholder, and the design should work. The visual design of the experimental example page should not have any dependency on the content of a specific example. An experimental example page will have exactly the same content sections and format as a consensus example page.

To transform an experimental example to a consensus example, the only content changes would be:

1. Remove the word experimental from headings and title tag.
2. Remove the `data-content-phase="experimental" attribute from the main element, which will trigger changes to read this first and the index.
3. Remove unnecessary information from the "About This Example" section.

I also wanted to weigh in on the search indexing question. The good news is that we recently figured out how to control the search indexes on the WAI website, but the bad news is that this needs to be controlled at the level of the WAI website and can't be directly configured from the wai-aria-practices repo. In effect we would need to make PRs against the wai-website repo for every new piece of experimental content. For this reason I find myself hoping that including the content in the search is a viable solution, assuming the fact that it's experimental is clearly communicated.

I don't know why it would have to be a new WAI web site PR for each new experimental page if the search code was simply looking for the `data-content-phase="experimental" attribute on main.

Nevertheless, if there are no concerns from WAI staff, I can get behind not excluding the pages from WAI site search. I've revised the specification to remove this requirement. Probably more people would discover the content via google anyway. I think the design and content will be sufficiently clear about the status of the content as experimental.

[ccanash]

HI @mcking65 , the functionality for this is ready we are just waiting on the content, do you have it?

[mcking65]

No, we do not yet have content. That will be addressed with #3015.

[mcking65]

Added documentation of the feature to the editorial guidelines.

This issue is now complete.