-
Notifications
You must be signed in to change notification settings - Fork 12
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix(documentation): repeated icon note #1027
Conversation
Codecov Report
@@ Coverage Diff @@
## main #1027 +/- ##
==========================================
Coverage 100.00% 100.00%
==========================================
Files 123 222 +99
Lines 1562 2406 +844
Branches 108 125 +17
==========================================
+ Hits 1562 2406 +844
Flags with carried forward coverage won't be shown. Click here to find out more.
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
apps/docs/_includes/icon-note.md
Outdated
@@ -0,0 +1 @@ | |||
Note: An icon on its own doesn't make a discernible text. An `aria-label`, `aria-labelledby` or `title` must be provided to ensure that the user can understand the component's purpose. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When the icon is followed by with text and has no real need for screen readers than authors should add aria-hidden="true"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
true, but that's valid for every bit of text in an app, not just when using an icon.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
not sure I understand..
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For SVG, If no explicit role/aria set, it's hidden by default. Is it not?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no.....
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When the icon is followed by with text and has no real need for screen readers than authors should add
aria-hidden="true"
the sentence starts with "An icon on its own..."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nice docs maintaining touch-up!
How come there are new snapshots for the nav-discloser? seems not relevant to this PR...
you're right, this should have been a doc only PR. but since I updated the |
why did you removed it? don't we have an icon-only option? |
Is this supported in GH markdowns? |
of course, that's nunjucks syntax, markdown is not a templating language. is that a dealbreaker? do you expect users to read the doc on GH? |
Yes. Otherwise we would have wrote directly in 11ty templates See And |
that's (partly) the point of this PR: we have repeating information and a templating engine, why not take advantage of it? |
because you lose documentation in GitHub. the closest you can get to mirroring content in GH is via permalinks. where in 11ty this type of url should be intercepted and replaced with the actual mirrored content. but that windowed content can still be somewhat confusing vivid-3/docs/design/design-tokens.md Lines 6 to 12 in ec2e819
|
include reverted and replaced by copy/paste, first post updated. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this caveat would make more sense when the documentation flow in this order
- text / label section
- icon section (showing icon only without text / label). in the icon section it makes sense to explain about the caveat sense it's a real case
- icon with text / label
also bear in mind to apply those same rules in the code snippet
there is an a11y note warning authors for using only an icon repeated in several components.
this PR replaces it with a small include.This PR:
accordion-item
and theoption
.badge
note (which was truncated) and the card one (which was wrong).nav-disclosure
for consistency (we don't do it for other widgets).