Components

Button

An interactive control component for actions and navigation. Supports multiple colors, visual styles, sizes, and states through the recipe system.

Overview

The Button is an interactive UI element used for triggering actions, submitting forms, and navigating between views. The useButtonRecipe() composable creates a fully configured recipe with color, variant, and size options — plus compound variants that handle the color-variant combinations automatically.

The Button recipe integrates directly with the default design tokens preset and generates type-safe utility classes at build time with zero runtime CSS.

Why use the Button recipe?

The Button recipe helps you:

  • Ship faster with sensible defaults: Get 9 colors, 6 visual styles, and 5 sizes out of the box with a single composable call.
  • Maintain consistency: Compound variants ensure every color-variant combination follows the same design rules, including hover, active, pressed, disabled, and dark mode states.
  • Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
  • Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, or size values at compile time.
  • Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.

Usage

Register the recipe

Add the Button recipe to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipe itself:

src/components/button.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useButtonRecipe } from '@styleframe/theme';

const s = styleframe();

const button = useButtonRecipe(s);

export default s;

Build the component

Import the button runtime function from the virtual module and pass variant props to compute class names:

src/components/Button.tsx
import { button, type ButtonProps } from "virtual:styleframe";

export function Button({
    color = "neutral",
    variant = "solid",
    size = "md",
    disabled = false,
    children,
}: ButtonProps & { children?: React.ReactNode }) {
    const classes = button({ color, variant, size });

    return (
        <button className={classes} disabled={disabled}>
            {children}
        </button>
    );
}

See it in action

Colors

The Button recipe includes 9 color variants: 6 semantic colors (primary, secondary, success, info, warning, error) plus 3 neutral-scale colors (light, dark, neutral). Each color is combined with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including hover, active, pressed, and dark mode states.

Color Reference

ColorTokenUse Case
primary@color.primaryDefault actions, links, key information
secondary@color.secondarySecondary actions, neutral states
success@color.successPositive actions, confirmations, completions
info@color.infoInformational actions, tips, highlights
warning@color.warningCaution actions, pending states
error@color.errorDestructive actions, error states, alerts
light@color.white / @color.gray-*Buttons on dark surfaces, keeps its look in either theme
dark@color.gray-900Buttons on light surfaces, keeps its look in either theme
neutralAdaptive (light ↔ dark)Default color, adapts to the current color scheme
Pro tip: Use semantic color names that describe purpose, not appearance. This makes it easier to update your palette without touching component code.

Variants

Six visual style variants control how the button is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background, text, and border colors for your chosen color.

Solid

Filled background with light text. The most prominent style, ideal for primary actions and call-to-action buttons.

Outline

Transparent background with colored border and text. Useful for secondary actions that shouldn't dominate the visual hierarchy.

Soft

Light tinted background with colored text. A subtle but visible style that works well for tertiary actions and grouped controls.

Subtle

Light tinted background with colored text and a matching border. Combines the softness of the soft variant with the definition of outline.

Ghost

Transparent background with colored text that reveals a tinted background on hover. Ideal for toolbar actions and icon buttons where the button chrome should be invisible until interaction.

Styled as an inline text link with no background or border. It's underlined at rest, so it doesn't rely on color alone to stand out from the text around it, and on hover the underline thickens and the text takes a stronger shade: darker on light surfaces, lighter on dark ones. Use for navigation actions that should look like hyperlinks.

Sizes

Five size variants from xs to xl control the font size, padding, gap, and border radius of the button.

Size Reference

SizeFont SizeBorder Radius
xs@font-size.xs@border-radius.md
sm@font-size.sm@border-radius.md
md@font-size.sm@border-radius.md
lg@font-size.md@border-radius.md
xl@font-size.lg@border-radius.lg

Disabled

The Button recipe styles the disabled state from the disabled attribute and from aria-disabled="true", through the &:disabled and &:aria-disabled modifiers. Disabled buttons have reduced opacity and a not-allowed cursor, and they keep their resting colors, so hovering or pressing them changes nothing. They keep their pointer events, so the cursor shows and clicks don't fall through to whatever is underneath. Blocking activation is up to your component: the disabled attribute does it for a native <button>.

Accessibility

The Button recipe follows the stylesheet rules of the Open Components Button standard. It styles each state from the attribute that exposes it, so what people see and what assistive technologies report can't drift apart. Behavior, like keyboard handling and ARIA wiring, stays with your component.

  • Use semantic HTML. Render buttons with <button type="button"> (or <a href> for navigation) to get built-in keyboard support and screen reader announcements.
<!-- Correct: semantic button element -->
<button type="button" class="...">Save Changes</button>

<!-- Correct: link styled as button for navigation -->
<a href="/settings" class="...">Settings</a>

