dembrandt/dembrandt-skills / skills/button-states
button-states
VerifiedRest, hover, active, focus, disabled and loading states, derived from the base colour. Use when designing buttons, links, inputs or any clickable component.
Button and Interactive Element States
Every interactive component must have a complete, visually distinct state for each interaction mode. Missing or ambiguous states make the UI feel unfinished and reduce user confidence.
The Six States
| State | Trigger | Visual signal |
|---|---|---|
| Rest | Default | Base colour, cursor: pointer |
| Hover | Mouse over | Slightly darker, subtle background shift |
| Active / Pressed | Mouse down / tap | Noticeably darker, slight scale-down |
| Focus | Keyboard navigation | Visible focus ring, no change to fill |
| Disabled | Not available | Low contrast, cursor: not-allowed, no interaction |
| Loading | Async action in progress | Spinner or pulse, non-interactive |
Deriving State Colours Algorithmically
State colours are not chosen independently — they are derived from the base colour by adjusting lightness in HSL. This guarantees coherence across the entire palette.
base: hsl(H, S%, L%)
hover: hsl(H, S%, L% - 8%) ← darken 8%
active: hsl(H, S%, L% - 14%) ← darken 14%
Example: primary button #635BFF (hsl 243, 100%, 68%)
.btn-primary {
background: hsl(243, 100%, 68%); /* rest #635BFF */
}
.btn-primary:hover {
background: hsl(243, 100%, 60%); /* hover #4A40FF */
}
.btn-primary:active {
background: hsl(243, 100%, 54%); /* active #3429FF */
}
For light buttons on dark backgrounds, invert the logic — lighten on hover instead of darkening.
Secondary / outlined buttons
.btn-secondary {
background: transparent;
border: 1px solid var(--color-border);
color: var(--color-text);
}
.btn-secondary:hover {
background: var(--color-grey-100); /* subtle fill */
border-color: var(--color-grey-300);
}
.btn-secondary:active {
background: var(--color-grey-200);
}
The Primary Fill Is Chosen per Background
A brand's main action is often not one colour. The bright brand colour carries it on white, a dark variant of the same hue on a light brand tint, black or white on photos and dark sections. Define the primary button as one role with a fill per surface it sits on, each with its own derived states and a contrast check, rather than forcing one fill onto every background. A near-black or desaturated colour of the brand hue is a variant in the brand family, not neutral ink.
Focus State
Focus is a keyboard navigation requirement (WCAG 2.2). It must be visible and must not rely on the hover style alone — keyboard users do not trigger hover.
.btn:focus-visible {
outline: 2px solid var(--color-primary);
outline-offset: 3px;
}
- Use
outline, notbox-shadow, for focus rings —outlinerespectsborder-radiusin modern browsers and does not affect layout outline-offset: 2–4pxgives the ring breathing room from the component edge- Never use
outline: nonewithout a replacement focus style
Disabled State
.btn:disabled,
.btn[aria-disabled="true"] {
opacity: 0.4;
cursor: not-allowed;
pointer-events: none;
}
- Disabled elements are exempt from WCAG contrast requirements — low opacity is correct and intentional
- Use
pointer-events: noneto prevent click events even if JS is bypassed - Do not change the shape or size of a disabled button — only colour and cursor change
Loading State
When a button triggers an async action, replace the label with a spinner and prevent re-submission.
.btn--loading {
pointer-events: none;
opacity: 0.7;
}
The cursor does not change while loading. It signals affordance, not progress: the arrow for ordinary content, pointer for something you can act on. Progress belongs to the element and the loading region, which the user is already looking at, rather than to wherever the mouse happens to rest. cursor: wait is also inert next to pointer-events: none, so the rule reads as deliberate while doing nothing.
- Keep the button width stable during loading — avoid layout shift when label is replaced by spinner
- Return to rest state on completion (success or error)
- For long-running operations, pair with a status message — a spinner alone does not tell the user what is happening
Scale on Active (Optional)
A subtle scale-down on press adds physical feedback — borrowed from Disney's squash principle.
.btn:active {
transform: scale(0.97);
transition: transform 80ms ease-out;
}
Keep the scale value between 0.95–0.98. Below 0.95 feels like the button is breaking.
Complete Button CSS Reference
.btn {
cursor: pointer;
background: var(--color-primary);
color: white;
border-radius: var(--radius-button);
padding: var(--component-padding-y-md) var(--component-padding-x-md);
height: var(--component-height-md);
border: none;
transition: background 120ms ease-out, transform 80ms ease-out;
}
.btn:hover { background: var(--color-primary-hover); }
.btn:active { background: var(--color-primary-active); transform: scale(0.97); }
.btn:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 3px; }
.btn:disabled { opacity: 0.4; cursor: not-allowed; pointer-events: none; }
.btn.btn--loading { opacity: 0.7; pointer-events: none; }
Review Checklist
- Does every interactive element have all six states defined?
- Does the primary button have a defined fill for each surface it sits on, each passing contrast?
- Are hover and active colours derived from the base by lightness adjustment (not chosen arbitrarily)?
- Is focus state visible and using
outline(not removed)? - Is disabled state low-opacity with
cursor: not-allowed? - Does loading state prevent re-submission?
- Are transition durations 80–150ms — not instant, not slow?
- Does
cursor: pointerappear on all interactive elements at rest? - Does the cursor stay unchanged while an action runs, with progress shown by the element itself?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |