canopy-button

Files (1)

• SKILL.md

SKILL.md (first lines)

# Canopy Button — Best Practices

This skill provides usage guidance, dos and don'ts, and input reference for the Canopy `lg-button` directive from `@legal-and-general/canopy`.

Apply this skill whenever you use `lg-button`, `LgButtonComponent`, `LgButtonGroupComponent`, or `LgButtonToggleDirective`.

---

## Import

```ts
import {
  LgButtonComponent,
  LgButtonGroupComponent,
  LgButtonToggleDirective,
} from '@legal-and-general/canopy';
```

---

## Basic Usage

Always use a `<button>` element. Only use `<a lg-button>` when navigating to a new page or route.

```html
<button lg-button type="button" priority="primary">Save changes</button>
```

---

## Priorities

| Priority | When to use |
|----------|-------------|
| `primary` | The single main action on a page. Only one per view. |
| `secondary` | Secondary or supporting actions. Multiple allowed per page. |
| `link` | An action that visually appears as a link. |
| `add-on` | Used as an add-on to another input element. |

Button colours are inherited from the parent colour mode — never set button colours directly.

---

## Anatomy variants

**Label-only button** - the default text-only button. Labels should be concise, action-oriented, and specific about the outcome.

```html
<button lg-button type="button">Save changes</button>
```

**Back icon button** — navigation back; use `[backIcon]="true"`. For non-link priorities, the arrow-left icon is fixed and you cannot substitute a custom icon. For `priority="link"`, a projected `<lg-icon>` is displayed instead of the fixed arrow-left, allowing a custom icon on the left.
```html
<!-- Non-link: fixed arrow-left icon, no custom icon permitted -->
<button lg-button type="button" [backIcon]="true">Back</button>

<!-- Link priority: custom icon on the left via backIcon -->
<button lg-button priority="link" [backIcon]="true">
  Back
  <lg-icon name="chevron-left" />
</button>
```

**Right icon button** — action with icon to the right:
```html
<button lg-button type="button">
  Next
  <lg-icon name="chevron-right" />
</button>
```

**Icon-only button** — must include visually hidden label text for screen readers:
```html
<button lg-button type="button" [iconButton]="true">
  Add item
  <lg-icon name="add" />
</button>
```

**Loading state** — shows a spinner and disables the button:
```html
<button lg-button [loading]="true">Saving…</button>
```

**Button as link** — a button styled as a link (`priority="link"`). Supports a custom icon on either side:
```html
<!-- Icon on the right (default) -->
<button lg-button priority="link">
  Label
  <lg-icon name="chevron-right" />
</button>

<!-- Icon on the left using backIcon -->
<button lg-button priority="link" [backIcon]="true">
  Label
  <lg-icon name="chevron-left" />
</button>
```

---

## Button Group

Group two or more related buttons on a single line:

```html
<lg-button-group>
  <button lg-button priority="primary">Submit</button>
  <button lg-button priority="secondary">Cancel</button>
</lg-button-group>
```

---

## Button Toggle

Use `lgButtonToggle` to show/hide content (e.g. a filter panel). Use it only as part of a pattern, and only on a `<button>` element.

Using `lgButtonToggle` on non-button elements (for example `<a>` or `<div>`) is not supported.

From Legal-and-General/canopy, MIT.

More from Legal-and-General/canopy