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
|
||||
Let's choose a feature-rich component set with easy theming control
|
||||
* -[ ] [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
|
||||
### Language and Runtime
|
||||
|
|
|
|||
Loading…
Reference in a new issue