docs(dialog): updated dialog docs for accessbility #5411
Conversation
|
Branch previewReview the following VRT differencesWhen a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:
If the changes are expected, update the |
Tachometer resultsCurrently, no packages are changed by this PR... |
| this.ref('metadata'); | ||
| // Boost title field for higher relevance when matching titles | ||
| this.field('title', { boost: 10 }); | ||
| this.field('title', { boost: 100 }); |
There was a problem hiding this comment.
Adding more to the dialog docs made dialog, dialog base, and dialog wrapper have higher result than base docs, so we boosted the value of a matching title.
There was a problem hiding this comment.
Love the way this is coming together! I completely agree with Casey — we’ve heard from a few of our customers that they’ve run into some friction when using sp-popover and sp-dialog. I think this is a great opportunity for us to meet them where they are and simplify the documentation.
Would it make sense to create a few clear blocks or usage patterns, and accompany them with real-world examples to make things more approachable?
Use sp-dialog-base when:
- You need to present important information that requires user acknowledgment
- You're building a modal interface that blocks interaction with the page
- You need a structured container with features like backdrop/underlay
- Your content is complex and requires formal layout with headings, content sections, and actions
Use sp-popover when:
- You need a lightweight, contextual container that's positioned relative to a trigger element
- You want to display simple content like menus, tooltips, or additional options
- You're building a non-modal interface where users can still interact with the page
- You need an element with an arrow/tip pointing to the trigger
Note: You can actually combine these approaches by using sp-dialog inside sp-popover for a styled popover with dialog-like formatting, as shown below:
<overlay-trigger>
<sp-popover slot="click-content" placement="bottom" tip>
<sp-dialog>
<h3 slot="heading">Styled Popover</h3>
<p>This uses sp-dialog inside sp-popover for a styled contextual interface.</p>
</sp-dialog>
</sp-popover>
<sp-button slot="trigger">Open Popover with Dialog</sp-button>
</overlay-trigger>
|
@caseyisonit @Rajdeepc thanks for the feedback. Please take a look at my changes. |
castastrophe
force-pushed
the
nikkimk/dialog-docs
branch
from
583ada1 to
f248c07
Compare
There was a problem hiding this comment.
@nikkimk this is a massively huge beautiful improvement and will be sooooo beneficial for our consumers! thanks for working through this. 🚀
Description
Related issue(s)
Motivation and context
Documentation should provide more information and examples that demonstrate how to use the components accessibly.
How has this been tested?
Review dialog docs
Review dialog base docs
Review dialog wrapper docs
Screenshots (if appropriate)
Types of changes
Checklist
Best practices
This repository uses conventional commit syntax for each commit message; note that the GitHub UI does not use this by default so be cautious when accepting suggested changes. Avoid the "Update branch" button on the pull request and opt instead for rebasing your branch against
main.