ikame-ui-lib

A modern React UI component library built with TypeScript, Tailwind CSS, and shadcn/ui. Features custom design tokens, comprehensive component variants, and a beautiful playground for development.

🚀 Features

• Modern Stack: React 18+, TypeScript, Tailwind CSS, shadcn/ui
• Custom Design System: Brand colors, typography, and functional tokens
• Comprehensive Components: Button, Input, Textarea, Dialog, Sidebar, and more
• TypeScript Support: Full type definitions included
• Tree Shaking: ES modules and CommonJS support
• Playground: Interactive demo with live code examples

📦 Install

npm install ikame-ui-lib
# or
yarn add ikame-ui-lib
# or
pnpm add ikame-ui-lib

⚙️ Setup

1. Install Tailwind CSS

This library requires Tailwind CSS to be configured in your project:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

2. Configure Tailwind

Add the library to your Tailwind config:

// tailwind.config.js
export default {
  content: [
    './index.html',
    './src/**/*.{ts,tsx}',
    './node_modules/ikame-ui-lib/dist/**/*.{js,jsx}'
  ],
  theme: { 
    extend: {
      // Optional: extend with custom tokens
    }
  },
  plugins: [],
}

3. Setup Import Alias

Configure path alias for @/* in your project:

tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

vite.config.ts:

import { defineConfig } from 'vite'
import path from 'node:path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

4. Import Styles

Import the styles CSS file to use utility classes and design tokens:

Option 1: Import in CSS (recommended)

/* Import in your main CSS file - place at the top */
@import 'ikame-ui-lib/styles.css';

Option 2: Import in JavaScript (recommended for Next.js)

// Import in your main layout or app file
import 'ikame-ui-lib/styles.css'

Option 3: Use JavaScript module (Next.js compatible)

// Import in your main layout or app file
import { injectTokens } from 'ikame-ui-lib'

// Call once in your app
injectTokens()

Option 4: Alternative CSS file

@import 'ikame-ui-lib/dist/styles.css';

Or copy the CSS variables to your project's CSS file:

/* Add these CSS variables to your global CSS */
:root {
  /* Brand Colors */
  --color-orange-800: #bb4307;
  --color-orange-600: #ec5509;
  --color-orange-500: #f76226;
  /* ... (see dist/tokens.css for complete list) */
  
  /* Functional Colors */
  --color-text-primary: var(--color-neutral-800);
  --color-text-secondary: var(--color-neutral-700);
  --color-bg-surface: var(--color-white);
  /* ... (see dist/tokens.css for complete list) */
}

🎯 Usage

Basic Components

import { UIButton, Input, Textarea } from 'ikame-ui-lib'

export default function App() {
  return (
    <div className="space-y-4">
      {/* Button variants */}
      <UIButton>Primary</UIButton>
      <UIButton variant="secondary">Secondary</UIButton>
      <UIButton variant="outline">Outline</UIButton>
      <UIButton variant="subtle">Subtle</UIButton>
      <UIButton variant="danger">Danger</UIButton>
      
      {/* Button sizes */}
      <UIButton size="xs">Extra Small</UIButton>
      <UIButton size="s">Small</UIButton>
      <UIButton size="m">Medium</UIButton>
      <UIButton size="l">Large</UIButton>
      <UIButton size="icon">+</UIButton>
      
      {/* Input variants */}
      <Input variant="filled" placeholder="Filled input" />
      <Input variant="borderless" placeholder="Borderless input" />
      
      {/* Textarea variants */}
      <Textarea variant="filled" placeholder="Filled textarea" />
      <Textarea variant="borderless" placeholder="Borderless textarea" />
    </div>
  )
}

Advanced Components

import { 
  Dialog, 
  DialogContent, 
  DialogHeader, 
  DialogTitle, 
  DialogTrigger,
  Sidebar,
  SidebarContent,
  SidebarProvider,
  BlockBreadcrumb
} from 'ikame-ui-lib'
import type { BlockBreadcrumbItem } from 'ikame-ui-lib'

export default function App() {
  const breadcrumbItems: BlockBreadcrumbItem[] = [
    { id: 'home', label: 'Trang chủ', href: '/' },
    { id: 'products', label: 'Sản phẩm', href: '/products' },
    { id: 'detail', label: 'Chi tiết', isCurrentPage: true }
  ]

  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarContent>
          {/* Sidebar content */}
        </SidebarContent>
      </Sidebar>
      
      <div className="p-4">
        {/* Breadcrumb navigation */}
        <BlockBreadcrumb items={breadcrumbItems} />
        
        <Dialog>
          <DialogTrigger asChild>
            <UIButton>Open Dialog</UIButton>
          </DialogTrigger>
          <DialogContent>
            <DialogHeader>
              <DialogTitle>Dialog Title</DialogTitle>
            </DialogHeader>
            {/* Dialog content */}
          </DialogContent>
        </Dialog>
      </div>
    </SidebarProvider>
  )
}

