Add accessible pattern references to agent skill

[dylan-isaac]

Problem

Arrow's agent skill provides excellent guidance for reactivity, templates, and components — but when agents generate interactive widgets (accordions, tabs, dialogs, etc.), accessibility is inconsistent. The current examples demonstrate this:

Component	What's Present	What's Missing
Tabs	role="tablist", aria-selected, aria-controls	Arrow key navigation between tabs
Accordion	Basic button + content structure	aria-expanded, aria-controls, heading wrapper, role="region"
Table	Sortable via buttons	Not a <table> — no grid semantics, no aria-sort
Gallery	Buttons with images	Empty alt, no accessible names, no focus trap in lightbox

This isn't an Arrow problem — it's a training data problem. Agents reproduce whatever patterns they've seen, and accessible implementations are underrepresented. The skill is the right place to fix this.

Proposal

Add a references/patterns/ directory to the skill containing accessible pattern documentation for common widgets. Each pattern doc would include:

1. Quick Implementation — Minimal accessible Arrow example (what agents copy most)
2. Required/Recommended ARIA — Tables of attributes, easy to verify
3. Keyboard Interaction — Required and optional key behaviors
4. Variants — Common variations (e.g., single-expand accordion)
5. Common Mistakes — What to avoid
6. APG Reference — Link to W3C source

These docs would be based on the W3C ARIA Authoring Practices Guide but translated into idiomatic Arrow code.

Integration

Update SKILL.md to reference the patterns:

## Quick workflow

2. Read the smallest relevant reference:
   - Getting started / scaffold shape: `references/getting-started.md`
   - API surface and package split: `references/api.md`
   - Common patterns and examples: `references/examples.md`
   - Accessible widget patterns: `references/patterns/` (accordion, tabs, dialog, etc.)

Add a rule of thumb:

- When building interactive widgets (accordion, tabs, dialog, disclosure, menu),
  read the matching pattern in `references/patterns/` for required ARIA and keyboard interactions.

Priority Patterns

Based on existing examples and common agent requests:

• Accordion — Fix current example
• Tabs — Add missing keyboard nav
• Dialog — Not currently in examples, frequently requested
• Disclosure — Simple show/hide toggle
• Menu Button — Dropdown menus

Why This Matters

Arrow is positioning itself as "the first UI framework for the agentic era." Accessibility is a differentiator here — most agent-generated UIs are inaccessible because agents guess from training data. Encoding accessible patterns directly in the skill means Arrow agents produce accessible output by default.

This also aligns with the sandbox use case. If agents are generating UIs for end users in chat interfaces, those UIs need to be usable by everyone.

[dylan-isaac]

Here's an example of what one pattern could look like:

Accordion

An accordion is a vertically stacked set of interactive headings that reveal or hide associated content panels. Use this pattern when presenting multiple sections of content on a single page where users typically need only one or two sections at a time.

Quick Implementation

import { component, html, reactive } from '@arrow-js/core'

interface AccordionItem {
  id: string
  title: string
  content: string
}

const AccordionPanel = component((props: { item: AccordionItem; open: boolean }) => {
  const state = reactive({ expanded: props.open })

  return html`
    <div class="accordion-item">
      <h3>
        <button
          id="${`header-${props.item.id}`}"
          aria-expanded="${() => String(state.expanded)}"
          aria-controls="${`panel-${props.item.id}`}"
          @click="${() => { state.expanded = !state.expanded }}"
        >
          ${props.item.title}
        </button>
      </h3>
      <div
        id="${`panel-${props.item.id}`}"
        role="region"
        aria-labelledby="${`header-${props.item.id}`}"
        hidden="${() => !state.expanded}"
      >
        ${props.item.content}
      </div>
    </div>
  `
})

const items = [
  { id: 'shipping', title: 'Shipping', content: 'We ship worldwide...' },
  { id: 'returns', title: 'Returns', content: 'Returns accepted within 30 days...' },
  { id: 'warranty', title: 'Warranty', content: 'All products include a 1-year warranty...' },
]

