Button
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:
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:
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
| Color | Token | Use Case |
|---|---|---|
primary | @color.primary | Default actions, links, key information |
secondary | @color.secondary | Secondary actions, neutral states |
success | @color.success | Positive actions, confirmations, completions |
info | @color.info | Informational actions, tips, highlights |
warning | @color.warning | Caution actions, pending states |
error | @color.error | Destructive actions, error states, alerts |
light | @color.white / @color.gray-* | Buttons on dark surfaces, keeps its look in either theme |
dark | @color.gray-900 | Buttons on light surfaces, keeps its look in either theme |
neutral | Adaptive (light ↔ dark) | Default color, adapts to the current color scheme |
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.
Link
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
| Size | Font Size | Border 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
warningcolor 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). Thelightcolor is made for dark surfaces and thedarkcolor 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-visibleonly (WCAG 2.4.7). Thecolor.focustoken defaults tocolor.primaryand keeps at least 3:1 against the page. - Target size and resizing. Each size sets a
min-heightand a matchingmin-widthinrem, from1.5rematxsto3rematxl, 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::beforehit 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
:disabledandaria-disabled="true", pressed and expanded readaria-pressed="true"andaria-expanded="true"and look like the active state, and loading readsdata-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.spinnerchild 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 globala:hoverstyles ofuseLinkElementonly apply on devices that can hover as well. - Forced colors. In forced colors mode, the focus ring uses
Highlightand thelinkvariant gets a border, so it keeps a boundary (both through&:forced-colors). Pressed and expanded buttons useHighlightandHighlightText, and disabled buttons, loading ones included, useGrayText, through rules in the recipe's setup that outrank the dark theme. A disabled toggle keeps itsHighlightbackground. - More contrast. With
prefers-contrast: more(&:contrast-more), theoutlineandsubtleborders take the label's color at full strength. - Motion. The recipe only fades colors, so nothing turns or slides when
prefers-reduced-motion: reduceis 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>
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:
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:
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;
API Reference
useButtonRecipe(s, options?)
Creates a full button recipe with all variants and compound variant styling.
Parameters:
| Parameter | Type | Description |
|---|---|---|
s | Styleframe | The Styleframe instance |
options | DeepPartial<RecipeConfig> | Optional overrides for the recipe configuration |
options.base | VariantDeclarationsBlock | Custom base styles for the button |
options.variants | Variants | Custom variant definitions for the recipe |
options.defaultVariants | Record<keyof Variants, string> | Default variant values for the recipe |
options.compoundVariants | CompoundVariant[] | Custom compound variant definitions for the recipe |
options.filter | Record<string, string[]> | Limit which variant values are generated |
Variants:
| Variant | Options | Default |
|---|---|---|
color | primary, secondary, success, info, warning, error, light, dark, neutral | neutral |
variant | solid, outline, soft, subtle, ghost, link | solid |
size | xs, sm, md, lg, xl | md |
Best Practices
- Choose colors by meaning, not appearance: Use
successfor positive actions anderrorfor destructive actions — this keeps your UI consistent when tokens change. - Establish a clear visual hierarchy: Use
solidfor the primary action,outlineorsoftfor secondary actions, andghostorlinkfor 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
ghostfor 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
filteroption to reduce generated CSS. - Override defaults at the recipe level: Set your most common variant combination as
defaultVariantsso component consumers write less code.
FAQ
The Button recipe uses compound variants to map each color-variant combination to specific styles. For example, when color is primary and variant is solid, the compound variant applies background: @color.primary, color: @color.white, and borderColor: @color.primary-shade-50, along with hover, active, pressed, and dark mode overrides. This approach keeps the individual color and variant definitions clean while handling all 54 combinations (9 colors × 6 variants) automatically.
Yes. Override the variants.color and compoundVariants options to add new colors. You'll need to define the empty color variant and add compound variants for each visual style:
const button = useButtonRecipe(s, {
variants: {
color: {
brand: {},
},
},
compoundVariants: [
{ match: { color: 'brand', variant: 'solid' }, css: { background: '@color.brand', color: '@color.white' } },
{ match: { color: 'brand', variant: 'outline' }, css: { color: '@color.brand', borderColor: '@color.brand' } },
// ... soft, subtle, ghost, and link
],
});
ghost and link have a transparent resting state. The difference is that ghost reveals a tinted background on hover (like a toolbar button), while link adds an underline on hover (like a hyperlink). Use ghost for actions within a layout and link for inline navigation actions.subtle also adds a matching colored border, giving the button more visual definition. Use soft when you want a gentler appearance, and subtle when the button needs slightly more structure.filter option, compound variants that reference filtered-out values are automatically removed. For example, if you filter variant to only ['solid', 'outline'], all compound variants matching soft, subtle, ghost, or link are excluded from the generated output. Default variants are also adjusted if they reference a removed value.&:disabled and &:aria-disabled modifiers. The base configuration reduces opacity to 0.75 and sets cursor: not-allowed, and trailing compound variants keep the resting colors, so hovering or pressing changes nothing. It keeps pointer events, so clicks don't fall through to whatever is underneath. Pass the HTML disabled attribute to your <button> element to activate both the visual style and the accessibility semantics, or aria-disabled="true" when it has to stay focusable.@color.primary, @font-size.sm, and @border-radius.md through string refs. These tokens need to be defined in your Styleframe instance for the recipe to generate valid CSS. The easiest way is to use useDesignTokensPreset(s), but you can also define the required tokens manually.Overview
Explore Styleframe's component recipes — pre-built, composable styling patterns for common UI elements like badges, buttons, and more.
Hamburger Menu
A three-bar toggle button that animates into a different glyph (X, arrow, plus, or minus) when opened. Supports three colors, three sizes, seven animations, and an active state through the recipe system.