docs(spec): Recommend Shadcn for V2 component library
Based on evaluation of both prototype implementations (v2/prototype/shadcn and v2/prototype/mantine), recommend Shadcn for the following reasons: - Component ownership: Components copied to codebase, not npm dependency - Tailwind CSS integration: Utility-first approach with purged bundles - Radix UI foundation: WCAG 2.1 compliant accessibility primitives - Simpler theming: CSS variables vs React context re-renders - Better DX: Source code visible and editable in project Includes comparison table and tradeoffs acknowledged. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
39976a4ff9
commit
e6400ca053
1 changed files with 66 additions and 1 deletions
|
|
@ -20,7 +20,72 @@
|
||||||
### Components and Theme
|
### Components and Theme
|
||||||
Let's choose a feature-rich component set with easy theming control
|
Let's choose a feature-rich component set with easy theming control
|
||||||
* -[ ] [Mantine](https://ui.mantine.dev/)
|
* -[ ] [Mantine](https://ui.mantine.dev/)
|
||||||
* -[ ] [Shadcdn](https://ui.shadcn.com/)
|
* -[x] [Shadcn](https://ui.shadcn.com/)
|
||||||
|
|
||||||
|
#### Shadcn Rationale
|
||||||
|
|
||||||
|
Shadcn is recommended based on evaluation of both prototype implementations (`v2/prototype/shadcn` and `v2/prototype/mantine`).
|
||||||
|
|
||||||
|
**Why Shadcn over Mantine:**
|
||||||
|
|
||||||
|
| Requirement | Shadcn | Mantine |
|
||||||
|
|-------------|--------|---------|
|
||||||
|
| Component ownership | Yes - Copy to codebase | No - npm dependency |
|
||||||
|
| Styling approach | Tailwind CSS | CSS-in-JS (emotion) |
|
||||||
|
| Bundle size | Minimal - Only used components | Larger - Full library |
|
||||||
|
| Customization | Full control - Edit source directly | Theme config only |
|
||||||
|
| Accessibility | Radix UI primitives | Built-in a11y |
|
||||||
|
| TypeScript support | Full type safety | Full type safety |
|
||||||
|
| Dark mode | CSS variables | Context provider |
|
||||||
|
|
||||||
|
**Benefits:**
|
||||||
|
|
||||||
|
1. **Component Ownership** - Components are copied into your project, not installed as dependencies. This means:
|
||||||
|
- Full control over implementation details
|
||||||
|
- No breaking changes from library updates
|
||||||
|
- Easy to modify for project-specific needs
|
||||||
|
- No version lock-in
|
||||||
|
|
||||||
|
2. **Tailwind CSS Integration** - Modern utility-first CSS approach:
|
||||||
|
- Consistent with broader React ecosystem trends
|
||||||
|
- Excellent DX with IDE autocomplete
|
||||||
|
- Easy theme customization via CSS variables
|
||||||
|
- Smaller production bundles (unused styles purged)
|
||||||
|
|
||||||
|
3. **Radix UI Foundation** - Built on battle-tested accessibility primitives:
|
||||||
|
- WCAG 2.1 compliant out of the box
|
||||||
|
- Keyboard navigation handled correctly
|
||||||
|
- Screen reader support built-in
|
||||||
|
- Focus management done right
|
||||||
|
|
||||||
|
4. **Simpler Theme Architecture** - CSS variables for theming:
|
||||||
|
- Light/dark mode via CSS class toggle
|
||||||
|
- No React context re-renders on theme change
|
||||||
|
- Easy to extend with custom color schemes
|
||||||
|
- Works seamlessly with Tailwind
|
||||||
|
|
||||||
|
5. **Developer Experience from Prototype**:
|
||||||
|
- Faster iteration when modifying components
|
||||||
|
- Clear, readable component code
|
||||||
|
- Better debugging (source is in your project)
|
||||||
|
- No "magic" - what you see is what you get
|
||||||
|
|
||||||
|
**Tradeoffs Acknowledged:**
|
||||||
|
|
||||||
|
- **Initial setup** - Requires adding components individually (vs Mantine's single install)
|
||||||
|
- **Less "batteries included"** - Some advanced features need additional work (e.g., date pickers, rich text)
|
||||||
|
- **Documentation** - Mantine has more extensive API docs for each prop
|
||||||
|
|
||||||
|
**Prototype Comparison:**
|
||||||
|
|
||||||
|
Both prototypes implement the same V2 UX spec. Key observations:
|
||||||
|
|
||||||
|
| Aspect | Shadcn Prototype | Mantine Prototype |
|
||||||
|
|--------|------------------|-------------------|
|
||||||
|
| Code clarity | Component code visible in project | Abstracted in node_modules |
|
||||||
|
| Theme toggle | CSS class swap | useMantineColorScheme hook |
|
||||||
|
| Custom styling | Add Tailwind classes directly | Override with sx prop or styles API |
|
||||||
|
| Component modification | Edit the file | Create wrapper or fork |
|
||||||
|
|
||||||
## Proxy Server
|
## Proxy Server
|
||||||
### Language and Runtime
|
### Language and Runtime
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue