claude-workspace: Skill for Claude Code

Accessibility (a11y)

Principle: Semantic HTML First

Use the right element before reaching for ARIA:

// BAD: div cosplaying as a button
<div onClick={handleClick} className="btn">
  Submit
</div>

// GOOD: actual button
<button onClick={handleClick} type="button">
  Submit
</button>

Semantic elements provide keyboard handling, focus management, and screen reader semantics for free.

Interactive Element Patterns

Buttons vs Links

// Button: performs an action
<button type="button" onClick={handleSave}>
  Save Changes
</button>

// Link: navigates somewhere
<a href="/settings">Go to Settings</a>

// NEVER: link styled as button that performs action
// <a href="#" onClick={handleSave}>Save</a> // NO!

Toggle Button

function ToggleButton({ isPressed, onToggle, label }: ToggleButtonProps) {
  return (
    <button
      type="button"
      aria-pressed={isPressed}
      onClick={onToggle}
    >
      {label}
    </button>
  );
}

Disclosure (Expand/Collapse)

function Disclosure({ title, children }: DisclosureProps) {
  const [isOpen, setIsOpen] = useState(false);
  const contentId = useId();

  return (
    <div>
      <button
        type="button"
        aria-expanded={isOpen}
        aria-controls={contentId}
        onClick={() => setIsOpen(!isOpen)}
      >
        {title}
      </button>
      <div id={contentId} role="region" hidden={!isOpen}>
        {children}
      </div>
    </div>
  );
}

Modal / Dialog

function Modal({ isOpen, onClose, title, children }: ModalProps) {
  const titleId = useId();
  const previousFocus = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      previousFocus.current = document.activeElement as HTMLElement;
    } else {
      previousFocus.current?.focus(); // Restore focus on close
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={titleId}
      onKeyDown={(e) => e.key === 'Escape' && onClose()}
    >
      <h2 id={titleId}>{title}</h2>
      {children}
      <button type="button" onClick={onClose} aria-label="Close dialog">
        ×
      </button>
    </div>
  );
}