Icon title feature + related bug fixes (#1858)

* Add title property to icon component
* Update icons in other templates

Author: tylersticka

.changeset/cuddly-poems-hang.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Add new `title` property to Icon component to make semantic fallback text much more straightforward

.changeset/curly-cameras-fix.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': patch
+---
+
+The Ground Nav button's icon is no longer presented inconsistently with other button icons

.changeset/gold-pans-sin.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': patch
+---
+
+The default icon fallback now exists (oops)

.changeset/sixty-starfishes-nail.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': patch
+---
+
+Icons used in the Alert component no longer use invalid `aria-hidden` values

src/components/alert/alert.twig

@@ -5,7 +5,6 @@
     {% if icon %}
       {% include '@cloudfour/components/icon/icon.twig' with {
         name: icon,
-        aria_hidden: true
       } only %}
     {% endif %}
   {% endblock %}
@@ -30,7 +29,6 @@
         {% include '@cloudfour/components/icon/icon.twig' with {
           class: 'c-alert__dismiss-icon',
           name: 'x',
-          aria_hidden: true,
         } %}
         <span class="u-hidden-visually">Dismiss alert</span>
       </button>

src/components/badge/badge.twig

@@ -3,7 +3,6 @@
     {% if icon %}
       {% include '@cloudfour/components/icon/icon.twig' with {
         name: icon,
-        aria_hidden: 'true',
       } only %}
     {% endif %}
   {% endblock %}

src/components/cloud-cover/demo/extra.twig

@@ -10,6 +10,7 @@
       We
       {% include '@cloudfour/components/icon/icon.twig' with {
         name: 'heart',
+        title: 'love',
         inline: true
       } only %}
       <span class="u-hidden-visually">love</span>

src/components/cloud-cover/demo/scene.twig

@@ -10,6 +10,7 @@
       We
       {% include '@cloudfour/components/icon/icon.twig' with {
         name: 'heart',
+        title: 'love',
         inline: true
       } only %}
       <span class="u-hidden-visually">love</span>

src/components/comment/comment.twig

@@ -56,7 +56,6 @@
             {% include '@cloudfour/components/icon/icon.twig' with {
               name: 'link',
               inline: true,
-              aria_hidden: 'true',
             } only %}
           </span>
           <span class="u-hidden-visually">

src/components/footnote/footnote.twig

@@ -6,7 +6,6 @@
 
     {% include '@cloudfour/components/icon/icon.twig' with {
       name: 'arrow-hook-left',
-      aria_hidden: 'true',
     } only %}
   </a>
 </li>

src/components/ground-nav/ground-nav.twig

@@ -18,23 +18,11 @@
         {{ lead_in }}
       </h2>
       <p class="c-ground-nav__action-title">
-        {% embed '@cloudfour/components/button/button.twig' with {
+        {% include '@cloudfour/components/button/button.twig' with {
           href: link,
           label: title,
-          _ground_nav_icon: icon
+          content_start_icon: icon ?? 'link'
         } only %}
-          {% block content %}
-            {% if _ground_nav_icon %}
-              {% include '@cloudfour/components/icon/icon.twig' with {
-                name: _ground_nav_icon,
-                fallback: 'link',
-                inline: true,
-                focusable: 'false'
-              } only %}
-            {% endif %}
-            {{ label }}
-          {% endblock %}
-        {% endembed %}
       </p>
       {% include '@cloudfour/assets/illustrations/portland.svg.twig' with {
         class: 'c-ground-nav__action-illustration'

src/components/heading/heading.twig

@@ -66,7 +66,6 @@
     <a class="c-heading__permalink" href="#{{ id }}">
       {% include '@cloudfour/components/icon/icon.twig' with {
         name: 'link',
-        aria_hidden: 'true'
       } only %}
       <span class="u-hidden-visually">Permalink to {{ _content }}</span>
     </a>

src/components/icon/demo/a11y.twig

@@ -0,0 +1,16 @@
+<p>
+  I
+  {% include '@cloudfour/components/icon/icon.twig' with {
+    name: 'heart',
+    title: 'love',
+    inline: true,
+  } %}
+  icons with semantic fallbacks.
+</p>
+<p>
+  {% include '@cloudfour/components/icon/icon.twig' with {
+    name: 'check',
+    inline: true
+  } %}
+  Decorative icons are nice, too!
+</p>

src/components/icon/icon.stories.mdx

@@ -8,6 +8,9 @@ import template from './icon.twig';
 // within a Storybook docs page and not within an actual component).
 // This can be revisited in the future if Storybook no longer relies on Webpack.
 // eslint-disable-next-line @cloudfour/import/no-webpack-loader-syntax
+import a11yDemoSource from '!!raw-loader!./demo/a11y.twig';
+import a11yDemo from './demo/a11y.twig';
+// eslint-disable-next-line @cloudfour/import/no-webpack-loader-syntax
 import inlineDemoSource from '!!raw-loader!./demo/inline.twig';
 import inlineDemo from './demo/inline.twig';
 const iconStory = (args) => {
@@ -38,12 +41,26 @@ For a list of available icons, visit [the Icons page](/docs/design-icons--page).
       fallback: { type: { name: 'string' } },
       inline: { type: { name: 'boolean' } },
       class: { type: { name: 'string' } },
+      title: { type: { name: 'string' } },
     }}
   >
     {(args) => iconStory(args)}
   </Story>
 </Canvas>
 
+## Accessibility
+
+By default, an icon is assumed to be decorative. If the `title` property is provided, it will be used as the icon's accessible fallback text. The default values for `aria-hidden` and `role` will be adjusted accordingly as well. ([More info](https://css-tricks.com/accessible-svgs/#aa-example-1-standalone-icon-meaningful))
+
+<Canvas>
+  <Story
+    name="Accessibility"
+    parameters={{ docs: { source: { code: a11yDemoSource } } }}
+  >
+    {a11yDemo}
+  </Story>
+</Canvas>
+
 ## Modifier: Inline
 
 Icons without a flex or grid container may appear [slightly low in comparison to adjacent text](https://cloudfour.com/thinks/some-imaginary-css/#align-to-typeface-median). The `c-icon--inline` modifier applies a slight positioning adjustment to account for this.
@@ -65,10 +82,11 @@ Icons without a flex or grid container may appear [slightly low in comparison to
 
 The component template supports the following unique properties:
 
-- `name`: The name of the intended icon [in our library](/docs/design-icons--page).
-- `fallback`: The name of an icon to display if the first doesn't exist. Useful if you are displaying unique icons based on dynamic content. Defaults to `close`.
-- `inline`: When `true`, the inline modifier will be applied.
 - `class`: Will append to `c-icon` and any other modifier classes.
+- `fallback`: The name of an icon to display if the one specified by `name` doesn't exist. Useful if you are displaying unique icons based on dynamic content. Defaults to `x`.
+- `inline`: When `true`, the inline modifier will be applied.
+- `name`: The name of the intended icon [in our library](/docs/design-icons--page).
+- `title`: If provided, a `title` element will be prepended to the icon source with the contents of this property. This will also set the `role` to `img` unless it is already specified. ([More info](https://css-tricks.com/accessible-svgs/#aa-example-1-standalone-icon-meaningful))
 
 Additional SVG properties will be passed to the Twig template for the asset itself:
 

src/components/icon/icon.twig

@@ -1,4 +1,4 @@
-{% set fallback = fallback|default('close') %}
+{% set fallback = fallback|default('x') %}
 
 {% set _dir = '@cloudfour/assets/icons/' %}
 {% set _ext = '.svg.twig' %}
@@ -15,6 +15,20 @@
   {% set _class = _class ~ ' ' ~ class %}
 {% endif %}
 
-{% include [ _path, _fallback_path ] with {
-  class: _class,
-} %}
+{% if title %}
+  {% set _role = role ?? 'img' %}
+  {% embed [ _path, _fallback_path ] with {
+    class: _class,
+    role: _role,
+  } %}
+    {% block before %}
+      <title>{{title}}</title>
+    {% endblock %}
+  {% endembed %}
+{% else %}
+  {% set _aria_hidden = aria_hidden ?? 'true' %}
+  {% include [ _path, _fallback_path ] with {
+    class: _class,
+    aria_hidden: _aria_hidden,
+  } %}
+{% endif %}

src/objects/rhythm/demo/article.twig

@@ -43,17 +43,11 @@
         <p>This is similar to <a href="http://sonspring.com/">Nathan Smith’s</a> <a href="http://adapt.960.gs/">Adaptive.js</a> library which puts breakpoints in JavaScript instead of CSS.</p>
         <p>So by definition, Google Plus is not a responsive web design. It may look like one, but it doesn’t contain the three technical pieces necessary to be a responsive web design.</p>
         <p>
-          {% embed '@cloudfour/components/button/button.twig' with {
-            href: 'https://cloudfour.com/thinks/defining-responsiveness/'
+          {% include '@cloudfour/components/button/button.twig' with {
+            href: 'https://cloudfour.com/thinks/defining-responsiveness/',
+            label: 'Full article',
+            content_end_icon: 'arrow-right'
           } only %}
-            {% block content %}
-              Full article
-              {% include '@cloudfour/components/icon/icon.twig' with {
-                name: 'arrow-right',
-                inline: true
-              } only %}
-            {% endblock %}
-          {% endembed %}
         </p>
       {% endblock %}
     {% endembed %}