🎨 Design Tokens & Class Names

The library includes comprehensive design tokens accessible via CSS classes. You can use these classes directly in your HTML/JSX without importing React components.

Brand Colors

/* Primary colors (Orange) */
.color-primary-50     /* #feefe9 */
.color-primary-500    /* #f76226 */
.color-primary-900    /* #993706 */
.bg-primary-500       /* Background color */
.border-primary-500   /* Border color */

/* Secondary colors (Blue) */
.color-secondary-50   /* #f6fafe */
.color-secondary-500  /* #0d87f2 */
.color-secondary-900  /* #043057 */
.bg-secondary-500     /* Background color */
.border-secondary-500 /* Border color */

Functional Colors

/* Text colors */
.color-text-primary   /* Primary text color */
.color-text-secondary /* Secondary text color */
.color-text-tertiary  /* Tertiary text color */
.color-fg-link-default /* Link default color */
.color-fg-link-active  /* Link active color */

/* Background colors */
.bg-surface           /* Surface background */
.bg-secondary         /* Secondary background */
.bg-primary           /* Primary background */

/* Border colors */
.border-primary       /* Primary border */
.border-secondary     /* Secondary border */
.border-tertiary      /* Tertiary border */

Typography

/* Font sizes */
.font-size-headline-xl    /* 48px */
.font-size-headline-l     /* 40px */
.font-size-headline-m     /* 32px */
.font-size-headline-s     /* 28px */
.font-size-headline-xs    /* 24px */
.font-size-body-xl        /* 20px */
.font-size-body-l         /* 18px */
.font-size-body-m         /* 16px */
.font-size-body-s         /* 14px */
.font-size-body-xs        /* 12px */
.font-size-body-xxs       /* 10px */

/* Font weights */
.font-weight-headline-strong /* 600 */
.font-weight-body-normal     /* 400 */
.font-weight-body-strong     /* 600 */

/* Line heights */
.font-line-height-headline-xl /* 50px */
.font-line-height-body-m      /* 24px */
.font-line-height-body-s      /* 22px */

/* Paragraph spacing */
.font-paragraph-spacing-body-xl /* 24px */
.font-paragraph-spacing-body-m  /* 14px */
.font-paragraph-spacing-body-s  /* 12px */

Shadcn/UI Utilities

/* Semantic colors */
.bg-background        /* Main background */
.text-foreground      /* Main text color */
.bg-card              /* Card background */
.text-card-foreground /* Card text color */
.bg-primary           /* Primary background */
.text-primary-foreground /* Primary text color */

/* Border radius */
.rounded-lg           /* Large border radius */
.rounded-md           /* Medium border radius */
.rounded-sm           /* Small border radius */

Using Class Names Directly

After importing the styles CSS, you can use these classes anywhere in your project:

<!-- Brand colors -->
<button class="bg-primary-500 text-white px-4 py-2 rounded-lg">
  Primary Button
</button>

<div class="bg-secondary-100 text-secondary-700 p-4 rounded-lg">
  Secondary Card
</div>

<!-- Typography -->
<h1 class="font-size-headline-xl font-weight-headline-strong color-text-primary">
  Main Heading
</h1>

<p class="font-size-body-m color-text-secondary">
  Body text with custom styling
</p>

<!-- Functional colors -->
<div class="bg-surface border border-primary p-6 rounded-lg">
  <h2 class="color-text-primary font-size-headline-s">Card Title</h2>
  <p class="color-text-secondary font-size-body-s">Card description</p>
</div>

// In React/JSX
<div className="color-text-primary bg-primary-50 border-primary-200 p-4 rounded-lg">
  Primary colored content
</div>

// Typography classes
<h1 className="font-headline-xl font-headline-strong font-line-height-headline-xl">
  Large Heading
</h1>

<p className="font-body-m font-body-normal font-line-height-body-m font-paragraph-spacing-body-m">
  Body text with proper spacing
</p>

// Combined with components
<Button className="color-text-primary font-body-strong">
  Custom styled button
</Button>

🛠️ Development

Playground

Run the interactive playground to explore components:

npm run dev

Visit http://localhost:5173 to see the playground.

Build

npm run build

Lint

npm run lint

📚 Available Components

UI Components

• Button - Multiple variants (primary, secondary, outline, subtle, danger) and sizes
• Input - Filled and borderless variants with different sizes
• Textarea - Filled and borderless variants with different sizes
• Dialog - Modal dialogs with header, content, and footer
• Sidebar - Collapsible sidebar navigation
• Separator - Visual dividers
• Sheet - Slide-out panels
• Skeleton - Loading placeholders
• Tooltip - Contextual information
• Breadcrumb - Navigation breadcrumbs with ellipsis support

Block Components

• BlockSidebar - Advanced sidebar with groups and navigation
• BlockBreadcrumb - Easy-to-use breadcrumb component with auto-collapse

🔄 Version History

• 0.1.0 - Initial release with core components and design system

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please open an issue on GitHub.