Skip to content

Button Specification

Jump to bottom
Radoslav Karaivanov edited this page Aug 29, 2023 · 11 revisions

Button Specification

Owned by

Team Name: CodeX

Developer Name: Diyan Dimitrov

Designer Name:

Requires approval from

  • Peer Developer Name | Date:
  • Design Manager Name | Date:

Signed off by

  • Radoslav Mirchev| Date:
  • Radoslav Karaivanov | Date:

Revision History

Version Users Date Notes
1 Diyan Dimitrov 2021-07-12
2 Radoslav Karaivanov 2023-08-28

Overview

The igc-button is an interactive component that wraps a native <button> or an <a> element depending on the its configuration.

Acceptance criteria

  1. The component should act as either a button or an anchor element depending on the passed configuration.
  2. It must support different visual variants according to the guidelines of Material, Fluent, etc.
  3. It must support sizing through a CSS variable.
  4. It must support projecting user provided content.
  5. It must support distinct visual styles based on its state (focused, disabled, etc.) and the guidelines set by the active theme.
  6. It must follow the WAI-ARIA guidelines as closely as possible and be accessible with both keyboard and mouse devices.

User stories

Developer stories:

As a developer I expect to be able to:

  • initialize an igc-button as a button
  • initialize an igc-button as an anchor
  • set a variant to control the visual appearance of the element
  • control the disabled state of the component
  • set a button type (reset, submit) when using the component as a button
  • set various anchor attributes (href, download, target, rel) when using the component as an anchor element
  • slot content in the exposed component slots so I can achieve customization in scenarios where additional visual indication is needed or certain design guidelines are required

End-user stories:

As an end-user I expect to be able to:

  • click a button which performs an action
  • click a button which navigates to a URL
  • have distinct visual indication reflecting the different states the component is in (disabled, focused, etc.)
  • interact with the element with keyboard and with a pointer device

Functionality

End-users must be able to interact with the component through pointer device and/or keyboard.

Developers must be able to configure the component to act as either a button or an anchor element.

End-user experience

Design hand-off

Developer experience

By default, the igc-button wraps and renders a native <button> element. In order to emulate an anchor button that wraps a native <a> underneath, one has to set the href property of the component.

Form integration

When an igc-button is rendered as a button inside a form element and its type is set to either submit or reset, interacting with it will perform the relevant form action, i.e. submit or reset.

If the component is rendered as an anchor the type attributes and its default behavior are ignored.

Initialization

<!-- Button -->
<igc-button>OK</igc-button>

<!-- Anchor button -->
<igc-button href="...">Follow</igc-button>

With attributes

<form>
  ...
  <!-- A raised submit button -->
  <igc-button variant="raised" type="submit">Submit form</igc-button>
</form>
<igc-button variant="flat">Button</igc-button>

<!-- An anchor that opens the passed `href` in a new window/tab -->
<igc-button variant="outlined" href="..." target="_blank"
  >Open in new tab</igc-button
>

<!-- An anchor that initiates a download of the passed `href` as 'report.pdf' -->
<igc-button variant="outlined" href="..." download="report.pdf"
  >Get report</igc-button
>

User slotted content

<igc-button>
  <igc-icon slot="prefix" name="github"></igc-icon>
  Clone
</igc-button>

<igc-button href="...">
  <igc-icon slot="suffix" name="open-in-new"></igc-icon>
</igc-button>

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

API

Properties

Property Attribute Modifiers Type Default Description
disabled disabled boolean false The disabled state of the component
download download string Prompts to save the linked URL instead of navigating to it.
form readonly Returns the HTMLFormElement associated with this element.
href href string The URL the button points to.
rel rel string The relationship of the linked URL.
See https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types
size size "small" | "medium" | "large" "medium" Determines the size of the component.
target target "_blank" | "_parent" | "_self" | "_top" | undefined Where to display the linked URL, as the name for a browsing context.
type type "button" | "reset" | "submit" The type of the button. Defaults to undefined.
variant variant "flat" | "contained" | "outlined" | "fab" "contained" Sets the variant of the button.

Methods

Method Type Description
blur (): void Removes focus from the button.
click (): void Simulates a mouse click on the element
focus (options?: FocusOptions | undefined): void Sets focus in the button.

Events

Event Description
igcBlur Emitted when the button loses focus.
igcFocus Emitted when the button gains focus.

Slots

Name Description
Renders the label of the button.
prefix Renders content before the label of the button.
suffix Renders content after the label of the button.

CSS Shadow Parts

Part Description
base The native button element.
prefix The prefix container.
suffix The suffix container.

Test scenarios

  • Should render <igc-button> with <button>/<a> element inside
  • Should render the content, prefix and suffix in the correct slots
  • Should apply correct CSS classes to the native element for all variants (flat, raised, outlined, icon, fab)
  • Should apply correct CSS classes to the native element for all sizes (small, medium, large)
  • Should apply correct CSS classes and attributes to the native element when the button is disabled
  • Should apply all <button> specific properties to the wrapped native element
  • Should apply all <a> specific properties to the wrapped native element
  • Should focus/blur the native element when focus/blur methods are called
  • Should emit igcFocus/igcBlur events

Accessibility

ARIA

  • if aria-label is present on the igc-button, it is copied to the underlying button/a element.
  • when the igc-button is rendered as an anchor button the underlying anchor element has its role set to button: role="button"
  • when the igc-button is rendered as an anchor button and it is disabled, the underlying anchor element has aria-disabled="true"

RTL

The component should work in a Right-To-Left context without additional setup or configuration.

Assumptions and Limitations

References

Clone this wiki locally