@hashicorp/design-system-components 0.0.13 → 0.0.14

package/.github/ISSUE_TEMPLATE/new-component-quest-issue-engineering-checklist.md

@@ -0,0 +1,78 @@
+---
+name: New Component Quest Issue/Engineering Checklist
+about: 'DS Team: Engineering Checklist for New Components'
+title: "[Quest] New Component: Component Name"
+labels: ''
+assignees: ''
+
+---
+
+This is the quest issue/engineering checklist for the COMPONENT_NAME Component. All new components will have their own feature branch, and any PR that adds an item from the checklist should target the feature branch, and not `main`. 
+
+## Pre-Flight Checklist
+Update this list and these links as appropriate.
+
+- [Component Doc](url_here): This file should exist before any code is written.
+- [FIGMA Design](url_here): Since we are trying to align the component API naming with the same terms used in the Figma file, it is likely useful to have a fairly stable Figma design before we create a component; it should definitely be finalized before the component ships, however. 
+- [Design System Website](https://design-system-website.vercel.app/?path=/story/example-introduction--page) (storybook of storybooks): use for reference, to consider existing features that we might need to replicate in the component.
+
+## Engineering Checklist 
+The engineering checklist has six parts: creating the feature branch, component template, component backing class, component style, tests, and documentation.
+
+### Component Creation
+
+- [ ] create new branch from main for the component.
+- [ ] create new component
+  - `ember generate component hds/COMPONENT_NAME/index --gc` (the component won't need to be invoked with index, it's just to put all the files in the correct place)
+  - if it's a variation on a component, then `hds/COMPONENT_NAME/VARIATION` instead of `index`
+- [ ] **component template**
+  - use semantic HTML
+  - the component should have a css class that is the same as the component (e.g. `hds/button` should have a class name of `hds-button` on the component, and additional CSS classes should start with this same class name.
+  - add `...attributes` unless doing so would be detrimental (e.g., a parent component and child component that both have ...attributes) 
+- [ ] **component class**
+  - use getters (vs template conditionals or constructors, if possible)
+  - write API comments in the JS doc way (copy from an existing DS component)
+  - use the same naming as the Figma file for the components API unless it conflicts with a pre-existing HTML attribute. If that is the case, document the difference in the comment.
+  - ensure that all existing functionality (from a Structure component) is accounted for in some way. If we are not providing existing functionality at all, it should be documented (along with the reason why). If we are providing temporary functionality, explain that it's temporary and why.
+  - check the [design system website](https://design-system-website.vercel.app/?path=/story/example-introduction--page) to see what kind of component functionality is being used across all products
+  - booleans should start with a verb (is/has/etc)
+  - assertion text should match the content style of the other components.
+  - goal is a terse invocation
+- [ ] **component style**
+  - create `component/COMPONENT_NAME.scss` in `app/styles` 
+  - add `@use` to `app/styles/@hashicorp/design-system-components.scss` (see existing code for precise syntax)
+  - use design tokens wherever possible, comment where they are not
+  - sizes should be in relative units
+  - line heights should be unitless
+- [ ] **testing**
+  - [ ] test basic functionality
+  - [ ] test defaults
+  - [ ] try not to repeat tests (i.e., don't have to test all sizes, all colors, etc.)
+  - [ ] test all accessibility attributes
+- [ ] **documentation**
+  - create component page `ember generate route components/COMPONENT_NAME --dummy`
+  - add link to `templates/index.hbs` page
+  - [ ] API docs
+  - [ ] Usage 
+  - [ ] Showcase 
+
+### Component Review
+
+Pre-review request checks:
+
+- [ ] make sure all tests pass (`ember s` then visit /tests; or `ember t -s`)
+- [ ] check for basic a11y on docs page: 
+  - keyboard navigation
+  - logical DOM order
+  - zoom up to 400% 
+  - color contrast
+  - (the axe-core browser plugin can run some basic tests and give immediate feedback) 
+- [ ] check page on browsers
+  - Chrome
+  - Firefox
+  - Safari
+  - Edge (once available) 
+
+When ready for review: 
+- [ ] add situationally appropriate reviewers
+- [ ] added instructions for reviewers in your PR, letting them know what kind of review you need

package/addon/components/hds/badge/index.hbs

@@ -1,4 +1,4 @@
-<div class="hds-badge {{this.sizeClass}} {{this.typeClass}} {{this.colorClass}}" ...attributes>
+<div class={{this.classNames}} ...attributes>
   {{#if @icon}}
     <div class="hds-badge__icon">
       <FlightIcon @name={{this.icon}} @size="16" @stretched="true" />

package/addon/components/hds/badge/index.js

@@ -37,15 +37,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method Badge#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-badge--size-${this.size}`;
-  }
-
   /**
    * Sets the type of the component
    * Accepted values: filled, inverted, outlined
@@ -67,15 +58,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return type;
   }
 
-  /**
-   * Get a class to apply to the component based on the type argument.
-   * @method Badge#typeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get typeClass() {
-    return `hds-badge--type-${this.type}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted values: neutral, neutral-dark-mode, highlight, success, warning, critical
@@ -97,15 +79,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * Get a class to apply to the component based on the color argument.
-   * @method Badge#colorClass
-   * @return {string} The css class to apply to the component.
-   */
-  get colorClass() {
-    return `hds-badge--color-${this.color}`;
-  }
-
   /**
    * @param text
    * @type {string}
@@ -145,4 +118,24 @@ export default class HdsBadgeIndexComponent extends Component {
     }
     return false;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method Badge#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-badge'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-badge--size-${this.size}`);
+
+    // add a class based on the @type argument
+    classes.push(`hds-badge--type-${this.type}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-badge--color-${this.color}`);
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/badge-count/index.hbs

@@ -1,3 +1,3 @@
-<div class="hds-badge-count {{this.sizeClass}} {{this.typeClass}} {{this.colorClass}}" ...attributes>
+<div class={{this.classNames}} ...attributes>
   {{@text}}
 </div>

package/addon/components/hds/badge-count/index.js

@@ -30,15 +30,6 @@ export default class HdsBadgeCountIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method BadgeCount#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-badge-count--size-${this.size}`;
-  }
-
   /**
    * Sets the type of the component
    * Accepted values: filled, inverted, outlined
@@ -60,15 +51,6 @@ export default class HdsBadgeCountIndexComponent extends Component {
     return type;
   }
 
-  /**
-   * Get a class to apply to the component based on the type argument.
-   * @method BadgeCount#typeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get typeClass() {
-    return `hds-badge-count--type-${this.type}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted colors: neutral, neutral-dark-mode
@@ -91,11 +73,22 @@ export default class HdsBadgeCountIndexComponent extends Component {
   }
 
   /**
-   * Get a class to apply to the component based on the color argument.
-   * @method BadgeCount#colorClass
-   * @return {string} The css class to apply to the component.
+   * Get the class names to apply to the component.
+   * @method BadgeCount#classNames
+   * @return {string} The "class" attribute to apply to the component.
    */
-  get colorClass() {
-    return `hds-badge-count--color-${this.color}`;
+  get classNames() {
+    let classes = ['hds-badge-count'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-badge-count--size-${this.size}`);
+
+    // add a class based on the @type argument
+    classes.push(`hds-badge-count--type-${this.type}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-badge-count--color-${this.color}`);
+
+    return classes.join(' ');
   }
 }

package/addon/components/hds/button/index.hbs

@@ -1,5 +1,5 @@
 <button
-  class="hds-button {{this.sizeClass}} {{this.colorClass}} {{this.widthClass}}"
+  class={{this.classNames}}
   ...attributes
   aria-label={{if this.isIconOnly this.text null}}
   type={{this.type}}

package/addon/components/hds/button/index.js

@@ -46,16 +46,6 @@ export default class HdsButtonIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * @param sizeClass
-   * @type {string}
-   * @default hds-button--size-medium
-   * @description Determines the CSS class that the button should have, based on the size value; automatically set.
-   */
-  get sizeClass() {
-    return `hds-button--size-${this.size}`;
-  }
-
   /**
    * @param color
    * @type {string}
@@ -75,16 +65,6 @@ export default class HdsButtonIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * @param colorClass
-   * @type {string}
-   * @default hds-button--color-primary
-   * @description Determines the CSS class that the button should have, based on the color value; automatically set
-   */
-  get colorClass() {
-    return `hds-button--color-${this.color}`;
-  }
-
   /**
    * @param icon
    * @type {string}
@@ -170,20 +150,6 @@ export default class HdsButtonIndexComponent extends Component {
     return this.args.isFullWidth ?? false;
   }
 
-  /**
-   * @param widthClass
-   * @type {string|null}
-   * @default null
-   * @description Determines if the full-width class should be applied to the component. This is set automatically based on the value of `isFullWidth`.
-   */
-  get widthClass() {
-    if (this.isFullWidth === true) {
-      return 'hds-button--width-full';
-    } else {
-      return null;
-    }
-  }
-
   /**
    * @param isDisabled
    * @type {boolean}
@@ -193,4 +159,30 @@ export default class HdsButtonIndexComponent extends Component {
   get isDisabled() {
     return this.args.isDisabled ?? null;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method Badge#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  // "hds-button {{this.sizeClass}} {{this.colorClass}} {{this.widthClass}}"
+  get classNames() {
+    let classes = ['hds-button'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-button--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-button--color-${this.color}`);
+
+    // add a class based on the @isFullWidth argument
+    if (this.isFullWidth) {
+      classes.push('hds-button--width-full');
+    }
+
+    // the button has a "low" elevation effect applied to it
+    classes.push('hds-elevation-low');
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/card/container.hbs

@@ -1,6 +1,3 @@
-<div
-  class="hds-card__container {{this.levelClass}} {{this.borderClass}} {{this.backgroundClass}} {{this.overflowClass}}"
-  ...attributes
->
+<div class={{this.classNames}} ...attributes>
   {{yield}}
 </div>

package/addon/components/hds/card/container.js

@@ -30,15 +30,6 @@ export default class HdsCardContainerComponent extends Component {
     return level;
   }
 
-  /**
-   * Get a class to apply to the component based on the level argument.
-   * @method Card#levelClass
-   * @return {string} The css class to apply to the component.
-   */
-  get levelClass() {
-    return `hds-card__container--level-${this.level}`;
-  }
-
   /**
    * Sets the background for the component
    * Accepted values: neutral-primary, neutral-secondary
@@ -60,24 +51,6 @@ export default class HdsCardContainerComponent extends Component {
     return background;
   }
 
-  /**
-   * Get a class to apply to the component based on the background argument.
-   * @method Card#backgroundClass
-   * @return {string} The css class to apply to the component.
-   */
-  get backgroundClass() {
-    return `hds-card__container--background-${this.background}`;
-  }
-
-  /**
-   * Get a class to apply to the component based on the hasBorder argument.
-   * @method Card#hasBorderClass
-   * @return {string} The css class to apply to the component.
-   */
-  get borderClass() {
-    return this.args.hasBorder ? `hds-card__container--has-border` : undefined;
-  }
-
   /**
    * Sets the level for the card
    * Accepted values: visible, hidden
@@ -100,11 +73,24 @@ export default class HdsCardContainerComponent extends Component {
   }
 
   /**
-   * Get a class to apply to the component based on the overflow argument.
-   * @method Card#overflowClass
-   * @return {string} The css class to apply to the component.
+   * Get the class names to apply to the component.
+   * @method Card#classNames
+   * @return {string} The "class" attribute to apply to the component.
    */
-  get overflowClass() {
-    return `hds-card__container--overflow-${this.overflow}`;
+  get classNames() {
+    let classes = ['hds-card__container'];
+
+    // add an "elevation" class helper based on the @level and @hasBorder arguments
+    classes.push(
+      `hds-${this.args.hasBorder ? 'surface' : 'elevation'}-${this.level}`
+    );
+
+    // add a class based on the @background argument
+    classes.push(`hds-card__container--background-${this.background}`);
+
+    // add a class based on the @overflow argument
+    classes.push(`hds-card__container--overflow-${this.overflow}`);
+
+    return classes.join(' ');
   }
 }

package/addon/components/hds/icon-tile/index.hbs

@@ -1,4 +1,4 @@
-<div class="hds-icon-tile {{this.entityClass}} {{this.sizeClass}} {{this.colorClass}}" aria-hidden="true" ...attributes>
+<div class={{this.classNames}} aria-hidden="true" ...attributes>
   {{#if @icon}}
     <div class="hds-icon-tile__icon">
       <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched="true" />

package/addon/components/hds/icon-tile/index.js

@@ -39,15 +39,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method IconTile#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-icon-tile--size-${this.size}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted values: see THE COLORS LIST
@@ -75,15 +66,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * Get a class to apply to the component based on the color argument.
-   * @method IconTile#colorClass
-   * @return {string} The css class to apply to the component.
-   */
-  get colorClass() {
-    return `hds-icon-tile--color-${this.color}`;
-  }
-
   /**
    * Sets the icon name (one of the FlightIcons)
    *
@@ -167,15 +149,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return entity;
   }
 
-  /**
-   * Get a class to apply to the component based on the its entity.
-   * @method IconTile#entityClass
-   * @return {string} The css class to apply to the component.
-   */
-  get entityClass() {
-    return `hds-icon-tile--${this.entity}`;
-  }
-
   /**
    * Sets the "secondary" icon name (one of the FlightIcons)
    *
@@ -186,4 +159,25 @@ export default class HdsIconTileIndexComponent extends Component {
   get iconSecondary() {
     return this.args.iconSecondary ?? null;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method IconTile#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  // hds-icon-tile {{this.entityClass}} {{this.sizeClass}} {{this.colorClass}}"
+  get classNames() {
+    let classes = ['hds-icon-tile'];
+
+    // add a class based on its entity argument
+    classes.push(`hds-icon-tile--${this.entity}`);
+
+    // add a class based on the @size argument
+    classes.push(`hds-icon-tile--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-icon-tile--color-${this.color}`);
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/link/standalone.hbs

@@ -0,0 +1,20 @@
+{{! template-lint-disable link-href-attributes }}
+{{! we can disable this linting rule because the developer will add the html attribute themselves }}
+<a class={{this.classNames}} target="_blank" rel="noopener noreferrer" ...attributes>
+  {{#if (eq this.iconPosition "leading")}}
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+  {{else}}
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+  {{/if}}
+</a>
+{{! template-lint-enable link-href-attributes }}

package/addon/components/hds/link/standalone.js

@@ -0,0 +1,132 @@
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+
+export const DEFAULT_ICONPOSITION = 'leading';
+export const DEFAULT_COLOR = 'primary';
+export const DEFAULT_SIZE = 'medium';
+export const ICONPOSITIONS = ['leading', 'trailing'];
+export const COLORS = ['primary', 'secondary'];
+export const SIZES = ['small', 'medium', 'large'];
+
+export default class HdsLinkStandaloneComponent extends Component {
+  /**
+   * @param text
+   * @type {string}
+   * @description The text of the link. If no text value is defined an error will be thrown.
+   */
+  get text() {
+    let { text } = this.args;
+
+    assert(
+      '@text for "Hds::Link::Standalone" must have a valid value',
+      text !== undefined
+    );
+
+    return text;
+  }
+
+  /**
+   * @param color
+   * @type {string}
+   * @default primary
+   * @description Determines the color of link to be used; acceptable values are `primary` and `secondary`
+   */
+  get color() {
+    let { color = DEFAULT_COLOR } = this.args;
+
+    assert(
+      `@color for "Hds::Link::Standalone" must be one of the following: ${COLORS.join(
+        ', '
+      )}; received: ${color}`,
+      COLORS.includes(color)
+    );
+
+    return color;
+  }
+
+  /**
+   * @param icon
+   * @type {string|null}
+   * @default null
+   * @description The name of the icon to be used. An icon name must be defined.
+   */
+  get icon() {
+    let { icon } = this.args;
+
+    assert(
+      '@icon for "Hds::Link::Standalone" must have a valid value',
+      icon !== undefined
+    );
+
+    return icon;
+  }
+
+  /**
+   * @param iconPosition
+   * @type {string}
+   * @default leading
+   * @description Positions the icon before or after the text; allowed values are `leading` or `trailing`
+   */
+  get iconPosition() {
+    let { iconPosition = DEFAULT_ICONPOSITION } = this.args;
+
+    assert(
+      `@iconPosition for "Hds::Link::Standalone" must be one of the following: ${ICONPOSITIONS.join(
+        ', '
+      )}; received: ${iconPosition}`,
+      ICONPOSITIONS.includes(iconPosition)
+    );
+
+    return iconPosition;
+  }
+
+  /**
+   * @param size
+   * @type {string}
+   * @default medium
+   * @description The size of the standalone link; acceptable values are `small`, `medium`, and `large`
+   */
+  get size() {
+    let { size = DEFAULT_SIZE } = this.args;
+
+    assert(
+      `@size for "Hds::Link::Standalone" must be one of the following: ${SIZES.join(
+        ', '
+      )}; received: ${size}`,
+      SIZES.includes(size)
+    );
+
+    return size;
+  }
+
+  /**
+   * @param iconSize
+   * @type {string}
+   * @default 16
+   * @description ensures that the correct icon size is used. Automatically calculated.
+   */
+  get iconSize() {
+    if (this.args.size === 'large') {
+      return '24';
+    } else {
+      return '16';
+    }
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method LinkStandalone#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-link-standalone'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-link-standalone--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-link-standalone--color-${this.color}`);
+
+    return classes.join(' ');
+  }
+}

package/addon/components/hds/link-to/standalone.hbs

@@ -0,0 +1,25 @@
+<LinkTo
+  class={{this.classNames}}
+  @current-when={{@current-when}}
+  @models={{hds-link-to-models @model @models}}
+  @query={{this.queryParams}}
+  @replace={{@replace}}
+  @route={{this.route}}
+  ...attributes
+>
+  {{#if (eq this.iconPosition "leading")}}
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+  {{else}}
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+  {{/if}}
+</LinkTo>

package/addon/components/hds/link-to/standalone.js

@@ -0,0 +1,158 @@
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+
+export const DEFAULT_ICONPOSITION = 'leading';
+export const DEFAULT_COLOR = 'primary';
+export const DEFAULT_SIZE = 'medium';
+export const ICONPOSITIONS = ['leading', 'trailing'];
+export const COLORS = ['primary', 'secondary'];
+export const SIZES = ['small', 'medium', 'large'];
+
+export default class HdsLinkToStandaloneComponent extends Component {
+  /**
+   * @param text
+   * @type {string}
+   * @description The text of the link. If no text value is defined an error will be thrown.
+   */
+  get text() {
+    let { text } = this.args;
+
+    assert(
+      '@text for "Hds::LinkTo::Standalone" must have a valid value',
+      text !== undefined
+    );
+
+    return text;
+  }
+
+  /**
+   * @param route
+   * @type {string|null}
+   * @description Checks to make sure route is defined.
+   */
+  get route() {
+    let { route } = this.args;
+    assert(
+      '@route must be defined for "Hds::LinkTo::Standalone"',
+      route !== undefined
+    );
+
+    return route;
+  }
+
+  /**
+   * @param color
+   * @type {string}
+   * @default primary
+   * @description Determines the color of link to be used; acceptable values are `primary` and `secondary`
+   */
+  get color() {
+    let { color = DEFAULT_COLOR } = this.args;
+
+    assert(
+      `@color for "Hds::LinkTo::Standalone" must be one of the following: ${COLORS.join(
+        ', '
+      )}; received: ${color}`,
+      COLORS.includes(color)
+    );
+
+    return color;
+  }
+
+  /**
+   * @param icon
+   * @type {string|null}
+   * @default null
+   * @description The name of the icon to be used. An icon name must be defined.
+   */
+  get icon() {
+    let { icon } = this.args;
+
+    assert(
+      '@icon for "Hds::LinkTo::Standalone" must have a valid value',
+      icon !== undefined
+    );
+
+    return icon;
+  }
+
+  /**
+   * @param iconPosition
+   * @type {string}
+   * @default leading
+   * @description Positions the icon before or after the text; allowed values are `leading` or `trailing`
+   */
+  get iconPosition() {
+    let { iconPosition = DEFAULT_ICONPOSITION } = this.args;
+
+    assert(
+      `@iconPosition for "Hds::LinkTo::Standalone" must be one of the following: ${ICONPOSITIONS.join(
+        ', '
+      )}; received: ${iconPosition}`,
+      ICONPOSITIONS.includes(iconPosition)
+    );
+
+    return iconPosition;
+  }
+
+  /**
+   * @param size
+   * @type {string}
+   * @default medium
+   * @description The size of the standalone link; acceptable values are `small`, `medium`, and `large`
+   */
+  get size() {
+    let { size = DEFAULT_SIZE } = this.args;
+
+    assert(
+      `@size for "Hds::LinkTo::Standalone" must be one of the following: ${SIZES.join(
+        ', '
+      )}; received: ${size}`,
+      SIZES.includes(size)
+    );
+
+    return size;
+  }
+
+  /**
+   * @param iconSize
+   * @type {string}
+   * @default 16
+   * @description ensures that the correct icon size is used. Automatically calculated.
+   */
+  get iconSize() {
+    if (this.args.size === 'large') {
+      return '24';
+    } else {
+      return '16';
+    }
+  }
+
+  // this is a workaround for https://github.com/emberjs/ember.js/issues/19693
+  // don't remove until we drop support for ember 3.27 and 3.28
+  get queryParams() {
+    if (this.args.query) {
+      return this.args.query;
+    } else {
+      return {};
+    }
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method LinkToStandalone#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    // Notice: we've left this class name the same as the hds::link::standalone (we didn't add the "-to") so we didn't have to replicate the CSS
+    let classes = ['hds-link-standalone'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-link-standalone--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-link-standalone--color-${this.color}`);
+
+    return classes.join(' ');
+  }
+}

package/addon/helpers/hds-link-to-models.js

@@ -0,0 +1,30 @@
+import { helper } from '@ember/component/helper';
+import { assert } from '@ember/debug';
+
+/*
+ * This helper can be used to support both @model and @models arguments when wrapping
+ * the `<LinkTo>` component without it triggering assertions or having to use the component helper.
+ *
+ * The result of this helper should be passed into the `@models` argument of the `<LinkTo>` component:
+ *
+ * ```hbs
+ * <LinkTo @models={{hds-link-to-models @model @models}} />
+ * ```
+ */
+
+export function hdsLinkToModels([model, models]) {
+  assert(
+    'You cannot provide both the `@model` and `@models` arguments to the component.',
+    !model || !models
+  );
+
+  if (model) {
+    return [model];
+  } else if (models) {
+    return models;
+  } else {
+    return [];
+  }
+}
+
+export default helper(hdsLinkToModels);

package/app/components/hds/link/standalone.js

@@ -0,0 +1 @@
+export { default } from '@hashicorp/design-system-components/components/hds/link/standalone';

package/app/components/hds/link-to/standalone.js

@@ -0,0 +1 @@
+export { default } from '@hashicorp/design-system-components/components/hds/link-to/standalone';

package/app/helpers/hds-link-to-models.js

@@ -0,0 +1 @@
+export { default } from '@hashicorp/design-system-components/helpers/hds-link-to-models';

package/app/styles/@hashicorp/design-system-components.scss

@@ -1,4 +1,6 @@
+// these are files coming from the 'design-system-tokens' package
 @use "tokens";
+@use "helpers/elevation";
 
 @use "../mixins/generic-focus-state";
 
@@ -7,6 +9,7 @@
 @use "../components/button";
 @use "../components/card";
 @use "../components/icon-tile";
+@use "../components/link/standalone";
 
 .sr-only {
 	border: 0 !important;

package/app/styles/components/button.scss

@@ -4,25 +4,9 @@ $hds-button-border-radius: 5px;
 $hds-button-border-width: 1px;
 $hds-button-focus-border-width: 3px;
 
-// TODO! generalize with the existing mixin in Card component
-@mixin tempElevation() {
-  box-shadow:
-    var(--token-elevation-low-shadow-01-x)
-    var(--token-elevation-low-shadow-01-y)
-    var(--token-elevation-low-shadow-01-blur)
-    var(--token-elevation-low-shadow-01-spread)
-    var(--token-elevation-low-shadow-01-color),
-    var(--token-elevation-low-shadow-02-x)
-    var(--token-elevation-low-shadow-02-y)
-    var(--token-elevation-low-shadow-02-blur)
-    var(--token-elevation-low-shadow-02-spread)
-    var(--token-elevation-low-shadow-02-color)
-  ;
-}
+$hds-button-sizes: ( 'small', 'medium', 'large' );
 
 .hds-button {
-  @include tempElevation();
-
   align-items: center;
   border: $hds-button-border-width solid transparent; // We need this to be transparent for a11y
   border-radius: $hds-button-border-radius;
@@ -101,41 +85,45 @@ $hds-button-focus-border-width: 3px;
 
 // SIZE
 
-.hds-button--size-small {
-  font-size: 0.8125rem; // 13px;
-  min-height: 1.75rem;  //28px
-  line-height: 1;
-  padding: 0 1rem;
-  
-  .hds-button__icon {
-    height: 0.75rem; // 12px
-    width: 0.75rem; // 12px
-  }
-}
-
-.hds-button--size-medium {
-  font-size: 0.875rem; // 14px
-  line-height: 1rem; // 16px
-  min-height: 2.25rem; //36px
-  padding: 0.625rem 1rem;
-
-  .hds-button__icon {
-    height: 1rem;
-    width: 1rem;
+// these values later may come from the design tokens
+$size-props: (
+  "small": (
+    "font-size": 0.8125rem, // 13px;
+    "line-height": 1,
+    "min-height": 1.75rem,  // 28px
+    "padding": 0 1rem, // 0 16px
+    "icon-size": 0.75rem, // 12px
+  ),
+  "medium": (
+      "font-size": 0.875rem, // 14px
+      "line-height": 1rem,// 16px
+      "min-height": 2.25rem, // 36px
+      "padding": 0.625rem 1rem, // 10px 16px
+      "icon-size": 1rem, // 16px
+  ),
+  "large": (
+      "font-size": 1rem, //16px
+      "line-height": 1.5rem, // 24px
+      "min-height": 3rem, // 48px
+      "padding": 0.75rem 1.25rem, // 12px 20px
+      "icon-size": 1.5rem, // 24px
+  )
+);
+
+@each $size in $hds-button-sizes {
+  .hds-button--size-#{$size} {
+    font-size: map-get($size-props, $size, "font-size");
+    min-height: map-get($size-props, $size, "min-height");
+    line-height: map-get($size-props, $size, "line-height");
+    padding: map-get($size-props, $size, "padding");
+
+    .hds-button__icon {
+      height: map-get($size-props, $size, "icon-size");
+      width: map-get($size-props, $size, "icon-size");
+    }
   }
 }
 
-.hds-button--size-large {
-  font-size: 1rem; //16px
-  line-height: 1.5rem; // 24px
-  min-height: 3rem; //48px
-  padding: 0.75rem 1.25rem; // 12px 20px
-
-  .hds-button__icon {
-    height: 1.5rem;
-    width: 1.5rem;
-  }
-}
 
 // COLORS & STATES
 // Note: the order of the pseuo-selectors need to stay the way they are; it doesn't match the Figma file but it's the correct order for browsers to render the styles correctly.

package/app/styles/components/card/container.scss

@@ -5,56 +5,6 @@
 //
 //
 
-// this mixin is used to apply the "elevation" styles to the card container
-// depending on the "elevation level" and if it has a border applied to it.
-// we are mimicking the way this effect is defined in Figma, through a set of
-// multiple drop shadows (also the border is a 1px shadow); we tried using an
-// outline but Safari still doesn't support rounded edges for outlines.
-// for details see: https://www.figma.com/file/oQsMzMMnynfPWpMEt91OpH/?node-id=1988%3A2
-
-@mixin getElevationStyle($level, $has-border: false) {
-  $drop-shadow: false;
-  $border-shadow: false;
-
-  // here we define the "drop-shadow" values (there are two shadows applied)
-  // notice: the "base" level doesn't have a "drop shadow" effect applied (no elevation)
-  @if ($level != 'base') {
-    $drop-shadow:
-      var(--token-elevation-#{$level}-shadow-01-x)
-      var(--token-elevation-#{$level}-shadow-01-y)
-      var(--token-elevation-#{$level}-shadow-01-blur)
-      var(--token-elevation-#{$level}-shadow-01-spread)
-      var(--token-elevation-#{$level}-shadow-01-color),
-      var(--token-elevation-#{$level}-shadow-02-x)
-      var(--token-elevation-#{$level}-shadow-02-y)
-      var(--token-elevation-#{$level}-shadow-02-blur)
-      var(--token-elevation-#{$level}-shadow-02-spread)
-      var(--token-elevation-#{$level}-shadow-02-color)
-    ;
-  }
-
-  // here we define the "border-shadow" values
-  // notice: we create a border via a shadow, so we have zero values for x/y/blur
-  @if ($has-border) {
-    $border-shadow:
-      0
-      0
-      0
-      var(--token-elevation-#{$level}-border-width)
-      var(--token-elevation-#{$level}-border-color);
-  }
-
-  // here we join the two effects in a single box-shadow (depending on the different cases)
-  @if ($drop-shadow and not $border-shadow) {
-    box-shadow: $drop-shadow;
-  } @else if($border-shadow and not $drop-shadow) {
-    box-shadow: $border-shadow;
-  } @else {
-    // notice: we put the "border-shadow" first because the final rendering in the browser looks better
-    // see: https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow - "The z-ordering of multiple box shadows is the same as multiple text shadows (the first specified shadow is on top)."
-    box-shadow: $border-shadow, $drop-shadow;
-  }
-}
 
 $hds-card-container-levels: ( 'base', 'mid', 'high' );
 
@@ -66,18 +16,6 @@ $hds-card-container-border-radius: 6px;
   position: relative;
 }
 
-// LEVEL (elevation style as "drop" + "border" shadow effects)
-
-@each $level in $hds-card-container-levels {
-  .hds-card__container--level-#{$level} {
-    @include getElevationStyle($level);
-
-    &.hds-card__container--has-border {
-      @include getElevationStyle($level, true);
-    }
-  }
-}
-
 
 // BACKGROUND
 

package/app/styles/components/link/standalone.scss

@@ -0,0 +1,126 @@
+$hds-link-standalone-border-radius: 5px;
+$hds-link-standalone-sizes: ( 'small', 'medium', 'large' );
+$hds-link-standalone-border-width: 1px;
+$hds-link-standalone-focus-border-width: 3px + $hds-link-standalone-border-width;
+
+
+.hds-link-standalone {
+  align-items: center;
+  background-color: transparent;
+  border: $hds-link-standalone-border-width solid transparent; // needs to exist AND be transparent for a11y
+  border-radius: $hds-link-standalone-border-radius;
+  color: var(--token-color-action-foreground-on-faint);
+  display: flex;
+  font-family: var(--token-typography-body-base-font-family);
+  justify-content: center;
+  outline-color: transparent;
+  padding: 0.25rem; // should be 4px; iconPosition will override it on one side
+  position: relative;
+  text-decoration: none;
+  width: fit-content;
+}
+
+// these values later may come from the design tokens
+$size-props: (
+  "small": (
+    "font-size": 0.8125rem, // 13px;
+    "icon-size": 0.75rem, // 12px
+    "line-height": 0.75,
+  ),
+  "medium": (
+    "font-size": 0.875rem, // 14px
+    "icon-size": 1rem, // 16px
+    "line-height": 1, // 16px
+  ),
+  "large": (
+    "font-size": 1rem, // 16px
+    "icon-size": 1.5rem, // 24px
+    "line-height": 1.5, // 24px
+  )
+);
+
+@each $size in $hds-link-standalone-sizes {
+  .hds-link-standalone--size-#{$size} {
+
+    .hds-link-standalone__icon {
+      height: map-get($size-props, $size, "icon-size");
+      width: map-get($size-props, $size, "icon-size");
+    }
+
+    .hds-link-standalone__text {
+      font-size: map-get($size-props, $size, "font-size");
+      line-height: map-get($size-props, $size, "line-height");
+    }
+
+  }
+}
+
+.hds-link-standalone__text {
+  flex: 1 0 0;
+  .hds-link-standalone__icon + & {
+    margin-left: 0.375rem;
+  }
+  & +.hds-link-standalone__icon {
+    margin-left: 0.375rem;
+  }
+}
+
+// COLORS & STATES
+// Note: the order of the pseuo-selectors need to stay the way they are
+
+.hds-link-standalone--color-primary {
+  color: var(--token-color-action-foreground-on-faint);
+
+  &:visited {
+    color: var(--token-color-action-foreground-on-faint);
+  }
+  &:hover,
+  &.is-hover {
+    text-decoration-color: #4E81E8;
+    text-decoration: underline;
+    transition: text-decoration-color 0.25s ease-in;
+  }
+  &:focus,
+  &:focus-visible,
+  &.is-focus {
+    outline: 2px solid transparent;
+    box-shadow: 
+    0 0 0 $hds-link-standalone-border-width var(--token-color-action-border-on-primary), 
+    0 0 0 $hds-link-standalone-focus-border-width #5990FF;
+  }
+  &:active,
+  &.is-active {
+    color: var(--token-color-action-foreground-high-contrast);
+    text-decoration: underline;
+    text-decoration-color: #596987;
+    &::before {
+      border-color: transparent;
+    }
+  }
+}
+
+.hds-link-standalone--color-secondary {
+  background-color: transparent;
+  color: var(--token-color-neutral-foreground-primary);
+
+  &:focus,
+  &:focus-visible,  
+  &.is-focus {
+    outline: 2px solid transparent;
+    box-shadow: 
+    0 0 0 $hds-link-standalone-border-width var(--token-color-action-border-on-primary), 
+    0 0 0 $hds-link-standalone-focus-border-width #5990FF;
+  }
+  &:hover,
+  &.is-hover {
+    text-decoration: underline;
+    text-decoration-color: var(--token-color-neutral-foreground-primary);
+  }
+  &:active, 
+  &.is-active {
+    color: var(--token-color-neutral-foreground-secondary);
+    text-decoration: underline;
+    text-decoration-color: var(--token-color-neutral-foreground-primary);
+
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashicorp/design-system-components",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "HashiCorp Design System Components",
   "keywords": [
     "hashicorp",
@@ -61,7 +61,7 @@
     "prepare": "husky install"
   },
   "dependencies": {
-    "@hashicorp/design-system-tokens": "^0.0.16",
+    "@hashicorp/design-system-tokens": "^0.1.0",
     "@hashicorp/ember-flight-icons": "^2.0.0",
     "ember-cli-babel": "^7.26.6",
     "ember-cli-htmlbars": "^5.7.1",
@@ -78,12 +78,14 @@
     "@percy/ember": "^3.0.0",
     "babel-eslint": "^10.1.0",
     "broccoli-asset-rev": "^3.0.0",
+    "ember-a11y-refocus": "^2.1.0",
     "ember-auto-import": "^2.2.3",
     "ember-cli": "~3.28.4",
     "ember-cli-dependency-checker": "^3.2.0",
     "ember-cli-inject-live-reload": "^2.1.0",
     "ember-cli-markdown-it-templates": "^0.0.3",
     "ember-cli-sri": "^2.1.1",
+    "ember-cli-string-helpers": "^6.1.0",
     "ember-cli-terser": "^4.0.2",
     "ember-disable-prototype-extensions": "^1.1.3",
     "ember-export-application-global": "^2.0.1",
@@ -104,8 +106,8 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.4.1",
     "eslint-plugin-qunit": "^6.2.0",
-    "husky": ">=6",
-    "lint-staged": ">=10",
+    "husky": "^7.0.4",
+    "lint-staged": "^12.1.2",
     "loader.js": "^4.7.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.3.2",