# Button

import { Callout } from "fumadocs-ui/components/callout";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import {
  Badge,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@pycolors/ui";
import {
  Accessibility,
  ArrowRight,
  CheckCircle,
  CircleAlert,
  ClockIcon,
  DotIcon,
  ExternalLink,
  MousePointerClick,
  Palette,
  PanelTop,
  Plus,
  ShieldAlert,
  Sparkles,
  Tags,
  XCircle,
} from "lucide-react";
import { PreferAvoid } from '@/components/docs/prefer-avoid';
import { DocsLinks } from "@/components/docs/docs-links";
import { DocsFeatureGrid } from "@/components/docs/docs-feature-grid";
import { DocsConceptTabs } from "@/components/docs/docs-concept-tabs";
import { DocsDecisionGrid } from "@/components/docs/docs-decision-grid";

<div className="flex flex-wrap items-center gap-2">
  <Badge variant="outline">
    UI
  </Badge>

  <Badge>
    Button
  </Badge>
</div>

## Actions users can trust

The **Button** component is the primary action primitive in PyColors UI.

Use it for:

* submitting forms
* triggering dialogs
* opening sheets
* starting checkout
* saving changes
* confirming destructive actions
* navigating when an element should visually behave like a button

This implementation extends the **shadcn/ui Button primitive** and is aligned with the PyColors design system: semantic color tokens, radius, shadows, and focus rings.

<Callout title="Core idea">
  Buttons communicate intent. Choose the variant based on action priority, not decoration.
</Callout>

### Import

```tsx title="button-import.tsx"
import { Button } from "@pycolors/ui";
```

### Basic usage

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <Button>
        Click me
      </Button>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="basic-button.tsx"
    import { Button } from "@pycolors/ui";

    export function BasicButton() {
      return <Button>Click me</Button>;
    }
    ```
  </Tab>
</Tabs>

The default button uses primary semantic tokens and adapts automatically to light and dark mode.

## Product action model

Buttons are one of the highest-frequency interaction primitives inside a SaaS product.

They influence:

* conversion clarity
* workflow confidence
* destructive action safety
* onboarding friction
* perceived product quality

<Callout title="Mental model">
  A button is not decoration. It is an interaction commitment.
</Callout>

## When to use Button

Use Button when the user is taking an action.

<DocsFeatureGrid
  columns={3}
  tone="platform"
  items={[
  {
    title: 'Primary actions',
    description:
      'Use for submit, save, continue, checkout, create, or upgrade actions.',
    icon: MousePointerClick,
  },
  {
    title: 'Secondary actions',
    description:
      'Use for cancel, view details, learn more, or alternative paths.',
    icon: Sparkles,
  },
  {
    title: 'Risky actions',
    description:
      'Use destructive styling only for dangerous or irreversible actions.',
    icon: ShieldAlert,
    tone: 'danger',
  },
]}
/>

### Decision model

<DocsConceptTabs
  items={[
  {
    value: 'Primary',
    title: 'Primary actions',
    icon: Sparkles,
    description: (
      <>
        <p>
          Primary buttons represent the highest-priority action inside a product surface.
        </p>

        <div className="mt-4 flex flex-wrap gap-2">
          <Badge variant="outline">Upgrade</Badge>
          <Badge variant="outline">Checkout</Badge>
          <Badge variant="outline">Continue</Badge>
        </div>
      </>
    ),
  },
  {
    value: 'Secondary',
    title: 'Secondary actions',
    icon: PanelTop,
    description: (
      <>
        <p>
          Secondary actions support workflows without competing visually with the primary path.
        </p>

        <div className="mt-4 flex flex-wrap gap-2">
          <Badge variant="outline">Preview</Badge>
          <Badge variant="outline">Cancel</Badge>
          <Badge variant="outline">Learn more</Badge>
        </div>
      </>
    ),
  },
  {
    value: 'Destructive',
    title: 'Destructive actions',
    icon: ShieldAlert,
    description: (
      <>
        <p>
          Destructive buttons communicate irreversible risk and require strong visual clarity.
        </p>

        <div className="mt-4 flex flex-wrap gap-2">
          <Badge variant="outline">Delete</Badge>
          <Badge variant="outline">Remove</Badge>
          <Badge variant="outline">Revoke</Badge>
        </div>
      </>
    ),
  },
]}
/>

### Variants

Buttons support variants for action priority and semantic meaning.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="flex flex-wrap gap-4">
        <Button variant="default">
          Default
        </Button>

        <Button variant="secondary">
          Secondary
        </Button>

        <Button variant="outline">
          Outline
        </Button>

        <Button variant="ghost">
          Ghost
        </Button>

        <Button variant="destructive">
          Destructive
        </Button>

        <Button variant="link">
          Link
        </Button>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="button-variants.tsx"
    import { Button } from "@pycolors/ui";

    export function ButtonVariants() {
      return (
        <div className="flex flex-wrap gap-4">
          <Button variant="default">Default</Button>
          <Button variant="secondary">Secondary</Button>
          <Button variant="outline">Outline</Button>
          <Button variant="ghost">Ghost</Button>
          <Button variant="destructive">Destructive</Button>
          <Button variant="link">Link</Button>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Available variants

| Variant       | Purpose                          |
| ------------- | -------------------------------- |
| `default`     | Primary action, highest emphasis |
| `secondary`   | Neutral alternative action       |
| `outline`     | Medium-emphasis action           |
| `ghost`       | Low-emphasis action in dense UI  |
| `destructive` | Dangerous or irreversible action |
| `link`        | Text-style inline action         |

<Callout type="info" title="Variant rule">
  A page should usually have one clear primary action. Use secondary, outline, or ghost for supporting actions.
</Callout>

### Sizes

Button supports standard sizes and icon-only sizes.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="flex flex-wrap items-center gap-4">
        <Button size="sm">
          Small
        </Button>

        <Button size="default">
          Default
        </Button>

        <Button size="lg">
          Large
        </Button>

        <Button size="icon" aria-label="History">
          <ClockIcon aria-hidden="true" />
        </Button>

        <Button size="icon-sm" aria-label="Small icon button">
          <DotIcon aria-hidden="true" />
        </Button>

        <Button size="icon-lg" aria-label="Large icon button">
          <DotIcon aria-hidden="true" />
        </Button>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="button-sizes.tsx"
    import { Button } from "@pycolors/ui";

    function ClockIcon(props: React.SVGProps<SVGSVGElement>) {
      return (
        <svg viewBox="0 0 20 20" fill="currentColor" {...props}>
          <path d="M10 1a9 9 0 100 18 9 9 0 000-18zM9 5a1 1 0 012 0v5a1 1 0 01-.293.707l-3 3a1 1 0 11-1.414-1.414L9 9.586V5z" />
        </svg>
      );
    }

    function DotIcon(props: React.SVGProps<SVGSVGElement>) {
      return (
        <svg viewBox="0 0 20 20" fill="currentColor" {...props}>
          <path d="M10 18a8 8 0 100-16 8 8 0 000 16z" />
        </svg>
      );
    }

    export function ButtonSizes() {
      return (
        <div className="flex flex-wrap items-center gap-4">
          <Button size="sm">Small</Button>
          <Button size="default">Default</Button>
          <Button size="lg">Large</Button>

          <Button size="icon" aria-label="History">
            <ClockIcon aria-hidden="true" />
          </Button>

          <Button size="icon-sm" aria-label="Small icon button">
            <DotIcon aria-hidden="true" />
          </Button>

          <Button size="icon-lg" aria-label="Large icon button">
            <DotIcon aria-hidden="true" />
          </Button>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### Available sizes

| Size      | Purpose                               |
| --------- | ------------------------------------- |
| `sm`      | Compact buttons for dense product UIs |
| `default` | Standard button size                  |
| `lg`      | Stronger visual weight                |
| `icon`    | Square icon-only button               |
| `icon-sm` | Compact icon-only button              |
| `icon-lg` | Larger icon-only button               |

<Callout title="Size rule">
  Keep button sizes consistent inside the same section. Use `lg` for major CTAs and `sm` for dense product actions.
</Callout>

### Disabled state

Use disabled state when an action is unavailable.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="flex flex-wrap gap-4">
        <Button disabled>
          Disabled
        </Button>

        <Button variant="secondary" disabled>
          Disabled
        </Button>

        <Button variant="outline" disabled>
          Disabled
        </Button>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="button-disabled.tsx"
    import { Button } from "@pycolors/ui";

    export function ButtonDisabled() {
      return (
        <div className="flex flex-wrap gap-4">
          <Button disabled>Disabled</Button>
          <Button variant="secondary" disabled>Disabled</Button>
          <Button variant="outline" disabled>Disabled</Button>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

Disabled buttons use reduced opacity and remove pointer interaction.

<Callout type="info" title="UX rule">
  When disabling a button, make sure the user can understand what is required to enable it.
</Callout>

### With icon

Use icons when they reinforce the action.

The Button applies a default `size-4` to nested SVG icons that do not already have a `size-*` class.

<Tabs items={["Leading", "Trailing"]}>
  <Tab value="Leading">
    ```tsx title="button-leading-icon.tsx"
    import { Button } from "@pycolors/ui";
    import { Plus } from "lucide-react";

    export function ButtonLeadingIcon() {
      return (
        <Button>
          <Plus className="mr-2 size-4" aria-hidden="true" />
          Add item
        </Button>
      );
    }
    ```
  </Tab>

  <Tab value="Trailing">
    ```tsx title="button-trailing-icon.tsx"
    import { Button } from "@pycolors/ui";
    import { ArrowRight } from "lucide-react";

    export function ButtonTrailingIcon() {
      return (
        <Button>
          Continue
          <ArrowRight className="ml-2 size-4" aria-hidden="true" />
        </Button>
      );
    }
    ```
  </Tab>
</Tabs>

<Callout title="Icon rule">
  Icons should support the label. For icon-only buttons, always provide an `aria-label`.
</Callout>

### Validation state

The Button supports invalid visual state through `aria-invalid`.

This can be useful for submit actions when the related form is invalid.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="flex flex-wrap gap-4">
        <Button aria-invalid="true">
          Fix errors
        </Button>

        <Button variant="outline" aria-invalid="true">
          Review
        </Button>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="button-invalid.tsx"
    import { Button } from "@pycolors/ui";

    export function ButtonInvalid() {
      return (
        <div className="flex flex-wrap gap-4">
          <Button aria-invalid="true">Fix errors</Button>
          <Button variant="outline" aria-invalid="true">
            Review
          </Button>
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

### With icon

Use `asChild` to render the button as another element while preserving button styling.

This is commonly used for links and router components.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <Button asChild>
        <a href="#docs">
          Go to docs
        </a>
      </Button>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="button-as-child.tsx"
    import { Button } from "@pycolors/ui";

    export function ButtonAsChild() {
      return (
        <Button asChild>
          <a href="#docs">Go to docs</a>
        </Button>
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Semantics rule">
  If the action navigates, render an anchor or router link. If it submits or mutates state, render a button.
</Callout>

### Usage patterns

<Steps>
  <Step>
    #### Choose the action priority

    Use `default` for the main action, then choose secondary, outline, or ghost for supporting actions.
  </Step>

  <Step>
    #### Use semantic intent

    Use `destructive` only when the action is dangerous or irreversible.
  </Step>

  <Step>
    #### Keep labels action-oriented

    Prefer clear verbs such as Save, Continue, Create project, Upgrade, Delete.
  </Step>

  <Step>
    #### Pair loading with state

    During async work, disable the button and update the label to show progress.
  </Step>

  <Step>
    #### Keep icon-only buttons accessible

    Always provide `aria-label` and mark decorative icons as `aria-hidden`.
  </Step>
</Steps>

## Product decision guide

<DocsDecisionGrid
  columns={2}
  items={[
  {
    eyebrow: 'Mutation',
    title: 'Use Button',
    icon: MousePointerClick,
    description:
      'Buttons should trigger actions, mutations, submissions, confirmations, or workflow progression.',
    items: [
      'save data',
      'submit forms',
      'open overlays',
      'trigger async actions',
    ],
  },
  {
    eyebrow: 'Navigation',
    title: 'Use Link',
    icon: ExternalLink,
    tone: 'primary',
    description:
      'Links should navigate between pages, routes, or external resources.',
    items: [
      'page navigation',
      'external docs',
      'route changes',
      'resource links',
    ],
  },
]}
/>

## Button vs link vs badge

| Situation               | Use                               |
| ----------------------- | --------------------------------- |
| Submit a form           | Button                            |
| Trigger a mutation      | Button                            |
| Open a Dialog or Sheet  | Button                            |
| Navigate to another URL | Link styled with `Button asChild` |
| Show metadata or status | Badge                             |
| Inline text navigation  | Link                              |
| Compact row actions     | DropdownMenu trigger button       |

<Callout title="Decision rule">
  Button is for intent. Link is for navigation. Badge is for metadata.
</Callout>

## API

| Prop        | Type            | Default     | Description                 |
| ----------- | --------------- | ----------- | --------------------------- |
| `variant`   | `ButtonVariant` | `"default"` | Visual style                |
| `size`      | `ButtonSize`    | `"default"` | Button size                 |
| `asChild`   | `boolean`       | `false`     | Render using Radix Slot     |
| `disabled`  | `boolean`       | `false`     | Disable interaction         |
| `className` | `string`        | —           | Additional Tailwind classes |

Button extends standard HTML button props.

```ts title="button-props.ts"
React.ComponentProps<"button">
```

### TypeScript types

```ts title="button-types.ts"
export type ButtonVariant =
  | "default"
  | "secondary"
  | "outline"
  | "ghost"
  | "destructive"
  | "link";

export type ButtonSize =
  | "default"
  | "sm"
  | "lg"
  | "icon"
  | "icon-sm"
  | "icon-lg";
```

### Accessibility

* Use clear, descriptive labels.
* Preserve keyboard focus styles.
* Use icon-only buttons only with an accessible `aria-label`.
* Mark decorative icons with `aria-hidden="true"`.
* Use `disabled` for unavailable actions.
* Do not rely on color alone to communicate destructive or invalid state.
* Use links for navigation and buttons for actions.

<Callout title="Accessibility rule">
  Every button must have an accessible name. Visible text is best; `aria-label` is required for icon-only buttons.
</Callout>

## Prefer / avoid

<PreferAvoid
  prefer={[
  'one clear primary action per section',
  'short verb-first labels',
  'consistent sizes in the same view',
  '`asChild` for links that look like buttons',
  'accessible labels for icon-only buttons',
]}
  avoid={[
  'multiple competing primary buttons',
  'destructive styling for non-destructive actions',
  'icon-only buttons without labels',
  'buttons used as navigation without link semantics',
  'vague labels like “OK” or “Submit” when context is unclear',
]}
/>

### Product copy guidelines

Button labels should communicate intent clearly and reduce hesitation.

<DocsConceptTabs
  items={[
  {
    value: 'Good',
    title: 'Good labels',
    icon: CheckCircle,
    description: (
      <>
        <p>
          Strong labels are explicit, action-oriented, and outcome-focused.
        </p>

        <div className="mt-4 flex flex-wrap gap-2">
          <Badge variant="outline">Save changes</Badge>
          <Badge variant="outline">Create project</Badge>
          <Badge variant="outline">Upgrade to Pro</Badge>
          <Badge variant="outline">Invite member</Badge>
          <Badge variant="outline">Delete project</Badge>
        </div>
      </>
    ),
  },
  {
    value: 'Avoid',
    title: 'Avoid vague labels',
    icon: XCircle,
    description: (
      <>
        <p>
          Generic labels create friction because the outcome is unclear.
        </p>

        <div className="mt-4 flex flex-wrap gap-2">
          <Badge variant="outline">OK</Badge>
          <Badge variant="outline">Submit</Badge>
          <Badge variant="outline">Click here</Badge>
          <Badge variant="outline">Do it</Badge>
          <Badge variant="outline">Proceed</Badge>
        </div>
      </>
    ),
  },
]}
/>

## Common questions

<Accordions type="single">
  <Accordion title="Should navigation use Button?">
    Navigation should use links. Use `Button asChild` to style an anchor or router link as a button.
  </Accordion>

  <Accordion title="How many primary buttons should a page have?">
    Usually one per major section. Too many primary buttons weaken the hierarchy.
  </Accordion>

  <Accordion title="When should I use destructive?">
    Use `destructive` for dangerous or irreversible actions, such as delete, revoke, remove, or cancel subscription.
  </Accordion>

  <Accordion title="Should disabled buttons explain why they are disabled?">
    Yes. Use nearby helper text, validation messages, or state copy to explain what is required.
  </Accordion>
</Accordions>

## Related

<DocsLinks
  variant="list"
  tone="platform"
  items={[
  {
    title: 'Badge',
    href: '/docs/ui/badge',
    description:
      'Use badges for metadata and status, not actions.',
    icon: Tags,
  },
  {
    title: 'Dialog',
    href: '/docs/ui/dialog',
    description:
      'Use buttons to trigger focused modal tasks and confirmations.',
    icon: PanelTop,
  },
  {
    title: 'Colors',
    href: '/docs/design-system/colors',
    description:
      'Semantic color roles used by button variants.',
    icon: Palette,
  },
  {
    title: 'Accessibility',
    href: '/docs/ui/accessibility',
    description:
      'Build accessible actions with clear labels and keyboard support.',
    icon: Accessibility,
  },
]}
/>