<!-- Avoid: non-semantic element as button -->
<div class="..." onclick="save()">Save Changes</div>
  • Contrast. Every label keeps at least 4.5:1 against its background at rest, on hover, when active, pressed or expanded, in every color and variant and in both themes (WCAG 1.4.3). The warning color takes a dark label, since a white one falls below 4.5:1 on it. Hover sets the label color too, so on devices that can hover, a button rendered as <a href> keeps it over the global link hover styles. Every border keeps at least 3:1 against the surface it's meant for (WCAG 1.4.11). The light color is made for dark surfaces and the dark color for light surfaces, so place them on those.
  • Focus visibility. Keyboard focus shows a 2px solid outline in color.focus, offset by 2px, on :focus-visible only (WCAG 2.4.7). The color.focus token defaults to color.primary and keeps at least 3:1 against the page.
  • Target size and resizing. Each size sets a min-height and a matching min-width in rem, from 1.5rem at xs to 3rem at xl, so every button is at least 24 × 24px (WCAG 2.5.8) and grows with larger text. Labels wrap instead of being clipped. On touch screens (&:any-pointer-coarse), a ::before hit area grows every button to at least 44 × 44px.
  • Stable size. No state changes the button's size or position: states only change colors, the cursor and opacity.
  • States. Disabled reads :disabled and aria-disabled="true", pressed and expanded read aria-pressed="true" and aria-expanded="true" and look like the active state, and loading reads data-loading. A loading button keeps its full opacity even when it's disabled, hides its content without removing it, so the size and the name stay, and centers a .spinner child over it.
  • Hover. Hover styles apply only on devices that can hover, through &:hover-capable:hover, so a tap on a touch screen doesn't leave a button looking hovered. That holds for a button rendered as <a href> too, since the global a:hover styles of useLinkElement only apply on devices that can hover as well.
  • Forced colors. In forced colors mode, the focus ring uses Highlight and the link variant gets a border, so it keeps a boundary (both through &:forced-colors). Pressed and expanded buttons use Highlight and HighlightText, and disabled buttons, loading ones included, use GrayText, through rules in the recipe's setup that outrank the dark theme. A disabled toggle keeps its Highlight background.
  • More contrast. With prefers-contrast: more (&:contrast-more), the outline and subtle borders take the label's color at full strength.
  • Motion. The recipe only fades colors, so nothing turns or slides when prefers-reduced-motion: reduce is set.
  • Right-to-left. Horizontal padding is set with paddingInline, the same on both sides, so it mirrors in right-to-left layouts.
<!-- Toggle button: pressed is styled from aria-pressed -->
<button type="button" class="..." aria-pressed="true">Bold</button>

<!-- Loading: stays focusable, keeps its size and name -->
<button type="button" class="..." aria-disabled="true" data-loading>
    <span class="spinner ..." aria-hidden="true">...</span>
    <span>Saving</span>
</button>
Good practice: When buttons appear next to each other in a toolbar or form, use the variant prop to create visual hierarchy. For example, use solid for the primary action and outline or ghost for secondary actions.

Customization

Overriding Defaults

The useButtonRecipe() composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:

src/components/button.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useButtonRecipe } from '@styleframe/theme';

const s = styleframe();

const button = useButtonRecipe(s, {
    base: {
        borderRadius: '@border-radius.full',
    },
    defaultVariants: {
        color: 'success',
        variant: 'soft',
        size: 'lg',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

src/components/button.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useButtonRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate primary and error colors, with solid and outline styles
const button = useButtonRecipe(s, {
    filter: {
        color: ['primary', 'error'],
        variant: ['solid', 'outline'],
    },
});

export default s;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

API Reference

useButtonRecipe(s, options?)

Creates a full button recipe with all variants and compound variant styling.

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the button
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorprimary, secondary, success, info, warning, error, light, dark, neutralneutral
variantsolid, outline, soft, subtle, ghost, linksolid
sizexs, sm, md, lg, xlmd

Learn more about recipes →

Best Practices

  • Choose colors by meaning, not appearance: Use success for positive actions and error for destructive actions — this keeps your UI consistent when tokens change.
  • Establish a clear visual hierarchy: Use solid for the primary action, outline or soft for secondary actions, and ghost or link for tertiary actions within the same context.
  • Stick to one or two sizes per context: Mixing too many sizes in the same area creates visual noise. Pick a default size and use alternatives sparingly.
  • Use ghost for toolbars and icon buttons: The transparent resting state keeps the interface clean while the hover state confirms interactivity.
  • Filter what you don't need: If your component only uses a few variants, pass a filter option to reduce generated CSS.
  • Override defaults at the recipe level: Set your most common variant combination as defaultVariants so component consumers write less code.

FAQ