@ixo/ui

A comprehensive React UI component library built with Emotion and Mantine, featuring a complete theming system, extensive icon library, and components designed for impact-focused applications.

✨ Features

• 🎨 Theming System: Light/dark theme support with customizable theme overrides
• 🧩 100+ Components: Buttons, cards, forms, navigation, data display, and specialized components
• 🎯 Icon Library: 300+ icons including crypto currencies, SDG icons, and general purpose icons
• 📱 Responsive: Mobile-first design with responsive breakpoints
• 🎭 Emotion CSS-in-JS: Styled with Emotion for dynamic styling and theme integration
• 📖 Storybook: Comprehensive component documentation and playground
• 🔧 TypeScript: Full TypeScript support with comprehensive type definitions
• ⚡ Tree-shakeable: Optimized bundle size with selective imports

🚀 Installation

npm install @ixo/ui @emotion/react @emotion/cache
# or
pnpm add @ixo/ui @emotion/react @emotion/cache
# or
yarn add @ixo/ui @emotion/react @emotion/cache

🛠️ Setup

1. Wrap your app with UiProvider

The UiProvider is required to provide theming context using Emotion's ThemeProvider:

import { UiProvider } from "@ixo/ui/components";

function App() {
  return <UiProvider>{/* Your app content */}</UiProvider>;
}

2. Custom Theme (Optional)

You can customize both light and dark themes:

import { UiProvider } from "@ixo/ui/components";

const customLightTheme = {
  colors: {
    focus: "#ff6b35", // Custom accent color
    focusHover: "#ff8c66"
  },
  text: {
    main: "#1a1a1a"
  }
};

const customDarkTheme = {
  colors: {
    focus: "#00d2ff",
    focusHover: "#2ad9ff"
  }
};

function App() {
  return (
    <UiProvider customlightTheme={customLightTheme} customDarkTheme={customDarkTheme}>
      {/* Your app content */}
    </UiProvider>
  );
}

3. Next.js Setup (SSR Support)

For Next.js applications, add Emotion cache provider:

// pages/_app.tsx
import { CacheProvider } from "@emotion/react";
import createCache from "@emotion/cache";
import { UiProvider } from "@ixo/ui/components";

const cache = createCache({ key: "css", prepend: true });

function MyApp({ Component, pageProps }) {
  return (
    <CacheProvider value={cache}>
      <UiProvider>
        <Component {...pageProps} />
      </UiProvider>
    </CacheProvider>
  );
}

📦 Usage

Components

import { Button, Card, Typography, TextInput, Avatar, Tag } from "@ixo/ui/components";

function MyComponent() {
  return (
    <Card>
      <Typography variant="h2">Welcome to IXO</Typography>

      <Avatar src="/path/to/avatar.jpg" name="John Doe" size="lg" />

      <TextInput label="Email" placeholder="Enter your email" required />

      <Tag value="Verified" color="success" />

      <Button value="Get Started" lg onClick={() => console.log("Button clicked!")} />
    </Card>
  );
}

Icons

import { Heart, User, Search, ChevronDown } from "@ixo/ui/icons";

function IconExample() {
  return (
    <div>
      <Heart size={24} color="#ff6b35" />
      <User size={20} />
      <Search size={16} />
    </div>
  );
}

Crypto Icons

import { Bitcoin, Ethereum, Solana } from "@ixo/ui/icons/crypto";

function CryptoIcons() {
  return (
    <div>
      <Bitcoin size={32} />
      <Ethereum size={32} />
      <Solana size={32} />
    </div>
  );
}

SDG Icons (Sustainable Development Goals)

import { SDG1, SDG2, SDG3 } from "@ixo/ui/icons/sdg";

function SDGIcons() {
  return (
    <div>
      <SDG1 size={48} />
      <SDG2 size={48} />
      <SDG3 size={48} />
    </div>
  );
}

Pictograms

import { Services, Impacts, Portfolio } from "@ixo/ui/pictograms";

function PictogramExample() {
  return (
    <div>
      <Services size={64} />
      <Impacts size={64} />
      <Portfolio size={64} />
    </div>
  );
}

Hooks

import { useColorScheme, useUITheme, useEventSubscribe } from "@ixo/ui/hooks";

