Merge pull request #81 from dmarcey/users/dmarcey/a11y

Fixing a few accessibility issues in theme and docs package

Author: dmarcey

docs/content/components/caption.mdx

@@ -8,7 +8,9 @@ The caption component can be used to append a caption to images used in document
 
 ```jsx live
 <Flex alignItems="center" flexDirection="column">
-  <img src="https://s3.us-west-2.amazonaws.com/photos.puppyspot.com/breeds/245/card/500000291_medium.jpg" />
+  <img alt="" src="https://s3.us-west-2.amazonaws.com/photos.puppyspot.com/breeds/245/card/500000291_medium.jpg" />
   <Caption>A beautiful husky puppy.</Caption>
 </Flex>
 ```
+
+_Note: Be sure to provide enough detail in your caption so users with assistive technology have adequate context. An empty alt tag `alt=""` should be used on the `img` in cases where the caption describes the image, thus making the image decorative in purpose.

docs/content/components/do-dont.mdx

@@ -11,37 +11,37 @@ The `Do` and `Dont` components are used for providing good and bad examples with
 To use these components in your MDX files, import them like so:
 
 ```js
-import {DoDont, Do, Dont} from '@primer/gatsby-theme-doctocat'
+import {DoDontContainer, Do, Dont} from '@primer/gatsby-theme-doctocat'
 ```
 
 ### Side-by-side
 
-To create a side-by-side Do/Don't example, wrap the `Do` and `Dont` components with the `DoDont` component:
+To create a side-by-side Do/Don't example, wrap the `Do` and `Dont` components with the `DoDontContainer` component:
 
 ```jsx live
-<DoDont>
+<DoDontContainer>
   <Do src="https://user-images.githubusercontent.com/586552/63106528-06de5100-bf51-11e9-8a5e-98583ed74874.png">
     Use brief and direct communication
   </Do>
   <Dont src="https://user-images.githubusercontent.com/586552/63106527-06de5100-bf51-11e9-858c-72de6a5c728a.png">
     Don't use wordy and redundant copy
   </Dont>
-</DoDont>
+</DoDontContainer>
 ```
 
-_Note: Caption text should describe the image and be able to stand on its own._
+_Note: Caption text should describe the image and be able to stand on its own. The `alt` prop should be used if a more detailed description of the image is needed._
 
 ### Stacked
 
-The `DoDont` component also accepts a `stacked` prop to create stacked Do/Don't examples:
+The `DoDontContainer` component also accepts a `stacked` prop to create stacked Do/Don't examples:
 
 ```jsx live
-<DoDont stacked>
+<DoDontContainer stacked>
   <Do src="https://user-images.githubusercontent.com/586552/63046880-46e5fb00-bea1-11e9-836d-be1b1c7d963f.png">
     Use a container class to give the text a max-width
   </Do>
   <Dont src="https://user-images.githubusercontent.com/586552/63046881-46e5fb00-bea1-11e9-87ee-80dbeb0bea1c.png">
     Don't let the text span the entire width of the window
   </Dont>
-</DoDont>
+</DoDontContainer>
 ```

theme/index.js

@@ -1,7 +1,7 @@
 export {default as Caption} from './src/components/caption'
 export {default as Container} from './src/components/container'
 export {default as Contributors} from './src/components/contributors'
-export {Do, DoDont, Dont} from './src/components/do-dont'
+export {Do, DoDontContainer, Dont} from './src/components/do-dont'
 export {default as Frame} from './src/components/frame'
 export {default as Head} from './src/components/head'
 export {default as Header} from './src/components/header'

theme/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/gatsby-theme-doctocat",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "main": "index.js",
   "license": "MIT",
   "scripts": {

theme/src/components/do-dont.js

@@ -3,7 +3,7 @@ import {Check, X} from '@primer/octicons-react'
 import React from 'react'
 import Caption from './caption'
 
-export function DoDont({stacked, children}) {
+export function DoDontContainer({stacked, children}) {
   return (
     <Grid
       gridTemplateColumns={['1fr', null, stacked ? '1fr' : '1fr 1fr']}
@@ -15,50 +15,40 @@ export function DoDont({stacked, children}) {
   )
 }
 
-DoDont.defaultProps = {
+DoDontContainer.defaultProps = {
   stacked: false,
 }
 
-export function Do({src, children}) {
-  return (
-    <Flex flexDirection="column">
-      <Flex alignSelf="start" flexDirection="row" alignItems="center" mb="2">
-        <CircleOcticon
-          icon={Check}
-          size={16}
-          bg="green.5"
-          color="white"
-          mr="2"
-          p="1"
-        />
-        <Text fontWeight="bold" color="gray.9" ml="1">
-          Do
-        </Text>
-      </Flex>
-      <img src={src} width="100%" alt="" />
-      <Caption mb={0}>{children}</Caption>
-    </Flex>
-  )
+export function Do(props) {
+  return <DoDontBase {...props} text="Do" icon={Check} iconBg="green.5" />
 }
 
-export function Dont({src, children}) {
+export function Dont(props) {
+  return <DoDontBase {...props} text="Don't" icon={X} iconBg="red.5" />
+}
+
+function DoDontBase({src, alt, children, text, icon, iconBg}) {
   return (
     <Flex flexDirection="column">
       <Flex alignSelf="start" flexDirection="row" alignItems="center" mb="2">
         <CircleOcticon
-          icon={X}
+          icon={icon}
           size={16}
-          bg="red.5"
+          bg={iconBg}
           color="white"
           mr="2"
           p="1"
         />
         <Text fontWeight="bold" color="gray.9" ml="1">
-          Don't
+          {text}
         </Text>
       </Flex>
-      <img src={src} width="100%" alt="" />
+      <img src={src} alt={alt} width="100%" />
       <Caption mb={0}>{children}</Caption>
     </Flex>
   )
 }
+
+DoDontBase.defaultProps = {
+  alt: "",
+}

theme/src/components/heading.js

@@ -22,11 +22,18 @@ const StyledHeading = styled(Heading)`
 
 function MarkdownHeading({children, ...props}) {
   const slugger = new GithubSlugger()
-  const id = children ? slugger.slug(textContent(children)) : ''
+  const text = children ? textContent(children) : ''
+  const id = text ? slugger.slug(text) : ''
 
   return (
     <StyledHeading id={id} {...props}>
-      <Link href={`#${id}`} p={2} ml={-32} color="gray.8">
+      <Link
+        href={`#${id}`}
+        p={2}
+        ml={-32}
+        color="gray.8"
+        aria-label={`${text} permalink`}
+      >
         <StyledOcticon
           className="octicon-link"
           icon={LinkIcon}