ENH: Add img-alt for card and grid-item-card (#114)

Co-authored-by: Chris Holdgraf <[email protected]>

Author: jpmckinney

docs/cards.md

@@ -84,6 +84,7 @@ You can also add an image as the background of a card or at the top/bottom of th
 :::{card} Title
 :img-background: images/particle_background.jpg
 :class-card: sd-text-black
+:img-alt: your desired alt text
 
 Text
 :::
@@ -92,6 +93,7 @@ Text
 
 ::::{grid-item-card} Title
 :img-top: images/particle_background.jpg
+:img-alt: your desired alt text
 
 Header
 ^^^
@@ -102,6 +104,7 @@ Footer
 
 ::::{grid-item-card} Title
 :img-bottom: images/particle_background.jpg
+:img-alt: your desired alt text
 
 Header
 ^^^
@@ -257,6 +260,9 @@ img-top
 img-bottom
 : A URI (relative file path or URL) to an image to be placed below the content.
 
+img-alt
+: Alternative text for the image (that will be used by screen-readers).
+
 link
 : Turn the entire card into a clickable link to an external/internal target.
 

docs/snippets/myst/card-images.txt

@@ -5,6 +5,7 @@
 :::{card} Title
 :img-background: images/particle_background.jpg
 :class-card: sd-text-black
+:img-alt: my text
 
 Text
 :::
@@ -13,6 +14,7 @@ Text
 
 ::::{grid-item-card} Title
 :img-top: images/particle_background.jpg
+:img-alt:
 
 Header
 ^^^

docs/snippets/rst/card-images.txt

@@ -5,11 +5,13 @@
         .. card:: Title
             :img-background: images/particle_background.jpg
             :class-card: sd-text-black
+            :img-alt: my text
 
             Text
 
     .. grid-item-card:: Title
         :img-top: images/particle_background.jpg
+        :img-alt:
 
         Header
         ^^^

sphinx_design/cards.py

@@ -59,6 +59,7 @@ class CardDirective(SphinxDirective):
         "img-top": directives.uri,
         "img-bottom": directives.uri,
         "img-background": directives.uri,
+        "img-alt": directives.unchanged,
         "link": directives.uri,
         "link-type": make_choice(["url", "any", "ref", "doc"]),
         "link-alt": directives.unchanged,
@@ -96,13 +97,15 @@ def create_card(
         )
         inst.set_source_info(card)
 
+        img_alt = options.get("img-alt") or ""
+
         container = card
         if "img-background" in options:
             card.append(
                 nodes.image(
                     uri=options["img-background"],
                     classes=["sd-card-img"],
-                    alt="background image",
+                    alt=img_alt,
                 )
             )
             overlay = create_component("card-overlay", ["sd-card-img-overlay"])
@@ -114,7 +117,7 @@ def create_card(
             image_top = nodes.image(
                 "",
                 uri=options["img-top"],
-                alt="card-img-top",
+                alt=img_alt,
                 classes=["sd-card-img-top"] + options.get("class-img-top", []),
             )
             container.append(image_top)
@@ -156,7 +159,7 @@ def create_card(
             image_bottom = nodes.image(
                 "",
                 uri=options["img-bottom"],
-                alt="card-img-bottom",
+                alt=img_alt,
                 classes=["sd-card-img-bottom"] + options.get("class-img-bottom", []),
             )
             container.append(image_bottom)

sphinx_design/grids.py

@@ -223,6 +223,7 @@ class GridItemCardDirective(SphinxDirective):
         "img-background": directives.uri,
         "img-top": directives.uri,
         "img-bottom": directives.uri,
+        "img-alt": directives.unchanged,
         "link": directives.uri,
         "link-type": make_choice(["url", "any", "ref", "doc"]),
         "link-alt": directives.unchanged,
@@ -266,6 +267,7 @@ def run(self) -> List[nodes.Node]:
                 "img-background",
                 "img-top",
                 "img-bottom",
+                "img-alt",
                 "link",
                 "link-type",
                 "link-alt",

tests/test_snippets/snippet_post_card-images.xml

@@ -6,7 +6,7 @@
             <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-3 sd-row-cols-md-3 sd-row-cols-lg-4" design_component="grid-row" is_div="True">
                 <container classes="sd-col sd-d-flex-column" design_component="grid-item" is_div="True">
                     <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-text-black" design_component="card" is_div="True">
-                        <image alt="background image" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img" uri="images/particle_background.jpg">
+                        <image alt="my text" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img" uri="images/particle_background.jpg">
                         <container classes="sd-card-img-overlay" design_component="card-overlay" is_div="True">
                             <container classes="sd-card-body" design_component="card-body" is_div="True">
                                 <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -16,7 +16,7 @@
                                     Text
                 <container classes="sd-col sd-d-flex-row" design_component="grid-item" is_div="True">
                     <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm" design_component="card" is_div="True">
-                        <image alt="card-img-top" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-top" uri="images/particle_background.jpg">
+                        <image alt="" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-top" uri="images/particle_background.jpg">
                         <container classes="sd-card-header" design_component="card-header" is_div="True">
                             <paragraph classes="sd-card-text">
                                 Header
@@ -43,4 +43,4 @@
                         <container classes="sd-card-footer" design_component="card-footer" is_div="True">
                             <paragraph classes="sd-card-text">
                                 Footer
-                        <image alt="card-img-bottom" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-bottom" uri="images/particle_background.jpg">
+                        <image alt="" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-bottom" uri="images/particle_background.jpg">

tests/test_snippets/snippet_pre_card-images.xml

@@ -6,7 +6,7 @@
             <container classes="sd-row sd-row-cols-2 sd-row-cols-xs-2 sd-row-cols-sm-3 sd-row-cols-md-3 sd-row-cols-lg-4" design_component="grid-row" is_div="True">
                 <container classes="sd-col sd-d-flex-column" design_component="grid-item" is_div="True">
                     <container classes="sd-card sd-sphinx-override sd-mb-3 sd-shadow-sm sd-text-black" design_component="card" is_div="True">
-                        <image alt="background image" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img" uri="images/particle_background.jpg">
+                        <image alt="my text" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img" uri="images/particle_background.jpg">
                         <container classes="sd-card-img-overlay" design_component="card-overlay" is_div="True">
                             <container classes="sd-card-body" design_component="card-body" is_div="True">
                                 <container classes="sd-card-title sd-font-weight-bold" design_component="card-title" is_div="True">
@@ -16,7 +16,7 @@
                                     Text
                 <container classes="sd-col sd-d-flex-row" design_component="grid-item" is_div="True">
                     <container classes="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm" design_component="card" is_div="True">
-                        <image alt="card-img-top" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-top" uri="images/particle_background.jpg">
+                        <image alt="" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-top" uri="images/particle_background.jpg">
                         <container classes="sd-card-header" design_component="card-header" is_div="True">
                             <paragraph classes="sd-card-text">
                                 Header
@@ -43,4 +43,4 @@
                         <container classes="sd-card-footer" design_component="card-footer" is_div="True">
                             <paragraph classes="sd-card-text">
                                 Footer
-                        <image alt="card-img-bottom" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-bottom" uri="images/particle_background.jpg">
+                        <image alt="" candidates="{'*': 'images/particle_background.jpg'}" classes="sd-card-img-bottom" uri="images/particle_background.jpg">