updated landmark design pattern

[jongund]

• Moved information from landmark example pages into the landmark patterns page
• Changed tabs used for code examples from Bootstrap to ARIA practice tabs
• Screenshot Images are now responsive and use figure/figcaption element
• Updated source code examples to use the same markup as other ARIA examples
• Updated AT to include skipTo.js example
• Updated Resources section
• Updated search landmark

Preview updated Landmarks Practices Page

---

WAI Preview Link (Last built on Tue, 15 Apr 2025 22:24:55 GMT).

[jongund]

@howard-e @mcking65
Hi Howard,
What do I need to do to get a preview of this pull request?
Thanks,
Jon

[jongund]

@howard-e

Hi Howard, I updated the URLs for landmark information in the index and coverage scripts.
How do I run them in this pull request to see if they generate the correct URLs?

[howard-e]

@howard-e

Hi Howard, I updated the URLs for landmark information in the index and coverage scripts. How do I run them in this pull request to see if they generate the correct URLs?

Hey @jongund, the generated link failed to build because of an unexpected structure, with the following message: "Error: Expected pattern landmarks to have an Example(s) section".

This comes from wai-aria-practices' transformPattern.js builder logic which expects that there is a section element which contains an h2, with Example (or Examples) as the text, to then apply a style, examples-section. This is the current structure for all the patterns and their example sections on the WAI-APG website. But they have their own individual pages.

We could probably replicate that structure with these landmark patterns but I assume this proposed change here is intentional in how it's structured. So I've submitted wai-aria-practices#382 to relax this constraint instead.

[howard-e]

... I updated the URLs for landmark information in the index and coverage scripts. How do I run them in this pull request to see if they generate the correct URLs?

The coverage report build step result matches exactly except for a newline being added at the end of the coverage-and-quality-report.html document. Perhaps your code editor is automatically doing this if you have the file open? Removing the new line at the end or just re-running npm run coverage-report without the file being open should do the trick.

[howard-e]

... I've submitted wai-aria-practices#382 to relax this constraint instead.

@jongund w3c/wai-aria-practices#382 has been merged now so the Landmarks page renders in the generated preview now.

Just the coverage report build step issue exists. #3216 (comment) should still resolve this

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3216 - Landmark pattern changes.

The full IRC log of that discussion

<jugglinmike> Topic: PR 3216 - Landmark pattern changes
<jugglinmike> github: https://github.com//pull/3216
<jugglinmike> Matt_King: I think we'll skip this for now because jongunderson isn't here today

[jongund]

@mcking65
Updated pull request to include search element as a way to define a search landmark region

[mcking65]

Thank you for working on this. Unfortunately, I don't think this approach fits the APG information architecture.

Problem: The new pattern page proposed in this PR combines practices, pattern, and examples into one large page.

The currently published version of the pattern page sticks to the pattern template. I don't think we should change that. It points people to the practices page for practices.

The currently published practices page is consistent with other practices pages. It does not need major revision.

The primary problem we need to solve is the current production example pages are inconsistent with other example pages. The current landmark example pages:

• Do not use the example template.
• duplicate information that is in the practices.
• Contain some information, e.g., resources, that is not in the practices. It is worth discussing whether we really want to keep maintaining that information. If yes, perhaps it should move to the practices page.

A discussion to have is what do we want an example page for a landmark to contain. Open questions:

• What do we want to be under the example heading?
• Do we want to include both HTML and ARIA on the example pages?

[jongund]

@mcking65

• I removed the landmark examples from the the patterns section
• Moved the AT and Resources and tools information to the practices page
• This will provide a view of not having any landmark examples in the APG since the APG architecture makes it difficult to include them

[jongund]

@mcking65

I have been doing some testing to try to figure out how to update the current landmarks examples to fit in to the production environment of the APG and would like to suggest what I think is a simple solution that preserves current work and improves APG work flow.

• Delete the current patterns pages for landmarks and try not to fit this square peg of examples into a round hole of widget examples. As the APG production environment gets more complex, the landmarks examples will probably continue to be an annoying problem so removing them eliminates this issue. The landmark examples also have a number of external references that will continue to break the production link checker as they become invalid causing headaches for future committers.
• Create a external resource for the example hosted on github of similar platform that can support stable URLs. I will probably do this anyway when the landmark examples are removed anyway, because I find the resource useful and I think other people do too.
• Rather than the example being considered a formal product of the working group it becomes a useful external resource that the working group can help manage. Maybe have an informal sub task force to review it and update it periodically.
• References from the current Landmark Regions Practices page can be updated to point to this external resource.

Let me know what you think of the idea,
All the best,
Jon

[mcking65]

@jongund

I don't see any reason why the APG can't be both a definitive and useful resource related to landmarks.

The APG task force should not be expanding its scope beyond the APG. Adding additional resources and repositories adds complexity and creates a long-term maintenance problem. We especially would not consider taking any responsibility for a repository outside the w3c org.

Is there a reason that we can't make a landmarks example page that fits within the example page template? We may have to slightly re-imagine what is in the actual "example" section of the page, but that seems entirely doable to me.

To me it seems the simplest path forward is to:

1. keep the currently published pattern page.
2. Remove any non-example content from the examples directory, judicially moving any must-keep content to the practices page.
3. Revise the example pages to fit the example template.

[jongund]

@mcking65

The example template I think would need to be modified to have a code example as the primary content, since the landmark code using elements or role values is what the current example is about. I guess I could look to see how the current example template could be used to make a code sample the primary content.