Skip to content

Improvements for screen readers #205

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Mar 8, 2021
Merged

Improvements for screen readers #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/lit-dev-content/site/_includes/header.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<header>
<nav>
<a href="{{ site.baseurl }}/">
<a href="{{ site.baseurl }}/" aria-label="Home">
<img id="headerLogo" src="{{ site.baseurl }}/images/logo.svg" />
</a>

Expand Down
6 changes: 6 additions & 0 deletions packages/lit-dev-content/site/css/docs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,12 @@ playground-ide {
background: var(--playground-code-background);
}

figure {
/* We put code snippets in figures for improved a11y semantics, but they come
with a default left margin. */
margin-left: 0;
}

/* ------------------------------------
* Headings
* ------------------------------------ */
Expand Down
2 changes: 1 addition & 1 deletion packages/lit-dev-content/site/css/home.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ p {
background: white;
}

.homeExample > h4 {
.homeExample > figcaption {
background: var(--color-blue);
color: white;
margin: 0;
Expand Down
2 changes: 1 addition & 1 deletion packages/lit-dev-content/site/css/home/1-splash.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
position: absolute;
}

#intro > h2 {
#intro > .homeSectionHeading {
border-top: 2px solid var(--color-blue);
margin: 2em 0 1em 0;
}
Expand Down
13 changes: 7 additions & 6 deletions packages/lit-dev-content/site/home/1-splash.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,16 @@
<div id="splash">
<section id="intro">
<div id="splashLogo">
<img src="{{site.baseurl}}/images/logo.svg" />
<img src="{{site.baseurl}}/images/logo.svg" aria-label="Lit" />
<!-- Trick for detecting when the logo has scrolled under the header.
See src/home.ts -->
<div id="splashLogoHeaderOffset"></div>
</div>

<h2 class="homeSectionHeading">
<p class="homeSectionHeading">
<!-- If in an h2, with the br, VoiceOver weirdly reads this twice.-->
Simple. Fast. Lightweight.<br />Web components.
</h2>
</p>

<p>
Lit is a library for building fast, lightweight web components. Based on
Expand All @@ -23,8 +24,8 @@ <h2 class="homeSectionHeading">
</section>

<section id="helloWorld">
<div class="homeExample">
<h4>Hello World</h4>
<figure class="homeExample">
<figcaption>Hello World</figcaption>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we allow both a heading and caption? The heading would be the title of the example, and the caption could be equivalent to the alt-text with longer content?

It looks like headings in figures are excluded from the outline algorithms (which screen readers might sort-of follow? afaik, nothing really implemented the HTML outline algorithm correctly) so I'm not sure if the heading should be inside or before the figure in that case.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah interesting, I guess we could put "Code example" in the <figcaption>, render if off screen somewhere so that it's not shown visually but still reads to screenreaders, and then keep the "Hello World" in a heading? Will play around with that for a followup.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the most part, we don't have titles on our examples. Occasionally, we have a filename attached to an example.

Generally the code example is described in the accompanying text. We use alt-text to describe stuff that the screen reader can't read, but it can read the code example. I think the caption "Code example" gives the information that's conveyed by formatting to the sighted reader.

(I don't know how you'd do this, but an additional cool perk would be if we could provide an optional title/filename that gets integrated into the figcaption. i.e., so looking at the page you see "my-element.js" above the example, but the screen reader would say, "Code example: my-element.js")

I wouldn't spent more than about 10 minutes thinking about that, though. I think "Code example" is good. With the obvious caveat, I Am Not An A11y Expert.

<div class="code">
{% highlight 'js' %}{% include './1-splash-example.js' %}{% endhighlight
%}
Expand All @@ -35,6 +36,6 @@ <h4>Hello World</h4>
endhighlight %}
</div>
</div>
</section>
</figure>
</div>
</div>
6 changes: 3 additions & 3 deletions packages/lit-dev-content/site/home/2-use-cases.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ <h2>More compatibility. Less complexity.</h2>

<div class="useCasesArt">
<div class="lhsBackground"></div>
<svg class="standalone">
<svg class="standalone" aria-hidden="true" focusable="false">
<use xlink:href="{{site.baseurl}}/images/home/standalone.svg#main"></use>
</svg>
</div>
Expand All @@ -27,7 +27,7 @@ <h3>Standalone Components</h3>

<div class="useCasesArt">
<div class="lhsBackground"></div>
<svg>
<svg role="presentation" aria-hidden="true" focusable="false">
<use xlink:href="{{site.baseurl}}/images/home/design-systems.svg#main"></use>
</svg>
</div>
Expand All @@ -43,7 +43,7 @@ <h3>Design Systems</h3>

<div class="useCasesArt last">
<div class="lhsBackground"></div>
<svg>
<svg aria-hidden="true" focusable="false">
<use xlink:href="{{site.baseurl}}/images/home/applications.svg#main"></use>
</svg>
</div>
Expand Down
4 changes: 2 additions & 2 deletions packages/lit-dev-content/site/home/3-simplicity.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ <h2 class="homeSectionHeading">Simplicity comes first.</h2>
</p>
</div>

<div class="homeExample">
<h4>Create a component</h4>
<figure class="homeExample">
<figcaption>Create a component</figcaption>
<div class="code">
{% highlight 'js' %}{% include './3-simplicity-example.js' %}{%
endhighlight %}
Expand Down
15 changes: 10 additions & 5 deletions packages/lit-dev-content/site/home/5-who-is-using.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,30 @@ <h2>
</h2>

<div id="whoIsUsingLogos">
<svg>
<svg role="img">
<title>Netflix</title>
<use xlink:href="{{ site.baseurl }}/images/logos/netflix.svg#logo"></use>
</svg>

<svg>
<svg role="img">
<title>Microsoft</title>
<use
xlink:href="{{ site.baseurl }}/images/logos/microsoft.svg#logo"
></use>
</svg>

<svg>
<svg role="img">
<title>Google</title>
<use xlink:href="{{ site.baseurl }}/images/logos/google.svg#logo"></use>
</svg>

<svg>
<svg role="img">
<title>GitHub</title>
<use xlink:href="{{ site.baseurl }}/images/logos/github.svg#logo"></use>
</svg>

<svg>
<svg role="img">
<title>YouTube</title>
<use xlink:href="{{ site.baseurl }}/images/logos/youtube.svg#logo"></use>
</svg>
</div>
Expand Down
2 changes: 1 addition & 1 deletion packages/lit-dev-tools/src/playground-plugin/renderer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ export class Renderer {
},
[lang, code]
);
const html = `<div class="CodeMirror cm-s-default">${codemirrorHtml}</div>`;
const html = `<figure class="CodeMirror cm-s-default">${codemirrorHtml}</figure>`;
return {html};
} finally {
this.releasePageLock();
Expand Down