@ws-ui/ui-components

Web Studio Design System

A comprehensive design system built with React, TypeScript, TailwindCSS, and Storybook for Qodly. This library provides a collection of reusable, accessible, and customizable UI components with consistent styling and behavior using a modern configuration-driven architecture.

✨ Features

• 🎨 Modern Design: Clean, professional components with consistent styling
• ♿ Accessibility First: Full ARIA support and keyboard navigation
• 🔧 Flexible & Configurable: Separation of concerns with dedicated styling configurations
• 📚 Well Documented: Comprehensive Storybook documentation with interactive examples
• ⚡ Performance Optimized: Built with modern React patterns and optimized bundle size
• 🎯 TypeScript: Full type safety and excellent developer experience
• 🌙 Dark Theme: Built-in support for dark mode styling
• 🔄 Consistent Patterns: Unified architecture across all components for maintainability
• 🧪 Comprehensive Testing: Unit tests and Storybook testing for each component

🚀 Quick Start

Installation

# Clone the repository
git clone https://git.4d-ps.com/4d/web-studio/design-system.git
cd design-system

# Install dependencies
npm install

Development

# Start the development server
npm run dev

# Run Storybook for component development
npm run storybook

# Build the project
npm run build

# Run linting
npm run lint

📖 Storybook

View all components and their documentation in Storybook:

npm run storybook

This will start Storybook on http://localhost:6006 where you can:

• Browse all available components
• Interact with component properties
• View code examples
• Test accessibility features
• Explore different states and variants

🛠️ Technical Stack

• React 19.1.0: Latest React with modern features
• TypeScript 5.8.3: Full type safety
• TailwindCSS 4.x: Utility-first CSS framework
• Storybook 9.x: Component development and documentation
• Vite 6.x: Fast build tool and dev server
• Vitest 3.x: Unit testing framework
• ESLint: Code linting and formatting

🔧 Development

Project Structure

src/                             # Reusable UI components
│   ├── Checkbox/
│   │   ├── Checkbox.tsx         # Component logic & rendering
│   │   ├── Checkbox.stories.tsx # Storybook documentation
│   │   ├── Checkbox.test.ts     # Unit tests
│   │   ├── checkbox.types.ts    # TypeScript definitions
│   │   ├── checkbox.style.ts    # Styling configuration
│   │   └── index.ts             # Clean exports
│   ├── Radio/
│   │   ├── Radio.tsx
│   │   ├── Radio.stories.tsx
│   │   ├── Radio.test.ts
│   │   ├── radio.types.ts
│   │   ├── radio.style.ts
│   │   └── index.ts
│   └── ...                 # Other components
├── styles/                 # Global styles and themes

Adding New Components

• Create component directory in src/components/ComponentName/
• Create the five core files:
  • ComponentName.tsx - Component logic & rendering
  • ComponentName.stories.tsx - Storybook documentation
  • ComponentName.test.ts - Unit tests
  • ComponentName.types.ts - TypeScript definitions
  • ComponentName.style.ts - Styling configuration
  • index.ts - Clean exports
• Include TypeScript interfaces and props
• Add comprehensive Storybook stories
• Ensure accessibility compliance
• Add unit tests
• Update documentation

Design Guidelines

• Consistency: Follow established patterns and conventions
• Accessibility: Ensure WCAG 2.1 AA compliance
• Performance: Optimize for bundle size and runtime performance
• Flexibility: Support multiple variants and customization options
• Documentation: Provide clear examples and usage guidelines
• Separation of Concerns: Keep logic, types, styling, stories, and tests in separate files

🧪 Testing

# Run unit tests
npm run test

# Run tests with storybook
npm run test-storybook

📝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-component
• Follow the development guidelines
• Add tests and documentation
• Submit a pull request

Code Standards

• Use TypeScript for all components
• Follow React best practices and hooks
• Ensure accessibility compliance
• Add comprehensive Storybook stories
• Include unit tests for complex logic
• Use semantic versioning for releases