Tailless shadcn/ui

A comprehensive React component library that replicates the shadcn/ui design system using CSS Modules (.module.scss) instead of Tailwind CSS.

🎯 Project Goals

• Visual Parity: Pixel-perfect alignment with shadcn/ui designs
• Functional Parity: Identical component behavior and interactions
• Accessibility: WCAG 2.1 AA compliance minimum
• Type Safety: Full TypeScript support with strict mode
• CSS Modules: Scoped styling without runtime overhead
• Modern React: Built with React 18+ best practices

🚀 Features

• ✅ 52 Components planned (matching shadcn/ui)
• ✅ CSS Modules with SCSS for styling
• ✅ Built on Radix UI primitives for accessibility
• ✅ Type-safe variants with class-variance-authority
• ✅ Comprehensive theme system with CSS custom properties
• ✅ Dark mode support
• ✅ Fully tested with Vitest and React Testing Library
• ✅ Tree-shakeable exports

📦 Installation

npm install tailless-shadcn
# or
yarn add tailless-shadcn
# or
pnpm add tailless-shadcn

🎨 Usage

import { Button } from 'tailless-shadcn';
import 'tailless-shadcn/styles';

function App() {
  return (
    <Button variant="default" size="default">
      Click me
    </Button>
  );
}

🏗️ Development

Prerequisites

• Node.js 18+ or 20+
• pnpm (recommended) or npm/yarn

Setup

# Clone the repository
git clone https://github.com/masious/tailless-shadcn.git
cd tailless-shadcn

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Build the library
pnpm build

# Lint code
pnpm lint

# Format code
pnpm format

📚 Documentation

Comprehensive documentation is available in multiple locations:

Live Documentation Site

The interactive documentation site is in the docs-site/ directory:

cd docs-site
npm install
npm run dev
# Visit http://localhost:3000

Features:

• 38 component documentation pages
• Interactive examples
• API reference tables
• Code snippets

Project Documentation

Technical documentation is available in the /docs directory:

• Architecture: System design and patterns
• Design Tokens: Colors, spacing, typography
• Components: Individual component documentation
• Guidelines: Coding standards and best practices

Key Documentation Files

• Architecture Overview
• Styling System
• Color Tokens
• Spacing Tokens
• Coding Standards
• Component Priority List
• Debugging Guide - UI debugging with Playwright

🗺️ Roadmap

See TODO.md for the complete implementation roadmap.

Current Status

Phase: 12 - Complete ✅

Component Progress: 38/52 core components implemented (73%)

• Tier 1 (Foundation): 4/4 ✅
• Tier 2 (High-Frequency): 6/6 ✅
• Tier 3 (Dialogs & Overlays): 7/7 ✅
• Tier 4 (Navigation): 4/8 (core complete, 4 complex skipped)
• Tier 5 (Forms): 5/10 (core complete, 5 specialized skipped)
• Tier 6 (Data Display): 5/5 ✅
• Tier 7 (Advanced Layout): 5/5 ✅
• Tier 8 (Specialized): 2/7 (Toggle + ToggleGroup, 5 complex skipped)

🧪 Testing

This project maintains high testing standards:

• Unit Tests: All components tested with Vitest
• Accessibility Tests: Automated axe-core testing
• Coverage Goal: 80%+ across all metrics

# Run all tests
pnpm test

# Run tests with UI
pnpm test:ui

# Generate coverage report
pnpm test:coverage

🎨 Theme System

The library uses CSS custom properties for theming:

:root {
  --color-primary: 221.2 83.2% 53.3%;
  --color-primary-foreground: 210 40% 98%;
  // ... more tokens
}

[data-theme='dark'] {
  --color-primary: 217.2 91.2% 59.8%;
  // ... dark mode values
}

Toggle dark mode by setting data-theme="dark" on the root element:

document.documentElement.setAttribute('data-theme', 'dark');

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• shadcn/ui - The original design system
• Radix UI - Accessible component primitives
• class-variance-authority - Variant management

🔗 Links

• Documentation
• NPM Package
• GitHub Repository
• Issue Tracker

📞 Support

If you have questions or need help, please:

• Check the documentation
• Search existing issues
• Open a new issue if needed

Built with ❤️ by the community