@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/button.md

@@ -0,0 +1,185 @@
+# Button
+
+> Triggers an action or event when activated. Five visual styles (default, secondary, ghost, destructive, ai) in a single 32px-tall size.
+
+**Status:** ready · **Category:** actions · **Since:** v0.4.0
+
+## Import
+
+```tsx
+import { Button } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Button variant="default" onClick={onSave}>
+  Save changes
+</Button>
+
+{/* Polymorphic: render as another element via the `render` prop */}
+<Button render={<a href="/docs" />} variant="ghost">Docs</Button>
+```
+
+Triggers an action or event. Five styles — `default` (Primary), `secondary`,
+`ghost`, `destructive`, `ai` — in a single 32px-tall size.
+
+## When to use
+
+- A user-initiated action: submit, save, cancel, open a dialog, run a command.
+
+## When not to use
+
+- Navigation to another page that should be a real link — compose with the
+  `render` prop so it renders an `<a>` (keeps link semantics), or use a link.
+- An icon-only control — use **ButtonIcon**.
+
+## Example (React — implemented)
+
+```tsx
+import { Button } from '@acronis-platform/ui-react';
+
+<Button variant="default" onClick={onSave}>Save changes</Button>
+<Button variant="destructive" disabled>Delete</Button>
+```
+
+Vue and Web Component implementations are planned and will target the same
+contract — see `api.yaml` `adapters`.
+
+## AI variant
+
+`variant="ai"` is special:
+
+- The icon is **optional** (hidden by default). Pass an icon explicitly when
+  needed:
+
+  ```tsx
+  <Button variant="ai">Ask AI</Button>
+  <Button variant="ai"><SparklesIcon /> Ask AI</Button>
+  ```
+
+- Its background is the `--ui-button-ai-container-color-*` gradient, which runs
+  **top-to-bottom** and covers the full button (including the transparent 1px
+  border box).
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'default' | 'secondary' | 'ghost' | 'destructive' | 'ai'` | `'default'` | no | Visual style. `default` is the Figma "Primary" style. Each variant maps to its dedicated `--ui-button-<style>-*` tokens. |
+| `disabled` | `boolean` | `false` | no | Disables interaction. Applies the design's explicit per-variant disabled tokens (not an opacity dim) and suppresses click. |
+| `type` | `'button' | 'submit' | 'reset'` | `'button'` | no | Native HTML button type. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation (pointer or keyboard). Not fired while disabled. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Label content. Plain text and/or an icon. An SVG child is auto-sized to 16px and tinted with the label color. |
+
+## Behavior
+
+### Variants
+
+#### Renders the requested visual style
+
+**Given** a Button with `variant` set to one of `default`, `secondary`, `ghost`,
+`destructive`, or `ai`
+**When** it renders
+**Then** background, label, and border resolve from that variant's
+`--ui-button-<style>-*` tokens for the current interaction state.
+
+#### Defaults to `default` (Primary)
+
+**Given** a Button with no `variant`
+**When** it renders
+**Then** it uses the `default` (Primary) style.
+
+#### AI variant icon is optional
+
+**Given** a Button with `variant="ai"`
+**When** it renders
+**Then** it renders the consumer-provided children (icon is optional, hidden by
+default — the consumer passes an icon explicitly when needed)
+**And** its background is the `--ui-button-ai-container-color-*` gradient, which runs
+**top-to-bottom** (start color → end color), covering the full button box.
+
+### Interaction states
+
+#### Tracks each state from its own token
+
+**Given** any variant
+**When** the button is idle, hovered, activated, or disabled
+**Then** background, label, and border each resolve from the matching
+`*-idle` / `*-hover` / `*-active` / `*-disabled` token — so brand/theme
+overrides that differ per state are honored.
+
+#### Ghost underlines its label on hover
+
+**Given** a Button with `variant="ghost"` (the link-like variant)
+**When** the pointer hovers it
+**Then** the label is underlined (`--ui-button-ghost-label-text-decoration-hover`)
+**And** the underline is dropped again while the button is pressed (`:active`)
+and in every other state — idle, disabled, focus.
+Other variants never underline.
+
+#### Shows a pointer cursor
+
+**Given** any enabled Button
+**When** the pointer is over it
+**Then** the cursor is `pointer` (disabled buttons have `pointer-events: none`).
+
+#### Disabled uses design tokens, not opacity
+
+**Given** a Button with `disabled`
+**When** it renders
+**Then** it applies the variant's `*-disabled` tokens (not a blanket opacity)
+**And** it does not emit `click`.
+
+### Size
+
+**Given** any Button
+**When** it renders
+**Then** it has a single size — 32px tall with 12px horizontal padding (the
+Figma button has no size variants).
+
+### Content
+
+#### Sizes and tints an icon child
+
+**Given** an SVG child
+**When** it renders
+**Then** the icon is sized to 16px and inherits the label color via
+`currentColor`.
+
+### Composition
+
+#### Renders as another element
+
+**Given** a `render` prop (React) targeting e.g. an anchor
+**When** it renders
+**Then** the Button's classes/props merge onto that element instead of a
+`<button>` (Base UI `useRender`), so a Button can be a link.
+
+## Accessibility
+
+- **Role:** native `<button>` (implicit `role="button"`); when composed as a
+  link via `render`, it becomes a native `<a>` with link semantics.
+- **Accessible name:** from the text content. An **icon-only** button has no
+  text, so it MUST be given an `aria-label` (or `aria-labelledby`). For
+  icon-only buttons prefer the dedicated `ButtonIcon` component.
+- **Keyboard:** Enter and Space activate (native). Tab focuses; a `disabled`
+  button is removed from the tab order (native).
+- **Focus visible:** keyboard focus shows a 3px ring in `--ui-focus-primary`
+  flush to the button edge (no offset), via `:focus-visible` (no ring on pointer
+  activation).
+- **Contrast:** label/background pairs come from the design tokens, which are
+  authored to meet WCAG contrast. State is never conveyed by color alone — the
+  disabled state also removes interactivity.
+- **WCAG:** 2.1.1 (keyboard), 2.4.7 (focus visible), 1.4.3 / 1.4.11 (contrast),
+  4.1.2 (name/role/value).