From fff72dff15e23d28d8bfaa64f3c4cce67c5c020d Mon Sep 17 00:00:00 2001 From: Heydon Pickering Date: Sat, 7 Oct 2017 12:27:26 +0100 Subject: [PATCH] numbered highlights explanation --- content/patterns/coding/code-blocks.md | 59 +++++++++++++++-- docs/css/styles.css | 55 +++++++--------- docs/js/dom-scripts.js | 2 +- docs/patterns/coding/code-blocks/index.html | 69 +++++++++++++++++--- docs/print-version/index.html | 69 +++++++++++++++++--- docs/service-worker.js | 2 +- themes/infusion/layouts/shortcodes/html.html | 3 +- themes/infusion/static/css/styles.css | 55 +++++++--------- themes/infusion/static/js/dom-scripts.js | 2 +- 9 files changed, 229 insertions(+), 87 deletions(-) diff --git a/content/patterns/coding/code-blocks.md b/content/patterns/coding/code-blocks.md index 32efc34..eaffc19 100644 --- a/content/patterns/coding/code-blocks.md +++ b/content/patterns/coding/code-blocks.md @@ -25,13 +25,58 @@ Note that the syntax highlighting uses a greyscale theme. **Infusion** is carefu To preserve the wrapping inside code blocks, horizontal scrolling is implemented. To make sure scrolling is keyboard accessible, code blocks are focusable. An `aria-label` is provided to identify the code block to screen reader users. {{% /note %}} -## Annotated +## Annotated HTML + +Since the structure of HTML is critical to interoperable web interfaces, **Infusion** offers the ability to highlight and annotate specific HTML elements and attributes using the `html` shortcode. + +Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies: {{}} - +
+ +

Confirmation

+

Press Okay to confirm or Cancel

+ + +
{{}} + +You mark out the highlighted areas with double parentheses like so: + +{{}} +{{<html>}} +<div ((role="dialog")) ((aria-labelledby="dialog-heading"))> + <button ((aria-label="close"))>x</button> + <h2 ((id="dialog-heading"))>Confirmation</h2> + <p>Press Okay to confirm or Cancel</p> + <button>Okay</button> + <button>Cancel</button> +</div> +{{</html>}} +{{}} + +Better still, if you include `numbered="true"`, each highlight is enumberated so you can reference it directly in the ensuing text. + +{{}} +
+ +

Confirmation

+

Press Okay to confirm or Cancel

