@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 from npm

Install the package in your project:

npm install @ws-ui/ui-components

Using Components

Import and use components in your React application:

import { Button, Input, Checkbox } from '@ws-ui/ui-components';

function App() {
  return (
    <div>
      <Input placeholder="Enter your name" label="Name" />
      <Checkbox
        label="Accept terms and conditions"
        onChange={(checked) => console.log(checked)}
      />
      <Button variant="primary" size="md" onClick={() => alert('Hello!')}>
        Submit
      </Button>
    </div>
  );
}

Available Components

• Button: Versatile button with multiple variants and sizes
• Input: Text input with label, error states, and validation
• Checkbox: Accessible checkbox with indeterminate state
• Radio: Radio button with group management
• Dropdown: Customizable dropdown with search and multi-select
• Menu: Context menu with nested submenus and keyboard navigation
• And more...

Check the Storybook documentation for complete component APIs and examples.

🔧 Development Setup

For contributors who want to develop and extend the design system:

Clone and Install

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

# Install dependencies
npm install

Development Commands

# 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