Description
We currently use custom icon
and svg
macros to reference user interface buttons in the docs.
AsciiDoc syntax:
Click icon:settings[name="Settings"] to configure your settings.
Click svg:ROOT:ui/icons/vector.svg[role="icon",name="Search"] to run a similarity search.
Generated HTML:
<p>Click <i class="icon-settings" aria-hidden='true'></i> <b>Settings</b> to configure your settings.</p>
<p>Click <svg class="inline-block icon" aria-hidden='true' width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd"
d="M17.68 14H16.89L16.61 13.73C17.59 12.59 18.18 11.11 18.18 9.5C18.18 5.91 15.27 3 11.68 3C8.25996 3 5.45996 5.64 5.20996 9H7.22996C7.47996 6.75 9.35996 5 11.68 5C14.17 5 16.18 7.01 16.18 9.5C16.18 11.99 14.17 14 11.68 14C11.5552 14 11.4357 13.9838 11.3138 13.9673C11.2696 13.9613 11.2252 13.9553 11.18 13.95V15.97C11.35 15.99 11.51 16 11.68 16C13.29 16 14.77 15.41 15.91 14.43L16.18 14.71V15.5L21.18 20.49L22.67 19L17.68 14ZM3 16.5859L12.293 7.29297L13.7072 8.70718L4.41436 18H6V20H1V15H3V16.5859Z"
fill="currentColor" />
</svg> <b>Search</b> to run a similarity search.</p>
Rendered output:
These macros help us enforce the Google Developer Documentation Style Guide's recommendations for buttons (placing the icon inline with the text, immediately followed by the name of the button in bold):
However, in our current CSS, icons render with a different color than the icon name
that's wrapped in a <b>
(bold) tag. We currently style bold font in pure white and pure black. This creates a minor but noticeable discontinuity when bold text is next to an icon (more obvious in light mode). This discontinuity diminishes the icon:

Recommended solutions
We currently style all text inside a <p>
tag to text.secondary
, and <b>
tags get text.primary
. Since it would be ideal for icons to inherit the text color from their parent, we could either:
- Remove
text.primary
from<b>
and<strong>
tags. (Bold font will be gray/off-white just like regular text and icons.) - Remove
text.secondary
from<p>
tags. (All regular text, bold text, and icons will go back to being black/white like it was before, instead of the gray/off-white that was introduced in New design tokens #169.