Infinity UI Elements

A comprehensive React TypeScript component library with a modern design system built on Tailwind CSS. Perfect for building consistent, accessible, and beautiful user interfaces for Infinity products.

🎯 Features

• 🎨 Comprehensive Design System: 25+ production-ready components with consistent styling
• 📦 Tree-shakable: ESM + CJS builds optimized with Rollup
• 🔒 TypeScript: Full type safety and IntelliSense support
• ♿ Accessible: ARIA compliant components following WAI-ARIA guidelines
• 🎭 Flexible: Support for variants, sizes, colors, and custom styling
• 📚 Well Documented: Interactive Storybook documentation
• ⚡ Performance: Optimized bundle size with zero runtime overhead
• 🌈 Theme Support: CSS custom properties for easy theming

🎨 Design System - Single Source of Truth

Infinity UI Elements is not just a component library—it's a complete design system that serves as the single source of truth for all design tokens, CSS variables, and styling for Infinity products.

Why This Matters

When you integrate this library:

• ✅ All design tokens (colors, typography, spacing, borders) are automatically available
• ✅ Designers update once → changes propagate to all apps via package updates
• ✅ No duplication → maintain consistency across products
• ✅ Easy updates → yarn upgrade infinity-ui-elements to get latest design changes

What You Get

import 'infinity-ui-elements/dist/index.css';

This single import gives you access to hundreds of CSS variables:

/* Colors (300+ tokens) */
var(--color-teal-500)
var(--color-action-fill-primary-default)
var(--color-surface-ink-neutral-normal)

/* Typography */
var(--font-functional)
var(--text-200)
var(--leading-500)

/* Spacing */
var(--spacing-5)
var(--size-32)

/* Borders & Radius */
var(--border-width-thin)
var(--radius-large)

Use these variables anywhere in your custom CSS—no need to redefine them!

📚 See DESIGN_TOKENS.md for complete reference
🚀 See INTEGRATION.md for integration guide

📦 Installation

yarn add infinity-ui-elements
# or
npm install infinity-ui-elements

Peer Dependencies

Install the required peer dependencies:

yarn add react react-dom clsx tailwind-merge class-variance-authority
# or
npm install react react-dom clsx tailwind-merge class-variance-authority

For Table component (optional):

yarn add @tanstack/react-table

🚀 Quick Start

1. Import CSS

In your main application file (e.g., App.tsx or index.tsx):

import 'infinity-ui-elements/dist/index.css';

2. Use Components

import { Button, TextField, Badge } from 'infinity-ui-elements';

function App() {
  return (
    <div>
      <Button variant="primary" color="primary">
        Get Started
      </Button>
      
      <TextField 
        label="Email"
        placeholder="Enter your email"
        type="email"
      />
      
      <Badge color="positive" variant="light">
        Active
      </Badge>
    </div>
  );
}

3. Configure Tailwind CSS

The library uses custom utility classes that are pre-built. Configure your Tailwind setup to avoid conflicts:

For Tailwind CSS v4:

// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Don't include node_modules - CSS is already compiled
  ],
}

For Tailwind CSS v3:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
  ],
  safelist: [
    { pattern: /^(font-size|leading|font-functional|font-display|text-surface|text-action|bg-action|border-action)/ },
  ],
}

🧩 Components

Form Components

Button

A versatile button component with multiple variants, colors, sizes, and loading states.

Key Features:

• 3 variants: primary, secondary, tertiary
• 6 color options: primary, positive, negative, notice, info, neutral
• 4 sizes: xsmall, small, medium, large
• Leading/trailing icons support
• Loading states with spinners
• Icon-only mode
• Full-width option

import { Button } from 'infinity-ui-elements';

<Button variant="primary" color="positive" size="medium">
  Save Changes
</Button>

<Button variant="secondary" color="negative" isLoading>
  Deleting...
</Button>

<Button variant="tertiary" leadingIcon={<PlusIcon />}>
  Add Item
</Button>

TextField

A text input component with validation, icons, and helper text.

Key Features:

• Label with required/optional indicators
• Prefix and suffix support
• Validation states: positive, negative
• Clear button option
• Helper text and error messages
• Info tooltip integration
• Link support

import { TextField } from 'infinity-ui-elements';

<TextField
  label="Email Address"
  placeholder="Enter your email"
  type="email"
  isRequired
  helperText="We'll never share your email"
  showClearButton
/>

<TextField
  label="Amount"
  prefix="$"
  suffix="USD"
  validationState="positive"
  successText="Valid amount"
/>

TextArea

A multi-line text input with auto-resize capability.

Key Features:

• Auto-resize option
• Character count display
• Validation states
• Helper text support
• All TextField features

import { TextArea } from 'infinity-ui-elements';

