Contract

Use when

Use this primitive for a native button or anchor whose extracted contract can be represented by the selected variant, size, and composition. Preserve the source action, label, URL, icon, disabled state, and accessible name exactly.

Do not use it for a toggle, disclosure, menu trigger with managed state, loading control, or grouped-control behavior unless separately approved components own those contracts.

Axes

• variant: default, destructive, outline, secondary, ghost, link.
• size: default, sm, lg, icon.

Use the exact resolved values from component-selection.json. Do not infer a new value from current shadcn documentation or substitute the nearest variation.

Compositions

• text: bind the exact visible label.
• leading-icon: bind an approved/source-backed icon before the label.
• trailing-icon: bind an approved/source-backed icon after the label.
• icon-only: bind an icon and an evidence-backed accessible name; omit visible label text only when the source is genuinely icon-only.
• as-link: render a native anchor through asChild and preserve its exact href and label. Do not turn navigation into a button action.

Adaptation boundary

Foundation tokens may change colors, radius, typography, and spacing to match the frozen source spec. Local layout may position the control. Do not remove native semantics, disabled behavior, keyboard focus, the forced-colors outline, or the accessible name. Do not add hydration to this statically rendered item.

Unsupported

The following require another approved primitive or the bounded custom path: loading spinners, button groups, client-managed toggles, and any axis value or composition absent from the approved capability manifest.