Agent skill

focus-states

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.

View SKILL.md on GitHub Repository
Stars 18
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/dylantarre/design-system-skills/tree/main/skills/accessibility/focus-states

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

Criterion Requirement Level
2.4.7 Focus Visible Focus indicator must be visible AA
2.4.11 Focus Appearance 2px+ perimeter, 3:1 contrast AAA
2.4.12 Focus Not Obscured Focus not hidden by other content AA

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

Style Character Best For
Ring Clean, defined Buttons, inputs, cards
Glow Soft, modern Dark themes, premium UI
Underline Minimal Text links, nav items
Offset High contrast When ring blends with element
Inset Subtle Contained elements

Output Formats

CSS Custom Properties + Utilities:

css
: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:

css
/* 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:

js
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:

html
<!-- 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:

json
{
  "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

css
/* 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:

Background Focus Ring Ratio
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:

css
.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:

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

Focus hidden behind sticky header:

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

Focus invisible on element with background:

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

dylantarre/design-system-skills

getting-started

Introduction to the design system skills plugin. Use when first installing the plugin, exploring available skills, or planning a design system implementation.

18 2
Explore
dylantarre/design-system-skills

responsive-typography

Implements fluid typography using CSS clamp() that scales with viewport. Use when creating responsive font sizes, viewport-aware headings, or type that adapts smoothly without breakpoints.

18 2
Explore
dylantarre/design-system-skills

spacing-scale

Generates consistent spacing tokens using base values and ratios. Use when creating margin/padding systems, gap tokens, or layout spacing. Outputs CSS custom properties, Tailwind config, or JSON tokens.

18 2
Explore
dylantarre/design-system-skills

color-scale

Generates perceptually uniform OKLCH color palettes from brand colors. Use when creating color systems, theme palettes, or converting hex values to 11-step scales. Outputs CSS custom properties, Tailwind config, or JSON tokens.

18 2
Explore
dylantarre/design-system-skills

shadow-scale

Generates layered box-shadow elevation tokens for depth hierarchy. Use when creating elevation systems, card shadows, modal depth, or dark mode shadow variants. Outputs CSS, Tailwind, or JSON.

18 2
Explore
dylantarre/design-system-skills

breakpoints

Generates responsive breakpoint tokens for media queries and container queries. Use when setting up responsive design, mobile-first layouts, or viewport-based styling. Outputs CSS, Tailwind, or JSON.

18 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results