<TextArea
  label="Description"
  placeholder="Enter description..."
  rows={4}
  maxLength={500}
  showCharCount
/>

Select

A dropdown select component with keyboard navigation.

Key Features:

• Searchable options
• Custom option rendering
• Prefix/suffix support
• Loading state
• Empty state customization
• Keyboard navigation
• Clear button

import { Select } from 'infinity-ui-elements';

const options = [
  { value: 'us', label: 'United States' },
  { value: 'uk', label: 'United Kingdom' },
  { value: 'ca', label: 'Canada' },
];

<Select
  label="Country"
  options={options}
  placeholder="Select a country"
  onChange={(value, option) => console.log(value)}
  showClearButton
/>

SearchableDropdown

An advanced dropdown with built-in search functionality.

Key Features:

• Real-time search filtering
• Multiple selection support
• Custom option rendering
• Grouped options
• Async data loading

import { SearchableDropdown } from 'infinity-ui-elements';

<SearchableDropdown
  label="Select Users"
  options={users}
  searchable
  placeholder="Search users..."
  onChange={(selected) => setSelectedUsers(selected)}
/>

Checkbox

A checkbox component with indeterminate state support.

Key Features:

• Indeterminate state for "select all"
• 3 sizes: small, medium, large
• Validation states
• Helper text and error messages
• Disabled state

import { Checkbox } from 'infinity-ui-elements';

<Checkbox 
  label="Accept terms and conditions"
  isRequired
  validationState="error"
  errorText="You must accept the terms"
/>

<Checkbox 
  label="Select all"
  isIndeterminate={someSelected && !allSelected}
  checked={allSelected}
/>

Radio

A radio button component for single selection.

Key Features:

• Custom styling
• Validation states
• Helper text support
• Disabled state
• Multiple sizes

import { Radio } from 'infinity-ui-elements';

<Radio
  label="Option 1"
  name="choice"
  value="option1"
  checked={selected === 'option1'}
  onChange={(e) => setSelected(e.target.value)}
/>

Switch

A toggle switch component for boolean states.

Key Features:

• Multiple sizes
• Disabled state
• Label support
• Custom colors
• Loading state

import { Switch } from 'infinity-ui-elements';

<Switch
  label="Enable notifications"
  checked={isEnabled}
  onChange={(checked) => setIsEnabled(checked)}
/>

Data Display Components

Table

A powerful data table built on TanStack Table with advanced features.

Key Features:

• Sorting, filtering, pagination
• Row selection
• Expandable detail panels
• Sticky headers
• Loading and empty states
• Custom cell rendering
• Horizontal scrolling
• Row hover effects

import { Table } from 'infinity-ui-elements';
import { useReactTable, getCoreRowModel, createColumnHelper } from '@tanstack/react-table';

const columnHelper = createColumnHelper<User>();

const columns = [
  columnHelper.accessor('name', {
    header: 'Name',
    cell: info => info.getValue(),
  }),
  columnHelper.accessor('email', {
    header: 'Email',
  }),
];

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

<Table 
  table={table}
  enableRowSelection
  showRowHover
  stickyHeader
  detailPanel={(row) => <UserDetails user={row.original} />}
/>

Badge

A small status indicator component.

Key Features:

• 2 variants: light, filled
• 6 color options
• 3 sizes: small, medium, large
• Optional dot indicator
• Custom content support

import { Badge } from 'infinity-ui-elements';

<Badge variant="filled" color="positive">
  Active
</Badge>

<Badge variant="light" color="notice" showDot>
  Pending
</Badge>

Avatar

A user avatar component with status indicators.

Key Features:

• Image or text initials
• Status indicator with custom icons
• 5 color variants
• 2 sizes: small, medium
• Label and trailing component support
• Fallback for broken images

import { Avatar } from 'infinity-ui-elements';

<Avatar
  src="/user-avatar.jpg"
  alt="John Doe"
  size="medium"
  showStatus
  statusColor="positive"
/>

<Avatar color="a1" size="small">
  JD
</Avatar>

<Avatar
  src="/user.jpg"
  label="John Doe"
  trailingComponent={<ChevronDown />}
/>

Counter

A numeric counter with increment/decrement controls.

Key Features:

• Min/max value constraints
• Step control
• Disabled state
• Custom formatting
• Size variants

import { Counter } from 'infinity-ui-elements';

<Counter
  value={count}
  onChange={setCount}
  min={0}
  max={100}
  step={1}
/>

Text

A typography component with consistent styling.

Key Features:

• Multiple variants: display, heading, body, label, caption
• Size options for each variant
• Weight options: regular, medium, semibold, bold
• Color options
• Polymorphic as prop

import { Text } from 'infinity-ui-elements';