+ + +
+{{}} + +You just include `numbered="true"` on the opening shortcode tag: + +{{}} +{{<html numbered="true">}} +<div ((role="dialog")) ((aria-labelledby="dialog-heading"))> + <button ((aria-label="close"))>x</button> + <h2 ((id="dialog-heading"))>Confirmation</h2> + <p>Press Okay to confirm or Cancel</p> + <button>Okay</button> + <button>Cancel</button> +</div> +{{</html>}} +{{}} diff --git a/docs/css/styles.css b/docs/css/styles.css index 5fb8c78..26d7090 100644 --- a/docs/css/styles.css +++ b/docs/css/styles.css @@ -65,8 +65,10 @@ figure p img { [data-expands]:focus svg, .patterns a:focus .text, [for="themer"] :focus + [aria-hidden] { - outline: 3px solid #888; - outline-offset: 2px; + outline: 4px solid #999; +} +a { + outline-offset: 2px; } /* fix for IE :( */ @@ -382,7 +384,7 @@ caption { } #menu-button:focus { outline: none; - box-shadow: inset 0 0 0 0.25rem #888; + box-shadow: inset 0 0 0 0.25rem #999; } /* Tables of contents */ @@ -522,37 +524,30 @@ pre[class*=language-] code * { margin-top: -1rem; } .html-annotated { - overflow-y: hidden; - overflow-x: auto; - padding: 1.5rem; - border: 1px solid; - white-space: pre; - counter-reset: annotation; + overflow-y: hidden; + overflow-x: auto; + padding: 1.5rem; + border: 1px solid; + white-space: pre; + counter-reset: annotation; } .highlight { - background: #ddd; - padding: 0.25rem 0.5rem; - border-radius: 0.5rem; + background: #ddd; + padding: 0.0625rem 0.33rem; + border-radius: 0.5rem; } -.highlight::after { - counter-increment: annotation; - content: counter(annotation); - font-weight: bold; - font-size: 0.5rem; - background: #111; - color: #fefefe; - display: inline-block; - width: 0.75rem; - height: 0.75rem; - line-height: 0.75rem; - text-align: center; - border-radius: 1rem; - vertical-align: middle; - margin-left: 0.25rem; +.numbered .highlight::after { + counter-increment: annotation; + content: counter(annotation); + font-weight: bold; + font-size: 0.5rem; + background: #111; + color: #fefefe; + border-radius: 1rem; + margin-left: 0.25rem; + padding: 0.125em 0.5em; + vertical-align: 0.33em; } - - - /*main { display: block; counter-reset: fig; diff --git a/docs/js/dom-scripts.js b/docs/js/dom-scripts.js index 1c89251..0c69d4a 100644 --- a/docs/js/dom-scripts.js +++ b/docs/js/dom-scripts.js @@ -82,7 +82,7 @@ /* Enable scrolling by keyboard of code samples */ (function () { - var codeBlocks = document.querySelectorAll('pre'); + var codeBlocks = document.querySelectorAll('pre, .html-annotated'); Array.prototype.forEach.call(codeBlocks, function (block) { if (block.querySelector('code')) { diff --git a/docs/patterns/coding/code-blocks/index.html b/docs/patterns/coding/code-blocks/index.html index 1c7d0f0..bca7d21 100644 --- a/docs/patterns/coding/code-blocks/index.html +++ b/docs/patterns/coding/code-blocks/index.html @@ -425,21 +425,74 @@ -

Annotated

+

Annotated HTML

+ +

Since the structure of HTML is critical to interoperable web interfaces, Infusion offers the ability to highlight and annotate specific HTML elements and attributes using the html shortcode.

+ +

Take an accessible dialog. You may wish to point out key attributes that make that dialog support assistive technologies:

-
-<ul> - <li>Here's a thing</li> - <li role="separator">Here's a thing</li> - <li>Here's a thing</li> - <li>Here's a thing <span aria-hidden="true"></span></li> -</ul> + +
+<div role="dialog" aria-labelledby="dialog-heading"> + <button aria-label="close">x</button> + <h2 id="dialog-heading">Confirmation</h2> + <p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong></p> + <button>Okay</button> + <button>Cancel</button> +</div>
+

You mark out the highlighted areas with double parentheses like so:

+ +

+{{<html>}}
+<div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
+  <button ((aria-label="close"))>x</button>
+  <h2 ((id="dialog-heading"))>Confirmation</h2>
+  <p>Press Okay to confirm or Cancel</p>
+  <button>Okay</button>
+  <button>Cancel</button>
+</div>
+{{</html>}}
+
+ + +

Better still, if you include numbered="true", each highlight is enumberated so you can reference it directly in the ensuing text.

+ + + + + +
+<div role="dialog" aria-labelledby="dialog-heading"> + <button aria-label="close">x</button> + <h2 id="dialog-heading">Confirmation</h2> + <p>Press <strong>Okay</strong> to confirm or <strong>Cancel</strong></p> + <button>Okay</button> + <button>Cancel</button> +</div> +
+ + +

You just include numbered="true" on the opening shortcode tag:

+ +

+{{<html numbered="true">}}
+<div ((role="dialog")) ((aria-labelledby="dialog-heading"))>
+  <button ((aria-label="close"))>x</button>
+  <h2 ((id="dialog-heading"))>Confirmation</h2>
+  <p>Press Okay to confirm or Cancel</p>
+  <button>Okay</button>
+  <button>Cancel</button>
+</div>
+{{</html>}}
+
+ +