agentleFS
dylantarredylantarre/design-system-skills/skills/accessibility/focus-states/SKILL.md

focus-states

Skill50 starsChanged 11 months agoMITView on GitHub

Generates accessible focus indicators meeting WCAG 2.4.7 and 2.4.11 requirements. Use when styling :focus-visible, keyboard navigation indicators, or fixing focus ring visibility issues.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask visibility approach: Always visible or focus-visible only?

    line 35
  2. Distinctive:

    Generate: Create focus tokens and utility classes

    line 36

≈ “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

Focus States Generator

Overview

Generate accessible, visible focus indicators for interactive elements. Creates focus styles that meet WCAG 2.4.7 (Focus Visible) and 2.4.11 (Focus Appearance) requirements while maintaining visual design consistency.

When to Use

  • Setting up focus styles for a design system
  • Ensuring keyboard navigation is visible
  • Creating custom focus rings that match brand
  • Fixing "invisible" focus states in existing UI

Quick Reference: WCAG Requirements

CriterionRequirementLevel
2.4.7 Focus VisibleFocus indicator must be visibleAA
2.4.11 Focus Appearance2px+ perimeter, 3:1 contrastAAA
2.4.12 Focus Not ObscuredFocus not hidden by other contentAA

The Process

  1. Get brand colors: Primary color and background colors
  2. Ask style preference:
    • Ring (outline around element)
    • Glow (soft shadow-based)
    • Underline (for text links)
    • Hybrid (ring + offset)
  3. Ask visibility approach: Always visible or focus-visible only?
  4. Generate: Create focus tokens and utility classes
  5. Test guidance: Provide keyboard testing checklist

Focus Style Options

StyleCharacterBest For
RingClean, definedButtons, inputs, cards
GlowSoft, modernDark themes, premium UI
UnderlineMinimalText links, nav items
OffsetHigh contrastWhen ring blends with element
InsetSubtleContained elements

Output Formats

CSS Custom Properties + Utilities:

:root {
  /* Focus tokens */
  --focus-ring-color: #2563eb;
  --focus-ring-width: 2px;
  --focus-ring-offset: 2px;
  --focus-ring-style: solid;

  /* Computed focus ring */
  --focus-ring: var(--focus-ring-width) var(--focus-ring-style) var(--focus-ring-color);
  --focus-ring-offset-shadow: 0 0 0 var(--focus-ring-offset) var(--color-background);
  --focus-ring-shadow: 0 0 0 calc(var(--focus-ring-offset) + var(--focus-ring-width)) var(--focus-ring-color);
}

/* Base focus reset */
*:focus {
  outline: none;
}

/* Focus-visible for keyboard only */
*:focus-visible {
  outline: var(--focus-ring);
  outline-offset: var(--focus-ring-offset);
}

/* Alternative: box-shadow approach (more styling control) */
.focus-ring:focus-visible {
  outline: none;
  box-shadow:
    var(--focus-ring-offset-shadow),
    var(--focus-ring-shadow);
}

Component-Specific Focus:

/* Buttons */
.btn:focus-visible {
  outline: 2px solid var(--focus-ring-color);
  outline-offset: 2px;
}

/* Inputs - inset focus */
.input:focus-visible {
  outline: none;
  border-color: var(--focus-ring-color);
  box-shadow: 0 0 0 3px rgb(37 99 235 / 0.2);
}

/* Cards - offset ring */
.card:focus-visible {
  outline: 2px solid var(--focus-ring-color);
  outline-offset: 4px;
}

/* Links - underline enhancement */
a:focus-visible {
  outline: none;
  text-decoration-thickness: 2px;
  text-underline-offset: 4px;
  background-color: rgb(37 99 235 / 0.1);
  border-radius: 2px;
}

/* Skip link */
.skip-link:focus {
  position: fixed;
  top: 1rem;
  left: 1rem;
  z-index: 9999;
  padding: 1rem;
  background: var(--color-background);
  outline: 2px solid var(--focus-ring-color);
}

Tailwind Config:

module.exports = {
  theme: {
    extend: {
      ringColor: {
        DEFAULT: '#2563eb',
      },
      ringWidth: {
        DEFAULT: '2px',
      },
      ringOffsetWidth: {
        DEFAULT: '2px',
      },
    }
  },
  plugins: [
    // Custom focus-visible variant
    plugin(function({ addVariant }) {
      addVariant('focus-visible-within', '&:has(:focus-visible)')
    })
  ]
}

Tailwind Utilities:

<!-- Standard focus ring -->
<button class="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2">
  Button
</button>

<!-- Glow style -->
<button class="focus-visible:outline-none focus-visible:ring-4 focus-visible:ring-blue-500/30">
  Glow Button
</button>

JSON Tokens:

{
  "focus": {
    "ring": {
      "color": { "value": "{color.primary.500}" },
      "width": { "value": "2px" },
      "offset": { "value": "2px" },
      "style": { "value": "solid" }
    },
    "glow": {
      "color": { "value": "{color.primary.500}" },
      "blur": { "value": "4px" },
      "spread": { "value": "2px" },
      "opacity": { "value": "0.3" }
    }
  }
}

Dark Mode Focus

/* Light mode */
:root {
  --focus-ring-color: #2563eb;
  --focus-ring-offset-color: #ffffff;
}

/* Dark mode - increase visibility */
:root.dark {
  --focus-ring-color: #60a5fa;
  --focus-ring-offset-color: #1f2937;
}

Focus Indicator Contrast

WCAG 2.4.11 requires 3:1 contrast between:

  1. Focus indicator and adjacent background
  2. Focus indicator and the element itself

Safe combinations:

BackgroundFocus RingRatio
White#2563eb (blue-600)4.7:1 ✓
Gray-100#1d4ed8 (blue-700)6.5:1 ✓
Gray-900#60a5fa (blue-400)6.2:1 ✓
Black#93c5fd (blue-300)9.4:1 ✓

Interactive States Order

Apply states in this specificity order:

.element { }
.element:hover { }
.element:focus { }
.element:focus-visible { }  /* Keyboard only */
.element:active { }
.element:disabled { }

Testing Checklist

  • Tab through entire page - focus always visible
  • Focus ring visible against all backgrounds
  • Focus visible on buttons, links, inputs, selects
  • Custom components (dropdowns, modals) receive focus
  • Focus trapped in modals when open
  • Skip link appears on first Tab press
  • Focus returns to trigger when modal closes
  • No focus on non-interactive elements
  • Focus order matches visual order

Common Fixes

Focus disappears on click:

/* Use focus-visible, not focus */
button:focus-visible { outline: ... }

Focus hidden behind sticky header:

:target { scroll-margin-top: 80px; }
*:focus { scroll-margin-top: 80px; }

Focus invisible on element with background:

/* Add offset to create separation */
outline-offset: 2px;
/* Or use contrasting ring color */

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.