Onyx Component Library

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:

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

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:

// 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:

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

MDI Icons (Alternative)

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

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

Custom SVG Support

You can also use custom SVG components:

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

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

Compound Pattern

Onyx components use a compound pattern for flexible composition:

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

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:

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