Hds::Icon - Add support for predefined "foreground" colors in@color argument

packages/components/src/components/hds/icon/index.hbs

@@ -9,7 +9,7 @@
   aria-hidden="{{if @title 'false' 'true'}}"
   aria-labelledby={{this.ariaLabelledby}}
   data-test-icon={{@name}}
-  fill="{{this.color}}"
+  fill="{{this.fillColor}}"
   id={{this.iconId}}
   role={{this.role}}
   width="{{this.svgSize.width}}"

packages/components/src/components/hds/icon/index.ts

@@ -7,14 +7,16 @@ import Component from '@glimmer/component';
 import { guidFor } from '@ember/object/internals';
 import { assert } from '@ember/debug';
 import { iconNames } from '@hashicorp/flight-icons/svg';
-import { HdsIconSizeValues } from './types.ts';
-import type { HdsIconSizes } from './types';
+import { HdsIconSizeValues, HdsIconColorValues } from './types.ts';
+import type { HdsIconSizes, HdsIconColors } from './types';
 import type { IconName } from '@hashicorp/flight-icons/svg';
 
+export const AVAILABLE_COLORS: string[] = Object.values(HdsIconColorValues);
+
 export interface HdsIconSignature {
   Args: {
     name: IconName;
-    color?: string;
+    color?: HdsIconColors | string | undefined;
     size?: HdsIconSizes;
     stretched?: boolean;
     isInline?: boolean;
@@ -24,6 +26,9 @@ export interface HdsIconSignature {
 }
 
 export default class HdsIcon extends Component<HdsIconSignature> {
+  iconId = 'icon-' + guidFor(this);
+  titleId = 'title-' + guidFor(this);
+
   constructor(owner: unknown, args: HdsIconSignature['Args']) {
     super(owner, args);
 
@@ -40,11 +45,23 @@ export default class HdsIcon extends Component<HdsIconSignature> {
     return this.args.isInline ?? false;
   }
 
-  get color(): string {
-    return this.args.color ?? 'currentColor';
+  get predefinedColor(): HdsIconColors | undefined {
+    const { color } = this.args;
+
+    if (color && AVAILABLE_COLORS.includes(color)) {
+      return color as HdsIconColors;
+    } else {
+      return undefined;
+    }
   }
 
-  iconId = 'icon-' + guidFor(this);
+  get fillColor(): string {
+    if (this.predefinedColor !== undefined) {
+      return 'currentColor';
+    } else {
+      return this.args.color ?? 'currentColor';
+    }
+  }
 
   get size(): string {
     return this.args.size ?? HdsIconSizeValues.Sixteen;
@@ -57,8 +74,6 @@ export default class HdsIcon extends Component<HdsIconSignature> {
     };
   }
 
-  titleId = 'title-' + guidFor(this);
-
   get title(): string | null {
     return this.args.title ?? null;
   }
@@ -82,6 +97,11 @@ export default class HdsIcon extends Component<HdsIconSignature> {
       classes.push('hds-icon--is-inline');
     }
 
+    // add a (helper) class based on the @color argument (if pre-defined)
+    if (this.predefinedColor) {
+      classes.push(`hds-foreground-${this.predefinedColor}`);
+    }
+
     // add an extra class to control the animation (depends on the icon)
     if (['loading', 'running'].includes(name)) {
       classes.push(`hds-icon--animation-${name}`);

packages/components/src/components/hds/icon/types.ts

@@ -4,3 +4,27 @@ export enum HdsIconSizeValues {
 }
 
 export type HdsIconSizes = `${HdsIconSizeValues}`;
+
+export enum HdsIconColorValues {
+  Primary = 'primary',
+  Strong = 'strong',
+  Faint = 'faint',
+  Disabled = 'disabled',
+  HighContrast = 'high-contrast',
+  Action = 'action',
+  ActionHover = 'action-hover',
+  ActionActive = 'action-active',
+  Highlight = 'highlight',
+  HighlightOnSurface = 'highlight-on-surface',
+  HighlightHighContrast = 'highlight-high-contrast',
+  Success = 'success',
+  SuccessOnSurface = 'success-on-surface',
+  SuccessHighContrast = 'success-high-contrast',
+  Warning = 'warning',
+  WarningOnSurface = 'warning-on-surface',
+  WarningHighContrast = 'warning-high-contrast',
+  Critical = 'critical',
+  CriticalOnSurface = 'critical-on-surface',
+  CriticalHighContrast = 'critical-high-contrast',
+}
+export type HdsIconColors = `${HdsIconColorValues}`;

showcase/app/routes/components/icon.js

@@ -1,3 +1,11 @@
 import Route from '@ember/routing/route';
 
-export default class IconRoute extends Route {}
+import { AVAILABLE_COLORS } from '@hashicorp/design-system-components/components/hds/icon/index';
+
+export default class IconRoute extends Route {
+  model() {
+    return {
+      AVAILABLE_COLORS,
+    };
+  }
+}

showcase/app/styles/showcase-pages/icon.scss

@@ -26,4 +26,10 @@ body.components-icon {
     gap: 4px;
     align-items: center;
   }
+
+  .shw-component-icon-sample-color--high-contrast {
+    width: fit-content;
+    background: #0c0c0e;
+    outline: 2px solid #0c0c0e;
+  }
 }

showcase/app/templates/components/icon.hbs

@@ -42,46 +42,71 @@
     </SF.Item>
   </Shw::Flex>
 
-  <Shw::Divider @level={{2}} />
+  <Shw::Divider />
 
   <Shw::Text::H2>Color</Shw::Text::H2>
 
+  <Shw::Text::H4 @tag="h3">Color inheritance</Shw::Text::H4>
   <Shw::Flex @direction="column" as |SF|>
     <SF.Item as |SFI|>
-      <SFI.Label>Unspecified color (<code>currentColor</code>)</SFI.Label>
-      <Hds::Icon @name="bookmark" />
+      <SFI.Label>unspecified color (<code>currentColor</code>)</SFI.Label>
+      <div>
+        <Hds::Icon @name="lock-fill" @size="24" />
+      </div>
     </SF.Item>
-    <SF.Item as |SFI|>
-      <SFI.Label>Custom red color, specified via <code>@color</code> argument</SFI.Label>
-      <Hds::Icon @name="folder-fill" @color="red" />
+    <SF.Item as |SGI|>
+      <SGI.Label>parent with <code>#e12568</code> color</SGI.Label>
+      <div {{style color="#e12568"}}>
+        <Hds::Icon @name="lock-fill" @size="24" />
+      </div>
     </SF.Item>
-    <SF.Item as |SFI|>
-      <SFI.Label>Unspecified color (<code>currentColor</code>) + parent with custom blue color (to check inheritance)</SFI.Label>
-      <a {{style color="blue"}} href="#">
-        <Hds::Icon @name="external-link" />
-      </a>
+  </Shw::Flex>
+
+  <Shw::Divider @level={{2}} />
+
+  <Shw::Text::H4 @tag="h3">Pre-defined colors</Shw::Text::H4>
+  <Shw::Grid @columns={{5}} as |SG|>
+    {{#each this.model.AVAILABLE_COLORS as |color|}}
+      <SG.Item @label={{color}}>
+        <div class="shw-component-icon-sample-color--{{color}}">
+          <Hds::Icon @name="lock-fill" @color={{color}} @size="24" />
+        </div>
+      </SG.Item>
+    {{/each}}
+  </Shw::Grid>
+
+  <Shw::Divider @level={{2}} />
+
+  <Shw::Text::H4 @tag="h3">Custom colors</Shw::Text::H4>
+  <Shw::Flex @direction="column" as |SF|>
+    <SF.Item as |SGI|>
+      <SGI.Label><code>#e91e63</code></SGI.Label>
+      <Hds::Icon @name="lock-fill" @color="#e91e63" @size="24" />
     </SF.Item>
-    <SF.Item as |SFI|>
-      <SFI.Label>Custom orange color, specified via
-        <code>@color</code>
-        argument + parent with
-        <code>!important</code>
-        green color declared (to check overrides not working)</SFI.Label>
+    <SF.Item as |SGI|>
+      <SGI.Label><code>--token-color-palette-purple-400</code></SGI.Label>
+      <Hds::Icon @name="lock-fill" @color="var(--token-color-palette-purple-400)" @size="24" />
+    </SF.Item>
+    <SF.Item as |SGI|>
+      <SGI.Label><code>orange</code>
+        + parent with
+        <code>green !important</code>
+      </SGI.Label>
       {{! template-lint-disable no-inline-styles }}
       <div style="color:green !important">
-        <Hds::Icon @name="heart-fill" @color="orange" />
+        <Hds::Icon @name="lock-fill" @color="orange" @size="24" />
       </div>
       {{! template-lint-enable no-inline-styles }}
     </SF.Item>
   </Shw::Flex>
 
-  <Shw::Divider @level={{2}} />
+  <Shw::Divider />
 
   <Shw::Text::H2>Display</Shw::Text::H2>
 
   {{#let (array false true) as |booleans|}}
     {{#each booleans as |isInline|}}
-      <Shw::Text::Body>{{if isInline "Inline" "Block (default)"}}</Shw::Text::Body>
+      <Shw::Text::H4 @tag="h3">{{if isInline "Inline" "Block (default)"}}</Shw::Text::H4>
 
       <Shw::Flex class="shw-foundation-outline-icons" as |SF|>
         <SF.Item @label="single icon">

website/docs/components/icon/partials/code/component-api.md

@@ -4,12 +4,12 @@
   <C.Property @name="name" @type="string" @required="true">
     The name of the icon you wish to use. If the value does not match an existing icon name, an error will be thrown. Search for existing icon names in [the Icon library](/icons/library).
   </C.Property>
-  <C.Property @name="color" @type="string" @default="currentColor">
-    The `@color` argument can be used to change the color. It works by setting the value of the icon SVG’s `fill` property.
-  </C.Property>
   <C.Property @name="size" @type="number" @default="16" @values={{array "16" "24"}}>
     Sets the size of the icon in pixels. Only two sizes are supported. (Setting a non-standard size will cause the SVG to render at the specified size but it will be invisible.)
   </C.Property>
+  <C.Property @name="color" @type="string | CSS color" @values={{array "primary" "strong" "faint" "disabled" "high-contrast" "action" "action-hover" "action-active" "highlight" "highlight-on-surface" "highlight-high-contrast" "success" "success-on-surface" "success-high-contrast" "warning" "warning-on-surface" "warning-high-contrast" "critical" "critical-on-surface" "critical-high-contrast" }}>
+    The color of the icon expressed as one of the possible [foreground color](/foundations/colors?tab=palette#foreground-1) names. As a fallback solution to handle special cases, a valid CSS color string (hex, rgb, rgba, etc.) is also accepted (in this case it works by setting the value of the icon SVG’s `fill` property). If no `@color` argument is provided, the component will inherit its color from the parent container/context (`fill="currentColor"`).
+  </C.Property>
   <C.Property @name="stretched" @type="boolean" @default="false">
     Determines whether the icon will stretch to fill the parent container. Setting it to `true` will make the icon have a height and width of 100%.
   </C.Property>

website/docs/components/icon/partials/code/how-to-use.md

@@ -36,13 +36,21 @@ The default size is 16px. To use the alternative 24px icon size, set the `@size`
 
 ### Color
 
-The default value is `currentColor` which uses the inherited text color as the icon color. When setting a custom value, we recommend using one of the pre-defined variables to ensure consistency with our design language:
+The default value is `currentColor` which uses the inherited text color as the icon color. When setting a custom value, we recommend using one of the pre-defined **foreground** color variables to ensure consistency with our design language:
 
 ```handlebars
-<Hds::Icon @name="zap" @color="var(--token-color-foreground-success)" />
+<Hds::Icon @name="zap" @color="success" />
 ```
 
-Other accepted values include named colors and color values themselves (e.g., hex, rgb, etc).
+For the list of possible foreground colors supported, refer to the [Component API](#component-api) section for details.
+
+It’s also possible to provide a CSS color as a string (in this case the color will be applied as SVG `fill` property). The string can be a CSS `var()` that uses one of the [predefined color tokens](/foundations/colors?tab=palette):
+
+```handlebars
+<Hds::Icon @name="zap" @color="var(--token-color-boundary-brand)" />
+```
+
+Or it can be one of the standard CSS color formats (hex, rgb, rgba, hsl, named color, etc.):
 
 ```handlebars
 <Hds::Icon @name="zap" @color="rebeccapurple" />
@@ -52,6 +60,12 @@ Other accepted values include named colors and color values themselves (e.g., he
 <Hds::Icon @name="zap" @color="rgb(46, 113, 229)" />
 ```
 
+!!! Warning
+
+We don’t validate the CSS color string to ensure that the value used is correct.
+
+!!!
+
 ### Stretched
 
 To have the icon fill the parent container (width: 100%, height: 100%), set the `@stretched` attribute to true: