# Button Starts an action on the current page, such as saving, exporting or opening a menu. Kind: component · Group: Actions and inputs · Status: built, import from @twoux/ui ## When to use - To start an action on the current page: New listing, Export, Save view. - To open a menu or popover of more actions, with a chevron on the right. - For the one step most people take next in a view, using the primary style. - As an icon-only ghost button for frequent, well-known row actions where space is tight. ## When not to use - To go to another page or URL. Use a link (button-link style) instead. - To switch between views of the same data. Use the Segmented control. - To turn a setting on or off. Use a Switch, not a button whose label flips. - For a long set of secondary actions on one object. Group them in a Dropdown menu. ## Structure 1. Container 2. Icon (optional) 3. Label 4. Shortcut hint (optional) 5. Chevron (menu buttons only) ## Guidelines - Seven variants, using shadcn names: default (the primary), outline (white with a light border), secondary (grey fill), ghost (no fill until hover), warning (risky but reversible, a TwoUX addition), destructive (red, inside a confirmation) and link. Pick by importance in the view, not by looks. - Only one primary button per view. In a dialog or side panel with its own task, that container may have its own primary. - Four sizes: 24px inside rows, 28px in toolbars and filter bars, 32px by default, 36px only for the single action of an empty state or sign-in page. Icon-only buttons are square at the same height. - States: default, hover, focus (2px primary ring with a 2px white gap), pressed, disabled (45% opacity), loading. - Avoid disabled buttons in forms. Keep Publish pressable and show what is missing through validation. - When a button must be disabled, give the reason in a tooltip or nearby text. - While an action runs, use loading: the spinner replaces the leading icon, the button ignores clicks and stays focusable, so it cannot be pressed twice and keyboard users keep their place. ## Content - Start with a verb and say what happens: Publish listing, Export 2 rows, Close listings. - Sentence case, no full stop, no articles: Save view, not Save The View. - Two to four words. Add the object for destructive actions: Delete listing, not Delete. - Add an ellipsis when the action needs more input before it runs: Extend to a date… - Never OK or Yes in a dialog. Name both outcomes: Close listings and Keep open. ## Accessibility - Use a native button element. Enter and Space activate it. - Icon-only buttons need an aria-label naming the action, plus a tooltip showing the same words. - The accessible name must contain the visible label so voice users can say what they see. - Focus ring and secondary border need at least 3:1 against the background; label text at least 4.5:1, white on primary included. - The 28px small button meets the 24px minimum target. Do not shrink icon buttons below 24px. - Menu buttons set aria-haspopup and aria-expanded. ## Keyboard | Keys | Action | |---|---| | Enter / Space | Activate the focused button | | Shortcut shown on the button | Run the action from anywhere in the view | ## Examples ### disabled ```tsx import { Button } from "@twoux/ui"; export const meta = { title: "Disabled", description: "Prefer leaving the button enabled and explaining what is missing when pressed. Disable only when the reason is visible next to it.", order: 6, }; export default function Example() { return (
Choose who gets the titles before you run this.
); } ``` ### icon-only ```tsx import { Button } from "@twoux/ui"; import { MoreHorizontal, Pencil, X } from "lucide-react"; export const meta = { title: "Icon only", description: "For well-known actions in dense places. The aria-label names the action and its target, not the icon, and a tooltip shows the same words.", order: 7, }; export default function Example() { return (
); } ``` ### icons ```tsx import { Button } from "@twoux/ui"; import { ChevronDown, ExternalLink, Plus } from "lucide-react"; export const meta = { title: "With icons", description: "An icon before the label clarifies the action. An icon after it says what happens next: a chevron opens a menu, an arrow leaves the app.", order: 4, }; export default function Example() { return (
); } ``` ### loading ```tsx import { Button } from "@twoux/ui"; import { useState } from "react"; export const meta = { title: "Loading", description: "While an action runs, the button shows a spinner and ignores clicks but stays focusable, so keyboard users keep their place. Press it to try.", order: 6, }; export default function Example() { const [busy, setBusy] = useState(false); return (
); } ``` ### matrix ```tsx import { Button } from "@twoux/ui"; export const meta = { title: "All sizes and variants", description: "Every combination, for checking alignment. Rows share a baseline at each size.", order: 9 }; const variants = ["default", "outline", "secondary", "ghost", "warning", "destructive"] as const; const sizes = ["xs", "sm", "default", "lg"] as const; export default function Example() { return (
{variants.map((v) => ( {v} ))} {sizes.map((s) => (
{s} {variants.map((v) => ( ))}
))}
); } ``` ### primary ```tsx import { Button } from "@twoux/ui"; import { Plus } from "lucide-react"; export const meta = { title: "One primary action per view", description: "The main action of the page is the only indigo button. Everything else is secondary or ghost.", order: 1, }; export default function Example() { return (
); } ``` ### shortcut ```tsx import { Button } from "@twoux/ui"; import { Clock, Copy } from "lucide-react"; export const meta = { title: "With keyboard shortcut", description: "Every frequent action shows its key, so people learn it by using it. The key is also in the tooltip for screen readers.", order: 4, }; export default function Example() { return (
); } ``` ### sizes ```tsx import { Button } from "@twoux/ui"; import { Download } from "lucide-react"; export const meta = { title: "Sizes", description: "Four compact sizes. 32px is the default. 28px in toolbars and filter bars, 24px inside table rows, 36px only for the single action of an empty state or sign-in page.", order: 3, }; export default function Example() { return (
); } ``` ### variants ```tsx import { Button } from "@twoux/ui"; export const meta = { title: "Variants", description: "Primary for the one main action, secondary for supporting actions, tertiary in toolbars and rows, warning for risky but reversible actions, destructive only inside a confirmation, link for navigation.", order: 2, }; export default function Example() { return (
); } ``` ## Related - Keyboard shortcut hint - Dropdown menu - Tooltip - Form validation