Utopique UI v5.0

Utilitarian Design System - A minimalist, functional React component library.

Philosophy

Utopique UI is built on utilitarian design principles:

• White is primary, Gray is secondary - Inverted color hierarchy for modern aesthetics
• Consistent spacing scale - 4, 8, 12, 16, 24, 32, 40, 48, 64px
• Dark mode first - Beautiful in both light and dark themes
• Function over form - Every element serves a purpose

Features

• ✨ Modern React components with hooks
• 🎨 Dark/Light theme support built-in
• 📱 Responsive and mobile-friendly
• ⚡ Lightweight with minimal dependencies
• 🎯 Tailwind CSS for styling
• 🔧 Full TypeScript support (coming soon)

Components

Inputs & Forms

• Button - Primary, Secondary, Ghost variants
• Input - Text, Password, Search with icons
• Tag - Active/Inactive states

Data Display

• Progress Bar - Linear progress with labels
• Segmented Progress - Step-by-step indicator
• Circular Progress - Radial progress indicator
• Index Table - Data table with hover states

Media

• Player - Audio/video player controls
• Mosaic Card - Grid layout cards

Controls

• Slider - Range input control
• Stepper - Increment/decrement control

Getting Started

Installation

npm install

Development

npm run dev                # Start dev server
npm run build:lib          # Build library
npm run test               # Run tests in watch mode
npm run test:ci            # Run tests once

Code Quality

npm run lint               # Check for linting errors
npm run lint:fix           # Auto-fix linting errors
npm run format             # Format all files with Prettier
npm run format:check       # Verify code is formatted
npm run type-check         # TypeScript type checking

Testing

Utopiq UI has a comprehensive testing infrastructure to ensure quality and accessibility.

Unit & Integration Tests

npm run test               # Run tests in watch mode
npm run test:ci            # Run tests once (for CI)
npm run test:ui            # Open Vitest UI
npm run test:coverage      # Generate coverage report

Test Stack:

• Vitest - Fast unit test runner (compatible with Jest)
• Testing Library - User-centric testing utilities
• jsdom - Browser environment simulation

Coverage Thresholds:

• Branches: 80%
• Functions: 80%
• Lines: 80%
• Statements: 80%

Accessibility Testing

Every component includes automated WCAG 2.1 AA compliance tests using vitest-axe:

import { axe } from 'vitest-axe';

it('should not have any accessibility violations', async () => {
  const { container } = render(<Button t={testTheme}>Click me</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Current status: 393 tests passing, including 8 accessibility tests across critical components.

Test File Structure

tests/
  ├── setup.ts              # Vitest + axe matchers configuration
  └── helpers.tsx           # Test theme and utilities

src/components/
  └── [Component]/
      ├── [Component].tsx       # Component implementation
      └── [Component].test.tsx  # Unit + a11y tests

Release Management

npm run changeset          # Create a new changeset (describe your changes)
npm run changeset:version  # Bump versions based on changesets
npm run changeset:publish  # Publish to npm

CI/CD

GitHub Actions Workflows

CI Workflow (.github/workflows/ci.yml):

• Runs on all PRs and pushes to master
• Tests on Node 18, 20, and 22
• Checks: lint, format, type-check, tests, build
• Uploads coverage reports to Codecov

Release Workflow (.github/workflows/release.yml):

• Runs on pushes to master
• Uses Changesets to manage versions and releases
• Automatically creates release PRs
• Publishes to npm when release PR is merged

Pre-commit Hooks

Husky runs these checks before each commit:

1. lint-staged: Lints and formats staged files
2. type-check: Verifies TypeScript types

Pre-push Hooks

Husky runs these checks before each push:

1. test:ci: Runs all tests

Usage

Import components from the main App.jsx file:

import UtopiaUI from './App';

function App() {
  return <UtopiaUI />;
}

Custom Theme

The theme system uses a createTheme function:

const theme = createTheme(isDark);
// Access: theme.bg, theme.text, theme.border, etc.

Design Tokens

Colors

• bg - Main background
• bgAlt - Alternate background
• surface - Card/surface background
• border - Border color
• text - Primary text (white in dark mode)
• textSecondary - Secondary text
• textMuted - Muted/disabled text
• solid - Solid fill (white in dark mode)
• placeholder - Empty state color

Spacing Scale

4px, 8px, 12px, 16px, 24px, 32px, 40px, 48px, 64px

Inspirations

Add your design references (JPEG, PNG, etc.) to the /inspirations folder.

Contributing

Making Changes

1. Create a branch for your changes
2. Make your code changes
3. Run npm run changeset to describe your changes
4. Commit your changes (pre-commit hooks will run)
5. Push and create a PR (CI will run automatically)

Release Process

1. Merge PRs with changesets to master
2. Changesets Action will create a "Version Packages" PR
3. Merge the version PR to trigger release and npm publish

Version

v6.0.0 - Production-ready with full infrastructure

License

MIT

Built with ❤️ for utilitarian design