Building Frontend Components

Iron Law

Pre-Implementation Checklist

1. Check for existing design system — tokens, components, patterns already in repo
2. Document component requirements — states (loading, error, empty), variants, accessibility needs
3. Plan keyboard interaction — focus order, shortcuts, trap requirements

references/patterns.md

references/patterns.md

Accessibility Essentials (Non-Negotiable)

Modal/Dialog Components

// REQUIRED attributes
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title-id"
  ref={dialogRef}
>
  <h2 id="modal-title-id">{title}</h2>
</div>

// REQUIRED behaviors
// 1. Focus first interactive element on open
// 2. Trap focus within modal (Tab cycles inside)
// 3. Restore focus to trigger element on close
// 4. Close on Escape key

references/patterns.md

Form Components

// REQUIRED: Link errors to fields
<input
  id="email"
  aria-invalid={errors.email ? 'true' : 'false'}
  aria-describedby={errors.email ? 'email-error' : undefined}
/>
{errors.email && (
  <span id="email-error" role="alert">
    {errors.email.message}
  </span>
)}

// REQUIRED: Form identification
<form aria-label="Login form">
  {/* or aria-labelledby pointing to a heading */}
</form>

Interactive Elements

role

aria-*

aria-expanded

aria-haspopup

Component State Checklist

• Default — Normal display state
• Loading — Skeleton or spinner (avoid for <500ms operations)
• Empty — Meaningful empty state, not blank
• Error — Actionable message with recovery path
• Disabled — Visual indication +

  aria-disabled

  or

  disabled

• Focus — Visible focus indicator (never

  outline: none

  without replacement)

Anti-Patterns (Stop If You See These)

Generic AI Aesthetics

• ❌ Purple-on-white gradients with no context
• ❌ Cookie-cutter card layouts (centered hero + three icons)
• ❌ Flat solid backgrounds lacking atmosphere
• ✅ Honor existing design system OR establish distinctive direction

Technical Debt

• ❌ Inline styles scattered throughout (use CSS modules, Tailwind, or tokens)
• ❌ Magic numbers instead of design tokens
• ❌ Hardcoded colors like

  #2563eb

  without token reference
• ✅ Use CSS custom properties or design tokens

Accessibility Oversights

• ❌ Missing

  role="dialog"

  and

  aria-modal

  on modals
• ❌ No focus trap in modals/drawers
• ❌ Error messages without

  role="alert"

• ❌ Form fields without

  aria-invalid

  /

  aria-describedby

• ❌ Interactive elements without visible focus indicators

Common Mistakes from Baseline Testing

role="dialog"

aria-invalid

aria-describedby

role="alert"

When NOT to Use This Skill

• Pure backend/API work with no UI
• Static content pages (use Astro or static HTML instead)
• Design system documentation (use the design system's own tooling)

Additional References

references/patterns.md

Definition of Done

• Pre-implementation checklist completed (design system check, requirements, keyboard plan)
• All states implemented (default, loading, empty, error, disabled)
• Keyboard navigation works (Tab, Shift+Tab, Enter, Escape, arrows)
• Screen reader announces all interactive elements
• Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
• Responsive at 360px, 768px, 1280px
• Works with 200% browser zoom

• prefers-reduced-motion

  respected
• Error boundaries catch render failures
• No

  any

  types, console logs, or TODOs remain
• Tests pass (unit, a11y, visual if applicable)