function HookExample() {
  const theme = useUITheme();
  const { isDark, toggle } = useColorScheme();

  return (
    <div style={{ color: theme.text.main }}>
      <p>Current theme: {isDark ? "Dark" : "Light"}</p>
      <button onClick={toggle}>Toggle Theme</button>
    </div>
  );
}

📚 Available Components

Layout & Navigation

• Layout, NavigationBar, NavButton, TabNavigation, TabSelector

Buttons & Actions

• Button, ButtonBasic, ButtonSubtle, RoundedButton, IconButton, ActionCard

Data Display

• Card, Table, Tag, Avatar, Typography, Chart, Tooltip

Forms & Inputs

• TextInput, Select, Checkbox, Switch, ComboBox, SearchInput

Feedback & Loading

• Loader, Modal, Toast, FeedbackMessage, Tooltip

Specialized Components

• ActivityCard, ProfileCard, EcosystemCard, SodaCard, PlanCard
• EntityList, GroupSelector, FilterTags, ImpactCreditState

And many more! See the full list in Storybook.

🎨 Theme System

The library uses a comprehensive theme system with:

• Colors: Focus colors, semantic colors (success, warning, error), neutral shades
• Typography: Font sizes, weights, and responsive text scaling
• Spacing: Consistent spacing scale for margins and padding
• Breakpoints: Mobile-first responsive breakpoints
• Glass effects: Modern glassmorphism styling
• Automatic theme switching: Based on user preference stored in localStorage

Theme Structure

type UITheme = {
  colors: {
    focus: string;
    focusSecondary: string;
    focusHover: string;
    // ... more colors
  };
  text: {
    main: string;
    secondary: string;
    overPicture: string;
  };
  bg: {
    card: string;
    main: string;
    navbar: string;
    // ... more backgrounds
  };
  semantic: {
    success: string;
    warning: string;
    error: string;
  };
  // ... spacing, radius, etc.
};

🧑‍💻 Local Development

Prerequisites

• Node.js 20+
• pnpm 10.6.5+

Setup

# Clone the repository
git clone <repository-url>
cd ixo-ui

# Install dependencies
pnpm install

Development Commands

# Start Storybook development server
pnpm dev

# Build the library
pnpm build

# Build for local testing (creates .tgz package)
pnpm build:local

# Lint code
pnpm lint
pnpm lint:fix

# Format code
pnpm format
pnpm format:check

# Build Storybook for production
pnpm build:storybook

Storybook

Launch the component playground and documentation:

pnpm dev

This will start Storybook at http://localhost:6006 where you can:

• 📖 Browse all components with live examples
• 🎛️ Interact with component props in real-time
• 🎨 Test different themes and configurations
• 📱 Test responsive behavior
• 📋 Copy code examples
• 🧪 Test accessibility features

Adding New Components

1. Create component directory: src/components/MyComponent/
2. Add implementation: index.tsx, types.ts
3. Create Storybook story: MyComponent.stories.tsx
4. Export from: src/export/components.ts
5. Test in Storybook: pnpm dev

🏗️ Build System

Built with Vite and configured for optimal library distribution:

• Multiple entry points: Components, hooks, icons, themes
• Dual format: ES modules (.mjs) and CommonJS (.cjs)
• TypeScript declarations: Full type support
• Tree-shaking: Import only what you need
• Emotion externalization: Prevents SSR issues
• Source maps: For easier debugging

Build Outputs

dist/
├── export/
│   ├── components.mjs/.cjs/.d.ts
│   ├── hooks.mjs/.cjs/.d.ts
│   ├── icons/index.mjs/.cjs/.d.ts
│   ├── icons/crypto.mjs/.cjs/.d.ts
│   ├── icons/sdg.mjs/.cjs/.d.ts
│   ├── pictograms.mjs/.cjs/.d.ts
│   ├── themes.mjs/.cjs/.d.ts
│   └── types.mjs/.cjs/.d.ts

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-component
3. Add your component with proper TypeScript types
4. Create comprehensive Storybook stories
5. Add component to exports
6. Test thoroughly in Storybook
7. Commit changes: git commit -m 'Add amazing component'
8. Push to branch: git push origin feature/amazing-component
9. Open a Pull Request