html`
  <div class="accordion">
    ${items.map((item, i) =>
      AccordionPanel({ item, open: i === 0 }).key(item.id)
    )}
  </div>
`

Required ARIA

Attribute	Element	Value
aria-expanded	Header button	"true" when panel visible, "false" when hidden
aria-controls	Header button	ID of the associated panel

Recommended ARIA

Attribute	Element	Value
role="region"	Panel	Identifies panel as a landmark (use only when ≤6 panels)
aria-labelledby	Panel	ID of the header button

Keyboard Interaction

Key	Behavior
Enter / Space	Toggle the panel associated with the focused header
Tab	Move focus to next focusable element
Shift + Tab	Move focus to previous focusable element

Optional Keyboard (for many items)

Key	Behavior
Down Arrow	Move focus to next accordion header
Up Arrow	Move focus to previous accordion header
Home	Move focus to first accordion header
End	Move focus to last accordion header

Single-Expand Variant

When only one panel should be open at a time, lift state to the parent:

import { component, html, reactive } from '@arrow-js/core'

interface AccordionItem {
  id: string
  title: string
  content: string
}

const Accordion = component(() => {
  const state = reactive({ activeId: 'shipping' as string | null })

  const items: AccordionItem[] = [
    { id: 'shipping', title: 'Shipping', content: 'We ship worldwide...' },
    { id: 'returns', title: 'Returns', content: 'Returns accepted within 30 days...' },
    { id: 'warranty', title: 'Warranty', content: 'All products include a 1-year warranty...' },
  ]

  const toggle = (id: string) => {
    state.activeId = state.activeId === id ? null : id
  }

  return html`
    <div class="accordion">
      ${items.map((item) => html`
        <div class="accordion-item">
          <h3>
            <button
              id="${`header-${item.id}`}"
              aria-expanded="${() => String(state.activeId === item.id)}"
              aria-controls="${`panel-${item.id}`}"
              @click="${() => toggle(item.id)}"
            >
              ${item.title}
            </button>
          </h3>
          <div
            id="${`panel-${item.id}`}"
            role="region"
            aria-labelledby="${`header-${item.id}`}"
            hidden="${() => state.activeId !== item.id}"
          >
            ${item.content}
          </div>
        </div>
      `.key(item.id))}
    </div>
  `
})

With Arrow Key Navigation

For accordions with many items, add arrow key support:

import { component, html, reactive, onCleanup } from '@arrow-js/core'

const Accordion = component(() => {
  const state = reactive({ activeId: null as string | null })
  
  const items = [
    { id: 'q1', title: 'Question 1', content: 'Answer 1...' },
    { id: 'q2', title: 'Question 2', content: 'Answer 2...' },
    { id: 'q3', title: 'Question 3', content: 'Answer 3...' },
  ]

  const handleKeyDown = (e: KeyboardEvent, index: number) => {
    const headers = document.querySelectorAll<HTMLButtonElement>('.accordion-header')
    let targetIndex: number | null = null

    switch (e.key) {
      case 'ArrowDown':
        targetIndex = (index + 1) % headers.length
        break
      case 'ArrowUp':
        targetIndex = (index - 1 + headers.length) % headers.length
        break
      case 'Home':
        targetIndex = 0
        break
      case 'End':
        targetIndex = headers.length - 1
        break
    }

    if (targetIndex !== null) {
      e.preventDefault()
      headers[targetIndex].focus()
    }
  }

  return html`
    <div class="accordion">
      ${items.map((item, i) => html`
        <div class="accordion-item">
          <h3>
            <button
              class="accordion-header"
              id="${`header-${item.id}`}"
              aria-expanded="${() => String(state.activeId === item.id)}"
              aria-controls="${`panel-${item.id}`}"
              @click="${() => { state.activeId = state.activeId === item.id ? null : item.id }}"
              @keydown="${(e: KeyboardEvent) => handleKeyDown(e, i)}"
            >
              ${item.title}
            </button>
          </h3>
          <div
            id="${`panel-${item.id}`}"
            role="region"
            aria-labelledby="${`header-${item.id}`}"
            hidden="${() => state.activeId !== item.id}"
          >
            ${item.content}
          </div>
        </div>
      `.key(item.id))}
    </div>
  `
})

