Added issues that are going to be tracked and will be deeply considering changes based on DX.

Co-authored-by: Copilot <copilot@github.com>
2026-05-06 00:21:13 +05:00
parent f6ae86617c
commit 0787525134
8 changed files with 1218 additions and 0 deletions
@@ -0,0 +1,51 @@
+# 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?