Tailwind Button Studio

The state stack: normal, hover, focus-visible, active, disabled, loading

A button is a stack of states, and the order of that stack is load-bearing. The cascade mnemonic, link, visited, hover, active, exists because CSS resolves equal-specificity conflicts by source order: while a pointer is both hovering and pressing, the rule declared later wins. That is why :active comes last. Declare :hover after :active and the press feedback never visibly fires. Add :focus-visible into the chain and the logic holds: each state must layer over the ones beneath it without permanently burying the ones above.

:focus-visible earns its careful spot. :focus fires on mouse clicks too, which makes focus rings on pointer interaction feel like noise. :focus-visible restricts the ring to keyboard navigation, the state keyboard users depend on entirely. The studio's generated classes include focus:ring-* utilities for this state, and its multi-state preview renders normal, hover, active, focus, and disabled side by side so each layer can be verified before the code ships.

The active state is press confirmation. Keep it short and physical: a scale-95 transform or a one-to-two pixel translate-y reads as the button yielding under the pointer, resolving in roughly the hover transition's duration so press and release feel like one gesture. The studio's click effects implement this with active: prefixed utilities.

Disabled and loading are where hand-written buttons quietly break. A disabled button needs the real disabled attribute, not just faded classes: the attribute removes the element from the tab order and blocks click events at the browser level, while opacity-60 and cursor-not-allowed only communicate the state visually. Loading is subtler: a spinner plus aria-busy="true" marks the control temporarily unavailable while keeping it focusable, and the click handler should be guarded so the action cannot fire twice mid-request. The studio generates the loading markup with a spinner; pairing the export with aria-busy on the button completes the pattern.

Touch targets: 44 points, 24 CSS pixels, and the space between targets

Touch target sizing is governed by three overlapping standards. WCAG 2.2 criterion 2.5.8, Target Size (Minimum), requires at least 24 by 24 CSS pixels at AA, with exceptions for inline targets, user-agent defaults, essential presentations, and equivalent controls. The AAA version, 2.5.5, raises it to 44 by 44. Apple recommends 44 by 44 points; Material specifies 48 by 48 density-independent pixels. A button clearing 44 by 44 satisfies all three, which is why 44 is the target.

The arithmetic is worth doing once. text-sm text has a 20-pixel line height; py-3 adds 12 pixels of padding top and bottom. Twelve plus twenty plus twelve equals 44. That is why px-6 py-3 at text-sm is the default comfortable button height in most Tailwind systems: it lands exactly on the Apple guideline with no arbitrary values. Drop to py-1.5 at text-xs and the target shrinks to about 32 pixels, which clears WCAG AA but misses the 44-pixel guideline, a defensible choice for dense toolbars and a poor one for a checkout page.

Padding is not the only input. Icon-only buttons need equal horizontal and vertical padding to stay square or circular as radius changes. Spacing between adjacent targets matters as much as size: two 44-pixel buttons with no gap form one row with an ambiguous boundary, so a gap-2 on the parent gives each target its own approachable zone. The minimum applies to the rendered box, not the visible glyph, so a ghost button still passes if its padding box reaches 44 pixels.

Design tokens in Tailwind v4: the `@theme` block as the button system

Tailwind v4 replaced the JavaScript config file with CSS-first configuration, and button systems show why clearly. Custom tokens live inside an @theme block in the stylesheet that imports Tailwind:

@import "tailwindcss"; @theme {--color-brand-600: #4f46e5; --color-brand-700: #4338ca; --animate-shimmer: shimmer 1s ease-in-out infinite; @keyframes shimmer {to { background-position: 200% 0; }}}

Each --color-* variable generates the full utility family, bg-brand-600, text-brand-600, ring-brand-600, automatically; each --animate-* variable generates the animate-* utility with its keyframes in the output. Keyframes declared inside @theme are emitted with the generated CSS, the detail people miss, so the animation utility works without a separate stylesheet.

The studio exports both worlds. Its version toggle switches between a v3 tailwind.config.js with theme.extend.colors.brand and a v4 global.css with the @theme block, registering the same nine-step color scale either way. Nine steps matter for buttons: 600 is the default fill, 700 the hover fill, 500 the focus ring, 100 the outline variant's hover tint, 800 the neobrutalist shadow edge. Shades referenced by role instead of hex values typed by hand is a design token system in miniature, and the @theme block is where it lives.

Six variants, one class skeleton

The six variants, solid, gradient, outline, ghost, glassmorphic, and neobrutalist, share one structure: an inline-flex container with centered content, a transition utility, padding, radius, font weight, and a color role. Only the fill strategy changes. Solid maps to bg-{color}-600 with a hover:bg-{color}-700 step. Gradient composes two- or three-stop gradients with independent from, via, and to colors plus a direction utility, shifting the stops darker on hover. Outline and ghost drop the fill, outline keeping a border-2 frame, and both read text and border colors from the theme scale so one color change re-themes them.

Glassmorphic and neobrutalist are where the class composition does real work. Glassmorphism pairs backdrop-blur with a low-alpha background and translucent border, and the preview renders it against light and dark canvases because frosted glass is unreadable without knowing what sits behind it. Neobrutalism hardens everything: a two-pixel solid border, flat fill, and an offset hard shadow that collapses on hover while the button translates into the shadow's former position. The generated markup keeps each variant's classes in the order the studio previewed them, so what you inspected is what ships.

Micro-interactions and the reduced-motion contract

The hover effects, lift-and-glow, scale, pulsing glow, and the 3D press, plus shimmer sweep, click ripple, and animated border glow, follow one pattern: a CSS transition on a visual property and a state class that changes it. The shimmer sweep is the instructive one. It needs a gradient band wider than the button, positioned off-canvas, translating across on hover inside an overflow-hidden container with a custom keyframe driving the sweep. That requires a pseudo-element or absolutely positioned child plus arbitrary values, exactly the class string nobody wants to assemble from memory. The click ripple needs JavaScript too: a handler reading click coordinates relative to the button's bounding rectangle, injecting a circle at that point, and removing it when the animation ends so ripples never accumulate in the DOM.

Decorative animation carries an obligation. An infinite pulsing glow is motion that serves aesthetics, not information, and prefers-reduced-motion exists for users who experience it as discomfort. Gate continuous animations behind it, by wrapping the keyframe application in the media query or using Tailwind's motion-safe: variant. Press feedback is different: a 150-millisecond scale on :active confirms an action the user initiated, and short user-triggered transforms are the category of motion that stays appropriate. Motion the user asked for, keep. Motion that plays on its own, make it opt out gracefully.

Related reading: the Tailwind button guide walks through variants, hover effects, and sizing with copy-paste examples, the border radius cheatsheet covers corner syntax, the transitions cheatsheet documents timing and easing, and the shine sweep button shows the shimmer pattern as a standalone element.

Frequently Asked Questions

Frequently Asked Questions