npm package: @pdendys181/awesome-ui-kit
Description: Modern, accessible React component library built with TypeScript and SCSS.
Latest version: 1.0.2

# 🎨 Awesome UI Kit

Modern, accessible React component library built with TypeScript and SCSS.

[![npm version](https://badge.fury.io/js/%40pdendys181%2Fawesome-ui-kit.svg)](https://www.npmjs.com/package/@pdendys181/awesome-ui-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Note:** This project was developed as a technical demonstration with primary focus on the **InputField** component. The InputField showcases comprehensive form handling, accessibility features, controlled/uncontrolled patterns, and extensive testing coverage.

## 📦 Installation

```bash
npm install @pdendys181/awesome-ui-kit
```

```bash
yarn add @pdendys181/awesome-ui-kit
```

## 🚀 Quick Start

```tsx
import { InputField, Button, ThemeProvider } from '@pdendys181/awesome-ui-kit';

function App() {
  return (
    <ThemeProvider theme="light"> // ligth / dark / auto
      <InputField 
        label="Email" 
        type="email" 
        placeholder="Enter your email" 
      />
      <Button>Submit</Button>
    </ThemeProvider>
  );
}
```

## 🛠️ Tech Stack

- **React 19** - Modern React with latest features
- **TypeScript** - Type-safe development
- **SCSS** - Advanced styling with design tokens
- **Vite** - Fast build tool and development server
- **Vitest** - Lightning fast unit testing
- **Storybook** - Component development and documentation
- **ESLint** - Code quality and consistency

## 🧩 Components

### Production Ready Components
- **InputField** - Comprehensive form input with validation states, password toggle, character counter
- **Icons** - SVG icon library (Eye, EyeCrossed, Success, Warning)
- **ThemeProvider** - Light/dark theme management with system preference detection

### Candidate Components
The `_candidates` folder contains components in development:
- **Button** - Basic button component with styling foundation
- **Header** - Simple header component structure

## ♿ Accessibility First

Accessibility is a core principle of this library. Every component is built with WCAG 2.1 AA compliance in mind.

### 🧪 Accessibility Testing Strategy

We use a comprehensive testing approach to ensure accessibility:

#### 1. **Automated Testing with axe-core**
```bash
npm run test:accessibility
```
- Automated WCAG violation detection
- Integration with Vitest for CI/CD
- Zero tolerance for accessibility regressions

#### 2. **Unit Tests for A11y Features**
```typescript
// Example accessibility test
it('should have proper ARIA attributes', () => {
  render(<InputField label="Email" error="Required" />);
  
  expect(screen.getByRole('textbox')).toHaveAttribute('aria-invalid', 'true');
  expect(screen.getByRole('textbox')).toHaveAttribute('aria-describedby');
});
```

#### 3. **Storybook Accessibility Addon**
- Real-time accessibility checking during development
- Visual accessibility testing in component isolation
- Color contrast validation

### 🎯 Accessibility Features

- **Keyboard Navigation** - Full keyboard operability
- **Screen Reader Support** - Proper ARIA labels and descriptions
- **Focus Management** - Visible focus indicators and logical tab order
- **Color Contrast** - WCAG AA compliant color combinations
- **Touch Targets** - Minimum 44px touch targets for mobile
- **Semantic HTML** - Proper HTML structure and landmarks

## 🧪 Testing

```bash
# Run all tests
npm test

# Unit tests only
npm run test:unit

# Accessibility tests only
npm run test:accessibility

# Test coverage
npm run test:coverage
```

### Testing Stack
- **Vitest** - Fast unit testing framework
- **Testing Library** - User-centric testing utilities
- **axe-core** - Automated accessibility testing
- **jsdom** - DOM simulation for testing

## 📚 Storybook

Explore components in isolation with our interactive Storybook:

```bash
# Start Storybook development server
npm run storybook

# Build Storybook for production
npm run storybook:build
```

**Features:**
- Interactive component playground
- Real-time accessibility testing
- Design token documentation
- Dark/light theme switching

## 🔧 Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Build library
npm run build
```

## 🚀 CI/CD Pipeline

Our GitHub Actions workflow ensures code quality and automated publishing:

### 🔄 Continuous Integration
- **Linting** - ESLint checks on every PR
- **Testing** - Unit and accessibility tests
- **Build Verification** - Ensures library builds successfully
- **Type Checking** - TypeScript compilation validation

### 📦 Automated Publishing
- **Version Detection** - Automatically detects version changes in `package.json`
- **NPM Publishing** - Auto-publishes to npm registry on version bump
- **Release Notes** - Automated changelog generation

```yaml
# Triggered on every push to main branch
- Lint code
- Run tests (unit + accessibility)
- Build library
- Publish to npm (if version changed)
```

## 🎨 Design System

Built with a comprehensive design token system:

- **Colors** - Semantic color palette with light/dark theme support
- **Typography** - Consistent font scales and weights
- **Spacing** - 4px grid-based spacing system
- **Border Radius** - Consistent corner radius values
- **Breakpoints** - Mobile-first responsive breakpoints

---

**Built with hope to be hired ❤️**