Outline key points for a play

[raunofreiberg]

There's probably room for improvement, but my current structure is something like this:

1. Component name, with visual, and concise description which could be reused throughout design systems, so it should be on point!
2. Functionality (describe how the component should behave)
3. Best practices (cover pitfalls, intricacies or any other non-obvious things to keep in mind)
4. Implementation (a bit more technical than the previous chapters, possibly get into framework-specific nuances, etc)
5. Examples (render a few well-implemented examples of the component from various frameworks)
6. Accessibility (basically links to WAI-ARIA docs for the component; it's probably redundant to duplicate the same info here)
7. Resources (any resources used to put the play together)

I'm very open to suggestions and feedback on this!

[Renddslow]

Per number 6, you mentioned that it may be redundant to have WAI-ARIA information present. My team has an internal design system that we've been running with for the past 3 years. Every new component we have to try to port what we think we're building to what WAI thinks we're building, and then do relevant porting back and forth (tabs and tooltips are specific ones that come to mind).

All that to say, it may be very nice to have the same place where a central name and definition for common components also shares the necessary a11y information and relevant recipes. Things like ensuring a describedBy is present on an element when a tooltip may reference it, making the information keyboard accessible, clipping for things that should be available to screen readers but not to the mouse user.

Anyway, just a thought.

[raunofreiberg]

Every new component we have to try to port what we think we're building to what WAI thinks we're building, and then do relevant porting back and forth (tabs and tooltips are specific ones that come to mind).

Could you elaborate? I'm not sure I understand what you mean. Do you suggest duplicating the WAI-ARIA rules, rather than linking to them?

[Renddslow]

So right now this is what the w3 has for their tooltip info: https://www.w3.org/TR/wai-aria-practices-1.1/#tooltip. I'd love if there was a place that I could see the rules along with visual examples and a table of relationships. That is in the case of a tooltip, these are the ingredients: the element which triggers the tooltip (receives hover/focus) and that must have an aria-describedby, and the element that is the tooltip which must have a role of tooltip.

I guess I am suggesting duplicating the rules at a high level, just so you have a place to see what ingredients you must have regardless of your framework or implementation, and then a link for more details from WAI.