<Text variant="heading" size="xlarge" weight="bold">
  Welcome Back
</Text>

<Text variant="body" size="medium" color="muted">
  This is a description
</Text>

<Text variant="label" as="label" htmlFor="input-id">
  Field Label
</Text>

Navigation Components

Link

A styled link component with various visual states.

Key Features:

• Multiple variants
• External link support
• Disabled state
• Icon support
• Underline options

import { Link } from 'infinity-ui-elements';

<Link href="/dashboard" variant="primary">
  Go to Dashboard
</Link>

<Link href="https://example.com" external>
  Visit Website
</Link>

Tabs / TabItem

Tab navigation components for organizing content.

Key Features:

• Horizontal and vertical layouts
• Active state management
• Icon support
• Disabled tabs
• Keyboard navigation

import { Tabs, TabItem } from 'infinity-ui-elements';

<Tabs>
  <TabItem active>Overview</TabItem>
  <TabItem>Settings</TabItem>
  <TabItem disabled>Analytics</TabItem>
</Tabs>

Pagination

A pagination component for navigating through pages.

Key Features:

• Page number display
• Previous/Next buttons
• First/Last page navigation
• Custom page size
• Controlled and uncontrolled modes

import { Pagination } from 'infinity-ui-elements';

<Pagination
  currentPage={page}
  totalPages={10}
  onPageChange={setPage}
  showFirstLast
/>

Layout Components

ButtonGroup

A component for grouping related buttons.

Key Features:

• Horizontal and vertical layouts
• Connected or separated styles
• Size variants
• Full-width option

import { ButtonGroup, Button } from 'infinity-ui-elements';

<ButtonGroup>
  <Button variant="secondary">Cancel</Button>
  <Button variant="primary">Save</Button>
</ButtonGroup>

Divider

A visual separator component.

Key Features:

• Horizontal and vertical orientations
• With or without text
• Custom styling
• Spacing control

import { Divider } from 'infinity-ui-elements';

<Divider />

<Divider orientation="vertical" />

<Divider>OR</Divider>

Modal

A modal dialog component for overlays.

Key Features:

• Multiple size options
• Header with title and description
• Footer support
• Close on overlay click
• Escape key support
• Scroll locking
• Animation transitions

import { Modal } from 'infinity-ui-elements';

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirm Action"
  description="Are you sure you want to proceed?"
  size="medium"
  footer={
    <>
      <Button variant="secondary" onClick={() => setIsOpen(false)}>
        Cancel
      </Button>
      <Button variant="primary" onClick={handleConfirm}>
        Confirm
      </Button>
    </>
  }
>
  <p>Modal content goes here...</p>
</Modal>

Tooltip

A tooltip component for displaying contextual information.

Key Features:

• Multiple placement options
• Trigger on hover or click
• Delay control
• Arrow indicator
• Custom styling

import { Tooltip } from 'infinity-ui-elements';

<Tooltip content="This is helpful information">
  <Button>Hover me</Button>
</Tooltip>

ListItem

A list item component for building lists.

Key Features:

• Leading and trailing content
• Multi-line support
• Clickable/interactive
• Custom styling
• Icon support

import { ListItem } from 'infinity-ui-elements';

<ListItem
  leadingIcon={<UserIcon />}
  title="John Doe"
  description="[email protected]"
  trailingContent={<ChevronRight />}
  onClick={() => console.log('Clicked')}
/>

Form Layout Components

FormHeader

A form header component with label and info tooltip.

Key Features:

• Required/optional indicators
• Info tooltip
• Link support
• Size variants
• Custom styling

import { FormHeader } from 'infinity-ui-elements';

<FormHeader
  label="Email Address"
  isRequired
  infoHeading="Why we need this"
  infoDescription="We use your email for account recovery"
  linkText="Privacy Policy"
  linkHref="/privacy"
/>

FormFooter

A form footer component for helper text and validation messages.

Key Features:

• Validation state styling
• Error/success messages
• Helper text
• Size variants

import { FormFooter } from 'infinity-ui-elements';

<FormFooter
  helperText="Password must be at least 8 characters"
  validationState="negative"
/>

Interactive Components

Dropdown / DropdownMenu

A flexible dropdown menu component.

Key Features:

• Custom trigger
• Nested menus
• Keyboard navigation
• Dividers and sections
• Icon support
• Custom item rendering

import { Dropdown } from 'infinity-ui-elements';

<Dropdown
  trigger={<Button>Options</Button>}
  items={[
    { title: 'Edit', onClick: handleEdit },
    { title: 'Delete', onClick: handleDelete, color: 'negative' },
  ]}
/>

🎨 Using Design Tokens in Your App

Using CSS Variables

After importing the library CSS, use design tokens anywhere in your application:

