diff --git a/.claude/skills/api/references/state.md b/.claude/skills/api/references/state.md index 5a8b6e98..43d96f19 100644 --- a/.claude/skills/api/references/state.md +++ b/.claude/skills/api/references/state.md @@ -2,6 +2,24 @@ Patterns for designing and using state management in TypeScript libraries. +## Contents + +- [Mental Models](#mental-models) — Zustand, Jotai, XState, Valtio +- [Core Subscription Interface](#core-subscription-interface) +- [Middleware as Higher-Order Functions](#middleware-as-higher-order-functions) +- [Slice Pattern](#slice-pattern) +- [Atomic Composition](#atomic-composition-jotai-pattern) +- [Selector Pattern](#selector-pattern) +- [Split Stores When Truly Isolated](#split-stores-when-truly-isolated) +- [Cross-Store Access](#cross-store-access) +- [Derived State Patterns](#derived-state-patterns) +- [Optimistic Updates](#optimistic-updates) +- [State Initialization](#state-initialization) +- [Request State Pattern](#request-state-pattern) +- [Proxy-Based Reactivity](#proxy-based-reactivity-valtio) +- [Presets as Transparent Collections](#presets-as-transparent-collections) +- [Dev Tools Integration](#dev-tools-integration) + ## Mental Models Daishi Kato created Zustand, Jotai, and Valtio with intentionally different architectures because **different problems need different mental models**. diff --git a/.claude/skills/aria/references/aria.md b/.claude/skills/aria/references/aria.md index a1bb6fbf..8a8e024a 100644 --- a/.claude/skills/aria/references/aria.md +++ b/.claude/skills/aria/references/aria.md @@ -2,6 +2,14 @@ Roles, states, properties, labeling strategies, and live regions. +## Contents + +- [First Rule of ARIA](#first-rule-of-aria) — Use native HTML when possible +- [Roles by Component](#roles-by-component) — Buttons, menus, dialogs, lists, tabs, sliders +- [Required Attributes by Role](#required-attributes-by-role) +- [State Attributes](#state-attributes) — pressed, expanded, selected, checked, current +- [Labeling](#labeling) — Priority order, aria-label vs aria-labelledby + --- ## First Rule of ARIA diff --git a/.claude/skills/aria/references/media.md b/.claude/skills/aria/references/media.md index 15d354ca..42766d6a 100644 --- a/.claude/skills/aria/references/media.md +++ b/.claude/skills/aria/references/media.md @@ -2,6 +2,16 @@ Accessibility patterns specific to video and audio players. Covers controls, keyboard shortcuts, captions, and screen reader support. +## Contents + +- [Player Container](#player-container) — Root element identification +- [Keyboard Shortcuts](#keyboard-shortcuts) — Standard media keys, key scope +- [Control Bar](#control-bar) — Toolbar pattern +- [Control Components](#control-components) — Play, mute, time slider, volume, fullscreen, captions +- [Settings Menu](#settings-menu) — Structure, keyboard navigation +- [Live Announcements](#live-announcements) — Announcer component, events to announce +- [Captions](#captions) — CVAA compliance requirements + --- ## Player Container diff --git a/.claude/skills/aria/references/react.md b/.claude/skills/aria/references/react.md index 672fbb43..59419244 100644 --- a/.claude/skills/aria/references/react.md +++ b/.claude/skills/aria/references/react.md @@ -2,6 +2,16 @@ React-specific patterns for accessibility. Covers hook architecture, ref management, and framework considerations. +## Contents + +- [Hook Architecture](#hook-architecture) — Layer separation, behavior hooks +- [Focus Management Hooks](#focus-management-hooks) — Scope, ring detection, roving tabindex +- [Ref Patterns](#ref-patterns) — Merging refs, callback refs +- [Event Handling](#event-handling) — Keyboard normalization, press events +- [Announcements](#announcements) — Live regions, status messages +- [SSR Considerations](#ssr-considerations) — ID generation, hydration +- [Portal Accessibility](#portal-accessibility) + --- ## Hook Architecture diff --git a/.claude/skills/claude-update/SKILL.md b/.claude/skills/claude-update/SKILL.md index 9c7add78..0a3f4a8d 100644 --- a/.claude/skills/claude-update/SKILL.md +++ b/.claude/skills/claude-update/SKILL.md @@ -1,6 +1,8 @@ --- name: claude-update -description: Update CLAUDE.md and skills when introducing new patterns or conventions +description: >- + Update CLAUDE.md and skills when introducing new patterns or conventions. + Triggers: "update claude", "update skills", "new pattern", "add convention". context: fork disable-model-invocation: true --- diff --git a/.claude/skills/component/SKILL.md b/.claude/skills/component/SKILL.md index 61761c92..61bb87a3 100644 --- a/.claude/skills/component/SKILL.md +++ b/.claude/skills/component/SKILL.md @@ -5,6 +5,7 @@ description: >- Use when creating component libraries, design systems, or reusable UI primitives. Handles compound components, state management, accessibility, styling hooks, and API design. Includes Lit (controllers, ReactiveElement) and React (hooks, context) patterns. + Triggers: "create component", "component pattern", "compound component", "headless component". --- # Component Architecture Patterns diff --git a/.claude/skills/docs/references/state-tooling.md b/.claude/skills/docs/references/state-tooling.md index 139ae896..961c100d 100644 --- a/.claude/skills/docs/references/state-tooling.md +++ b/.claude/skills/docs/references/state-tooling.md @@ -2,6 +2,12 @@ Patterns from Zustand, Jotai, XState, Vite, Vitest, esbuild, Biome. +## Contents + +- [State Management Documentation](#state-management-documentation) — Zustand, Jotai, XState patterns +- [Configuration Documentation](#configuration-documentation) — Vite, esbuild patterns +- [Testing Documentation](#testing-documentation-vitest) — Test examples, mocking media + ## State Management Documentation ### Zustand Pattern: Minimal Getting Started diff --git a/.claude/skills/review-branch/SKILL.md b/.claude/skills/review-branch/SKILL.md index 6c752629..5a572b32 100644 --- a/.claude/skills/review-branch/SKILL.md +++ b/.claude/skills/review-branch/SKILL.md @@ -75,97 +75,18 @@ For deeper domain-specific review, load the relevant skill: Skip this step for quick reviews using the inline checklists below. -### Step 4: Apply Skill-Based Review Checklists +### Step 4: Apply Skill-Based Review -Based on detected categories, apply the relevant quick checklists: +Based on detected categories, load the relevant skill's review checklist: ---- +| Category | Load Checklist | +| ------------- | ---------------------------------- | +| API/Code | `api/review/checklist.md` | +| UI Components | `component/review/checklist.md` | +| Accessibility | `aria/review/checklist.md` | +| Documentation | `docs/review/workflow.md` | -#### API/Code Changes Checklist (from `api` skill) - -**Types & Inference:** - -- [ ] Types infer without manual annotation -- [ ] Generics infer from arguments, not explicit type params -- [ ] No unnecessary `as` casts -- [ ] Explicit context narrowing where needed - -**API Surface:** - -- [ ] Config objects for 3+ parameters (no long param lists) -- [ ] No function overloads (use config objects instead) -- [ ] Flat returns for independent values -- [ ] Consistent naming with existing codebase - -**Composition & Extensibility:** - -- [ ] Extension through composition, not inheritance -- [ ] Tree-shakeable exports -- [ ] Framework-agnostic where appropriate - -**Patterns:** - -- [ ] Uses existing utilities from `@videojs/utils` where applicable -- [ ] Follows Symbol identification pattern for cross-realm objects -- [ ] Subscribe pattern returns unsubscribe function -- [ ] Destroy pattern guards re-entry - ---- - -#### UI Component Changes Checklist (from `component` and `aria` skills) - -**Component Architecture:** - -- [ ] Compound component pattern where appropriate -- [ ] Render props over implicit requirements -- [ ] Controlled and uncontrolled modes supported -- [ ] Context properly scoped for nesting - -**Styling:** - -- [ ] Data attributes for state-based styling (`data-*`) -- [ ] CSS variables for customization -- [ ] No inline animation JS (prefer CSS transitions) - -**Accessibility:** - -- [ ] Proper ARIA roles and attributes -- [ ] Keyboard navigation supported -- [ ] Focus management correct (trap, restore, roving) -- [ ] Screen reader announcements where needed - ---- - -#### Documentation Changes Checklist (from `docs` skill) - -**Tone & Style:** - -- [ ] No filler words ("basically", "simply", "just", "in order to") -- [ ] No hedging ("might", "could", "perhaps") -- [ ] Active voice, second person ("you") -- [ ] Direct and confident - -**Structure:** - -- [ ] Code before explanation (show, don't tell first) -- [ ] Progressive disclosure (simple → complex) -- [ ] Matches appropriate doc type (handbook, guide, API ref, component) -- [ ] Has "See Also" section with cross-links - -**Code Examples:** - -- [ ] All imports shown -- [ ] Examples are runnable/copy-pasteable -- [ ] Includes Do/Don't patterns where helpful - -**AI Readiness:** - -- [ ] Self-contained (doesn't rely on external context) -- [ ] Clean markdown (no complex HTML) - ---- - -#### Test Changes Checklist +For test changes, apply these checks: - [ ] Tests follow `act → assert` pattern - [ ] Test file named `.test.ts` @@ -173,8 +94,6 @@ Based on detected categories, apply the relevant quick checklists: - [ ] Uses `vi.fn()` for mocks - [ ] Tests live in `tests/` directory next to implementation ---- - ### Step 5: General Code Review In addition to skill-based checks, review for: