UI Playbook: The Missing Manual for Component Behavior That Design Systems Don't Document

Hook

You've implemented a dozen dropdown menus across different projects, yet each time you find yourself Googling the same questions: Should Escape close nested menus? What happens when you type while focused? Every design system shows you the code, but none explain the decisions.

Context

Design systems have proliferated across the web development ecosystem—Material UI, Ant Design, Chakra UI, and dozens more offer pre-built components with beautiful documentation. Yet developers repeatedly encounter the same problem: these systems document what components do, not why they behave that way or how to make consistent decisions when implementing your own.

The reality is that most design systems are optimized for consumption, not education. They provide API references and visual guidelines but rarely explain the nuanced behavioral specifications that separate good components from great ones. When you need to understand why a modal should trap focus, or how a combobox should handle rapid keyboard input, you're left spelunking through GitHub issues, comparing implementations across multiple systems, or deciphering the ARIA Authoring Practices Guide. Rauno Freiberg's UI Playbook emerged from this frustration—a centralized reference that documents the tribal knowledge of UI component implementation in a framework-agnostic, accessibility-first format.

Technical Insight

UI Playbook's architecture is deceptively simple: it's a collection of "plays" (think playbook in sports), where each play documents a single component pattern with exhaustive detail. Rather than providing copy-paste code, it focuses on specifications—the behavioral contracts that any implementation should fulfill regardless of framework.

Take the Combobox play as an example. Instead of showing you React or Vue code, it breaks down the component into atomic concerns: keyboard interactions (Arrow keys navigate, Enter selects, Escape closes), focus management (where does focus go when the list opens?), ARIA relationships (aria-expanded, aria-controls, aria-activedescendant), and edge cases (what if the user types faster than your filter function?). Here's the kind of specification detail you'll find:

// Combobox keyboard interaction specification
interface ComboboxKeyboardBehavior {
  // When focus is on the input
  onArrowDown: () => {
    action: 'open-and-focus-first' | 'focus-next';
    condition: 'listbox-closed' | 'listbox-open';
  };
  
  onArrowUp: () => {
    action: 'focus-previous' | 'focus-last';
    note: 'Consider wrapping to last item when at first';
  };
  
  onEscape: () => {
    action: 'clear-and-close' | 'close-only';
    consideration: 'Does clearing the input make sense for your use case?';
  };
  
  onEnter: () => {
    action: 'select-highlighted' | 'submit-form';
    note: 'Prevent form submission if an option is highlighted';
  };
}

This isn't executable code—it's a decision framework. The TypeScript-style interface documents what decisions you need to make, not what the implementation should be. This approach is brilliant because it forces you to think through edge cases before writing code.

The plays also document common pitfalls with refreshing honesty. The Dialog play, for instance, explicitly warns about the z-index wars that ensue when you have nested modals, and discusses whether your dialog should close when clicking the backdrop (spoiler: it depends on whether the action is destructive). It references real-world implementations from Radix UI, Headless UI, and React Aria, showing where they differ and why.

Each play follows a consistent structure: an overview of the component's purpose, anatomy (the constituent parts like trigger, content, overlay), state management considerations (open/closed, selected items, focus state), accessibility requirements with specific ARIA attributes mapped to each part, and finally, behavioral specifications for both keyboard and pointer interactions. This structure means you can quickly scan to find the specific aspect you're uncertain about.

The accessibility documentation is particularly valuable. Rather than just listing ARIA attributes, it explains the relationships between elements and why they matter for screen reader users:

<!-- Dialog accessibility structure -->
<div role="dialog" 
     aria-labelledby="dialog-title"
     aria-describedby="dialog-description"
     aria-modal="true">
  
  <h2 id="dialog-title">Delete Account</h2>
  <p id="dialog-description">
    This action cannot be undone. All your data will be permanently removed.
  </p>
  
  <!-- Note: aria-modal="true" tells assistive tech to treat 
       content outside this dialog as inert, but you still need 
       to implement focus trapping in JavaScript -->
</div>

The comments explain the why behind each attribute, which is exactly what's missing from most documentation. You learn that aria-modal="true" is a hint, not a solution—you still need JavaScript focus trapping.

What makes UI Playbook particularly useful is its opinionated nature. Rather than presenting every possible approach with equal weight, Freiberg makes recommendations based on modern best practices. The Tooltip play, for example, explicitly discourages putting interactive content inside tooltips (use a Popover instead) and recommends against tooltips triggered solely by hover on touch devices. These opinions come from battle-tested experience, not academic theory.

Gotcha

UI Playbook's greatest strength—being framework-agnostic—is also its primary limitation. You won't find copy-paste solutions here. If you're looking for a React component you can npm install and use tomorrow, this isn't it. The project serves as a specification guide, which means you'll need to translate these patterns into your framework of choice. For junior developers or teams under tight deadlines, this translation step might feel like an obstacle rather than an educational opportunity.

The project is also notably incomplete, with only nine components documented as of this writing (Combobox, Dialog, Dropdown Menu, Popover, Select, Tabs, Toast, Toggle, and Tooltip). Critical patterns like Tables, Trees, Accordions, and Date Pickers are missing. This incompleteness means you can't rely on UI Playbook as your sole reference—you'll inevitably need to fall back to the ARIA Authoring Practices Guide or specific design system documentation for components not yet covered. The project's pace of updates is also uncertain, as it appears to be a solo endeavor maintained in Freiberg's spare time rather than a well-resourced open-source project with multiple contributors.

Verdict

Use if: you're building a component library from scratch and need comprehensive behavioral specifications before writing code; you're auditing an existing design system for accessibility gaps and edge case handling; you're a mid-level developer leveling up your understanding of proper UI component implementation; or you need a reference to align your team on component behavior during design reviews. UI Playbook excels as a research and specification tool that saves hours of cross-referencing multiple design systems. Skip if: you need production-ready component code you can ship this week; you're working with components not yet documented in the playbook; you prefer learning from complete, executable examples rather than specifications; or you're already deeply familiar with ARIA patterns and just need a quick component implementation. In those cases, reach for Radix UI Primitives or Headless UI instead—they provide the implementation alongside the patterns.