@adam-milo/ui

A modern, accessible, and fully-typed React component library built with TypeScript and TailwindCSS.

🎨 Features

• React 18 with TypeScript for type-safe development
• Modern CSS with native nesting and logical properties for RTL support
• TailwindCSS integration with comprehensive design tokens
• Radix UI primitives for accessible components
• Fully Typed with comprehensive TypeScript definitions
• Tested with Vitest and React Testing Library
• Documented with Storybook
• Accessible - WCAG compliant components
• RTL Ready - Built-in right-to-left language support

📦 Installation

npm install @adam-milo/ui
# or
yarn add @adam-milo/ui
# or
pnpm add @adam-milo/ui

Peer Dependencies

Make sure you have React 18+ installed:

npm install react react-dom

🚀 Quick Start

1. Import Styles

Import the styles in your app's entry point:

// App.tsx or index.tsx
import '@adam-milo/ui/styles.css';

2. Use Components

import { Button, Input, Card } from '@adam-milo/ui';

function App() {
  return (
    <Card>
      <h2>Welcome</h2>
      <Input label="Name" placeholder="Enter your name" />
      <Button variant="primary-workspace">Submit</Button>
    </Card>
  );
}

3. With TypeScript

Full TypeScript support out of the box:

import { Button, type ButtonProps } from '@adam-milo/ui';

const MyButton: React.FC<{ customProp: string }> = ({ customProp }) => {
  const buttonProps: ButtonProps = {
    variant: 'primary-workspace',
    fullWidth: true,
    onClick: () => console.log(customProp),
  };

  return <Button {...buttonProps}>Click me</Button>;
};

📚 Components

Core Components

Button

Multiple variants with full accessibility support:

import { Button } from '@adam-milo/ui';

// Variants
<Button variant="primary-workspace">Primary Workspace</Button>
<Button variant="primary-builder">Primary Builder</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>

// With icons
<Button
  variant="primary-workspace"
  iconLeft={<Icon name="plus" />}
>
  Add Item
</Button>

// Full width
<Button variant="primary-workspace" fullWidth>
  Submit
</Button>

// Disabled state
<Button variant="primary-workspace" disabled>
  Loading...
</Button>

Icon

SVG icon wrapper component:

import { Icon } from '@adam-milo/ui';

<Icon name="check" size="md" />;

Form Components

Input

Text input with label and validation:

import { Input } from '@adam-milo/ui';

<Input label="Email" type="email" placeholder="[email protected]" required />;

Layout Components

Stack

Flexbox-based spacing utility:

import { Stack } from '@adam-milo/ui';

<Stack direction="vertical" spacing={4}>
  <Button>Button 1</Button>
  <Button>Button 2</Button>
</Stack>;

Card

Content container with elevation:

import { Card } from '@adam-milo/ui';

<Card>
  <h3>Card Title</h3>
  <p>Card content goes here</p>
</Card>;

Data Display

DataTable

Semantic table component:

import { DataTable } from '@adam-milo/ui';

<DataTable headers={['Name', 'Email', 'Status']} rows={data} />;

Feedback Components

Alert

Contextual feedback messages:

import { Alert } from '@adam-milo/ui';

<Alert variant="success">Operation completed!</Alert>
<Alert variant="error">Something went wrong</Alert>
<Alert variant="warning">Please review your input</Alert>
<Alert variant="info">New updates available</Alert>

Navigation Components

Tabs

Accessible tabbed interface:

import { Tabs } from '@adam-milo/ui';

<Tabs defaultValue="tab1">
  <Tabs.List>
    <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
    <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">Content 1</Tabs.Content>
  <Tabs.Content value="tab2">Content 2</Tabs.Content>
</Tabs>;

Overlay Components

Dialog

Accessible modal dialog:

import { Dialog } from '@adam-milo/ui';

<Dialog>
  <Dialog.Trigger asChild>
    <Button>Open Dialog</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Dialog Title</Dialog.Title>
    <Dialog.Description>Dialog content goes here</Dialog.Description>
  </Dialog.Content>
</Dialog>;

🎨 Design Tokens

CSS Variables

All design tokens are available as CSS custom properties:

/* Colors */
--color-text: #191a39;
--color-action: #272643;
--color-popup: #ed6726;
--color-card: #ffffff;

/* Spacing */
--spacing-1: 0.25rem; /* 4px */
--spacing-2: 0.5rem; /* 8px */
--spacing-4: 1rem; /* 16px */

/* Typography */
--font-size-8: 1rem; /* 16px */
--font-size-6: 1.25rem; /* 20px */

/* Border Radius */
--radius-default: 0.25rem; /* 4px */
--radius-lg: 0.75rem; /* 12px */

Using Design Tokens

// In your components
const CustomComponent = styled.div`
  color: var(--color-text);
  padding: var(--spacing-4);
  border-radius: var(--radius-default);
`;

♿ Accessibility

All components follow WCAG 2.1 Level AA guidelines:

• ✅ Semantic HTML structure
• ✅ ARIA attributes where needed
• ✅ Keyboard navigation support
• ✅ Focus management
• ✅ Screen reader friendly
• ✅ Color contrast compliance
• ✅ Focus-visible indicators

🌍 RTL Support

Components automatically support right-to-left languages:

// Set direction on your root element
<html dir="rtl">
  <body>
    <App />
  </body>
</html>

All components use logical CSS properties that automatically adapt to text direction.

🧪 Testing

Unit Tests

Run tests with Vitest:

npm run test

Watch mode:

npm run test:watch

E2E Tests

Cypress tests are available in the main repository.

📖 Documentation

Storybook

View interactive component documentation:

# Clone the repository
git clone https://github.com/adam-milo/adam-milo-design-system.git
cd adam-milo-design-system

# Install dependencies
npm install

# Run Storybook
npm run storybook

Visit http://localhost:6006 to explore all components.

🛠️ Development

Project Structure

packages/ui/
├── src/
│   ├── components/
│   │   ├── core/           # Button, Icon
│   │   ├── forms/          # Input, Checkbox, Select
│   │   ├── navigation/     # Tabs, Breadcrumb
│   │   ├── feedback/       # Alert, Toast
│   │   ├── data-display/   # Card, DataTable
│   │   ├── overlays/       # Dialog, Modal
│   │   └── layout/         # Stack, Grid
│   ├── lib/                # Utilities
│   ├── index.ts            # Main exports
│   └── styles.css          # Global styles
├── dist/                   # Build output
├── package.json
├── vite.config.ts
└── README.md

Component Naming

Each component follows this structure:

ComponentName/
├── ComponentName.component.tsx  # Implementation
├── ComponentName.css           # Styles (if needed)
├── ComponentName.stories.tsx   # Storybook stories
└── ComponentName.spec.tsx      # Tests

📋 Requirements

• Node.js: >= 18.0.0
• npm: >= 9.0.0
• React: >= 18.2.0
• TypeScript: >= 5.0.0

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: npm test
5. Commit: git commit -m "feat: add new feature"
6. Push: git push origin feature/my-feature
7. Open a Pull Request

📄 License

MIT © Adam Milo

See LICENSE for details.

🔗 Links

• GitHub Repository
• npm Package
• Issue Tracker
• Changelog

💬 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🙏 Acknowledgments

Built with:

• React
• TypeScript
• TailwindCSS
• Radix UI
• Vite
• Storybook

Made with ❤️ by the Adam Milo team