{"id":16958795,"url":"https://github.com/kaihotz/kai-ui","last_synced_at":"2026-04-13T17:07:30.866Z","repository":{"id":244121114,"uuid":"814237876","full_name":"KaiHotz/kai-ui","owner":"KaiHotz","description":"A design system composed out of custom react components, supporting dark and light mode","archived":false,"fork":false,"pushed_at":"2024-10-23T18:08:10.000Z","size":23914,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-24T02:53:17.528Z","etag":null,"topics":["css-variables","dark-mode","dark-theme","design-system","react","react-components","scss-styles","storybook"],"latest_commit_sha":null,"homepage":"https://kaihotz.github.io/kai-ui/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KaiHotz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-12T15:50:04.000Z","updated_at":"2024-10-23T18:08:14.000Z","dependencies_parsed_at":"2024-06-13T01:55:30.653Z","dependency_job_id":"3323b5c4-9804-42b2-a614-888e194cc9fc","html_url":"https://github.com/KaiHotz/kai-ui","commit_stats":null,"previous_names":["kaihotz/kai-ui"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaiHotz%2Fkai-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaiHotz%2Fkai-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaiHotz%2Fkai-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaiHotz%2Fkai-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KaiHotz","download_url":"https://codeload.github.com/KaiHotz/kai-ui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244815254,"owners_count":20514919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css-variables","dark-mode","dark-theme","design-system","react","react-components","scss-styles","storybook"],"created_at":"2024-10-13T22:43:36.896Z","updated_at":"2026-04-13T17:07:30.839Z","avatar_url":"https://github.com/KaiHotz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kai-ui\n\nA modern, TypeScript-based React component library built with Vite, featuring a comprehensive collection of customizable UI components with built-in theming support.\n\n[![Version](https://img.shields.io/badge/version-5.1.0-blue.svg)](https://github.com/KaiHotz/kai-ui)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## 🚀 Features\n\n- **🎨 Comprehensive Component Library** - 30+ production-ready components including forms, charts, tables, and navigation\n- **🌓 Theme System** - Built-in light/dark mode support with customizable themes\n- **📦 Tree-shakeable** - Optimized bundle size with ES modules\n- **🔷 TypeScript First** - Full TypeScript support with comprehensive type definitions\n- **⚡ Modern Stack** - Built with Vite, React 19, and SWC for optimal performance\n- **🎭 Storybook Integration** - Interactive component documentation and development\n- **✅ Fully Tested** - Comprehensive test coverage with Vitest and React Testing Library\n- **♿ Accessible** - WCAG compliant components\n- **🎯 SCSS Styling** - Flexible styling with SCSS and BEM methodology\n\n## 📦 Installation\n\n```bash\nnpm install kai-ui\n# or\nyarn add kai-ui\n```\n\n### Peer Dependencies\n\nThis library requires the following peer dependencies:\n\n```bash\nnpm install react react-dom @floating-ui/react react-hook-form react-icons react-tooltip react-transition-group ag-grid-community ag-grid-react clsx date-fns highcharts highcharts-react-official highcharts-custom-events lodash yup\n```\n\n## 🏗️ Architecture\n\n### Project Structure\n\n```\nkai-ui/\n├── src/\n│   ├── components/       # UI components\n│   │   ├── Accordion/\n│   │   ├── Avatar/\n│   │   ├── Button/\n│   │   ├── Charts/\n│   │   ├── DataTable/\n│   │   ├── Forms/\n│   │   └── ...\n│   ├── hooks/           # Custom React hooks\n│   ├── providers/       # Context providers (Theme, etc.)\n│   ├── styles/          # Global styles and theming\n│   └── utils/           # Utility functions\n```\n\n### Component Architecture\n\nEach component follows a consistent structure:\n\n- **Component File** (`*.tsx`) - Main component implementation\n- **Styles** (`*.scss`) - Component-specific styles using BEM methodology\n- **Stories** (`*.stories.tsx`) - Storybook documentation\n- **Tests** (`*.test.tsx`) - Unit tests with Vitest\n- **Types** - TypeScript interfaces exported for consumers\n- **Index** (`index.ts`) - Clean exports\n\n### Design Principles\n\n1. **Composition over Configuration** - Components are designed to be composed together\n2. **Prop-driven** - Behavior controlled through clear, typed props\n3. **Accessibility First** - ARIA attributes and keyboard navigation built-in\n4. **Theme Integration** - All components respect the global theme system\n5. **Performance Optimized** - Minimal re-renders and optimized bundle size\n\n## 🎯 Usage\n\n### Basic Setup\n\n```tsx\nimport { ThemeProvider } from 'kai-ui';\nimport 'kai-ui/styles.css';\n\nfunction App() {\n  return \u003cThemeProvider name=\"my-app\"\u003e{/* Your app content */}\u003c/ThemeProvider\u003e;\n}\n```\n\n### Using Components\n\n```tsx\nimport { Button, Input, Modal, DataTable } from 'kai-ui';\n\nfunction MyComponent() {\n  return (\n    \u003cdiv\u003e\n      \u003cButton variant=\"primary\" onClick={() =\u003e console.log('clicked')}\u003e\n        Click Me\n      \u003c/Button\u003e\n\n      \u003cInput label=\"Email\" type=\"email\" placeholder=\"Enter your email\" /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n### Theme System\n\nThe library includes a built-in theme system with light and dark modes:\n\n```tsx\nimport { useTheme } from 'kai-ui';\n\nfunction ThemeToggle() {\n  const { theme, isDark, setTheme } = useTheme();\n\n  return \u003cbutton onClick={() =\u003e setTheme(isDark ? 'light' : 'dark')}\u003eCurrent: {theme}\u003c/button\u003e;\n}\n```\n\nTheme preferences are automatically:\n\n- Persisted to localStorage\n- Synchronized with system preferences\n- Applied via CSS custom properties\n\n### Custom Hooks\n\nThe library provides several custom hooks:\n\n```tsx\nimport { useClickOutside, useCloseByEscape, useCountdown, useEventListener, useTheme } from 'kai-ui';\n\nfunction MyComponent() {\n  const ref = useClickOutside(() =\u003e console.log('Clicked outside'));\n  useCloseByEscape(() =\u003e console.log('Escape pressed'));\n\n  return \u003cdiv ref={ref}\u003eContent\u003c/div\u003e;\n}\n```\n\n## 📚 Component Categories\n\n### Layout \u0026 Navigation\n\n- **Accordion** - Collapsible content sections\n- **Drawer** - Side panel with slide-in animation\n- **Modal** - Dialog overlays\n- **SideNav** - Sidebar navigation\n- **Tabs** - Tabbed interfaces\n- **Stepper** - Multi-step workflows\n\n### Forms \u0026 Inputs\n\n- **Button** - Multiple variants (primary, secondary, tertiary, ghost, danger)\n- **Checkbox** - Single and grouped checkboxes\n- **ColorPicker** - Color selection with presets\n- **DatePicker** - Date and range selection\n- **Input** - Text input with validation\n- **Radio** - Radio button groups\n- **Select** - Dropdown selection\n- **Switch** - Toggle switches\n- **Textarea** - Multi-line text input\n- **Forms** - Complete form components with validation\n\n### Data Display\n\n- **Avatar** - User avatars with initials fallback\n- **DataRows** - Key-value data display\n- **DataTable** - Advanced data grid (powered by AG Grid)\n- **HeatMapCalendar** - Calendar-based heatmaps\n- **Score** - Rating display\n- **Label** - Status badges and labels\n\n### Charts \u0026 Visualization\n\n- **Chart** - Base chart component\n- **DateTimeSeries** - Time-based line charts\n- **PieChart** - Circular data visualization\n- **SpiderWebChart** - Radar/spider charts\n\n### Feedback \u0026 Overlays\n\n- **Backdrop** - Modal backdrops\n- **Hint** - Tooltips and hints\n- **Spinner** - Loading indicators\n- **ContextMenu** - Right-click menus\n- **MenuButton** - Dropdown action menus\n\n### Navigation\n\n- **Pagination** - Page navigation controls\n- **PseudoLink** - Link-styled buttons\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js \u003e= 22\n- Yarn or npm\n\n### Scripts\n\n```bash\n# Install dependencies\nyarn install\n\n# Start Storybook development server\nyarn storybook\n\n# Build the library\nyarn build\n\n# Run tests\nyarn test\n\n# Run linting\nyarn lint\n\n# Fix linting issues\nyarn lint:fix\n\n# Type checking\nyarn check-types\n\n# CI pipeline (lint + test)\nyarn ci\n```\n\n### Building\n\nThe library is built using Vite with the following optimizations:\n\n- **TypeScript declarations** generated with `vite-plugin-dts`\n- **Tree-shaking** enabled with ES modules\n- **Code splitting** for optimal chunk sizes\n- **SVG as React components** with `vite-plugin-svgr`\n- **Minification** with Terser\n- **Peer dependencies** externalized to reduce bundle size\n\nBuild output structure:\n\n```\ndist/\n├── index.js           # Main entry point\n├── index.d.ts         # Type definitions\n├── styles.css         # Bundled styles\n└── src/              # Individual component types\n```\n\n## 🧪 Testing\n\nTests are written using:\n\n- **Vitest** - Fast unit test runner\n- **React Testing Library** - Component testing utilities\n- **@testing-library/jest-dom** - Custom matchers\n\nRun tests:\n\n```bash\nyarn test          # Watch mode\nyarn ci           # Single run (CI)\n```\n\n## 📖 Storybook\n\nInteractive component documentation is available via Storybook:\n\n```bash\nyarn storybook\n```\n\nAccess at http://localhost:6006\n\nBuild static Storybook:\n\n```bash\nyarn storybook:build\n```\n\n## 🎨 Styling\n\n### SCSS Architecture\n\nThe library uses SCSS with a BEM-inspired methodology:\n\n```scss\n// Global styles\n@import 'kai-ui/dist/styles.css';\n\n// Component-specific\n.ui-btn {\n  \u0026--primary {\n    /* ... */\n  }\n  \u0026--secondary {\n    /* ... */\n  }\n  \u0026--small {\n    /* ... */\n  }\n}\n```\n\n### CSS Custom Properties\n\nTheming is implemented using CSS custom properties:\n\n```scss\n:root {\n  --color-primary: #007bff;\n  --color-background: #ffffff;\n  --font-family-base: 'Inter', sans-serif;\n  // ... more variables\n}\n\n[data-theme='dark'] {\n  --color-background: #1a1a1a;\n  // ... dark theme overrides\n}\n```\n\n### Custom Fonts\n\nThe library includes custom font faces. Ensure fonts are properly loaded:\n\n```tsx\nimport 'kai-ui/dist/styles.css'; // Includes font faces\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for new functionality\n4. Ensure all tests pass (`yarn ci`)\n5. Commit changes (`git commit -m 'Add amazing feature'`)\n6. Push to branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Code Style\n\n- Follow existing patterns and conventions\n- Use TypeScript for all new code\n- Write tests for components and hooks\n- Document props with JSDoc comments\n- Create Storybook stories for visual components\n\n## 📄 License\n\nMIT © Kai Hotz\n\n## 🔗 Links\n\n- [GitHub Repository](https://github.com/KaiHotz/kai-ui)\n- [NPM Package](https://npm.pkg.github.com/KaiHotz)\n- [Issues](https://github.com/KaiHotz/kai-ui/issues)\n\n## 💡 Utilities\n\nThe library provides utility functions for common tasks:\n\n- `capitalizeWords()` - String formatting\n- `cleanObj()` - Object sanitization\n- `getInitials()` - Extract initials from names\n- `highlightText()` - Text highlighting\n- `isEditableElement()` - DOM element checks\n- `getCSSVariable()` - Theme variable access\n- And more...\n\n## 🌟 Acknowledgments\n\nBuilt with:\n\n- [React](https://react.dev/)\n- [TypeScript](https://www.typescriptlang.org/)\n- [Vite](https://vitejs.dev/)\n- [Storybook](https://storybook.js.org/)\n- [AG Grid](https://www.ag-grid.com/)\n- [Highcharts](https://www.highcharts.com/)\n- [date-fns](https://date-fns.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaihotz%2Fkai-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaihotz%2Fkai-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaihotz%2Fkai-ui/lists"}