# Design System
import { Callout, Kbd } from '@/components/mdx';
# Design System
**@loke/design-system** is a pre-styled, accessible React component library built on Tailwind CSS v4. It provides production-ready components — Button, Card, Dialog, Form inputs, and more — along with layout primitives and a comprehensive color system. All styles are pre-compiled and ship as standard CSS, so you can use it with no build tool configuration.
This section covers everything you need to use the design system effectively:
* **Quick Start** — Get running in 5 minutes
* **[Form Input](/docs/design-system/form-input)** — Button, Input, Select, Checkbox, and more
* **[Feedback & Status](/docs/design-system/feedback-status)** — Alert, Badge, Toast, Spinner, and more
* **[Overlay & Navigation](/docs/design-system/overlay-navigation)** — Dialog, Dropdown, Tabs, Accordion, and more
* **[Data Display](/docs/design-system/data-display)** — Card, Table, Avatar, Text, and more
* **[Layout](/docs/design-system/layout)** — Box, Stack, Columns, and Inline primitives for structure
* **[Utilities](/docs/design-system/utilities)** — Helper functions and responsive utilities
* **[Guides](/docs/guides)** — Tailwind integration, color system, accessibility, and more
***
## Quick Start
This guide walks you through adding the LOKE Design System to an existing React project. By the end, you'll have a working setup with components rendering correctly.
The design system is designed to be plug-and-play. Install it, import the styles, and start using components — no additional configuration required.
***
## 1. Install the package
```bash
# bun (recommended)
bun add @loke/design-system
# npm
npm install @loke/design-system
# pnpm
pnpm add @loke/design-system
```
To use icons, also install the icon package:
```bash
bun add @loke/icons
```
***
## 2. Check your TypeScript config
The design system uses the `exports` field in `package.json` for granular imports. Your `tsconfig.json` must use a module resolution strategy that supports this.
Set the following in your `tsconfig.json`:
```json
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler"
}
}
```
If you see Cannot find module '@loke/design-system/button' errors, this is almost always a `moduleResolution` issue. The `"nodenext"` setting can cause problems with package exports — switch to `"bundler"` to resolve it.
***
## 3. Import the styles
Add the design system stylesheet to your app's root layout or entry point. This single import provides all component styles, theme variables, and color tokens.
### Next.js
```tsx
// app/layout.tsx
import "@loke/design-system/styles";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
### Vite / other frameworks
```tsx
// main.tsx or index.tsx
import "@loke/design-system/styles";
import { createRoot } from "react-dom/client";
import { App } from "./App";
createRoot(document.getElementById("root")!).render();
```
That's the only setup step. The design system ships pre-compiled CSS — you don't need to install or configure Tailwind CSS, PostCSS, or any other CSS tooling.
***
## 4. Use your first component
Import components individually from their specific paths:
```tsx
import { Button } from "@loke/design-system/button";
export function MyPage() {
return (
Hello, Design System
);
}
```
Components are imported from `@loke/design-system/` — not from the package root. This keeps your bundles small through tree-shaking.
```tsx
// Correct
import { Button } from "@loke/design-system/button";
import { Card, CardHeader, CardTitle, CardContent } from "@loke/design-system/card";
import { Input } from "@loke/design-system/input";
// Wrong — there is no barrel export
import { Button } from "@loke/design-system";
```
***
## 5. Build a simple page
Here's a more complete example combining several components:
```tsx
import { Button } from "@loke/design-system/button";
import { Card, CardHeader, CardTitle, CardContent, CardFooter } from "@loke/design-system/card";
import { Input } from "@loke/design-system/input";
import { Label } from "@loke/design-system/label";
import { Stack } from "@loke/design-system/stack";
export function LoginPage() {
return (
Sign in
);
}
```
***
## Dark mode
The design system supports dark mode via a CSS class. Add the `dark` class to your `` element to activate it:
```tsx
// Toggle dark mode
document.documentElement.classList.toggle("dark");
```
All components and color tokens automatically adapt when dark mode is active.
***
## What's included
When you import `@loke/design-system/styles`, you get:
* **Component styles** — all visual styles for every component
* **Color tokens** — semantic colors like `primary`, `secondary`, `muted`, `destructive`
* **Dark mode** — automatic dark mode support via the `.dark` class
* **Base styles** — sensible defaults for borders, backgrounds, and typography
* **Common CSS utilities** — a set of pre-compiled utility classes for spacing, layout, and more
You do **not** need to install Tailwind CSS separately. The design system bundles everything it needs.
If you want to use Tailwind CSS utilities beyond what the design system provides (e.g., for custom layout or one-off styling), see the [Tailwind CSS Guide](/docs/guides/tailwind) for setup instructions.
***
## Troubleshooting
### "Cannot find module '@loke/design-system/button'"
Set `"moduleResolution": "bundler"` and `"module": "esnext"` in your `tsconfig.json`. The `"nodenext"` resolution strategy doesn't always resolve package `exports` correctly in all toolchains.
### Styles not appearing
Make sure you've imported the stylesheet in your root layout or entry file:
```tsx
import "@loke/design-system/styles";
```
This import must run before any components render.
### Components look unstyled or broken
Check that you don't have conflicting global CSS that resets component styles. The design system's base layer sets `border-color` and `outline` on all elements — other CSS resets may conflict.
***
## Next steps
* [Form Input](/docs/design-system/form-input) — Button, Input, Select, Checkbox, and more
* [Feedback & Status](/docs/design-system/feedback-status) — Alert, Badge, Toast, Spinner, and more
* [Overlay & Navigation](/docs/design-system/overlay-navigation) — Dialog, Dropdown, Tabs, Accordion, and more
* [Data Display](/docs/design-system/data-display) — Card, Table, Avatar, Text, and more
* [Layout](/docs/design-system/layout) — layout primitives (Box, Stack, Columns, etc.)
* [Utilities](/docs/design-system/utilities) — reusable helpers and responsive utilities
* [Tailwind CSS Guide](/docs/guides/tailwind) — using Tailwind alongside the design system
* [Color System](/docs/guides/colors) — brand colors and semantic tokens
* [Icons](/docs/icons) — the LOKE icon library
# Accessibility Guide
import { Callout } from '@/components/mdx';
# Accessibility Guide
Accessibility is a core requirement for all LOKE applications. This guide outlines the accessibility features built into the design system and provides best practices for creating accessible interfaces.
## Why Accessibility Matters
* Inclusivity: Making our applications usable by people with disabilities
* Legal Compliance: Meeting accessibility standards and regulations
* Better UX for Everyone: Accessibility improvements benefit all users
* SEO Benefits: Many accessibility practices improve search engine visibility
***
## Design System Accessibility Features
The LOKE Design System includes several built‑in accessibility features:
### Keyboard Navigation
* All interactive components are keyboard accessible
* Focus states are clearly visible
* Logical tabbing order is maintained
* Keyboard shortcuts are consistent
### Screen Reader Support
* Semantic HTML is used throughout components
* ARIA attributes are correctly implemented
* Form elements have proper labels and descriptions
* Dialogs announce their presence appropriately
### Color and Contrast
* Color schemes meet WCAG 2.1 AA standards
* Text has sufficient contrast against backgrounds
* Information is not conveyed by color alone
* Focus states have adequate visibility
### Responsive Design
* Content resizes appropriately for different zoom levels
* Layouts adapt to different screen sizes
* Touch targets are appropriately sized for mobile
***
## Using Components Accessibly
### Buttons and Links
```jsx
// Good: Button with clear purpose
// Good: Icon button with accessible label
// Good: Alternative approach with VisuallyHidden
// Avoid: Icon-only button without accessible name
```
### Forms
```jsx
// Good: Properly labeled form controls
(
Email
We'll never share your email with anyone else.
)}
/>
// Avoid: Inputs without labels
```
### Images and Icons
```jsx
// Good: Image with alt text
// Good: Decorative image marked as such
// Good: SVG icon with title for assistive tech
// Avoid: Image without alt text
```
### Dialog and Modals
```jsx
// Good: Dialog with proper ARIA attributes
```
### Content Structure
```jsx
// Good: Proper heading hierarchy
Page TitleSection Title
Section content...
Subsection Title
Subsection content...
// Avoid: Skipping heading levels
Page Title
Section Title
```
***
## Accessibility Checklist
Use this checklist when implementing interfaces with the LOKE Design System:
### Keyboard Navigation
* [ ] All interactive elements can be accessed using the Tab key
* [ ] Focus order is logical and follows content flow
* [ ] Focus is visible at all times with good contrast
* [ ] No keyboard traps exist (except in modals with proper handling)
* [ ] Custom widgets provide keyboard interaction (arrow keys, escape, etc.)
### Screen Readers
* [ ] Proper heading structure is used (h1, h2, etc.)
* [ ] Images have appropriate alt text
* [ ] Form controls have associated labels
* [ ] ARIA landmarks are used appropriately
* [ ] Dynamic content changes are announced
* [ ] Status messages are conveyed to screen readers
### Visual Design
* [ ] Text color has sufficient contrast against backgrounds
* [ ] Information is not conveyed by color alone
* [ ] UI is usable at 200% zoom
* [ ] Text can be resized without loss of functionality
* [ ] Content is readable in both light and dark modes
### Content and Interactions
* [ ] Error messages are clear and suggest solutions
* [ ] Sufficient time is given for reading and interaction
* [ ] Motion and animations can be paused/reduced
* [ ] Instructions are clear and do not rely on sensory characteristics
* [ ] Link text is descriptive (no “click here” or “read more”)
***
## Testing Accessibility
### Automated Testing
Use automated tools as a first check:
* Lighthouse (in Chrome DevTools)
* axe DevTools (Chrome extension)
### Manual Testing
Always supplement automated tests with manual testing:
1. Keyboard navigation: Navigate using only the keyboard
2. Screen reader testing: Test with VoiceOver (macOS), NVDA (Windows), or other screen readers
3. Zoom testing: Test at 200% zoom
4. Contrast checking: Verify text contrast meets WCAG AA standards
5. Reduced motion: Test with reduced motion settings enabled
***
## Common Accessibility Issues
### 1) Missing Alternative Text
```jsx
// Issue
// Fix
```
### 2) Poor Color Contrast
```jsx
// Issue
Low-contrast text
// Fix
Improved contrast text
```
### 3) Missing Form Labels
```jsx
// Issue
// Fix
```
### 4) Non-descriptive Links
```jsx
// Issue
Click here
// Fix
View Privacy Policy
```
### 5) Missing Focus Styles
```css
/* Issue */
*:focus { outline: none; }
/* Fix - The design system provides appropriate focus styles by default
Do not remove these styles */
```
***
## Resources
* W3C Web Content Accessibility Guidelines (WCAG): [https://www.w3.org/WAI/standards-guidelines/wcag/](https://www.w3.org/WAI/standards-guidelines/wcag/)
* WebAIM Contrast Checker: [https://webaim.org/resources/contrastchecker/](https://webaim.org/resources/contrastchecker/)
* A11y Project Checklist: [https://www.a11yproject.com/checklist/](https://www.a11yproject.com/checklist/)
* MDN Accessibility Documentation: [https://developer.mozilla.org/en-US/docs/Web/Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
***
## Conclusion
Accessibility is everyone’s responsibility. By using the LOKE Design System components as intended and following the guidelines in this document, you’ll create interfaces that are accessible to all users. When in doubt, test with real assistive technologies and seek feedback from users with diverse abilities.
# Color System
import { Callout } from '@/components/mdx';
import { ColorPalette } from '@/components/colors/ColorPalette';
# Color System
The @loke/design-system provides a comprehensive color system designed for accessibility, consistency, and flexibility across light and dark modes. Colors are expressed as CSS variables and primarily defined in OKLCH for better perceptual uniformity.
The interactive palette below reflects your current theme. Use the toggle to switch between light and dark and copy values in different formats (OKLCH, HEX, RGB, HSL).
***
## Usage
The color system is implemented using CSS variables with support for both light and dark themes.
```css
.my-element {
background-color: var(--card);
color: var(--card-foreground);
}
```
In React components using Tailwind CSS:
```tsx
Card Content
```
***
## Color Palette
Our color system is organized into semantic categories (Base UI, Component, Sidebar, Action, Subtle UI, Data Visualization, and Brand). Explore and copy values:
***
## Color Decision Guidelines
When choosing colors for your UI:
1. Use semantic colors — choose by function, not by appearance.
2. Maintain contrast — ensure text and essential UI meet accessibility standards.
3. Be consistent — the same meaning should use the same color systemwide.
4. Consider dark mode — test both light and dark modes for each state.
***
## Accessibility Standards
All color combinations in our system are designed to meet WCAG 2.1 AA contrast requirements where applicable. Primary CTAs and critical text aim for AAA where possible.
```tsx
// Example: Emphasized action
// Example: Subtle content
This is less prominent supporting text.
```
```css
/* Example: Using tokens in CSS-in-JS or global CSS */
.cta {
background: var(--primary);
color: var(--primary-foreground);
}
.subtle {
color: var(--muted-foreground);
}
```
# Contribution Guide
import { Callout } from '@/components/mdx';
# Contribution Guide
This guide outlines the process and standards for contributing to the LOKE Design System. Whether you're fixing a bug, improving documentation, or adding a new component, this guide will help you understand how to contribute effectively.
The LOKE Design System is maintained internally for LOKE products. All LOKE team members are encouraged to contribute improvements that benefit our product ecosystem.
## Overview
The LOKE Design System is built and maintained specifically for LOKE applications. Contributions from LOKE team members help ensure the system evolves with our product needs and maintains consistency across our ecosystem.
## Getting Started
### Repository Setup
1. Clone the repository:
```bash
git clone https://github.com/LOKE/design-system-beta
cd design-system-beta
```
2. Install dependencies:
```bash
bun install
```
3. Start the development environment:
```bash
bun dev
```
This will launch the documentation site where you can explore components, test your changes, and see live documentation updates.
## Development Workflow
### Branch Strategy
* `main`: The production branch containing the latest stable release
* `feature/*`: Feature branches for new components or significant changes
* `fix/*`: Branches for bug fixes
Always create a new branch from `main` when starting work on a new feature or fix:
```bash
git checkout main
git pull
git checkout -b feature/your-feature-name
```
### Creating Changesets
We use [changesets](https://github.com/changesets/changesets) to manage versioning and changelogs.
Before submitting a PR, create a changeset that describes your changes:
```bash
bun changeset
```
Follow the prompts to:
1. Select the package(s) you've modified
2. Choose the appropriate semver increment (patch, minor, major)
3. Write a description of your changes
This will create a markdown file in the `.changeset` directory that will be used to generate the changelog when the changes are released.
### Code Standards
The repository includes Biome and TypeScript configurations that enforce code standards. Run the linter before submitting your PR:
```bash
bun lint
```
To check TypeScript types:
```bash
bun check-types
```
### Component Development Guidelines
When creating or modifying components for LOKE products:
1. **Modular Structure**: Each component should be in its own directory
2. **TypeScript**: All components must be written in TypeScript for type safety
3. **Documentation**: Create comprehensive MDX documentation pages
4. **Accessibility**: Ensure all components meet WCAG 2.1 AA standards
5. **Testing**: Include relevant tests for your component
6. **Performance**: Optimize for real-world LOKE product usage patterns
7. **Brand Consistency**: Follow LOKE design principles and visual identity
### Folder Structure
Components should follow this folder structure:
```
packages/design-system/src/components/your-component/
├── index.ts # Exports from the component
├── YourComponent.tsx # Main component implementation
└── YourComponent.test.tsx # Component tests (if applicable)
```
Documentation should be added to the docs site:
```
apps/docs/src/content/docs/components/
└── your-component.mdx # Component documentation page
```
## Pull Request Process
1. **Create a PR**: Push your branch and create a pull request against `main`
2. **CI Checks**: Ensure all CI checks pass (linting, type checking, tests)
3. **Code Review**: Request review from team members
4. **Feedback**: Address any feedback from reviewers
5. **Approval**: Once approved, your PR will be merged by a maintainer
## Release Process
Releases are managed by the design system maintainers. The process generally follows these steps:
1. Changesets are collected from merged PRs
2. Maintainers run the release workflow which:
* Updates versions based on changesets
* Generates changelogs
* Publishes to the package registry
## Adding New Components
When adding a new component:
1. **Research**: Ensure the component is needed and not duplicating existing functionality
2. **Design Review**: Get design approval for the component
3. **Implementation**: Develop the component following our guidelines
4. **Documentation**: Create comprehensive documentation and stories
5. **Testing**: Thoroughly test the component, including accessibility tests
6. **Example Usage**: Include example usage in your PR description
### Component Documentation Template
Documentation for each component should include:
* Component purpose and use cases
* Props API documentation
* Examples of basic and advanced usage
* Accessibility considerations
* Any known limitations or caveats
## Updating Existing Components
When updating existing components:
1. **Backward Compatibility**: Consider the impact on existing usage
2. **Semver**: Follow semantic versioning guidelines
* **Patch**: Bug fixes and minor changes that don't affect the API
* **Minor**: New features that don't break existing functionality
* **Major**: Breaking changes to the component API
3. **Migration Guide**: For breaking changes, provide a migration guide
## Icons
To add new icons to the system:
1. Place the SVG file in the `src/icons/svg/{source}` directory
2. Run the icon generation script:
```bash
bun build:icons
```
3. This will generate the React component and update exports
Follow these guidelines for icon SVGs:
* Use a 24×24 viewBox
* Use simple paths with minimal points
* Use a consistent stroke width (typically 2px)
* Remove unnecessary metadata
## Styling Guidelines
* Use the built-in theme variables for colors
* Follow the spacing scale for margins and padding
* Use the Tailwind class naming convention
## Testing
Components should be tested for:
* **Functionality** — Core behaviors work as expected
* **Accessibility** — WCAG 2.1 AA compliance
* **Responsive behavior** — Works across LOKE product viewport sizes
* **Cross-browser compatibility** — Tested in browsers used by LOKE customers
* **Type safety** — TypeScript types are accurate and helpful
To run type checks:
```bash
bun check-types
```
To run linting:
```bash
bun lint
```
Always test your components in a real LOKE product environment when possible to ensure they work as expected in production.
## Documentation Best Practices
* Use clear, concise language
* Include examples for different use cases
* Document all props with types and descriptions
* Explain any non-obvious behaviors
* Provide accessibility information
## Troubleshooting
### Common Issues
1. **Development server not starting**: Try clearing caches and reinstalling dependencies
```bash
rm -rf node_modules .next
bun install
bun dev
```
2. **Type errors**: Ensure all packages are built and dependencies are up to date
```bash
bun run build
bun check-types
```
3. **Build errors**: Make sure all dependencies are properly installed
```bash
bun install
```
## Getting Help
If you need help contributing to the LOKE Design System:
* **Documentation** — Check existing documentation and component examples
* **Team** — Reach out to other LOKE engineers on Slack
* **Codebase** — Look for similar components or patterns in the repository
* **Design Team** — Consult with LOKE designers for visual and UX guidance
Questions about design decisions or component usage? The LOKE design team is here to help ensure consistency across our products.
## Conclusion
Thank you for contributing to the LOKE Design System! Your efforts help improve the quality and consistency of all LOKE products.
Remember:
* **This system serves LOKE products** — design decisions should align with LOKE's product needs
* **Quality over speed** — take time to ensure accessibility, performance, and maintainability
* **Documentation matters** — good docs help other LOKE developers use components correctly
* **Ask questions** — the team is here to help you contribute effectively
The design system is a living project that evolves with LOKE's needs. Your contributions shape the future of our product ecosystem.
# Design Principles
# Design Principles
This document outlines the core design principles that guide the LOKE Design System. These principles help maintain consistency, quality, and usability across all LOKE applications.
## Consistency
Consistency is key to providing a cohesive user experience across all LOKE products. This means using the same patterns, components, and styles throughout our applications.
### Guidelines
* Use design system components rather than creating custom variants
* Maintain consistent spacing using the design system's spacing scale
* Follow established patterns for similar interactions
* Use consistent terminology in the interface
### Examples
**Good:**
```jsx
// Using standard design system components
Transaction Details
```
## Modularity
Build complex interfaces from simple, reusable components. This approach makes our code more maintainable and allows for greater flexibility.
### Guidelines
* Compose complex UIs from simple components
* Keep components focused on a single responsibility
* Use layout components (`Box`, `Stack`, `Columns`) to structure content
* Avoid creating monolithic components with many responsibilities
### Examples
**Good:**
```jsx
User Profile
```
**Avoid:**
```jsx
```
## Accessibility
All LOKE interfaces must be accessible to all users, including those with disabilities. This isn't just a nice-to-have; it's an essential design requirement.
### Guidelines
* Ensure sufficient color contrast for text and interactive elements
* Provide text alternatives for non-text content
* Ensure keyboard navigability for all interactive elements
* Use semantic HTML and ARIA attributes correctly
* Test with screen readers and other assistive technologies
### Examples
**Good:**
```jsx
// Or using VisuallyHidden
```
**Avoid:**
```jsx
```
## Responsiveness
LOKE applications should work well on all device sizes and orientations. Our design system includes responsive capabilities built into its components.
### Guidelines
* Use responsive component props for adaptable layouts
* Test on different screen sizes including mobile and large displays
* Avoid fixed dimensions that might break on smaller screens
* Implement appropriate touch targets for mobile interfaces
### Examples
**Good:**
```jsx
Content 1Content 2Content 3Content 4
```
**Avoid:**
```jsx
Content 1Content 2Content 3Content 4
// This will be 4 columns on all screen sizes, which is problematic on mobile
```
## Performance
User interfaces should be fast and efficient, avoiding unnecessary complexity that might impact performance.
### Guidelines
* Import only the components and utilities you need
* Use memoization for expensive computations
* Avoid excessive re-renders by using appropriate hooks and patterns
* Consider code splitting for large applications
* Test performance on lower-end devices
### Examples
**Good:**
```jsx
// Import only what you need
import { Button } from '@loke/design-system/button';
import { Card } from '@loke/design-system/card';
```
**Avoid:**
```jsx
// Importing everything
import * as DesignSystem from '@loke/design-system';
// Using deeply nested destructuring that may prevent tree-shaking
const { Button, Card } = DesignSystem;
```
## Clarity
Interfaces should be clear and intuitive, helping users accomplish their goals without confusion.
### Guidelines
* Use clear, descriptive labels for interactive elements
* Provide helpful feedback for user actions
* Use appropriate visual hierarchy to guide user attention
* Balance simplicity and functionality
* Use consistent patterns for similar interactions
### Examples
**Good:**
```jsx
```
**Avoid:**
```jsx
;
{
isOpen && (
Settings
{/* Settings content */}
);
}
```
## Visual Hierarchy
Establish a clear visual hierarchy to guide users through the interface and highlight what's most important.
### Guidelines
* Use typography scale to indicate information hierarchy
* Apply whitespace strategically to group related elements
* Use color and contrast to direct attention
* Consider the reading flow when arranging elements
### Examples
**Good:**
```jsx
Quarterly ReportQ3 2023 Financial Results
${revenue.toLocaleString()}
Total RevenueKey MetricsNew Customers: {newCustomers}Retention Rate: {retentionRate}%
```
**Avoid:**
```jsx
Q3 2023 Financial Results
Quarterly Report
${revenue.toLocaleString()} Total Revenue
New Customers: {newCustomers}
Retention Rate: {retentionRate}%
```
## Feedback
Provide clear feedback to users to confirm their actions and communicate system status.
### Guidelines
* Indicate loading states with appropriate visual cues
* Confirm successful actions with feedback
* Show clear error messages when things go wrong
* Use appropriate animations to communicate state transitions
* Ensure feedback is accessible to all users
### Examples
**Good:**
```jsx
;
{
isSuccess && Form submitted successfully!;
}
{
error && (
Error{error.message}
);
}
```
**Avoid:**
```jsx
;
{
isSuccess &&
Success!
;
}
{
error &&
Error: Something went wrong.
;
}
```
## Conclusion
These design principles are not just guidelines—they represent LOKE's commitment to creating high-quality, user-friendly applications. By following these principles, we ensure that our products are consistent, accessible, and delightful to use.
When implementing interfaces with the LOKE Design System, regularly refer back to these principles to guide your decisions and maintain the high quality standards we strive for.
# Guides
# Guides
These guides cover integration, design language, best practices, and reference materials that apply across the design system. Whether you're getting started with Tailwind, learning our design principles, ensuring accessibility, or understanding our color system, you'll find what you need here.
***
## Setup & Integration
### Tailwind CSS
Learn how Tailwind CSS relates to the design system — what's pre-compiled and available without setup, when you might want to install Tailwind in your project, and how to configure it. Whether you're using the pre-compiled stylesheet or building your own Tailwind setup, this guide explains the trade-offs and shows you how to work effectively with both approaches.
***
## Design Language & Foundations
### Design Principles
The core principles that guide every decision in the LOKE Design System: consistency, modularity, accessibility, responsiveness, performance, clarity, visual hierarchy, and feedback. Read this to understand the *why* behind the system's design, and to ensure your interfaces align with LOKE's design philosophy. Includes good and bad examples for each principle.
### Color System
Explore the design system's semantic color tokens, usage guidelines, and interactive palette preview. Colors automatically adapt between light and dark modes. This guide explains how to choose colors by function (not appearance), access tokens via CSS custom properties or Tailwind classes, and maintain accessible contrast ratios throughout your interface.
### Brand
Visual identity assets and branding guidelines for LOKE — logos, wordmarks, and approved brand usage. Use this when you need official brand assets for marketing, product, or communication materials.
***
## Best Practices
### Accessibility Guide
Build interfaces that work for everyone, including people with disabilities. This guide covers keyboard navigation, screen reader support, color contrast, and testing strategies. Includes a practical checklist, common issues and fixes, and code examples showing accessible and inaccessible patterns for buttons, forms, images, and dialogs.
***
## Reference & Contribution
### Component Reference
Full API reference for all design system components. Look here when you need detailed prop documentation, examples, and advanced usage patterns for any component.
### Contribution Guide
Want to improve the design system? This guide covers the contribution workflow, code standards, testing requirements, and release process. Whether you're adding a new component, fixing a bug, or updating documentation, start here to understand how LOKE's design system is maintained and evolved.
# Contributing
import { Callout, Kbd } from '@/components/mdx';
# Contributing
This page covers deeper technical details about the LOKE Design System for contributors — including architecture concepts, theming, common patterns, and how to write documentation.
Looking to get started using the design system? See the [Quick Start](/docs) guide instead. This page is for contributors who need deeper context.
***
## Key concepts
* Individual imports
* Import only what you use to keep bundles small
* TypeScript‑first
* Rich types across components and utilities
* Tailwind‑based styling
* Class‑driven, utility‑first styling
* Accessibility baked in
* Sensible ARIA usage, keyboard navigation, visible focus
* Dark mode
* Fully themed, light and dark compatible
***
## Installation
Install the package in your app:
```bash
# bun (recommended)
bun add @loke/design-system
# npm
npm install @loke/design-system
```
For a step-by-step walkthrough including TypeScript configuration, see the [Quick Start Guide](/docs).
***
## Project setup
Ensure your `tsconfig.json` uses bundler module resolution:
```json
{
"compilerOptions": {
"module": "esnext",
"moduleResolution": "bundler"
}
}
```
Add the design system styles in your root (e.g. Next.js app layout or entry file):
```tsx
// app/layout.tsx or main entry
import '@loke/design-system/styles';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
That’s it — the system includes its CSS variables and Tailwind integration. You can begin importing components individually.
***
## Usage guidelines
### Import only what you need
```tsx
// Good: individual imports
import { Button } from '@loke/design-system/button';
import { Card, CardHeader, CardTitle, CardContent } from '@loke/design-system/card';
```
```tsx
// Example component usage (MDX or app code)
Card Title
Card content
```
Tips:
* Prefer individual imports: import {'{ Button }'} from '@loke/design-system/button'
* Compose primitives (e.g. Box, Stack, Columns) for consistent spacing and layout
* Keep accessibility in mind (labels, alt text, keyboard flows)
***
## Layout primitives
The system includes primitives to build consistent layouts:
```tsx
import { Box } from '@loke/design-system/box';
import { Stack } from '@loke/design-system/stack';
import { Columns, Column } from '@loke/design-system/columns';
function MyLayout() {
return (
Page Title
Column 1Column 2Column 3
);
}
```
***
## Icons
Use the included icon set for a consistent look:
```tsx
import { Search, ArrowRight } from '@loke/icons';
```
***
## Theming and colors
### Semantic tokens
The system ships a semantic color palette via CSS variables:
* \--primary / --primary-foreground
* \--secondary / --secondary-foreground
* \--background / --foreground
* \--card / --card-foreground
* \--muted / --muted-foreground
* \--accent / --accent-foreground
* \--destructive / --destructive-foreground
* \--border, --input, --ring
Use them via Tailwind tokens or directly with CSS vars:
```tsx
Card Content
```
```css
.my-element {
background: var(--accent);
color: var(--accent-foreground);
}
```
See the interactive palette and guidelines:
* Color System: /docs/brand/colors
### Dark mode
Enable dark mode by toggling the dark class on the root:
```tsx
function ThemeToggle() {
const [isDark, setIsDark] = React.useState(false);
React.useEffect(() => {
document.documentElement.classList.toggle('dark', isDark);
}, [isDark]);
return (
);
}
```
***
## Common patterns
### Forms
```tsx
import { Form, FormField, FormItem, FormLabel, FormControl } from '@loke/design-system/form';
import { Input } from '@loke/design-system/input';
import { Button } from '@loke/design-system/button';
function LoginForm() {
// Assume form setup with your favorite form library
return (
);
}
```
### Data display
```tsx
import {
Table,
TableHeader,
TableBody,
TableRow,
TableHead,
TableCell,
} from '@loke/design-system/table';
import { Badge } from '@loke/design-system/badge';
function DataTable({ data }: { data: { id: string; name: string; status: 'active' | 'inactive' }[] }) {
return (
);
}
```
***
## Accessibility
* Use semantic HTML and labeled controls
* Ensure sufficient color contrast
* Verify keyboard and screen reader flows
* Prefer component APIs over ad‑hoc markup
Read the full guide:
* Accessibility Guide: /docs/guides/accessibility
***
## Quick links for LOKE developers
* [Quick Start](/docs) — Get up and running fast
* [Tailwind CSS Guide](/docs/guides/tailwind) — How Tailwind relates to the design system
* [Color System](/docs/guides/colors) — LOKE brand colors and semantic tokens
* [Logo Guidelines](/docs/guides/brand/logos) — Official LOKE logo assets
* [Accessibility Guide](/docs/guides/accessibility) — Building inclusive experiences
* [Component Guide](/docs/guides/reference/component-guide) — Comprehensive component reference
***
## Tailwind CSS
The design system is built with Tailwind CSS, but you do **not** need to install Tailwind to use it. All styles are pre-compiled and included when you import `@loke/design-system/styles`.
If you're familiar with Tailwind, you can use utility classes alongside design system components — common classes like `p-4`, `flex`, `gap-4`, `bg-primary`, etc. are included in the pre-compiled stylesheet.
The layout components ([Box](/docs/design-system/layout/box), [Stack](/docs/design-system/layout/stack), [Columns](/docs/design-system/layout/columns)) provide equivalent functionality to common Tailwind layout patterns through a props-based API.
For full details, see the [Tailwind CSS Guide](/docs/guides/tailwind).
***
## Troubleshooting
* Styles not loading
* Ensure import '@loke/design-system/styles' is present in your root
* Dark mode not toggling
* Confirm the dark class is being added to html
* Type errors
* Verify you're importing the correct path for a component (individual import paths)
* "Cannot find module" errors
* Set moduleResolution: "bundler" in your `tsconfig.json`
***
## Writing documentation with MDX
This site uses custom components to enhance documentation. Here's what's available:
### Custom MDX components
You can use the following custom components inside MDX pages to keep content consistent and easy to scan.
### Callout
```tsx
This is an informational callout used to surface important context.
This indicates a successful action or a positive state.
This warns the reader about potential issues.
This highlights a critical problem or a blocking issue.
```
### Kbd
Use `` for keyboard keys or shortcuts.
Examples:
* Press Cmd + K to open search
* Take a screenshot with Shift + Cmd + 4
* Confirm with Enter and cancel with Esc
Variants:
* Default: Ctrl
* Small: Ctrl
* Outline: Ctrl
* Large: Ctrl
### TypeTable
Use TypeTable (from fumadocs-ui) to quickly document API props for a component.
```tsx
import { TypeTable } from 'fumadocs-ui/components/type-table';
) => void',
},
}}
/>
```
***
## Next steps for contributors
* [Contribution Guide](/docs/guides/contribution) — How to add or improve components
* Review the [Color System](/docs/guides/colors) and [Logo Guidelines](/docs/guides/brand/logos) to maintain LOKE brand consistency
* Use layout primitives ([Box](/docs/design-system/layout/box), [Stack](/docs/design-system/layout/stack), [Columns](/docs/design-system/layout/columns)) to establish consistent structure
* Reference the [Accessibility Guide](/docs/guides/accessibility) while building features to ensure all LOKE products are inclusive
* Check the [Component Guide](/docs/guides/reference/component-guide) to understand when to use each component
# Tailwind CSS
import { Callout, Kbd } from '@/components/mdx';
# Tailwind CSS
The LOKE Design System is built with [Tailwind CSS](https://tailwindcss.com) internally, but you **do not need to install Tailwind** to use the design system. All styles are pre-compiled and shipped as standard CSS.
This guide explains the relationship between Tailwind and the design system, and when you might want to set up Tailwind in your own project.
***
## Do I need Tailwind?
**No.** The design system works without Tailwind installed in your project. When you import the stylesheet:
```tsx
import "@loke/design-system/styles";
```
You get pre-compiled CSS that includes all component styles, color tokens, and a set of common utility classes. No build tools, PostCSS plugins, or Tailwind configuration needed.
The design system is plug-and-play. Install it, import the styles, and start using components. Tailwind is an implementation detail — not a requirement.
***
## What is Tailwind CSS?
If you've never used Tailwind before, here's the short version: Tailwind is a CSS framework that provides small, single-purpose CSS classes you apply directly in your HTML/JSX. Instead of writing CSS in a separate file, you compose styles using class names.
```tsx
// Traditional CSS approach
```
Each class does one thing: `p-4` sets padding, `bg-white` sets background color, `rounded-lg` sets border radius. You combine them to build up your styles.
Common patterns you'll see in examples:
| Class | What it does |
| ------------ | ---------------------------------------- |
| `p-4` | Padding on all sides (1rem) |
| `px-4` | Horizontal padding |
| `py-2` | Vertical padding |
| `m-4` | Margin on all sides |
| `mt-2` | Top margin |
| `flex` | Display flex |
| `gap-4` | Gap between flex/grid children |
| `w-full` | Width 100% |
| `text-sm` | Small text size |
| `bg-primary` | Background using the primary color token |
| `rounded-lg` | Rounded corners |
| `border` | 1px border |
For a full reference, see the [Tailwind CSS documentation](https://tailwindcss.com/docs).
***
## What ships with the design system
The pre-compiled stylesheet (`@loke/design-system/styles`) includes:
1. **All component styles** — everything needed for design system components to render correctly
2. **Theme tokens** — CSS custom properties for colors, radii, and animations that components use
3. **Common utility classes** — a subset of Tailwind utilities pre-compiled for convenience
The included utilities cover the most common layout and styling needs: spacing (`p-*`, `m-*`, `gap-*`), flexbox (`flex`, `items-center`, `justify-between`), sizing (`w-full`, `h-*`), grid (`grid`, `grid-cols-*`), positioning, borders, shadows, typography, and more.
This means you can use Tailwind-style classes in your own components without installing Tailwind:
```tsx
import { Button } from "@loke/design-system/button";
export function Header() {
return (
My App
);
}
```
The pre-compiled stylesheet includes utilities that the design system itself uses, plus a broad set of common classes. If you use a Tailwind class that isn't included, it simply won't have any effect. If you find yourself needing classes that aren't available, consider [setting up Tailwind in your project](#setting-up-tailwind-in-your-project).
***
## Layout components vs. Tailwind classes
The design system includes layout components like [Box](/docs/design-system/layout/box), [Stack](/docs/design-system/layout/stack), [Columns](/docs/design-system/layout/columns), and [Inline](/docs/design-system/layout/inline). These provide a props-based API for common layout patterns. If you're comfortable with Tailwind, you can achieve the same results with utility classes directly.
Here's how they compare:
### Vertical stack
```tsx
// Using the Stack component
import { Stack } from "@loke/design-system/stack";
Item 1
Item 2
Item 3
// Equivalent Tailwind classes
Item 1
Item 2
Item 3
```
### Horizontal row
```tsx
// Using the Inline component
import { Inline } from "@loke/design-system/inline";
LabelNew
// Equivalent Tailwind classes
LabelNew
```
### Grid columns
```tsx
// Using the Columns component
import { Columns } from "@loke/design-system/columns";
OneTwoThree
// Equivalent Tailwind classes
OneTwoThree
```
### Spacing and backgrounds
```tsx
// Using the Box component
import { Box } from "@loke/design-system/box";
Content
// Equivalent Tailwind classes
Content
```
### Responsive layout
The layout components support responsive values via arrays, where each value maps to a breakpoint (`[mobile, sm, md, lg]`):
```tsx
// Using Box with responsive props
Content
// Equivalent Tailwind classes
Content
```
### Which should I use?
Use whichever you prefer — both approaches are valid. Here are some considerations:
* **Layout components** are useful if you're not familiar with CSS/Tailwind, or if you want a more React-like API with type-checked props
* **Tailwind classes** give you more flexibility and are the standard approach if you're already comfortable with CSS
* **Mix and match** — you can use layout components for structure and Tailwind classes for fine-tuning, or vice versa. All components accept a `className` prop
***
## Using color tokens
The design system defines semantic color tokens as CSS custom properties. These are available as Tailwind color classes whether or not you have Tailwind installed in your project:
```tsx
// Background colors
Primary background
Secondary background
Card background
Muted background
Destructive background
// Text colors
Default text
Secondary text
Accent text
// Border colors
Default border
Primary border
```
These tokens automatically adapt for dark mode when the `dark` class is on the `` element. See the [Color System](/docs/guides/colors) page for the full palette.
***
## CSS custom properties
You can also use the design system's tokens directly in your own CSS via custom properties:
```css
.my-custom-element {
background: var(--card);
color: var(--card-foreground);
border: 1px solid var(--border);
border-radius: var(--radius);
}
```
Available tokens include:
* `--background` / `--foreground`
* `--card` / `--card-foreground`
* `--primary` / `--primary-foreground`
* `--secondary` / `--secondary-foreground`
* `--muted` / `--muted-foreground`
* `--accent` / `--accent-foreground`
* `--destructive` / `--destructive-foreground`
* `--border`, `--input`, `--ring`
* `--radius`
* `--brand-50` through `--brand-950`
***
## Setting up Tailwind in your project
If you need Tailwind utilities beyond what ships with the design system — for example, arbitrary values, additional responsive breakpoints, or classes that aren't pre-compiled — you can install Tailwind in your project.
### 1. Install Tailwind CSS
```bash
bun add -d tailwindcss @tailwindcss/postcss
```
### 2. Configure PostCSS
Create or update `postcss.config.mjs`:
```js
const config = {
plugins: {
"@tailwindcss/postcss": {},
},
};
export default config;
```
### 3. Set up your stylesheet
Replace the `import "@loke/design-system/styles"` import in your entry point with a custom CSS file that imports Tailwind and the design system's theme:
```css
/* globals.css */
@import "tailwindcss";
@import "@loke/design-system/styles/tailwind";
@plugin "tailwindcss-animate";
/* Scan the design system source so its classes are included */
@source "node_modules/@loke/design-system/dist";
@custom-variant dark (&:is(.dark *));
@layer base {
* {
@apply border-border outline-ring/50;
}
body {
@apply bg-background text-foreground;
}
}
```
Then import this file in your app entry instead:
```tsx
// app/layout.tsx
import "./globals.css";
```
The `@loke/design-system/styles/tailwind` import provides the theme configuration (color tokens, radii, animations) without the pre-compiled utilities. Tailwind will generate the utility classes itself based on what your code uses.
### 4. Install the animate plugin
If you use components that animate (like Accordion), install the animation plugin:
```bash
bun add -d tailwindcss-animate
```
***
## The `cn` utility
The design system exports a `cn` utility for merging class names. It combines [clsx](https://github.com/lukeed/clsx) (conditional classes) with [tailwind-merge](https://github.com/dcastil/tailwind-merge) (conflict resolution):
```tsx
import { cn } from "@loke/design-system/cn";
function MyComponent({ className, isActive }: { className?: string; isActive: boolean }) {
return (
Content
);
}
```
`cn` is useful when you want to:
* Conditionally apply classes
* Let consumers override styles via a `className` prop
* Resolve conflicting Tailwind classes (e.g., `cn("p-4", "p-2")` results in `"p-2"`)
See the [cn utility reference](/docs/ui/lib/cn) for details.
***
## Summary
| Question | Answer |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Do I need to install Tailwind? | No. The design system ships pre-compiled CSS. |
| Can I use Tailwind classes? | Yes. Common utility classes are included in the pre-compiled stylesheet. |
| Can I use layout components instead of Tailwind? | Yes. Box, Stack, Columns, and Inline provide equivalent functionality with a props API. |
| When should I install Tailwind myself? | When you need utilities beyond what's pre-compiled, or want full Tailwind in your project. |
| Do the color tokens work without Tailwind? | Yes. They're standard CSS custom properties. |
# AI Agent Skills (TanStack Intent)
# AI Agent Skills (TanStack Intent)
All three LOKE packages ship `SKILL.md` files via `@tanstack/intent`. These skills guide AI agents through common tasks — composing overlays, building forms, using icons, and more.
***
## 1. Run install
```bash
npx @tanstack/intent@latest install
```
This prints a skill — a prompt you paste into your AI agent. The skill instructs your agent to:
1. Check for existing `intent-skills` mappings in your config files (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, etc.)
2. Run `npx @tanstack/intent@latest list` to discover available skills from your installed packages
3. Scan your repository structure to understand your project
4. Propose relevant skill-to-task mappings based on your codebase patterns
5. Ask if you want a target other than `AGENTS.md`
6. Write or update an `intent-skills` block in your agent config
If an `intent-skills` block already exists, the agent updates that file in place. If none exists, `AGENTS.md` is the default target.
***
## 2. Use skills in your workflow
When your AI agent works on a task matching a skill mapping, it loads the corresponding `SKILL.md` into context automatically. This means agents can discover and apply best practices without manual prompting — they get domain-specific guidance tailored to the LOKE libraries directly in their context.
***
## 3. Keep skills up-to-date
Skills version with each package release. Updating a package brings updated skills — no manual action needed:
```bash
bun update @loke/design-system @loke/ui @loke/icons
```
To see what skills are available:
```bash
npx @tanstack/intent@latest list
```
To check for skills referencing outdated source docs:
```bash
npx @tanstack/intent@latest stale
```
***
## Available skills
### @loke/design-system skills
These skills cover all design system components and theming. Load paths: `node_modules/@loke/design-system/skills//SKILL.md`
| Skill | Covers |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `getting-started` | Install, Tailwind v4 config, stylesheet import, TooltipProvider setup |
| `forms` | Form components: Input, Select, Checkbox, RadioGroup, Switch, Textarea, Calendar, DatePicker |
| `display-components` | Alert, Badge, Avatar, Card, Heading, Text, Separator, Pagination, Skeleton |
| `data-tables` | Table component patterns and column configuration |
| `layout` | Box, Stack, Inline, Columns, MaxWidthWrapper, PageLayout, VisuallyHidden |
| `overlay-composition` | Dialog, Sheet, Popover, DropdownMenu, Command, Tooltip, Toast — "use client" boundaries |
| `interactive-components` | Accordion, Collapsible, Tabs, Sidebar |
| `theming` | CSS custom properties, dark mode, color token customization |
### @loke/ui skills
These skills cover headless primitives, utility functions, and hooks. Load paths: `node_modules/@loke/ui/skills//SKILL.md`
| Skill | Covers |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loke-ui` | Overview of all headless primitives and when to use @loke/ui vs @loke/design-system |
| `choosing-the-right-component` | Decision guide for picking the right primitive |
| `accordion` | Accordion primitive |
| `alert-dialog` | AlertDialog primitive |
| `checkbox` | Checkbox primitive |
| `collapsible` | Collapsible primitive |
| `command` | Command (combobox/search) primitive |
| `context-and-collection` | Context and Collection utilities |
| `dialog` | Dialog primitive |
| `dropdown-menu` | DropdownMenu and Menu primitives |
| `hooks` | useCallbackRef, useControllableState, useDirection, useEscapeKeydown, useId, useIsDocumentHidden, useIsHydrated, useLayoutEffect, useMobile, usePrevious, useSize |
| `label` | Label primitive |
| `overlay-infrastructure` | Portal, Presence, DismissableLayer, FocusGuards |
| `popover` | Popover primitive |
| `primitive-and-slot` | Primitive and Slot utilities |
| `radio-group` | RadioGroup primitive |
| `select` | Select primitive |
| `switch` | Switch primitive |
| `tabs` | Tabs primitive |
| `tooltip` | Tooltip primitive |
### @loke/icons skills
These skills cover icon discovery, usage, and customization. Load paths: `node_modules/@loke/icons/skills//SKILL.md`
| Skill | Covers |
| --------------------- | ------------------------------------------------- |
| `use-icons` | Importing and rendering icons in React |
| `find-icons` | Searching the icon catalog to find the right icon |
| `add-icons` | Adding new SVG icons to the library |
| `create-custom-icons` | Creating custom icon components |
# Contributing Icons
import { Callout, Kbd } from '@/components/mdx';
# Contributing Icons
The `@loke/icons` library contains 107 carefully crafted icons. New icons are generated from SVG source files using a build script. This guide walks you through the process of adding icons to the library.
Icons are auto-generated from SVG sources. Always run bun run gen after adding or updating SVGs.
***
## Step 1: Add your SVG
**Location:** `packages/icons/src/meta/`
**Naming convention:** Use PascalCase for SVG filenames (matching React component conventions).
Examples:
* `SearchIcon.svg`
* `ChevronUp.svg`
* `MailAlert.svg`
**SVG requirements:**
* Include a `viewBox` attribute (e.g., `viewBox="0 0 24 24"`)
* Prefer stroke-based designs for consistency with the icon library style
* Keep dimensions square (24×24 is standard)
* Simplify paths when possible
Example SVG structure:
```xml
```
***
## Step 2: Add metadata (optional)
Metadata helps organize, tag, and alias icons for search and filtering. Create a JSON file with the same base name as your SVG.
**Location:** `packages/icons/src/meta/.json`
**Schema:**
```json
{
"tags": ["keyword1", "keyword2", "keyword3"],
"categories": ["ui", "navigation", "commerce"],
"aliases": [
{
"name": "AlternativeName"
},
{
"name": "OldName",
"deprecated": true,
"deprecationReason": "Use SearchIcon instead",
"toBeRemovedInVersion": "2.0.0"
}
]
}
```
**Fields:**
| Field | Type | Description |
| ------------ | ---------- | ----------------------------------------------------------------------------- |
| `tags` | `string[]` | Keywords for searching/filtering (e.g., "search", "find", "magnifying-glass") |
| `categories` | `string[]` | Icon categories for organization (see available categories below) |
| `aliases` | `object[]` | Alternative import names (optional, useful for backward compatibility) |
**Available categories:**
* `ui` — General UI elements (menu, checkbox, button, etc.)
* `navigation` — Navigation-related (arrows, chevrons, etc.)
* `commerce` — Commerce-related (cart, payment, discount, etc.)
* `notifications` — Alerts, bells, messages
* `media` — Images, video, play, pause
* `arrows` — Directional arrows
* `social` — Social media
* `finance` — Money, currency, dollar signs
* `time` — Clock, calendar, schedule
* `user` — User profiles, people
* And 27 more...
**Example metadata file:**
```json
{
"tags": ["search", "find", "magnifying glass", "lookup"],
"categories": ["ui", "navigation"],
"aliases": [
{
"name": "SearchIcon"
},
{
"name": "Magnifier",
"deprecated": true,
"deprecationReason": "Use Search instead",
"toBeRemovedInVersion": "1.5.0"
}
]
}
```
***
## Step 3: Generate icons
After adding SVG and metadata files, run the generation script:
```bash
cd packages/icons
bun run gen
```
This script will:
1. Parse all SVG files in `src/meta/`
2. Convert SVG paths to React component format
3. Generate TypeScript components in `src/icons/` (kebab-case filenames)
4. Create or update metadata JSON files if missing
5. Regenerate `src/loke-icons.ts` (exports all icons)
6. Regenerate `src/aliases.ts` (exports aliases)
7. Regenerate `src/index.ts` (main entry point)
8. Format all files with Biome
***
## Step 4: Build and verify
Compile the package for distribution:
```bash
cd packages/icons
bun run build
```
This generates the `dist/` folder with compiled JavaScript and TypeScript declarations.
Verify the icon appears in documentation and can be imported:
```tsx
import { Search } from '@loke/icons';
function App() {
return ;
}
```
***
## Step 5: Commit
Commit all generated and source files together:
```bash
git add packages/icons/src/meta/*.svg
git add packages/icons/src/meta/*.json
git add packages/icons/src/icons/
git add packages/icons/src/loke-icons.ts
git add packages/icons/src/aliases.ts
git add packages/icons/src/index.ts
git commit -m "feat(icons): add Search icon"
```
Always commit the generated files alongside source SVGs. The generated components are part of the published package.
***
## Icon metadata schema (detailed)
### Tags
Keywords that describe the icon. Use common synonyms:
```json
{
"tags": [
"search",
"find",
"magnifying glass",
"lookup",
"query",
"filter"
]
}
```
### Categories
Assign icons to one or more of 37 categories for organization:
```json
{
"categories": ["ui", "navigation"]
}
```
### Aliases
Define alternative names for the icon (useful for backward compatibility or multiple naming conventions):
```json
{
"aliases": [
{
"name": "SearchIcon"
},
{
"name": "Magnifier",
"deprecated": true,
"deprecationReason": "Use Search instead",
"toBeRemovedInVersion": "2.0.0"
}
]
}
```
**Alias properties:**
| Property | Type | Description |
| ---------------------- | --------- | --------------------------------------------- |
| `name` | `string` | Alternative import name |
| `deprecated` | `boolean` | Mark as deprecated (optional) |
| `deprecationReason` | `string` | Reason for deprecation (optional) |
| `toBeRemovedInVersion` | `string` | Version when alias will be removed (optional) |
***
## Workflow example
1. **Add SVG:**
```
packages/icons/src/meta/NotificationBell.svg
```
2. **Add metadata:**
```
packages/icons/src/meta/notification-bell.json
{
"tags": ["alert", "notification", "bell", "sound"],
"categories": ["notifications", "ui"],
"aliases": [
{ "name": "BellAlert" }
]
}
```
3. **Generate:**
```bash
cd packages/icons && bun run gen
```
4. **Build:**
```bash
bun run build
```
5. **Verify:**
```tsx
import { NotificationBell, BellAlert } from '@loke/icons';
```
6. **Commit:**
```bash
git add packages/icons/
git commit -m "feat(icons): add NotificationBell icon"
```
***
## Best practices
* **Consistent style:** Match the stroke width, roundness, and visual weight of existing icons
* **Descriptive names:** Use clear, descriptive names that indicate what the icon represents
* **Good tags:** Add 3-5 relevant keywords for discoverability
* **Test imports:** Verify the icon can be imported after generation
* **SVG optimization:** Keep SVG files clean and minimal; complex shapes should be simplified
* **Aliases for variants:** If you have multiple similar icons, use aliases to provide alternative names
***
## Troubleshooting
**Icon isn't appearing after gen:**
* Verify the SVG filename uses PascalCase
* Check that `src/meta/` contains the SVG file
* Run `bun run gen` again
* Check for build errors in the console
**Import path is wrong:**
* The generated component name is kebab-case version of the filename
* Example: `SearchIcon.svg` → `import { SearchIcon } from '@loke/icons'`
**Metadata not generated:**
* Metadata JSON files are optional; if missing, `gen` creates a basic one
* You can manually edit metadata after generation
**Build fails:**
* Run `bun run lint` to check for syntax errors
* Verify SVG is valid XML
* Check that all SVGs have `viewBox` attributes
***
## Resources
* **Icon library:** [@loke/icons on npm](https://www.npmjs.com/package/@loke/icons)
* **Source code:** `packages/icons/` in the monorepo
* **Build script:** `packages/icons/gen.ts`
* **Documentation:** `packages/icons/README.md`
# Icon Gallery
import { IconGalleryServer } from '@/components/icons/icon-gallery-server';
Browse all icons from the `@loke/icons` package. Click any icon to copy its import statement.
# Icons
import { Callout } from '@/components/mdx';
# Icons
**@loke/icons** is a curated collection of 110+ icons designed as React components. Built to pair seamlessly with the LOKE Design System, each icon supports customizable size, color, and stroke width — letting you adapt them for any context. Icons are exported individually for optimal tree-shaking, and many have aliases for common naming conventions.
[Browse the Icon Gallery →](/docs/icons/gallery) to search and preview all available icons.
***
## Installation
```bash
bun add @loke/icons
```
***
## Usage
Import icons individually for optimal tree-shaking:
```tsx
import { SearchIcon, UserIcon, SettingsIcon } from "@loke/icons";
function Example() {
return (
);
}
```
***
## Props
All icons accept the following props:
| Prop | Type | Default | Description |
| --------------------- | ------------------ | -------------- | --------------------------------------------- |
| `size` | `number \| string` | `24` | Width and height of the icon |
| `color` | `string` | `currentColor` | Stroke color of the icon |
| `strokeWidth` | `number` | `2` | Width of the icon strokes |
| `absoluteStrokeWidth` | `boolean` | `false` | Keep stroke width absolute regardless of size |
Icons also accept all standard SVG attributes.
***
## Aliases
Many icons have aliases that match common naming conventions. For example:
```tsx
// These are equivalent
import { SearchIcon } from "@loke/icons";
import { Search } from "@loke/icons";
// Material-style aliases
import { Person } from "@loke/icons"; // Alias for UserIcon
import { Delete } from "@loke/icons"; // Alias for TrashIcon
import { Home } from "@loke/icons"; // Alias for HouseIcon
```
***
## Best Practices
* Use semantic icon names that match their purpose (e.g., `TrashIcon` for delete actions)
* Maintain consistent icon sizes within the same context
* Ensure sufficient color contrast for accessibility
* Use `aria-label` or `aria-hidden` for accessibility when icons convey meaning
* Prefer individual imports over importing the entire library
***
## Accessibility
When using icons, consider accessibility:
```tsx
// Decorative icon (hidden from screen readers)
// Icon with meaning (provide label)
// Icon with visible text
```
***
## Icon Gallery
[View the full Icon Gallery →](/docs/icons/gallery) to browse all available icons with:
* **Search** by name, alias, or tag
* **Filter** by category
* **Customize** color, size, and stroke width
* **Copy** import statements with a single click
***
## Contributing
Want to add a new icon? See the [Contributing guide](/docs/icons/contributing).
# @loke/ui
import Link from 'fumadocs-core/link';
import { Callout } from '@/components/mdx';
# @loke/ui
`@loke/ui` is a comprehensive toolkit of unstyled, accessible React components and utilities that power the LOKE Design System. It provides the behavior and accessibility foundation without any visual opinions, giving you complete control over styling and design.
Use `@loke/ui` when you need low-level control over appearance, are building highly specialized components, or want to avoid design-system dependencies in utility libraries.
## Philosophy
* **Headless**: Components provide behavior and accessibility; you bring the styles.
* **Accessible by default**: Every primitive follows WAI-ARIA patterns, includes full keyboard support, and is tested with screen readers.
* **Framework-agnostic utilities**: Hooks and lib utilities work anywhere React is used, not just within design-system components.
* **Composable**: Build complex widgets by combining simpler primitives and utilities.
* **Typed**: Full TypeScript support with predictable, documented APIs.
## When to use @loke/ui vs @loke/design-system
| Scenario | Use @loke/design-system | Use @loke/ui |
| ------------------------------------------------------------- | ----------------------- | ------------ |
| Building a standard button, card, or input | ✓ | — |
| Need pre-made, consistent styling | ✓ | — |
| Building a standard form | ✓ | — |
| Need complete styling control | — | ✓ |
| Building a specialized component (rich editor, custom select) | — | ✓ |
| Avoiding design-system dependencies | — | ✓ |
| Learning or prototyping interaction patterns | — | ✓ |
When in doubt, start with `@loke/design-system`. Use primitives when you have a specific reason to customize.
## What's included
### Primitives
26 unstyled, accessible headless components that form the foundation of `@loke/design-system`. Components like Dialog, Popover, Accordion, Tabs, and others provide complete behavior and accessibility with zero styling assumptions.
**Use when**: You need custom styling, building specialized components, or want to understand how the design system components work.
### Hooks
Small, focused React hooks for common UI patterns: state management (controlled/uncontrolled), DOM measurement, keyboard handling, environment detection, and accessibility. Hooks can be used independently from primitives.
**Use when**: Building custom components, need a specific behavior pattern, or integrating with your own UI framework.
### Lib
Framework-agnostic utility functions and low-level primitives for building accessible components: context creation, event composition, ref composition, DOM measurement, focus management, dismissable layers, and number utilities.
**Use when**: Building component libraries, need fine-grained control over interactions, or want reusable utilities for complex widgets.
## Install
```bash
bun add @loke/ui
```
## Import patterns
Import from granular entry points for best tree-shaking:
```tsx
// Primitives
import { Dialog, DialogTrigger, DialogContent } from '@loke/ui/dialog';
import { Accordion, AccordionItem, AccordionTrigger } from '@loke/ui/accordion';
// Hooks
import { useControllableState } from '@loke/ui/use-controllable-state';
import { useMobile } from '@loke/ui/use-mobile';
// Lib
import { createContext } from '@loke/ui/context';
import { composeRefs } from '@loke/ui/compose-refs';
```
Never import from the package root; use specific subpaths.
**Design System Components**: If you want pre-styled, ready-to-use components, see [@loke/design-system](/docs/design-system). Those components are built on top of these primitives and handle all the styling for you.
## Where to start
* **Building a custom component?** Start with Primitives to understand what's available and how components compose.
* **Need a specific behavior?** Check Hooks for state management, keyboard handling, or environment detection.
* **Building a component library?** Explore Lib utilities for context, event composition, and DOM utilities.
# Avatar
import { Callout, Kbd } from '@/components/mdx';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { User } from '@loke/icons';
import { DefaultAvatarExample, FallbackAvatarExample, SizesAvatarExample, DelayedFallbackAvatarExample, GroupAvatarExample, GroupSizesAvatarExample, BadgeAvatarExample, IconFallbackAvatarExample, CustomColorsAvatarExample, ErrorHandlingAvatarExample, NonCircularAvatarExample } from '@/components/examples/components/avatar';
# Avatar
The Avatar component displays a user's profile image with graceful fallbacks. It intelligently handles image loading states and shows a fallback (like initials or an icon) when the image is missing or fails to load.
Use Avatar anywhere you need a compact representation of a user or entity (navigation bars, lists, comments, menus). Provide meaningful alt text, and always include a fallback.
***
## Features
* Three built-in sizes via the size prop: `sm` (24px), `default` (32px), `lg` (40px)
* Intelligent image loading with automatic fallback display
* Optional delay for fallback to prevent flicker
* AvatarBadge for status indicators that scale with the avatar size
* AvatarGroup and AvatarGroupCount for overlapping avatar stacks
* Accessible semantics and best practices
* Works with text initials or icons as fallback
***
## Usage
```tsx
import {
Avatar,
AvatarImage,
AvatarFallback,
AvatarBadge,
AvatarGroup,
AvatarGroupCount,
} from '@loke/design-system/avatar';
export default function Example() {
return (
JD
);
}
```
Tips:
* Use the size prop (`sm`, `default`, `lg`) for standard sizes
* Use initials or an icon for the fallback; consider delayMs to reduce flicker
* Ensure alt text clearly describes the represented user or entity
***
## Props
### Avatar
### AvatarImage
void',
},
'referrerPolicy / crossOrigin': {
description: 'Standard image loading attributes.',
type: 'string',
},
'className / style': {
description: 'Styling hooks for the image.',
type: 'string | React.CSSProperties',
},
}}
/>
### AvatarFallback
### AvatarBadge
A small status indicator positioned at the bottom-right of the avatar. Scales automatically with the avatar's size prop.
### AvatarGroup
A container that arranges child avatars in an overlapping stack. Automatically adds a ring to each avatar for visual separation.
### AvatarGroupCount
A count indicator for avatar groups (e.g., "+3 more"). Automatically matches the size of sibling avatars.
***
## Examples
### Default
```tsx
CN
```
### With fallback (invalid image)
```tsx
JD
```
### Sizes
Use the `size` prop instead of custom width/height classes.
```tsx
………
```
### Delayed fallback
```tsx
Appears after 600ms
```
### Badge
Add AvatarBadge inside an Avatar to show a status indicator. At `lg` size, the badge can display an icon.
```tsx
CNCN
```
### Group / Stack
Use AvatarGroup to stack avatars with overlap and AvatarGroupCount for the overflow count.
```tsx
CN……+3
```
### Group sizes
AvatarGroupCount automatically matches the size of sibling avatars.
```tsx
CNJD+2CNJD+2
```
### Icon fallback
```tsx
```
### Custom colors
```tsx
ABCDEFGH
```
### Error handling
```tsx
MissingMissing image source
404Invalid image URL
```
### Non-circular avatars
```tsx
CN
```
***
## Accessibility
* Provide meaningful alt text that identifies the person or entity
* Ensure fallback content is legible and meets contrast guidelines
* Avatars are typically decorative, but when used as buttons/links, add appropriate ARIA labels
* AvatarBadge is purely visual; pair it with a text label or tooltip if the status must be conveyed to screen readers
***
## Best practices
* Always include AvatarFallback for reliability
* Use short, recognizable initials or a clear icon for the fallback
* Prefer the size prop over custom width/height classes for consistency
* Use AvatarGroup instead of manually building overlapping layouts
* Prefer a slight fallback delay to reduce flicker for fast connections
* Keep shapes consistent (circular or rounded) within the same UI context
# Card
import { Callout } from '@/components/mdx';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { BasicCardExample, CardWithHeaderFooterExample, CardVariantsExample, InteractiveCardExample } from '@/components/examples/components/card';
# Card
The Card component provides a flexible container for grouping and displaying related content. It supports headers, descriptions, content areas, and footers, making it ideal for dashboards, product listings, and content previews.
Cards are compositional — use `Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, and `Card.Footer` to build your layout.
***
## Features
* Compositional API with separate header, content, and footer components
* Built-in title and description styling
* Consistent border, shadow, and spacing
* Flexible content area for any child components
* Customizable via className props
* Works well with other design system components
***
## Usage
```tsx
import {
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
CardFooter,
} from '@loke/design-system/card';
export default function Example() {
return (
Card TitleCard description goes here.
Your content goes here.
);
}
```
Tips:
* Use `CardHeader` with `CardTitle` and `CardDescription` for consistent heading styles.
* `CardContent` provides proper padding for your main content.
* `CardFooter` is ideal for action buttons or metadata.
***
## Props
### Card
### CardHeader
### CardTitle
### CardDescription
### CardContent
### CardFooter
***
## Examples
### Basic card
```tsx
NotificationsYou have 3 unread messages.
Check your inbox for new updates.
```
### Card with header and footer
```tsx
Create projectDeploy your new project in one-click.
```
### Card variants
```tsx
```
***
## Accessibility
* Cards use semantic HTML structure with proper heading hierarchy.
* Use appropriate heading levels (`h2`, `h3`, etc.) within `CardTitle` for screen reader navigation.
* When cards are interactive, ensure they have proper focus states and click handlers.
* Consider using `asChild` with a link element for navigational cards.
***
## Best practices
* Use consistent card layouts within the same context (e.g., all dashboard cards).
* Keep card titles concise and descriptive.
* Use `CardDescription` for supplementary information, not critical content.
* Group related actions in `CardFooter`.
* Consider responsive behavior — cards often need different sizes on mobile vs desktop.
* Don't overload cards with too much content; they should be scannable.
# Heading
import { Callout, Kbd } from '@/components/mdx';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { HeadingVariantsExample, HeadingColorsExample, HeadingSemanticExample, HeadingResponsiveExample } from '@/components/examples/components/heading';
# Heading
The Heading component provides semantic headings with consistent typography and easy-to-use variants. It automatically maps variants to appropriate HTML tags while allowing customization.
When no variant is specified, the Heading uses the semantic level (h1-h6) to determine styling.
***
## Features
* Semantic heading levels (h1-h6)
* Special purpose variants (display, title, subtitle, section)
* Color customization
* Responsive variant support
* Automatic tag inference from variant
* Custom tag override with `as` prop
***
## Usage
```tsx
import { Heading } from '@loke/design-system/heading';
export default function Example() {
return (
Page TitleSubtitle hereSection Heading
);
}
```
Tips:
* Use semantic heading levels for proper document outline.
* The `variant` prop controls visual appearance, `as` controls the HTML tag.
* When `variant` matches a heading level (h1-h6), the tag is inferred automatically.
***
## Props
***
## Variants
### Heading Levels
| Variant | Size | Weight | Usage |
| ------- | ---- | ---------- | --------------- |
| `h1` | 4xl | Extra Bold | Main page title |
| `h2` | 3xl | Bold | Major sections |
| `h3` | 2xl | Semibold | Subsections |
| `h4` | xl | Semibold | Minor sections |
| `h5` | lg | Medium | Group headings |
| `h6` | base | Medium | Small headings |
### Special Variants
| Variant | Size | Weight | Usage |
| ---------- | ---- | ---------- | ----------------- |
| `display` | 5xl | Extra Bold | Hero sections |
| `title` | 4xl | Bold | Feature titles |
| `subtitle` | 2xl | Medium | Supporting titles |
| `section` | xl | Semibold | Section labels |
***
## Examples
### Heading variants
```tsx
Display HeadingHeading 1Heading 2Heading 3Heading 4TitleSubtitleSection
```
### Color variants
```tsx
ForegroundPrimarySecondaryNeutral 500
```
### Semantic structure
```tsx
Article TitleArticle SubtitleFirst Section
Content for the first section...
Subsection
More detailed content...
```
### Custom tag with variant
```tsx
{/* Use h2 tag but display variant styling */}
Hero Section Title
{/* Use h3 tag but section variant styling */}
Sidebar Section
```
***
## Accessibility
* Uses semantic heading tags (h1-h6) for proper document outline.
* Maintains heading hierarchy for screen reader navigation.
* Color variants ensure sufficient contrast ratios.
* Supports custom tags for visual flexibility without breaking semantics.
***
## Best practices
* Maintain proper heading hierarchy (h1 → h2 → h3, etc.).
* Use only one h1 per page for the main title.
* Choose variants based on visual hierarchy, tags based on document structure.
* Use special variants (display, title) for marketing/hero sections.
* Use section variant for sidebar or secondary navigation headings.
* Consider responsive variants for different screen sizes.
# Data & Display
import Link from "fumadocs-core/link";
# Data & Display
Data and display components help you structure, present, and format information clearly. These include layout containers, data tables, typography, and supporting elements for user profiles and pagination.
## Layout containers
Use Card as a versatile container for grouping related content—dashboards, product listings, or detailed views. Cards have a composable API with header, content, and footer sections, making them flexible for various layouts. Cards provide consistent padding, borders, and shadows, and they're ideal for creating scannable information hierarchies.
## Data display
Use Table when displaying structured, tabular data (lists of users, transactions, reports). Tables use semantic HTML (`
`, ``, ``) and are fully keyboard accessible. Pair with Pagination for navigating large datasets, showing page controls and allowing users to jump between sections.
## Typography
Use Heading and Text for consistent typography styling. Headings create visual hierarchy and aid screen reader navigation. Text components handle body copy, captions, and secondary information with appropriate sizing and color.
## Supporting elements
Use Avatar to display user profile images with automatic fallback initials when images aren't available. Avatars work well in cards, comments, team displays, and user lists.
Use Separator as a subtle visual divider between sections, groups of items, or content areas. Separators improve scanability without being visually heavy.
## Components
| Component | Purpose | Context | Example |
| -------------------------------------------------------------------------- | ----------------------------- | ------------------------------------- | ------------------------------------ |
| Card | Container for grouped content | Layouts, dashboards, product listings | Dashboard metrics, user profiles |
| Table | Structured data grid | Lists, reports, comparisons | Transaction history, user directory |
| Pagination | Navigate through pages | Large datasets | 100+ item lists, search results |
| Heading | Section titles with hierarchy | Page structure, visual hierarchy | Page titles, section headings |
| Text | Body copy and captions | All text content | Descriptions, metadata, labels |
| Avatar | User profile images | User displays, comments, lists | Team member photos, profile pictures |
| Separator | Visual divider | Content organization | Between sections, within lists |
## Quick decision tree
* **Displaying a group of related info (stats, article, user profile)?** → Card
* **Showing structured data rows and columns?** → Table
* **Navigating a large dataset?** → Pagination
* **Titles that structure the page hierarchy?** → Heading
* **Body text, descriptions, metadata?** → Text
* **User profile picture with fallback?** → Avatar
* **Visual separation between sections?** → Separator
# Pagination
import { Callout, Kbd } from '@/components/mdx';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { BasicPaginationExample, PaginationWithEllipsisExample, PaginationDisabledExample } from '@/components/examples/components/pagination';
# Pagination
The Pagination component provides navigation controls for content split across multiple pages. It includes previous/next buttons, page number links, and ellipsis for large page ranges.
Pagination is a composable component. Combine the subcomponents to build your desired pagination UI.
***
## Features
* Previous and next navigation buttons
* Individual page number links
* Ellipsis for large page ranges
* Active page indicator
* Disabled state support
* Accessible navigation landmark
***
## Usage
```tsx
import {
Pagination,
PaginationContent,
PaginationItem,
PaginationLink,
PaginationPrevious,
PaginationNext,
PaginationEllipsis,
} from '@loke/design-system/pagination';
export default function Example() {
return (
123
);
}
```
Tips:
* Use `isActive` to highlight the current page.
* Use `PaginationEllipsis` for gaps in page numbers.
* Disable buttons when on first/last page.
***
## Components
### Pagination
The root container. Uses `
// Good: SVG icon with title for assistive tech
// Avoid: Image without alt text
// Good: Decorative image marked as such
// Good: SVG icon with title for assistive tech
// Avoid: Image without alt text
// Fix