agentleFS
dembrandtdembrandt/dembrandt-skills/skills/button-states/SKILL.md

button-states

Skill194 starsChanged 4 months agoMITView on GitHub

Rest, hover, active, focus, disabled and loading states, derived from the base colour. Use when designing buttons, links, inputs or any clickable component.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every interactive component must have a complete, visually distinct state for each interaction mode.

    line 48
  2. Very specific:

    Use outline, not box-shadow, for focus rings — outline respects border-radius in modern browsers and does not affect layout

    line 119
  3. Very specific:

    Never use outline: none without a replacement focus style

    line 121
  4. Very specific:

    Use pointer-events: none to prevent click events even if JS is bypassed

    line 135
  5. Distinctive:

    Do not change the shape or size of a disabled button — only colour and cursor change

    line 136
  6. Distinctive:

    When a button triggers an async action, replace the label with a spinner and prevent re-submission.

    line 140
  7. Distinctive:

    Keep the button width stable during loading — avoid layout shift when label is replaced by spinner

    line 151
  8. Very specific:

    Keep the scale value between 0.95–0.98.

    line 166

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

StateTriggerVisual signal
RestDefaultBase colour, cursor: pointer
HoverMouse overSlightly darker, subtle background shift
Active / PressedMouse down / tapNoticeably darker, slight scale-down
FocusKeyboard navigationVisible focus ring, no change to fill
DisabledNot availableLow contrast, cursor: not-allowed, no interaction
LoadingAsync action in progressSpinner 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, not box-shadow, for focus rings — outline respects border-radius in modern browsers and does not affect layout
  • outline-offset: 2–4px gives the ring breathing room from the component edge
  • Never use outline: none without 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: none to 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: pointer appear on all interactive elements at rest?
  • Does the cursor stay unchanged while an action runs, with progress shown by the element itself?

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.