Icon macro update

preview-src/asciidoc/images.adoc

@@ -1,4 +1,4 @@
-= Images and media
+= Images, icons, and media
 :idprefix:
 :idseparator: -
 :figure-caption!:
@@ -8,24 +8,24 @@
 == Block images
 
 .Optional title
-image::../img/screenshot.png[Screenshot of Astra Portal Home]
+image::../img/screenshot.png[alt="Screenshot of Astra Portal Home"]
 
 === Sizing and alignment
 
-.400px width, align="left"
-image::../img/screenshot.png[Screenshot of Astra Portal Home,400,align="left"]
+.width=400,align=left
+image::../img/screenshot.png[alt="Screenshot of Astra Portal Home",width=400,align=left]
 
-.400px width, align="right"
-image::../img/screenshot.png[Screenshot of Astra Portal Home,400,align="right"]
+.width=400 width,align=right
+image::../img/screenshot.png[alt="Screenshot of Astra Portal Home",width=400,align=right]
 
-.400px width, align="center"
-image::../img/screenshot.png[Screenshot of Astra Portal Home,400,align="center"]
+.width=400 width,align=center
+image::../img/screenshot.png[alt="Screenshot of Astra Portal Home",width=400,align=center]
 
 === Float
 
 [.float-group]
 --
-image:../img/screenshot.png[Screenshot of Astra Portal Home,300,float=right,role=float-gap]
+image:../img/screenshot.png[alt="Screenshot of Astra Portal Home",300,float=right,role=float-gap]
 In AsciiDoc, creating paragraphs is a straightforward process that does not require any special markup. A paragraph can be defined as one or more lines of consecutive text that are logically grouped together. To differentiate between paragraphs, you simply need to insert at least one blank line between them.
 --
 
@@ -35,149 +35,262 @@ image::../img/multirepo-ssg.svg[Multirepo SSG,300,float=left,role=float-gap]
 In AsciiDoc, creating paragraphs is a straightforward process that does not require any special markup. A paragraph can be defined as one or more lines of consecutive text that are logically grouped together. To differentiate between paragraphs, you simply need to insert at least one blank line between them.
 --
 
-== Inline images
-
-Click image:../img/play_circle_FILL0_wght400_GRAD0_opsz24.svg[title=Play] to get the party started.
+=== Light and dark mode images
 
-Click image:../img/pause_circle_FILL0_wght400_GRAD0_opsz24.svg[title=Pause] when you need a break.
+You can make an image appear differently in light mode vs. dark mode.
 
-== Image theming (light/dark mode)
+==== Two separate images
 
 [NOTE]
-======
-You can define an image such that it appears differently in light mode vs. dark mode.
-There are methods for doing this.
+====
+Define two images: one that looks good in light mode, and one that looks good in dark mode.
+Then, assign the corresponding `for-light` and `for-dark` roles to each image.
+
+* All non-SVG images, such as screenshot PNG files, must use this method.
+* All SVG images that do not use <<svg-images-css,CSS variables>> must use this method.
 
-Method 1: Two separate images::
-Define two images, one that looks good in light mode and one that looks good in dark mode.
-Assign the corresponding roles -- `for-light` and `for-dark` -- to each image.
-+
-All non-SVG images, such as screenshot PNG files, must use this method.
-All SVG images that do not use CSS variables must also use this method.
-+
-.block image
-[source,asciidoc]
-----
-image::light-mode-illustration.png[Alt text,400,role=for-light]
-image::dark-mode-illustration.png[Alt text,400,role=for-dark]
-----
-+
-.inline image
 [source,asciidoc]
 ----
-Click the Astra Vector icon image:../img/astra-vector-light.svg[title="Astra Vector",role=for-light] image:../img/astra-vector-dark.svg[title="Astra Vector",role=for-dark].
+image::vector-ui-light.png[alt="Alt text",width=400,role=for-light]
+image::vector-ui-dark.png[alt="Alt text",width=400,role=for-dark]
 ----
+====
 
-Method 2: SVG image with CSS variables::
+image::../img/vector-ui-light.png[alt="Alt text",width=400,role=for-light]
+image::../img/vector-ui-dark.png[alt="Alt text",width=400,role=for-dark]
+
+[#svg-images-css]
+==== SVG images with CSS variables
+
+[NOTE]
+======
 Use the custom `svg` macro to define an SVG image that uses CSS variables to support light and dark mode.
-+
-.block svg
-[source,asciidoc]
-----
-svg::ROOT:illustration.svg[Alt text,400]
-----
-+
-.inline svg
+
 [source,asciidoc]
 ----
-Click the Astra Vector icon svg:ROOT:your-diagram.svg[title="Astra Vector"].
+svg::ROOT:illustration.svg[alt="Alt text",width=400]
+svg::ROOT:illustration.svg[Alt text,400,275]
 ----
-+
+
+The `svg` macro supports the following attributes: `width`, `height`, `role`, `alt`, `ariaLabel` and `title`.
+
 [IMPORTANT]
 ====
 CSS variables must use the tokens supported by the UI.
 For example:
 
-[source,svg]
+[source,svg,subs="+quotes"]
 ----
 <svg viewBox="0 0 300 200" fill="none">
-  <path fill="var(--ds-text-primary)" d="..." />
-  <path stroke="var(--ds-primary-outlined-border)" d="..." />
-  <path fill="var(--ds-neutral-outlined-border)" d="..." />
+  <path fill="**var(--ds-text-primary)**" d="..." />
+  <path stroke="**var(--ds-primary-outlined-border)**" d="..." />
+  <path fill="**var(--ds-neutral-outlined-border)**" d="..." />
 </svg>
 ----
 ====
 ======
 
-.themed block image
-image::../img/light-mode-illustration.png[Alt text,400,role=for-light]
+// svg::../img/quickstart-overview.svg[]
 
-.themed block image
-image::../img/dark-mode-illustration.png[Alt text,400,role=for-dark]
+[#icons]
+== Icons
 
-.themed inline image
-Click the Astra Vector icon image:../img/astra-vector-light.svg[title="Astra Vector",role=for-light] image:../img/astra-vector-dark.svg[title="Astra Vector",role=for-dark].
+You can add icons in line with text and other elements.
 
-== Icons
+[#font-icons]
+=== Font icons
 
 [NOTE]
 ======
-You can define icons from https://fonts.google.com/icons?icon.set=Material+Icons&icon.style=Outlined[Material Icons,window=_blank] and https://lucide.dev/icons/[Lucide Icons,window=_blank]. You can also apply an svg file using the customized `icon` macro.
+Use the `icon` macro to invoke font icons from https://lucide.dev/icons/[Lucide Icons] and https://fonts.google.com/icons[Material Icons].
+The `icon` macro follows https://developers.google.com/style/ui-elements#buttons[accessibility standards] and provides built-in support for light and dark mode.
 
-Method 1: Inline icon macro with an svg file::
-The customized inline icon macro accepts a file path as it's target source. The file must be an svg file.
-+
-This methods supports using CSS variables within the svg.
-+
-[source]
+Lucide is the default icon set.
+You can invoke a Lucide icon with either `\icon:ICON-NAME[]` or `\icon:lucide:ICON-NAME[]`:
+
+.Lucide
+[source,asciidoc]
 ----
-icon:ROOT:ui/icons/vector.svg[]
+Click icon:settings[name="Settings"] to configure your settings. // <.>
+
+icon:moon[alt="That's no moon"] // <.>
+
+icon:sun[ariaLabel="Day time"] // <.>
+
+icon:atom[title="Split the atom"] // <.>
+
+icon:star[role="text-failure text-2xl"] // <.>
+
+icon:star[size="60"] or icon:star[60] // <.>
 ----
 
-Method 2: Inline icon macro with a material-icons target::
-The customized inline icon macro supports material icon names as it's target source prefixed with `material-icons:`. Ensure the name is lower case with underscores instead of spaces.
+<.> Use the `name` attribute to add visible text to the right of the icon.
+
+<.> Use the `alt` attribute to define an `aria-label` for the icon.
+The text is invisible but is read by screen readers.
 +
-This macro does not yet support Lucide icons.
+_Do not use `alt` if `name` or `ariaLabel` is already defined._
+
+<.> Identical to the `alt` attribute.
 +
-This method supports light and dark mode automatically.
+_Do not use `ariaLabel` if `name` or `alt` is already defined._
+
+<.> The `title` attribute provides a visible tooltip on hover for pointer devices (not visible on touch devices).
 +
-[source]
+_The `title` attribute is not read by most screen readers, and therefore its use is discouraged._
+_If used, make sure to also define `alt` or `ariaLabel` to ensure accessibility._
+
+<.> Use the `role` attribute to apply Tailwind CSS classes to the icon.
+
+<.> Use the `size` attribute to define the size of the icon in pixels.
+Alternatively, you can define the size in the first https://docs.asciidoctor.org/asciidoc/latest/attributes/positional-and-named-attributes/#positional[positional attribute] (shorthand for the `size` attribute).
+
+You can invoke a Material icon with `\icon:material:icon-name[]`.
+All of the same attributes apply:
+
+.Material
+[source,asciidoc]
 ----
-icon:material-icons:thumb_up[]
+Click icon:material:settings[name="Settings"] to configure your settings.
+
+icon:material:air[alt="Whooosh"]
+
+icon:material:volume-up[title="Turn it up"]
+
+icon:material:directions-boat[role="text-warning text-2xl"]
+
+icon:material:thumb-up[size=60]
 ----
 
-Method 3: material-icons role::
-Use the custom role `material-icons` on block or inline content. The content must be a material icon name in lower case. If there are spaces in the name, use underscores instead.
+.Legacy font icon methods
+[%collapsible]
+=====
+[WARNING]
+====
+These methods were previously used to invoke font icons and should no longer be used.
+====
+
+Block or inline span with material-icons role::
 +
+--
+Use the custom role `material-icons` on block or inline content. The content must be a material icon name in lower case. If there are spaces in the name, use underscores instead.
+
 This method supports light and dark mode automatically.
-+
+
 .block style
 [source]
 ----
 [.material-icons]
 thumb_up
 ----
-+
+
 .Inline style using a text span
 [source]
 ----
 Inline material icons [.material-icons]#thumb_up#
 ----
-+ 
+
 [.material-icons]#thumb_up# [.material-icons]#rocket_launch#
+--
 
-Method 4: Lucide icons with HTML passthrough::
-Use block or inline HTML passthrough to create an icon element `<i class="icon-{icon-name}"></i>`.
+HTML passthrough::
 +
+--
+Use block or inline HTML passthrough to create an icon element `<i class="icon-ICON-NAME"></i>`.
+
 This method supports light and dark mode automatically.
-+
+
 .Block passthrough
 [source]
 ----
 ++++
 <i class="icon-boom-box"></i>
 ++++
 ----
-+
+
 .Inline passthrough
 [source]
 ----
 Inline lucide icons +++<i class="icon-boom-box"></i>+++
 ----
-+
+
 +++<i class="icon-boom-box"></i>+++ +++<i class="icon-atom"></i>+++ +++<i class="icon-moon"></i>+++
+--
+=====
+======
+
+// Lucide::
+// +
+// Click icon:settings[name="Settings"] to configure your settings.
+// +
+// icon:moon[alt="That's no moon"]
+// +
+// icon:atom[title="Split the atom"]
+// +
+// icon:star[role="text-failure text-2xl"]
+// +
+// icon:star[size="60"]
+
+// Material::
+// +
+// Click icon:material:settings[name="Settings"] to configure your settings.
+// +
+// icon:material:air[alt="Whooosh"]
+// +
+// icon:material:volume-up[title="Turn it up"]
+// +
+// icon:material:directions-boat[role="text-warning text-2xl"]
+// +
+// icon:material:thumb-up[size=60]
+
+=== SVG icons
+
+[NOTE]
 ======
+Use the inline `svg` macro to display a local SVG file as an icon.
 
+[source,asciidoc]
+----
+svg:ROOT:ui/icons/vector.svg[role="icon"] // <.>
+
+Click svg:ROOT:ui/icons/vector.svg[role="icon"] *Search* to run a similarity search based on the selected document's vector.
+
+svg:ROOT:ui/icons/vector.svg[role="icon text-2xl"] // <.>
+
+svg:ROOT:ui/icons/vector.svg[width="60",height="60"] // <.>
+----
+
+<.> The `icon` role adds CSS styles that set the width and height of the image to an appropriate size relative to the font size of the parent element.
+Without the `icon` role, the image displays as large as possible unless a width and height is set in the SVG file itself (not recommended).
+
+<.> Manually control the icon size using Tailwind `text-*` utilities, such as `text-2xl`.
+
+<.> Manually control the icon size using the `width` and `height` attributes.
+
+[IMPORTANT]
+====
+Unlike <<font-icons,font icons>>, the `svg` macro doesn't automatically support light and dark mode.
+You'll need to add supported <<svg-images-css,CSS variables>> to the SVG file for the icon to display properly in light and dark mode.
+
+If the svg is a simple, single-color icon, you can use `currentColor` for all fill and stroke colors.
+This will automatically inherit the text color of the parent element or the body text color which is black or white depending on the theme.
+====
+======
+
+// Click svg:ROOT:ui/icons/vector.svg[role="icon"] *Search* to run a similarity search based on the selected document's vector.
+
+[#inline-images]
+== Inline images
+
+[IMPORTANT]
+====
+Avoid using inline images.
+Use <<icons>> instead.
+====
+
+Click image:../img/play_circle_FILL0_wght400_GRAD0_opsz24.svg[title=Play] to get the party started.
+
+Click image:../img/pause_circle_FILL0_wght400_GRAD0_opsz24.svg[title=Pause] when you need a break.
 
 == Video