@double-great/alt-text - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

clues.js

 module.exports = {
+  notOnlySpace: {
+    heading: "Empty alt text",
+    warning: () => `Alt text should not be a single space`,
+    rationale:
+      'If you use null (empty) alt text (`alt=""`) to hide decorative images, make sure that there is no space character in between the quotes. **If a space character is present, the image may not be effectively hidden from assistive technologies.** For instance, some screen readers will still announce the presence of an image if a space character is put between the quotes.',
+    source: ["https://www.w3.org/WAI/tutorials/images/tips/#tips"],
+    ok: '`<img src="photo.png" alt="">`',
+    notOk: '`<img src="photo.png" alt=" ">`'
+  },
+  charLength: {
+    heading: "Character length",
+    warning: length =>
+      `Alt text length should be less than 125 characters${
+        length ? `, it is currently ${length} characters` : ""
+      }`,
+    rationale:
+      "Alt text should be less than 125 characters in length. The JAWS screen reader reads alt text in 125 character chunks. Any information about the image, such as copyright information, image source or extra information should be placed in the caption text below the image.",
+    source: [
+      "https://accessibility.psu.edu/images/imageshtml/#alt",
+      "https://terrillthompson.com/tests/altlength.html"
+    ],
+    ok:
+      "George Washington and Lafayette on horseback talking to soldiers in snow at Valley Forge.",
+    notOk:
+      "Caption: Painting “Washington and Lafayette at Valley Forge” by John Ward Dunsmore from 1907. Image courtesy of the Library of Congress."
+  },
+  imageLink: {
+    heading: "Image is link",
+    warning: () =>
+      `Images inside a link tag require alt text that describes the purpose of the link`,
+    rationale:
+      "Images inside a link tag require alt text that describes the purpose of the link.",
+    source: ["https://axesslab.com/alt-texts/#images-in-links"],
+    ok:
+      '`<a href="https://github.com/double-great"><img src="logo.png" alt="double great on GitHub"></a>`',
+    notOk:
+      '`<a href="https://github.com/double-great"><img src="logo.png" alt="double great logo"></a>`'
+  },
+  endPeriod: {
+    heading: "End in a period",
+    warning: () => `Alt text should end in a period`,
+    rationale:
+      "End the alt text with a period. This will make screen readers pause a bit after the last word in the alt text, which creates a more pleasant reading experience for the user.",
+    source: ["https://axesslab.com/alt-texts/#end-with-a-period"],
+    ok: "A child holding a photograph.",
+    notOk: "A child holding a photograph"
+  },
+  noAlt: {
+    heading: "Missing alt attribute",
+    warning: () => `Missing "alt" attribute`,
+    rationale:
+      "All images must have alternate text to convey their purpose and meaning to screen reader users.",
+    source: ["https://dequeuniversity.com/rules/axe/3.4/image-alt"],
+    ok: '`<img src="photograph.jpg" alt="A child holding a photograph.">`',
+    notOk: '`<img src="photograph.jpg">`'
+  },
   contains: {
+    heading: "Alt text contains unhelpful words",
     fn: (item, alt) => alt.includes(item),
-    message: value => `Alt text should not contain "${value}".`,
+    warning: value => `Alt text should not contain "${value}"`,
     rules: [
@@ -14,9 +71,19 @@ "picture of",
       "photographer:"
-    ]
+    ],
+    rationale:
+      "Screen readers announce the presence of an image before reading the alt text. Adding “picture of” or “photo of” is redundant in this context.",
+    source: [
+      "https://www.w3.org/WAI/tutorials/images/tips/#tips",
+      "https://axesslab.com/alt-texts/#dont-say-its-an-image"
+    ],
+    ok: "Dog jumping through a hoop.",
+    notOk: "Image of a dog jumping through a hoop."
   },
   exactMatch: {
+    heading: "Alt text is unhelpful",
     fn: (item, alt) => item == alt.trim(),
-    message: value => `Alt text should not be "${value}".`,
+    warning: value => `Alt text should not be "${value}"`,
     rules: [
       "image",
+      "icon",
       "graphic",
@@ -38,2 +105,3 @@ "photo",
       "blank",
+      "empty",
       "chart",
@@ -44,7 +112,16 @@ "table",
       "*"
-    ]
+    ],
+    rationale:
+      "Usually, there’s no need to include words like “image”, “icon”, or “picture” in the alt text. People who can see will know this already, and screen readers announce the presence of an image.",
+    source: [
+      "https://www.w3.org/WAI/tutorials/images/tips/#tips",
+      "https://axesslab.com/alt-texts/#dont-say-its-an-image"
+    ],
+    ok: "A child holding a photograph.",
+    notOk: "photograph"
   },
   endWith: {
+    heading: "Alt text should not end with",
     fn: (item, alt) => alt.endsWith(item),
-    message: value => `Alt text should not end with "${value}".`,
+    warning: value => `Alt text should not end with "${value}"`,
     rules: [
@@ -59,7 +136,12 @@ ".jpg",
       "graphic"
-    ]
+    ],
+    rationale: "A file name in alt text does not provide helpful context.",
+    source: ["https://axesslab.com/alt-texts/"],
+    ok: "A child holding a photograph.",
+    notOk: "photograph.jpg"
   },
   startWith: {
+    heading: "Alt text should not start with",
     fn: (item, alt) => alt.startsWith(item),
-    message: value => `Alt text should not start with "${value}".`,
+    warning: value => `Alt text should not start with "${value}"`,
     rules: [
@@ -74,4 +156,20 @@ "picture",
       "spacer"
-    ]
+    ],
+    rationale:
+      "Usually, there’s no need to include words like “image”, “icon”, or “picture” in the alt text. People who can see will know this already, and screen readers announce the presence of an image.",
+    source: [
+      "https://www.w3.org/WAI/tutorials/images/tips/#tips",
+      "https://axesslab.com/alt-texts/#dont-say-its-an-image"
+    ],
+    ok: "A child holding a photograph.",
+    notOk: "Image of a child."
+  },
+  decorative: {
+    heading: "Image is decorative",
+    warning: () => `Empty alt text should only be used for decorative images`,
+    rationale: `Provide "null" \`alt\` attributes (using \`alt=""\`) for images which do not provide information or do not require alternative text because the image is described in the page content. Some developers will mistakenly leave off the alt attribute altogether on images which they deem do not need alternatives. This is not helpful to assistive technology users because the assistive technology, such as screen reader, will often read the source attribute (i.e., file name) as the alternative text. To tell assistive technology to ignore an image, use a "blank alternative text" attribute: \`alt=""\`.`,
+    source: ["https://dequeuniversity.com/rules/axe/3.0/image-alt"],
+    ok: '`<img src="decorative-photo.jpg" alt="">`',
+    notOk: '`<img src="quarterly-earnings-chart.png" alt=""/>`'
   }
 };

