API Design & Developer Experience

Principles for designing TypeScript library APIs and evaluating developer experience.

Goal: APIs should feel obvious, fast, safe, and composable — with great defaults and great escape hatches.

Quick Reference

Foundational

• Emergent extensibility — Best extension points look like well-designed APIs, not plugin systems
• Composition over configuration — devtools(persist(fn)) beats { middlewares: [] }
• Onion model — Transformative middleware innermost, observational outermost

API Surface

• Config objects for 3+ parameters (no overloads)
• Flat returns for independent values, namespaced for cohesive units
• Rule of two — Tuples for 2 values, objects for 3+
• Inference over annotation — If users annotate, types aren’t flowing

Progressive Disclosure

• Complexity grows with use case — Zero-config → Options → Composition → Headless → Core
• Escape hatches compose — Don’t require reimplementing defaults
• Explicit contracts — Render props over implicit requirements

Developer Experience

• Time-to-first-success — Minimize time from install to working code
• Cognitive load — Fewer concepts > fewer keystrokes
• Predictable outcomes — Match user mental models
• Editor ergonomics — TypeScript inference should just work

Conflict Resolution

When principles conflict, prioritize:

1. Correctness — wrong behavior > verbose API
2. Type Safety — inference failures > extra generics
3. Simplicity — fewer concepts > fewer keystrokes
4. Consistency — match existing codebase patterns
5. Bundle Size — tree-shaking matters, but not at DX cost

Anti-Patterns

Anti-Pattern	Why It Fails
Function overloads	Poor errors, autocomplete confusion
Runtime plugin registration	Loses type safety, implicit ordering
Positional parameters (3+)	Order confusion, breaking changes
Implicit contracts	Silent breakage when requirements unmet
Per-module middleware	Unexpected interactions
Shotgun parsing	Validation scattered, not at boundaries
Boolean traps	fn(true, false) — what do these mean?
Multiple competing APIs	Confusing — which method to use?

Reference Files

File	Contents
references/principles.md	Core design and DX principles
references/typescript.md	Type inference patterns (author + consumer)
references/state.md	State management patterns and architecture
references/extensibility.md	Pipelines, builders, adapters, lifecycles
references/anti-patterns.md	Common mistakes to avoid
references/libraries.md	Reference libraries and their patterns
references/voices.md	Practitioner heuristics and reference URLs

Loading by Domain

Domain	Load
General API work	principles.md
TypeScript/types	typescript.md
State management	state.md
Middleware/plugins	extensibility.md
Avoiding mistakes	anti-patterns.md
Library comparisons	libraries.md, voices.md

Review

For reviewing APIs and architecture, load review/workflow.md.

File	Contents
review/workflow.md	Review process and checklists
review/agents.md	Sub-agent prompts
review/templates.md	Issue format, report template
review/checklist.md	Quick single-agent checklist
review/example.md	Complete example review

Related Skills

Need	Use
Building UI components	component skill
Accessibility patterns	aria skill
Documentation	docs skill