52 lines
1.5 KiB
Markdown
52 lines
1.5 KiB
Markdown
# Component API Design Guidelines
|
|
|
|
Use this when creating or evolving components so the API remains predictable.
|
|
|
|
## Goals
|
|
|
|
- Consistency across all components
|
|
- Safe defaults for user content
|
|
- Low ceremony for common use cases
|
|
- Explicit escape hatches for advanced scenarios
|
|
|
|
## Baseline API Conventions
|
|
|
|
For every new component, prefer:
|
|
|
|
- `className` for caller-supplied Tailwind/CSS classes
|
|
- `attributes` for arbitrary HTML attributes (`aria-*`, `data-*`, test IDs)
|
|
- Strongly typed semantic options where practical (enums or constants)
|
|
- Named item records instead of tuples for complex lists
|
|
|
|
## Safety Rules
|
|
|
|
1. Plain text input should be encoded by default.
|
|
2. Raw HTML should require an explicit trusted path.
|
|
3. Never require callers to manually concatenate unsafe attribute strings for normal usage.
|
|
|
|
## Documentation Rules
|
|
|
|
Every component doc should include:
|
|
|
|
1. Quick example
|
|
2. All options
|
|
3. Security notes
|
|
4. Accessibility notes
|
|
5. JS dependency notes (if interactive)
|
|
6. Extension points (`className`, `attributes`)
|
|
|
|
## Evolution Rules
|
|
|
|
1. Prefer additive changes first.
|
|
2. Mark old APIs as deprecated with migration examples.
|
|
3. Remove deprecated paths only in major release.
|
|
|
|
## Review Checklist
|
|
|
|
- Is the API consistent with sibling components?
|
|
- Can callers add classes without wrapper divs?
|
|
- Can callers pass `aria-*` and `data-*` safely?
|
|
- Are semantic options type-safe?
|
|
- Are user-provided strings encoded by default?
|
|
- Are interactive JS requirements documented?
|