Structure Requirements

1. Header button inside heading: The button must be the only interactive element inside the heading. This preserves heading semantics for screen reader users.

2. Heading level: Use the appropriate heading level (h2, h3, etc.) for your page's information architecture. Don't skip levels.

3. Panel visibility: Use hidden attribute or CSS to hide collapsed panels. Avoid display: none on the panel content while keeping the panel element visible.

Common Mistakes

Mistake	Why It Matters	Fix
Using <div> instead of <button> for header	Not keyboard accessible, no implicit role	Use <button> element
Missing aria-expanded	Screen reader users can't determine panel state	Add aria-expanded that updates reactively
Using aria-hidden on panels	Content still focusable, creates confusing state	Use hidden attribute instead
Forgetting heading wrapper	Breaks document outline for screen reader users	Wrap button in <h2>-<h6>

APG Reference

W3C ARIA Authoring Practices: Accordion Pattern

[justin-schroeder]

Would love to produce more accessible results! I'm somewhat concerned about, effectively, just including an wcag spec into the skill though. Wouldn't that be better as its own skill rather than attached to the arrow-js skill?

[dylan-isaac]

I don't think so. To clarify, this isn't embedding the WCAG into the skill. If it were, we'd be including success criteria, conformance levels, understanding docs, etc. This is something different.

LLMs don't generate accessible UI by default. It's even present on your examples where tables aren't using semantic table elements. They reproduce whatever patterns are overrepresented in training data, and accessible implementations are not. The skill is the exact right place to fix that, because the skill is what shapes generation.

What I'm actually proposing is opinionated component patterns. "If you're building something that functions as an accordion, here's what it needs." That includes ARIA and keyboard interaction, yes, but only because those are minimum requirements for a UI element performing that role to actually work for everyone. It's not a spec reference, but a practical guide to not shipping broken components.

This also creates a reusable pattern for any opinionated guidance you want to embed, not just accessibility. Want to establish conventions for animation, error states, loading patterns, responsive behavior? Same structure, same progressive disclosure model. Agents read the relevant pattern doc only when building that specific widget.

The alternative is a separate accessibility skill that gives generic advice without knowing Arrow's reactive model. An agent would then have to reconcile two skills' guidance and figure out how to translate abstract ARIA rules into reactive() state, html templates, and @keydown handlers. That translation step is exactly where things break down.

Accessibility is the initial driver for this, but the pattern is general purpose. There isn't any reason why it can and should be limited to only accessibility.

[justin-schroeder]

ok! thank you for the write up. I would accept a PR in this direction! lets try to keep the token count as low as possible 🙏

[dylan-isaac]

Awesome! I appreciate you hearing me out. I'll draft a PR likely this weekend for you all to review and I will keep the token count down 😁

[xinha-sh]

It's even present on your examples where tables aren't using semantic table elements. They reproduce whatever patterns are overrepresented in training data, and accessible implementations are not. The skill is the exact right place to fix that, because the skill is what shapes generation.

Isn't this a generic problem and not arrow-js issue. Shouldn't this skill be a generic one for any framework ? All frameworks have component based state management and stuff, so a generic skill might work.

[dylan-isaac]

It's even present on your examples where tables aren't using semantic table elements. They reproduce whatever patterns are overrepresented in training data, and accessible implementations are not. The skill is the exact right place to fix that, because the skill is what shapes generation.

Isn't this a generic problem and not arrow-js issue. Shouldn't this skill be a generic one for any framework ? All frameworks have component based state management and stuff, so a generic skill might work.

Accessibility isn't a framework, it's a necessary implementation detail that allows all humans to interact with information equally on the web. By building it into the skill for arrow itself, it not only allows us to build in accessibility best practices, but establishes a place where other opinionated implementation details can be embedded to ensure that awesome UIs are created with Arrow.js