Designing a library API means designing for people you'll never meet, and for change over time. The decisions:

Surface & ergonomics

• Small surface area — expose the minimum that's useful. Every public API is a forever-commitment.
• Sensible defaults, progressive disclosure — the common case should need almost no config; advanced power available but not in your face.
• Consistency — naming, argument order, return shapes, async patterns all uniform. Predictability beats cleverness.
• Intuitive naming — names that reveal intent; follow ecosystem conventions.

Architecture

• Composition over configuration — small composable pieces beat one giant component with 40 props. (Compound components, hooks, plugins.)
• Controlled vs uncontrolled — for UI components, support both: value/onChange and defaultValue.
• Headless option? — separating logic from presentation (headless UI) maximizes flexibility.
• Escape hatches — className, style, ref forwarding, ...rest props so consumers aren't trapped.

The contract

• TypeScript types are the API contract — precise, exported types; they're documentation and a compile-time guard.
• Good error messages — actionable, pointing at the fix, with dev-only warnings for misuse.
• Predictable, documented side effects — be explicit about what the library touches.

Versioning & change

• Semver discipline — breaking changes are major versions, period. Deprecate with warnings before removing.
• Backwards compatibility — additive changes preferred; migration guides + codemods for breaks.

Distribution & footprint

• Tree-shakable — ESM build, named exports, sideEffects: false so consumers ship only what they use.
• Ship ESM + CJS (and types).
• Minimal dependencies; use peerDependencies for shared libs (React) so consumers control the version and you don't duplicate it.
• Bundle size is a feature — measure and budget it.

Beyond code

• Documentation & examples — the API isn't usable if it isn't documented; runnable examples.
• Accessibility baked in for UI libraries.

The overarching principle

Optimize for the consumer's experience and for your ability to evolve it without breaking them. Those two — DX and changeability — drive most of the decisions.

The framing

"You're designing for strangers and for change. So: a small, consistent surface with sensible defaults and progressive disclosure; composition over a mega-config component; controlled and uncontrolled support; escape hatches like className and ref forwarding. TypeScript types are the contract. Then the change axis — strict semver, deprecate-before-remove, migration guides. And distribution — tree-shakable ESM + CJS, minimal deps with peerDependencies for shared libs, bundle size as a budgeted feature. Plus docs and accessibility. The two things every decision serves are consumer DX and your freedom to evolve it without breaking them."