/* YourCustomComponent.css */
.my-card {
  background: var(--color-surface-fill-neutral-intense);
  border: var(--border-width-thin) solid var(--color-surface-outline-neutral-muted);
  border-radius: var(--radius-large);
  padding: var(--spacing-7);
  color: var(--color-surface-ink-neutral-normal);
}

.my-button {
  background: var(--color-action-fill-primary-default);
  color: var(--color-action-ink-on-primary-normal);
  padding: var(--spacing-3) var(--spacing-6);
  font-family: var(--font-functional);
  font-size: var(--text-100);
  border-radius: var(--radius-medium);
}

.my-button:hover {
  background: var(--color-action-fill-primary-hover);
}

Using Inline Styles (React)

<div style={{
  backgroundColor: 'var(--color-teal-500)',
  padding: 'var(--spacing-5)',
  borderRadius: 'var(--radius-medium)',
  fontFamily: 'var(--font-functional)',
}}>
  Styled with design tokens
</div>

Overriding Tokens (Advanced)

Only override if absolutely necessary for app-specific themes:

/* app-overrides.css - Import AFTER the library CSS */
:root {
  /* Override specific tokens for your app */
  --app-specific-color: var(--color-teal-700);
}

⚠️ Important: Do NOT duplicate design tokens in your app. Always use the tokens from this package to maintain consistency. When designers make changes, update the package version to get the latest design system.

📚 Complete Token Reference: See DESIGN_TOKENS.md for all available variables.

🛠️ Development

Prerequisites

• Node.js 18+
• Yarn 4.5.2 (managed via Corepack)

Setup

# Install dependencies
yarn install

# Start Storybook for development
yarn storybook

# Build the library
yarn build

# Type checking
yarn type-check

Project Structure

src/
├── components/           # All UI components
│   ├── Button/
│   │   ├── Button.tsx           # Component implementation
│   │   ├── Button.stories.tsx   # Storybook stories
│   │   └── index.ts             # Exports
│   └── ...
├── lib/                  # Utilities and helpers
│   ├── utils.ts          # Utility functions
│   └── icons.tsx         # Icon system
├── styles/               # Global styles
│   ├── theme/            # Theme variables
│   ├── animations.css    # Animations
│   └── utilities/        # Utility classes
└── index.ts              # Main entry point

Adding New Components

1. Create component folder in src/components/
2. Implement component with TypeScript
3. Add Storybook stories for documentation
4. Export from component's index.ts
5. Add export to main src/index.ts

📚 Storybook

View interactive documentation and examples:

yarn storybook

Or visit the deployed Storybook (if available).

📤 Publishing

Automated Publishing

# For bug fixes (1.0.0 -> 1.0.1)
yarn publish:patch

# For new features (1.0.0 -> 1.1.0)
yarn publish:minor

# For breaking changes (1.0.0 -> 2.0.0)
yarn publish:major

# For beta releases
yarn publish:beta

Manual Publishing

# 1. Login to npm
npm login

# 2. Update version
yarn version:patch  # or version:minor, version:major

# 3. Build
yarn build

# 4. Publish
npm publish

Pre-publish Checklist

• ✅ All tests pass
• ✅ Type checking passes (yarn type-check)
• ✅ Storybook builds successfully
• ✅ CHANGELOG.md updated
• ✅ Version bumped in package.json

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the coding standards
4. Add tests if applicable
5. Update documentation (README, Storybook)
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Component Guidelines

• Use TypeScript with strict mode
• Follow existing naming conventions
• Use Tailwind CSS for styling via class-variance-authority
• Include proper prop types and JSDoc comments
• Create comprehensive Storybook stories
• Ensure accessibility (ARIA attributes, keyboard navigation)
• Export from barrel files (index.ts)

🔍 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📝 License

MIT © Himanshu Barmola

🔗 Links

• NPM Package
• GitHub Repository
• Storybook Documentation
• Report Issues

💡 Tips & Best Practices

Performance

• Import only the components you need (tree-shaking enabled)
• Use the cn() utility for conditional classes
• Avoid inline styles when possible

Styling

• Always import the main CSS file: import 'infinity-ui-elements/dist/index.css'
• Use the provided design tokens for consistency
• Extend with custom classes using className prop

Accessibility

• Always provide labels for form components
• Use semantic HTML elements
• Include ARIA attributes where needed
• Test with keyboard navigation

TypeScript

• All components are fully typed
• Use IntelliSense for prop discovery
• Extend interfaces if needed for custom types

🆘 Support

Need help? Have questions?

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

🎉 Acknowledgments

Built with:

• React
• TypeScript
• Tailwind CSS
• Storybook
• TanStack Table
• Lucide Icons
• Class Variance Authority

Made with ❤️ by the Infinity Team