playbooks

home / skills / harborgrid-justin / lexiflow-premium / headless-component-architecture

headless-component-architecture skill

/frontend/.github-skills/headless-component-architecture

This skill helps you design headless components that expose logic and accessibility via hooks or render props, without UI styling.

npx playbooks add skill harborgrid-justin/lexiflow-premium --skill headless-component-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
851 B
---
name: headless-component-architecture
description: Design components that provide logic and accessibility without prescribing UI styling.
---

# Headless Component Architecture

## Summary
Design components that provide logic and accessibility without prescribing UI styling.

## Key Capabilities
- Expose state and handlers via Render Props or Hooks.
- Ensure accessible aria attributes are correctly applied.
- Support total styling inversion by consumers.

## PhD-Level Challenges
- Design an API that supports all valid user interactions.
- Prevent internal state inconsistencies in controlled mode.
- Type-check slot props for type-safe consumption.

## Acceptance Criteria
- Provide a library of headless UI primitives.
- Demonstrate two distinct visual implementations of one primitive.
- Pass accessibility audits on both implementations.

Overview

This skill teaches how to design headless components that deliver behavior and accessibility without imposing visual styling. It focuses on APIs that expose state and handlers, ensuring consumers can fully control presentation while preserving correct ARIA semantics. The outcome is reusable logic primitives that integrate into any design system or CSS framework.

How this skill works

Components expose state and event handlers via Render Props or Hooks so consumers compose UI separately from logic. The library enforces accessible attributes and keyboard behavior, while offering controlled and uncontrolled modes to match consumer needs. Tests and audits verify accessibility across multiple visual implementations.

When to use it

  • Building design-system primitives that must be style-agnostic.
  • Creating accessible interactive controls (menus, dialogs, lists) without a preset look.
  • Offering consumers maximum flexibility to implement distinct visual themes.
  • Supporting both framework-agnostic integration and React-specific Hook APIs.
  • Replacing monolithic styled components with logic-only building blocks.

Best practices

  • Expose a minimal, well-documented API: state, handlers, and slot props only.
  • Support both Render Props and Hooks to accommodate different consumer patterns.
  • Make ARIA roles/attributes canonical and test keyboard flows thoroughly.
  • Design for controlled mode first; provide stable warnings and noop fallbacks.
  • Type-check slot props and events to surface integration errors early.

Example use cases

  • A headless dropdown primitive used to build two different styled dropdowns: compact and feature-rich.
  • An accessible dialog that supplies focus management and escape/overlay handling while letting CSS define visuals.
  • A toggle switch Hook that returns checked state and accessible props for any custom switch UI.
  • Composing a listbox primitive into both a plain HTML list and a card-based selection grid.

FAQ

How do I prevent internal state conflicts when consumers control state?

Design the API for controlled-first usage: accept value/checked and onChange, keep internal state as fallback, and emit stable warnings if both controlled and uncontrolled props are mixed.

How can I ensure accessibility across visual implementations?

Encode ARIA attributes and keyboard handling in the primitive, run automated accessibility audits, and include example implementations demonstrating correct use in different visual contexts.