index.js

 const rules = require("./rules");
 
 function altText(alt) {
+  if (!alt) return rules.createWarning("decorative");
   alt = alt.toLowerCase();
@@ -5,0 +6,0 @@ const warning = [

package.json

 {
   "name": "@double-great/alt-text",
-  "version": "0.1.0",
-  "description": "Check for common issues found in alt text and suggests improvements to improve accessibility.",
+  "version": "0.2.0",
+  "description": "Check for unhelpful alt text.",
   "main": "index.js",
@@ -10,3 +10,4 @@ "scripts": {
     "test": "tape tests/*.test.js",
-    "pretty-quick": "pretty-quick"
+    "pretty-quick": "pretty-quick",
+    "write-docs": "node scripts/write-docs.js && node scripts/url.js"
   },
@@ -23,14 +24,17 @@ "repository": {
   "homepage": "https://github.com/double-great/alt-text#readme",
-  "dependencies": {},
+  "dependencies": {
+    "cli-git.io": "^1.0.1",
+    "github-slugger": "^1.2.1"
+  },
   "devDependencies": {
     "babel-eslint": "^10.0.3",
     "eslint": "^6.8.0",
-    "husky": "^3.1.0",
+    "husky": "^4.2.1",
     "prettier": "^1.19.1",
     "pretty-quick": "^2.0.1",
-    "tape": "^4.12.1"
+    "tape": "^4.13.0"
   },
   "husky": {
     "hooks": {
-      "pre-commit": "pretty-quick --staged"
+      "pre-commit": "npm run write-docs && git add README.md && pretty-quick --staged && node scripts/url.js"
     }
@@ -40,3 +44,7 @@ },
     "test": "tests"
-  }
+  },
+  "keywords": [
+    "accessibility",
+    "alt text"
+  ]
 }

README.md

 # alt-text [![Build Status](https://travis-ci.com/double-great/alt-text.svg?branch=master)](https://travis-ci.com/double-great/alt-text)
 
+Check for unhelpful alt text.
+
 Alt text describes an image. This description provides context for people with low or no vision. The text is a fallback for users with images turned off or when an image fails to load.
@@ -31,10 +33,138 @@
 
-## References
+## Warnings
 
-- W3C alt text decision tree: https://www.w3.org/WAI/tutorials/images/decision-tree/
-- W3C alt text tips https://www.w3.org/WAI/tutorials/images/tips/
-- Axess Lab Ultimate Guide https://axesslab.com/alt-texts/
-- Shopify alt text https://polaris.shopify.com/content/alternative-text
-- WCAG 2.1 1.1.1 Non-text content https://webaim.org/standards/wcag/checklist#sc1.1.1
-- WCAG 2.1 2.4.4 Link purpose (in context) https://webaim.org/standards/wcag/checklist#sc2.4.4
-- Webaim WAVE documentation https://wave.webaim.org/api/docs?format=html
+<!-- this section is generated on commit !-->
+
+### Alt text contains unhelpful words
+
+Warning: `Alt text should not contain "graphic of, image of, photo of, photo:, photograph of, photographer:, picture of, screenshot of"`
+
+Screen readers announce the presence of an image before reading the alt text. Adding “picture of” or “photo of” is redundant in this context.
+
+- ✅ Dog jumping through a hoop.
+- 🚫 Image of a dog jumping through a hoop.
+
+Sources:
+
+- <https://www.w3.org/WAI/tutorials/images/tips/#tips>
+- <https://axesslab.com/alt-texts/#dont-say-its-an-image>
+
+### Alt text is unhelpful
+
+Warning: `Alt text should not be "*, alt, arrow, artwork, blank, bullet, button, chart, diagram, drawing, empty, graph, graphic, icon, image, logo, more, painting, photo, photograph, placeholder, spacer, table, temp"`
+
+Usually, there’s no need to include words like “image”, “icon”, or “picture” in the alt text. People who can see will know this already, and screen readers announce the presence of an image.
+
+- ✅ A child holding a photograph.
+- 🚫 photograph
+
+Sources:
+
+- <https://www.w3.org/WAI/tutorials/images/tips/#tips>
+- <https://axesslab.com/alt-texts/#dont-say-its-an-image>
+
+### Alt text should not end with
+
+Warning: `Alt text should not end with ".gif, .jpeg, .jpg, .png, .svg, .webp, graphic, image"`
+
+A file name in alt text does not provide helpful context.
+
+- ✅ A child holding a photograph.
+- 🚫 photograph.jpg
+
+Sources:
+
+- <https://axesslab.com/alt-texts/>
+
+### Alt text should not start with
+
+Warning: `Alt text should not start with "graphic, image, photo, photograph, photographer, picture, screenshot, spacer"`
+
+Usually, there’s no need to include words like “image”, “icon”, or “picture” in the alt text. People who can see will know this already, and screen readers announce the presence of an image.
+
+- ✅ A child holding a photograph.
+- 🚫 Image of a child.
+
+Sources:
+
+- <https://www.w3.org/WAI/tutorials/images/tips/#tips>
+- <https://axesslab.com/alt-texts/#dont-say-its-an-image>
+
+### Character length
+
+Warning: `Alt text length should be less than 125 characters`
+
+Alt text should be less than 125 characters in length. The JAWS screen reader reads alt text in 125 character chunks. Any information about the image, such as copyright information, image source or extra information should be placed in the caption text below the image.
+
+- ✅ George Washington and Lafayette on horseback talking to soldiers in snow at Valley Forge.
+- 🚫 Caption: Painting “Washington and Lafayette at Valley Forge” by John Ward Dunsmore from 1907. Image courtesy of the Library of Congress.
+
+Sources:
+
+- <https://accessibility.psu.edu/images/imageshtml/#alt>
+- <https://terrillthompson.com/tests/altlength.html>
+
+### Empty alt text
+
+Warning: `Alt text should not be a single space`
+
+If you use null (empty) alt text (`alt=""`) to hide decorative images, make sure that there is no space character in between the quotes. **If a space character is present, the image may not be effectively hidden from assistive technologies.** For instance, some screen readers will still announce the presence of an image if a space character is put between the quotes.
+
+- ✅ `<img src="photo.png" alt="">`
+- 🚫 `<img src="photo.png" alt=" ">`
+
+Sources:
+
+- <https://www.w3.org/WAI/tutorials/images/tips/#tips>
+
+### End in a period
+
+Warning: `Alt text should end in a period`
+
+End the alt text with a period. This will make screen readers pause a bit after the last word in the alt text, which creates a more pleasant reading experience for the user.
+
+- ✅ A child holding a photograph.
+- 🚫 A child holding a photograph
+
+Sources:
+
+- <https://axesslab.com/alt-texts/#end-with-a-period>
+
+### Image is decorative
+
+Warning: `Empty alt text should only be used for decorative images`
+
+Provide "null" `alt` attributes (using `alt=""`) for images which do not provide information or do not require alternative text because the image is described in the page content. Some developers will mistakenly leave off the alt attribute altogether on images which they deem do not need alternatives. This is not helpful to assistive technology users because the assistive technology, such as screen reader, will often read the source attribute (i.e., file name) as the alternative text. To tell assistive technology to ignore an image, use a "blank alternative text" attribute: `alt=""`.
+
+- ✅ `<img src="decorative-photo.jpg" alt="">`
+- 🚫 `<img src="quarterly-earnings-chart.png" alt=""/>`
+
+Sources:
+
+- <https://dequeuniversity.com/rules/axe/3.0/image-alt>
+
+### Image is link
+
+Warning: `Images inside a link tag require alt text that describes the purpose of the link`
+
+Images inside a link tag require alt text that describes the purpose of the link.
+
+- ✅ `<a href="https://github.com/double-great"><img src="logo.png" alt="double great on GitHub"></a>`
+- 🚫 `<a href="https://github.com/double-great"><img src="logo.png" alt="double great logo"></a>`
+
+Sources:
+
+- <https://axesslab.com/alt-texts/#images-in-links>
+
+### Missing alt attribute
+
+Warning: `Missing "alt" attribute`
+
+All images must have alternate text to convey their purpose and meaning to screen reader users.
+
+- ✅ `<img src="photograph.jpg" alt="A child holding a photograph.">`
+- 🚫 `<img src="photograph.jpg">`
+
+Sources:
+
+- <https://dequeuniversity.com/rules/axe/3.4/image-alt>

rules.js

 const clues = require("./clues");
+const urls = require("./urls");
 
-function filterClues(clue, alt) {
+function createWarning(ruleName, value) {
+  return `${clues[ruleName].warning(value)} (${urls[ruleName]}).`;
+}
+
+function filterClues(ruleName, clue, alt) {
   return clue.rules.reduce((arr, item) => {
-    if (clue.fn(item, alt)) arr.push(clue.message(item));
+    if (clue.fn(item, alt)) arr.push(createWarning(ruleName, item));
     return arr;
@@ -12,3 +17,4 @@ }, []);
   return Object.keys(clues).reduce((arr, item) => {
-    arr = [...arr, ...filterClues(clues[item], alt)];
+    if (clues[item].rules)
+      arr = [...arr, ...filterClues(item, clues[item], alt)];
     return arr;
@@ -19,11 +25,7 @@ }, []);
 function checkLength(alt) {
-  return alt.length > 100
-    ? [
-        `Alt text length should be less than 100 characters, it is currently ${alt.length} characters.`
-      ]
-    : [];
+  return alt.length > 125 ? [createWarning("charLength", alt.length)] : [];
 }
 
 function checkOnlySpace(alt) {
-  return alt == " " ? ["Alt text must not only contain a space."] : [];
+  return alt == " " ? [createWarning("notOnlySpace")] : [];
 }
@@ -33,3 +35,3 @@
   return !alt.endsWith(".") && alt.length > 1
-    ? ["Alt text should end in a period."]
+    ? [createWarning("endPeriod")]
     : [];
@@ -42,3 +44,4 @@ }
   checkOnlySpace,
-  checkPeriod
+  checkPeriod,
+  createWarning
 };

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17639

increased by66.86%

Number of lines in readme file

170

increased by325%

Worsened metrics

Dependency count

2

increased byInfinity%

Number of package files

7

decreased by-36.36%

Lines of code

234

decreased by-2.5%

Number of medium supply chain risk alerts

2

increased byInfinity%

Dependency changes

• + Addedcli-git.io@^1.0.1

• + Addedgithub-slugger@^1.2.1

• + Addedcli-git.io@1.0.1(transitive)

• + Addedgithub-slugger@1.5.0(transitive)