diff --git a/content/patterns/code/_index.md b/content/patterns/code/_index.md new file mode 100644 index 0000000..e369b94 --- /dev/null +++ b/content/patterns/code/_index.md @@ -0,0 +1,3 @@ ++++ +title = "Exhibiting code" ++++ diff --git a/content/patterns/code/code-blocks.md b/content/patterns/code/code-blocks.md new file mode 100644 index 0000000..b577112 --- /dev/null +++ b/content/patterns/code/code-blocks.md @@ -0,0 +1,47 @@ ++++ +title = "Code blocks" ++++ + +Markdown already supports code samples both inline (using single backticks like \`some code here\`) and in blocks. **Infusion** will syntax highlight HTML, CSS, and JavaScript if you provide the correct language in the formulation of the block. + +So, this… + +{{}} +```html +<button aria-pressed="false">toggle me</button> +``` +{{}} + +… will result in this: + +```html + +``` + +Note that the syntax highlighting uses a greyscale theme. **Infusion** is careful not to use color as part of its own design, because these colors may clash with those of the design being illustrated and discussed. + +## Line-numbered code blocks + +In addition to the basic markdown support, **Infusion** provides a mechanism to display code blocks with line numbers. This is via the `codeBlock` shortcode. Here is the code for a block of JavaScript with line numbers: + +{{}} +{{<codeBlock lang="js" numbered="true">}} +var toggle = demo.querySelector('[aria-pressed]'); + +toggle.addEventListener('click', (e) => { + let pressed = e.target.getAttribute('aria-pressed') === 'true'; + e.target.setAttribute('aria-pressed', !pressed); +}); +{{</codeBlock>}} +{{}} + +The output will look like the following. Now you are able to refer to particular bits of the code, like the arrow function on line `3`. + +{{}} +var toggle = demo.querySelector('[aria-pressed]'); + +toggle.addEventListener('click', (e) => { + let pressed = e.target.getAttribute('aria-pressed') === 'true'; + e.target.setAttribute('aria-pressed', !pressed); +}); +{{}} diff --git a/content/patterns/code/codepen-embedding.md b/content/patterns/code/codepen-embedding.md new file mode 100644 index 0000000..ad7c7d2 --- /dev/null +++ b/content/patterns/code/codepen-embedding.md @@ -0,0 +1,21 @@ ++++ +title = "CodePen embedding" ++++ + +Sometimes just pictures of the pattern you're documenting aren't enough. Interactive patterns benefit from live demos, so that readers can test their functionality. + +**Infusion** offers a couple of ways to do this. The first is by embedding CodePen demos into the content. The `codePen` shortcode takes just one argument: the codePen's `ID`. + +{{}} +{{% codePen VpVNKW %}} +{{}} + +This will embed the identified codePen into the content wherever you placed the shortcode, with the result view showing by default: + +{{% codePen VpVNKW %}} + +{{% warning %}} +The compiled site will output an error if your `config.toml` does not include your CodePen username (in the `codePenUser` parameter). This is needed to construct the embed URL. +{{% /warning %}} + +**Infusion** also supports the ability to write inline demos directly in markdown files. See {{% pattern "Writing inline demos" %}}. diff --git a/content/patterns/code/writing-inline-demos.md b/content/patterns/code/writing-inline-demos.md new file mode 100644 index 0000000..5e336b2 --- /dev/null +++ b/content/patterns/code/writing-inline-demos.md @@ -0,0 +1,77 @@ ++++ +title = "Writing inline demos" ++++ + +There are some issues with {{% pattern "CodePen embedding" %}}, like them not working offline. They also come with CodePen branding, which will clash with the pattern you're trying to illustrate. + +**Infusion** offers another option: a special `demo` shortcode that allows you to write HTML, CSS, and JavaScript directly into the markdown file. The outputted demo is encapsulated using Shadow DOM, so you don't have to worry about broken styles and global JS. + +Here's the example code for an inline demo of a toggle button: + +{{}} +{{<demo>}} +<button aria-pressed="false">Toggle Me</button> +<style> +button { + background: DarkCyan; + color: white; + border: 0; + font-size: 1.5rem; + padding: 0.5em 1em; + border-right: 5px solid #000; + border-bottom: 5px solid #000; +} + +[aria-pressed="true"] { + border: 0; + border-top: 5px solid #000; + border-left: 5px solid #000; +} +</style> +<script> +var toggle = demo.querySelector('[aria-pressed]'); + +toggle.addEventListener('click', (e) => { + let pressed = e.target.getAttribute('aria-pressed') === 'true'; + e.target.setAttribute('aria-pressed', !pressed); +}); +</script> +{{</demo>}} +{{}} + +Note the `demo.querySelector` on line `21`. **Infusion** automatically provides `demo`, representing the root node of the demo. It's like the `document` keyword but for a demo's subtree. + +Here's a live demo of… the demo: + +{{}} + + + +{{}} + +{{% note %}} +Firefox does not currently support Shadow DOM and **Infusion** does not include a polyfill. Firefox will output an error message. These demos function correctly in Chrome, Safari, and Opera. +{{% /note %}} diff --git a/content/patterns/project-setup.md b/content/patterns/library-setup.md similarity index 100% rename from content/patterns/project-setup.md rename to content/patterns/library-setup.md diff --git a/content/patterns/writing/_index.md b/content/patterns/writing/_index.md index eb1689f..c536213 100644 --- a/content/patterns/writing/_index.md +++ b/content/patterns/writing/_index.md @@ -1,3 +1,4 @@ +++ title = "Writing" +weight = 1 +++ diff --git a/content/patterns/writing/expandable-sections.md b/content/patterns/writing/expandable-sections.md new file mode 100644 index 0000000..a826d7f --- /dev/null +++ b/content/patterns/writing/expandable-sections.md @@ -0,0 +1,44 @@ ++++ +title = "Expandable sections" +weight = 6 ++++ + +In some cases, where there is a lot of content, it's helpful to collapse certain sections. That way, readers get an overview of what's in the content and can choose where to focus in. **Infusion** provides a shortcode method for creating expandable sections which generates accessible markup using `aria-expanded`. + +The `expandable` shortcode takes three parameters: + +* **label** — This is the label for the the section heading. +* **level** — This is the heading level (e.g. `2` or `

`) that will contain the label. If you omit a level parameter, no heading is used; it's just a button +* **open** — Include this and give it a value of "true" or "yes" to make the section expanded on page load + +Here's what the code might look like for a simple expandable section containing markdown: + +{{}} +{{% expandable label="A section of dummy text" level="2" %}} +Here is some markdown including [a link](https://twitter.com/heydonworks). Donec erat est, feugiat a est sed, aliquet pharetra ipsum. Vivamus in arcu leo. Praesent feugiat, purus a molestie ultrices, libero massa iaculis ante, sit amet accumsan leo eros vel ligula. +{{% /expandable %}} +{{}} + +Let's look at what that outputs as: + +{{% expandable label="A section of dummy text" level="2" %}} +Here is some markdown including [a link](https://twitter.com/heydonworks). Donec erat est, feugiat a est sed, aliquet pharetra ipsum. Vivamus in arcu leo. Praesent feugiat, purus a molestie ultrices, libero massa iaculis ante, sit amet accumsan leo eros vel ligula. +{{% /expandable %}} + +Successive collapsible sections fit snugly together. The second of the following two has `open="true"`. + +{{% expandable label="A section of dummy text" level="2" %}} +Mauris eget elit ut neque venenatis placerat id nec libero. Nunc accumsan cursus elit nec iaculis. Proin id rutrum magna, a aliquet sem. Sed et tortor id sem eleifend porta vitae eget elit. Cras sodales porta malesuada. Suspendisse at odio ac tortor. +{{% /expandable %}} + +{{% expandable label="Another dummy section" level="2" open="true" %}} +Ut vulputate enim ut lorem iaculis, vel faucibus metus iaculis. Aliquam erat volutpat. Aliquam luctus orci vel consectetur dignissim. Nullam et efficitur lorem, et ornare est. Sed tristique porttitor justo, quis malesuada velit. Nullam et elit finibus, sollicitudin velit placerat, ultricies dui. +{{% /expandable %}} + +Unfortunately, it is not currently possible to include shortcodes inside other shortcodes, using the `{{% %}}` notation (which is designated for markdown content). If you use the angle brackets notation (illustrated below) it is possible, but markdown will no longer be permitted. You will have to code HTML inside such a section manually. + +{{}} +{{<expandable label="Another dummy section" level="2">}} +<p>Here is a nested pattern reference shortcode: {{% pattern "Writing inline demos" %}}.</p> +{{</expandable>}} +{{}} diff --git a/content/patterns/writing/references.md b/content/patterns/writing/references.md index b2aa594..c97dd32 100644 --- a/content/patterns/writing/references.md +++ b/content/patterns/writing/references.md @@ -4,14 +4,18 @@ title = "References" ## Cross-references -**Infusion** provides an easy mechanism to cross-reference patterns, by name, using the `pattern` shortcode. For example, I can reference the {{% pattern "Notes and warnings" %}} pattern here. Here's what the markdown looks like, including the shortcode: +**Infusion** provides an easy mechanism to cross-reference patterns, by title, using the `pattern` shortcode. For example, I can reference the {{% pattern "Notes & warnings" %}} pattern. Here's what the markdown looks like, including the shortcode: {{}} -I can reference the {{% pattern "Notes and warnings" %}} pattern here. +I can reference the {{% pattern "Notes & warnings" %}} pattern here. {{}} This saves you having to worry about pathing and decorates the generated link with a bookmark icon, identifying the link as a pattern reference visually. +{{% note %}} +The title argument you supply to the shortcode must be exactly the same as the referenced pattern's `title` metadata value and is case sensitive. +{{% /note %}} + ## WCAG References [WCAG 2.0](https://www.w3.org/TR/WCAG/) is the _de facto_ standard for accessible interfaces. When writing about inclusive design patterns, sometimes you'll want to refer to WCAG to highlight which success criteria the pattern meets. diff --git a/public/categories/index.xml b/public/categories/index.xml index a05405a..6475998 100644 --- a/public/categories/index.xml +++ b/public/categories/index.xml @@ -1,9 +1,9 @@ - Categories on Inclusive Pattern Docs + Categories on Infusion /categories/ - Recent content in Categories on Inclusive Pattern Docs + Recent content in Categories on Infusion Hugo -- gohugo.io en-us diff --git a/public/css/styles.css b/public/css/styles.css index 9d940e9..ba5b8fe 100644 --- a/public/css/styles.css +++ b/public/css/styles.css @@ -1,16 +1,3 @@ - -/* - -Colors: -Blue color = #38608F -Dark blue color = #153B62 -Gold color = #FCB316 -Grey color = #707174 -Red color = #C83737 -Green color = #217844 - -*/ - *, *::before, *::after { font-family: inherit; color: inherit; @@ -56,10 +43,18 @@ img { max-width: 100%; } +p img { + margin-top: 0.75rem; +} + +figure p img { + margin-top: 0; +} + :focus:not([tabindex="-1"]), [data-expands]:focus svg, .patterns a:focus span { - outline: 3px solid #FCB316; + outline: 3px solid #ccc; outline-offset: 2px; } @@ -100,9 +95,40 @@ kbd { vertical-align: 0.33em; } +pre { + overflow-x: auto; + padding: 1.5rem; + border: 1px solid; +} + code { font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace; - font-size: 0.85rem; + font-size: 0.85em; +} + +.cmd { + padding: 0.75rem; + background: #111; +} + +.cmd code { + color: #fff; + white-space: nowrap; +} + +.cmd code::before { + content: '$'; + font-weight: bold; + padding-right: 0.25em; +} + +.cmd code::after { + content: ''; + display: inline-block; + width: 0.75em; + height: 1.25em; + background: #fff; + margin-left: 0.25em; } /* Lists */ @@ -196,6 +222,10 @@ th:empty { padding: 2.25rem; } +[role="contentinfo"] { + font-size: 0.85rem; +} + /* Patterns navigation */ .patterns { @@ -360,6 +390,7 @@ figcaption { main { display: block; counter-reset: fig; + min-height: 100vh; } figcaption::before { @@ -371,7 +402,6 @@ figcaption::before { /* Code blocks */ pre[class*=language-] { - padding: 0 !important; background: none; margin-top: 2.25rem; margin-bottom: 0; @@ -393,7 +423,6 @@ pre[class*=language-] code * { } *:not(pre) > code { - background: #f7f7f7; padding: 0.125rem 0.25rem; white-space: nowrap; } @@ -430,7 +459,6 @@ pre[class*=language-] code * { .token.attr-value, .token.keyword { color: #666; - font-weight: bold; } .token.function { @@ -438,18 +466,19 @@ pre[class*=language-] code * { } .line-numbers code { - padding-left: 1.5rem; + padding-left: 2.25rem; margin-top: -1rem; + overflow-x: auto; + overflow-y: hidden; } .line-numbers { - padding-bottom: 2.25rem !important; + padding: 1.5rem !important; } .line-numbers .line-numbers-rows { margin-left: 2.25rem; top: 1.25rem; - border-right-style: dashed color: #111; } @@ -506,6 +535,10 @@ p:empty { display: none; } +*:not(p) + p:empty + p { + margin-top: 2.25rem; +} + /* WCAG and principles */ .wcag ul li { @@ -547,6 +580,10 @@ a .bookmark { width: 0.75em; } +a .balloon { + height: 1.125em; +} + /* cross references */ .pattern-link { @@ -562,3 +599,56 @@ a .bookmark { [id^="demo-"] * { all: initial; } + +@media (max-width: 45em) { + + [role="banner"] { + position: static; + width: auto; + height: auto; + } + + .intro { + text-align: center; + } + + .intro-and-nav > div { + padding: 1.5rem; + padding-bottom: 0; + } + + .logo img { + max-width: 15rem; + } + + .main-and-footer { + margin: 0; + } + + .patterns h3 { + margin-top: 0.75rem; + } + + .patterns li { + margin: 0; + } + + .patterns a { + padding: 0.75rem 0; + font-size: 1rem; + } + + .patterns a[aria-current] { + background: #111; + color: #fff; + padding: 0.75rem; + } + + .patterns a[aria-current] span { + text-decoration: none; + } + + .patterns li + li { + border-top: 1px solid; + } +} diff --git a/public/images/open_in_desktop.png b/public/images/open_in_desktop.png new file mode 100644 index 0000000..7255ad5 Binary files /dev/null and b/public/images/open_in_desktop.png differ diff --git a/public/images/steve_faulkner.jpg b/public/images/steve_faulkner.jpg new file mode 100644 index 0000000..d2d07d4 Binary files /dev/null and b/public/images/steve_faulkner.jpg differ diff --git a/public/index.html b/public/index.html index 38a8b9e..b19302e 100644 --- a/public/index.html +++ b/public/index.html @@ -12,8 +12,8 @@ - Inclusive Pattern Docs | Inclusive Pattern Docs - + Infusion + @@ -33,25 +33,109 @@ - - - - - + + + + + + + + + + + + + + + + + +
@@ -59,14 +143,59 @@
-

- - - Inclusive Pattern Docs -

-
    - -
+

The Infusion Pattern Library Builder

+

Welcome to Infusion: a pattern library builder with a focus on inclusive interface design. These are Infusion’s docs, but they are also an example of a pattern library built with Infusion. Here’s are some of the features:

+ +
+
    +
  • Built with Hugo, so easy to structure content and fast to compile it
    • +
  • Include live code demos easily, using either CodePen embeds or via inline demo shortcodes (that use Shadow DOM)
    • +
  • Quickly include WCAG and Inclusive Design Principles references by key
    • +
  • Easily make sections collapsible without writing HTML
    • +
  • Choose between plain or line-numbered code blocks
    • +
  • A responsive, screen reader and keyboard accessible output site
    • +
+ +
+ + +

To get started using Infusion, you’ll first need to look at the + + + + + + + + + + + + + + + Installation + + + + + + + + + + + + + + + + + + pattern.

+