@octopusdeploy/design-system-components/skills/octopus-design-system/rules/feedback.md

The design systems component library.

# Feedback and Messaging Components

Use the most appropriate messaging component for the context. Do not build custom alert/notice UI.

## Callout variants

Use callouts sparingly. A page should have at most one callout visible at a time. If you find
yourself rendering multiple callouts simultaneously, reconsider the design — either consolidate
the messages or use a less prominent component (`InlineMessage`) for secondary information.

❌ Do not conditionally render several callouts where multiple could appear together.
✅ Prioritise: show the most important callout only, or gate secondary ones behind the first
   being dismissed or resolved.

All callout variants are from `@octopusdeploy/design-system-components`.

| Component | When to use |
|---|---|
| `Callout` | Page-level informational or warning messages with prominence |
| `QuietCallout` | Subdued, lower-emphasis informational messages |
| `ActionableCallout` | Messages that include a direct action the user should take |
| `InlineMessage` | Compact inline messages within a form or content area |

Choose the variant based on the visual weight required — do not use `Callout` when `QuietCallout`
or `InlineMessage` would be appropriate, and vice versa.

## Notification (toast)

Use `Notification` for transient feedback that appears after a user action (e.g. save success,
operation started). It appears as a toast and is self-dismissing.

❌ Don't use `Snackbar` — it is deprecated. Use `Notification` or `InlineSnackbar` instead.

`InlineSnackbar` is an inline variant for embedding feedback within a content area rather than
overlaying the page.

## Tooltip

Use `Tooltip` for short supplementary information on hover. Check the component's JSDoc — some
props are marked `@deprecated`.

- Do not use tooltips as the sole source of information for an action (the UI must be
  understandable without hovering)
- Keep tooltip content short — a phrase, not a paragraph

## Beacon

`Beacon` is a pulsing indicator used to draw attention to a specific element. Use sparingly and
only when directed by a design spec.

## Choosing between components

```
Is the message persistent and part of the page layout?
  → Callout / QuietCallout / ActionableCallout / InlineMessage

Is the message a transient response to a user action?
  → Notification (toast) / InlineSnackbar

Is the message supplementary info revealed on hover?
  → Tooltip
```