👌 IMPROVE: Add link-alt to fix card link accessibility (#89)

This PR adds the `link-alt` option to `card` (and `grid-item-card`) directives,
in order to assign a discernable name to the link (for screen readers).

As noted in #78, it may be ideal to add `aria-label/`aria-hidden` to the actual link `<a>` HTML element.
However, this would entail having to override aspects of the sphinx HTML builder.
Instead, we include the link alt text, but add a `sd-hide-link-text` CSS class, to set `font-size: 0`, to hide the text.
This solution was taken from https://stackoverflow.com/questions/471510/hide-text-using-css, and seemed to be the simplest solution.

fixes #78

docs/cards.md

@@ -135,13 +135,15 @@ Try hovering over then clicking on the cards below:
 
 :::{card} Clickable Card (external)
 :link: https://example.com
+:link-alt: example
 
 The entire card can be clicked to navigate to <https://example.com>.
 :::
 
 :::{card} Clickable Card (internal)
 :link: cards-clickable
 :link-type: ref
+:link-alt: cards-clickable
 
 The entire card can be clicked to navigate to the `cards-clickable` reference target.
 :::
@@ -261,6 +263,9 @@ link
 link-type
 : Type of link: `url` (default), `ref`, `doc`, `any`.
 
+link-alt
+: Alternative text for the link (that will be used by screen-readers).
+
 shadow
 : The size of the shadow below the card: `none`, `sm` (default), `md`, `lg`.
 

sphinx_design/cards.py

@@ -61,6 +61,7 @@ class CardDirective(SphinxDirective):
         "img-background": directives.uri,
         "link": directives.uri,
         "link-type": make_choice(["url", "any", "ref", "doc"]),
+        "link-alt": directives.unchanged,
         "shadow": make_choice(["none", "sm", "md", "lg"]),
         "class-card": directives.class_option,
         "class-header": directives.class_option,
@@ -159,25 +160,33 @@ def create_card(
 
         if "link" in options:
             link_container = PassthroughTextElement()
+            _classes = ["sd-stretched-link"]
+            _rawtext = options.get("link-alt") or ""
+            if options.get("link-alt"):
+                _classes.append("sd-hide-link-text")
             if options.get("link-type", "url") == "url":
                 link = nodes.reference(
-                    "",
+                    _rawtext,
                     "",
                     refuri=options["link"],
-                    classes=["sd-stretched-link"],
+                    classes=_classes,
                 )
+                if options.get("link-alt"):
+                    link.append(nodes.inline(_rawtext, _rawtext))
             else:
                 options = {
                     # TODO the presence of classes raises an error if the link cannot be found
-                    "classes": ["sd-stretched-link"],
+                    "classes": _classes,
                     "reftarget": options["link"],
                     "refdoc": inst.env.docname,
                     "refdomain": "" if options["link-type"] == "any" else "std",
                     "reftype": options["link-type"],
                     "refexplicit": True,
                     "refwarn": True,
                 }
-                link = addnodes.pending_xref("", nodes.inline(), **options)
+                link = addnodes.pending_xref(
+                    _rawtext, nodes.inline(_rawtext, _rawtext), **options
+                )
             inst.set_source_info(link)
             link_container += link
             container.append(link_container)

sphinx_design/grids.py

@@ -222,6 +222,7 @@ class GridItemCardDirective(SphinxDirective):
         "img-bottom": directives.uri,
         "link": directives.uri,
         "link-type": make_choice(["url", "any", "ref", "doc"]),
+        "link-alt": directives.unchanged,
         "shadow": make_choice(["none", "sm", "md", "lg"]),
         "class-item": directives.class_option,
         "class-card": directives.class_option,
@@ -262,6 +263,7 @@ def run(self) -> List[nodes.Node]:
                 "img-bottom",
                 "link",
                 "link-type",
+                "link-alt",
                 "shadow",
                 "class-card",
                 "class-body",

style/_button.scss

@@ -88,3 +88,7 @@
   z-index: 1;
   content: "";
 }
+
+.sd-hide-link-text {
+  font-size: 0;
+}