npm package: @noxickon/onyx
Description: ![React](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/noxickon/c0b3115a7fbd0b01ccf3e74192756dfb/raw/onyx-react-version-badge.json) ![CI Report](https://github.com/noxickon/onyx/actions/workflows/ci.yml/badge.svg) ![Coverage %](ht
Latest version: 5.0.2

# Onyx Component Library

![React](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/noxickon/c0b3115a7fbd0b01ccf3e74192756dfb/raw/onyx-react-version-badge.json)
![CI Report](https://github.com/noxickon/onyx/actions/workflows/ci.yml/badge.svg)
![Coverage %](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/noxickon/c0b3115a7fbd0b01ccf3e74192756dfb/raw/onyx-coverage-badge.json)
![Last Build](https://github.com/noxickon/onyx/actions/workflows/release.yml/badge.svg)

Onyx is a modern React component library built with Tailwind CSS, designed for building beautiful and accessible UI interfaces. The library offers a collection of 70+ reusable components following consistent design patterns, optimized for dark mode by default.

## Features

- **Modern React Components** - Built with React 19 and TypeScript
- **70+ Components** - UI, Forms, Layouts, Typography, and more
- **Tree-Shakeable** - Multi-entry build system, only import what you need
- **Dark Mode Optimized** - All components designed for dark interfaces
- **Lucide React Icons** - Modern, tree-shakeable icons (MDI as alternative)
- **Tailwind CSS 4** - Fully customizable with latest Tailwind
- **Type-Safe** - Full TypeScript support with strict typing
- **Compound Patterns** - Flexible composition with dot notation
- **Accessibility First** - WCAG compliant, tested with jest-axe
- **Comprehensive Documentation** - Interactive Storybook with 61 stories

## Installation

Install Onyx and its peer dependencies:

```bash
npm install @noxickon/onyx lucide-react
```

### Peer Dependencies

**Required:**

- `react` ^19.0.0
- `react-dom` ^19.0.0
- `lucide-react` ^0.500.0

**Optional:**

- `@apollo/client` ^4.0.0 (if using Apollo features)
- `graphql` ^16.0.0 (if using GraphQL features)
- `@mdi/js` ^7.4.47 (alternative icon library)
- `@mdi/react` ^1.6.1 (alternative icon library)

## Basic Usage

```tsx
import { OxButton, OxIcon } from '@noxickon/onyx';
import { Check, Home } from 'lucide-react';
import '@noxickon/onyx/styles';

function App() {
  return (
    <div>
      <OxButton variant="primary">
        <OxIcon icon={Check} />
        Click Me
      </OxButton>
      <OxIcon icon={Home} />
    </div>
  );
}
```

## Package Exports

Onyx uses a multi-entry build system for optimal tree-shaking:

```tsx
// UI Components
import { OxButton, OxCard, OxDialog } from '@noxickon/onyx';

// Contexts
import { OxAuthProvider, useOxAuth } from '@noxickon/onyx/contexts';

// Hooks
import { useForm, useFilterQuery } from '@noxickon/onyx/hooks';

// Layouts
import { OxAppLayout, OxSidebar } from '@noxickon/onyx/layouts';

// Pages
import { OxLogin } from '@noxickon/onyx/pages';

// Route Guards
import { ProtectedRoute, GuestRoute } from '@noxickon/onyx/routes';

// Utilities
import { cn, formatter, validation } from '@noxickon/onyx/utils';

// CSS Imports
import '@noxickon/onyx/styles'; // Main component styles (required)
import '@noxickon/onyx/shared'; // Shared utility classes (optional)
import '@noxickon/onyx/animations'; // Animation utilities (optional)
```

## Component Categories

### UI Components (37)

Accordion, Alert, AspectRatio, Avatar, Badge, Breadcrumb, Button, Calendar, Card, DescriptionList, Dialog, Drawer, Dropdown, HoverCard, Icon, JsonField, Link, Notifications, PageOutline, Pagination, Popover, Popper, Progress, Separator, Skeleton, Slider, Spinner, StatusDisplay, Stepper, Table, Tabs, Tag, ThemeSwitcher, Timeline, Toast, Toggle, Tooltip

### Form Components (8)

Checkbox, FileUpload, Form, Input (Text, Number, Date, Time, OTP), Radio, Select, Switch, Textarea

### Layout Components (5)

AppLayout, MainContent, Sidebar, Header (Legacy), Sidebar (Legacy)

### Typography Components (5)

Description, Error, Heading, Label, Legend

### Contexts (3)

AuthContext, DialogContext, FeatureFlagContext

### Hooks (11)

useControllableState, useFileUpload, useFilterQuery, useFocus, useForm, useFormState, useKeyboard, useOverflowDetection, useScrollSpy, useSize, useTheme

### Route Guards (3)

GuestRoute, ProtectedRoute, RoleRoute

### Utilities (9)

builder, cn, copyToClipboard, createId, errorHelper, formatter, hasDataSlot, scrollToElement, validation

## Icons

### Lucide React (Primary)

Onyx uses Lucide React for modern, tree-shakeable icons:

```tsx
import { User, Mail, Calendar, Settings } from 'lucide-react';
import { OxIcon } from '@noxickon/onyx';

<OxIcon icon={User} />
<OxIcon icon={Mail} />
<OxIcon icon={Calendar} />
<OxIcon icon={Settings} />
```

Browse 1,500+ available icons at [lucide.dev](https://lucide.dev)

### MDI Icons (Alternative)

Material Design Icons are supported as an alternative when Lucide doesn't have the icon you need:

```tsx
import { mdiAccount, mdiHome } from '@mdi/js';
import { OxIcon } from '@noxickon/onyx';

<OxIcon path={mdiAccount} />
<OxIcon path={mdiHome} />
```

Browse 7,000+ MDI icons at [pictogrammers.com/library/mdi](https://pictogrammers.com/library/mdi/)

### Custom SVG Support

You can also use custom SVG components:

```tsx
import { OxIcon } from '@noxickon/onyx';

<OxIcon>
  <CustomSvgIcon />
</OxIcon>;
```

## Compound Pattern

Onyx components use a compound pattern for flexible composition:

```tsx
import { OxCard, OxButton } from '@noxickon/onyx';

<OxCard>
  <OxCard.Header>
    <OxCard.Title>Card Title</OxCard.Title>
    <OxCard.Subtitle>Optional subtitle text</OxCard.Subtitle>
  </OxCard.Header>
  <OxCard.Body>Card content goes here with full flexibility</OxCard.Body>
  <OxCard.Footer>
    <OxButton variant="primary">Action</OxButton>
    <OxButton variant="secondary">Cancel</OxButton>
  </OxCard.Footer>
</OxCard>;
```

### Layout Example

```tsx
import { OxAppLayout, OxSidebar, OxMainContent } from '@noxickon/onyx/layouts';

<OxAppLayout>
  <OxAppLayout.Sidebar>
    <OxSidebar>
      <OxSidebar.Header>App Logo</OxSidebar.Header>
      <OxSidebar.Content>
        <OxSidebarMenu>
          <OxSidebarMenu.Item>
            <OxSidebarMenu.Button>Dashboard</OxSidebarMenu.Button>
          </OxSidebarMenu.Item>
        </OxSidebarMenu>
      </OxSidebar.Content>
    </OxSidebar>
  </OxAppLayout.Sidebar>
  <OxAppLayout.Main>
    <OxMainContent>
      <OxMainContent.Header title="Page Title" />
      <OxMainContent.Body>Page content</OxMainContent.Body>
    </OxMainContent>
  </OxAppLayout.Main>
</OxAppLayout>;
```

## Documentation

Onyx includes comprehensive style guides for developers:

1. **Style Guide** - Design system documentation
   - Color palette and hierarchy
   - Typography standards (H1-H7)
   - Border and spacing conventions
   - Background layer system
   - Hover and focus states
   - Interactive variants with CVA
   - Icon usage patterns

2. **Architecture Guide** - Development standards
   - Component structure patterns
   - Compound pattern implementation
   - Slot pattern for polymorphic components
   - Naming conventions
   - TypeScript standards
   - NO COMMENTS policy
   - Context patterns
   - Testing and accessibility requirements

3. **Stories Guidelines** - Storybook best practices
   - Story file structure
   - Meta configuration
   - ArgTypes documentation
   - Code/Story patterns

Access these guides by running `npm run dev` and opening http://localhost:6006

## Development

### Available Commands

| Command                    | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `npm run dev`              | Starts Storybook development server on port 6006 |
| `npm run build`            | Builds the component library for production      |
| `npm run build:analyze`    | Builds and opens bundle size analyzer            |
| `npm run preview`          | Previews the built package locally               |
| `npm run build:storybook`  | Builds static Storybook site for deployment      |
| `npm run test`             | Runs all tests with Vitest                       |
| `npm run test:coverage`    | Runs tests with coverage report                  |
| `npm run coverage:preview` | Preview coverage report in browser               |
| `npm run lint`             | Lint code with ESLint                            |
| `npm run lint:fix`         | Fix lint issues automatically                    |
| `npm run format`           | Format code with Prettier                        |
| `npm run format:all`       | Format with Prettier and fix lint issues         |

### Testing

Onyx uses a comprehensive testing approach:

- **Framework**: Vitest with jsdom environment
- **Libraries**: React Testing Library for component testing
- **Accessibility**: jest-axe for automated accessibility testing
- **Coverage**: Focuses on implementation files (`src/**/src/**`)

Run tests:

```bash
npm run test              # Run all tests
npm run test:coverage     # Generate coverage report
npm run coverage:preview  # View coverage in browser
```

### Adding a New Component

1. Create a new directory under `src/ui/[ComponentName]` or `src/forms/[ComponentName]`
2. Add the component implementation in `src/[category]/[ComponentName]/src/[ComponentName].tsx`
3. Create types in `src/[category]/[ComponentName]/src/[ComponentName].types.ts`
4. Add an `index.ts` file that exports the component with the `Ox` prefix
5. Create stories in `src/[category]/[ComponentName]/[ComponentName].stories.tsx`
6. Add tests in `src/[category]/[ComponentName]/test/[ComponentName].test.tsx`

Follow the patterns documented in the Architecture Guide and Stories Guidelines (accessible via Storybook).

## Performance

- **Multi-Entry Build**: Import only what you need from separate entry points
- **Tree-Shakeable**: Optimized bundle size through selective imports
- **Externalized Dependencies**: React, Tailwind CSS, and peer deps are external
- **React Compiler**: Optimized with babel-plugin-react-compiler
- **Full Library**: ~1.5MB dist, tree-shakes significantly in production

## License

This project is privately owned and not available for public use without permission.

## Contributors

- Noxickon