Lattice: Kognitos Design System

A comprehensive, production-ready design system built on top of shadcn/ui with seamless Tailwind CSS integration, TypeScript support, and Figma plugin compatibility.

🎯 Philosophy

Use components, not custom styling. This design system provides a complete set of pre-built, accessible components that follow consistent design patterns. Avoid creating custom CSS, inline styles, or hardcoded values - leverage the existing component library, Tailwind utility classes, and design tokens instead.

Why avoid inline styles?

• ❌ Theme Breaking: Inline styles don't respond to theme changes
• ❌ Maintenance Nightmare: Hard to update across multiple components
• ❌ Design Inconsistency: Bypasses the design system's consistency rules
• ❌ Performance Issues: Inline styles can't be optimized by CSS engines
• ❌ Accessibility: May not respect user preferences and accessibility settings

🚀 Quick Start

import { Button, Card, Input } from '@kognitos/lattice';

function MyComponent() {
  return (
    <Card>
      <Input placeholder="Enter your name" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}

📚 Documentation

• Contributing Guide - How to add components, test, and publish
• Storybook - Interactive component examples and documentation
• shadcn/ui Docs - Base component documentation and examples

🎨 Design Tokens

Our design system uses CSS custom properties (variables) as the single source of truth for all design tokens. This approach provides:

• Type Safety: Full TypeScript support with autocomplete
• Runtime Flexibility: Dynamic theme switching
• Figma Integration: Seamless sync with design tools
• Performance: CSS variables are optimized for rendering

Color System

import { ds } from '@kognitos/lattice';

// Use semantic color tokens (recommended)
const primaryColor = ds.color('primary'); // Returns "var(--primary)"

// Available semantic colors:
// - primary, secondary, accent
// - background, foreground, card
// - border, input, ring
// - destructive, muted
// - chart-1 through chart-5
// - sidebar variants

// For typography, use the Title and Text components instead:
import { Title, Text } from '@kognitos/lattice';
<Title level={1}>Heading</Title>
<Text level="xs">Body text</Text>

Theme Management

The design system supports automatic light/dark theme switching with system preference detection:

import { useTheme, ModeToggle } from '@kognitos/lattice';

function App() {
  const { theme, setTheme } = useTheme();

  return (
    <div>
      <ModeToggle />
      <p>Current theme: {theme}</p>
    </div>
  );
}

🌓 Theme System

Our theme system is built on CSS custom properties that automatically switch between light and dark values based on the .dark class on the document root.

How It Works

1. CSS Variables: All colors are defined as CSS custom properties in theme.css
2. Theme Classes: The .dark class on :root switches all variable values
3. Automatic Switching: Components automatically adapt to theme changes
4. System Preference: Automatically detects and applies user's system preference

:root {
  --primary: oklch(0.205 0 0);
  --background: oklch(1 0 0);
  /* ... other light theme values */
}

.dark {
  --primary: oklch(0.922 0 0);
  --background: oklch(0.145 0 0);
  /* ... other dark theme values */
}

Adding New Theme Colors

1. Confirm with the design team that the new color is needed
2. Add the CSS variable to both :root and .dark in theme.css
3. Add the TypeScript token to tokens/colors.ts
4. Use the token in your components

Getting CSS Variable Values

For cases where you need to access the computed value of CSS variables in JavaScript, use the getTokenValue function:

import { getTokenValue } from '@kognitos/lattice';

// Get the computed value of a CSS variable
const shadowValue = getTokenValue('--shadow-xl');
const primaryColor = getTokenValue('--primary');

// Works with or without -- prefix
const accentColor = getTokenValue('accent-foreground');

console.log('Shadow XL:', shadowValue);
console.log('Primary Color:', primaryColor);

Note: This function is useful for advanced use cases like:

• Dynamic calculations based on theme values
• Third-party library integration
• Custom animations that need theme-aware values

For most styling needs, prefer using Tailwind classes and pre-built components instead of accessing CSS variables directly.

Getting Color Token References

For cases where you need the CSS variable reference (not the computed value), use the design system's ds.color() method:

import { ds } from '@kognitos/lattice';

// Get CSS variable reference (returns "var(--primary)")
const primaryColor = ds.color('primary'); // Returns "var(--primary)"
const secondaryColor = ds.color('secondary'); // Returns "var(--secondary)"
const accentColor = ds.color('accent-foreground'); // Returns "var(--accent-foreground)"

// These CSS variable references are resolved by Tailwind and can be used as values
const customStyle = {
  backgroundColor: ds.color('primary'),
  color: ds.color('primary-foreground'),
  borderColor: ds.color('border'),
};

Note: This method returns CSS variable references (e.g., "var(--primary)") that are automatically resolved by Tailwind CSS. These can be used as values in inline styles, CSS-in-JS, or anywhere you need theme-aware color values. Use getTokenValue() if you need the actual computed color value for JavaScript calculations.

📱 Responsive Design

All components are built with responsive design in mind:

• Mobile-first approach: Components work seamlessly on all screen sizes
• Flexible layouts: Use Tailwind's responsive utilities
• Touch-friendly: Proper touch targets and spacing
• Accessible: WCAG compliant with proper ARIA attributes

Responsive Utilities

import { useIsMobile } from '@kognitos/lattice';

function ResponsiveComponent() {
  const isMobile = useIsMobile();

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
      {/* Content adapts to screen size */}
    </div>
  );
}

🎨 Figma Integration

We use the shadcn/ui Figma plugin to maintain perfect synchronization between design and code:

Workflow

1. Design in Figma: Create and refine components in Figma
2. Plugin Sync: Use the shadcn/ui plugin to sync design tokens
3. Code Updates: CSS variables automatically update in theme.css
4. Type Safety: TypeScript types are automatically generated
5. Component Updates: Components automatically use the new tokens

Updating theme.css

📖 See UPDATE_THEME_CSS.md for detailed instructions on how to update the src/theme.css file using the Figma Shadcn plugin.

The guide covers:

• Step-by-step process for syncing design tokens
• OKLCH color system verification
• Change verification and testing
• Common issues and solutions

Benefits

• Single Source of Truth: Figma is the authoritative design source
• Automatic Sync: No manual token management required
• Design-Code Parity: Perfect alignment between design and implementation
• Version Control: Track design changes alongside code changes
• OKLCH Color System: Modern, perceptually uniform color space

🧩 Component Library

Our component library includes:

Layout & Structure

• Card, AspectRatio, Separator, Skeleton, ResizablePanelGroup, ResizablePanel, ResizableHandle

Typography

• Title, Text with semantic levels and variants

Navigation

• Breadcrumb, NavigationMenu, Pagination, Sidebar, Tabs

General

• Button

Data Display

• Avatar, Badge, Calendar, DatePicker, Chart, Progress, Table

Data Entry

• Input, DatePicker, InputOTP, Select, Checkbox, RadioGroup, Switch, Slider, Textarea, Toggle, ToggleGroup, Form components

Feedback

• Alert, AlertDialog, Toaster

Overlays

• Dialog, Drawer, Popover, Tooltip, DropdownMenu, ContextMenu, HoverCard, Sheet

Interactive

• Accordion, Carousel, Collapsible, Command, Combobox, MultiCombobox

Menus & Navigation

• Menubar, ScrollArea, ScrollBar

Advanced Components

• Collapsible - Collapsible content sections
• Command - Command palette and search interface
• Combobox - Searchable select dropdown
• MultiCombobox - Multi-select searchable dropdown
• InputOTP - One-time password input
• Toggle - Toggle button component
• ToggleGroup - Group of toggle buttons
• HoverCard - Hover-triggered card overlay
• Sheet - Slide-out panel overlay
• ResizablePanelGroup - Resizable panel layout
• Menubar - Horizontal menu bar
• ScrollArea - Custom scrollable area

🎨 Styling Best Practices

Priority Order for Styling

1. Pre-built Components (Highest Priority)

   <Button variant="primary">Click me</Button>
   <Card className="p-4">Content</Card>

2. Component Variants & Props

   <Button size="lg" variant="outline">Large Outline Button</Button>
   <Title level="h1" color="primary">Main Heading</Title>

3. Tailwind Utility Classes

   <div className="flex items-center gap-4 p-6 bg-card rounded-lg">
     <Avatar />
     <div className="flex-1">
       <Title>Name</Title>
       <Text className="text-muted-foreground">Description</Text>
     </div>
   </div>

4. Custom CSS Classes (Last Resort)

   // Only for truly unique cases that can't be achieved with utilities
   <div className="custom-animation">Special effect</div>

🚫 Discouraged Practices

❌ Don't Use Custom Styling

// ❌ Avoid inline styles - they break theme consistency
<div style={{ backgroundColor: '#ff0000', padding: '20px' }}>
  Custom styled content
</div>

// ❌ Avoid custom Tailwind classes for design tokens
<div className="bg-[#ff0000] p-[20px]">
  Custom styled content
</div>

// ❌ Avoid inline styles even with semantic tokens
<div style={{ backgroundColor: ds.color('primary') }}>
  Semantic content
</div>

✅ Use Design System Components

// ✅ Use pre-built components (preferred)
<Card className="p-4">
  <Text>Content</Text>
</Card>

// ✅ Use Tailwind's semantic classes
<div className="bg-primary text-primary-foreground p-4 rounded-md">
  Semantic content
</div>

// ✅ Use component variants and props
<Button variant="primary" size="lg">
  Primary Action
</Button>

// ✅ Use utility classes for layout and spacing
<div className="flex items-center gap-4 p-6">
  <Avatar />
  <div className="flex-1">
    <Title level="h3">Title</Title>
    <Text>Description</Text>
  </div>
</div>

🔧 Development Guidelines

Creating New Components

1. Start with shadcn/ui: Use the shadcn/ui CLI to add new components
2. Follow patterns: Maintain consistency with existing components
3. Add TypeScript: Include proper type definitions
4. Make it responsive: Ensure mobile-first design
5. Test themes: Verify light/dark theme compatibility
6. Add to exports: Update index.ts with new component exports

Component Requirements

• ✅ Responsive: Works on all screen sizes
• ✅ Themed: Supports light and dark themes
• ✅ Accessible: WCAG compliant with proper ARIA
• ✅ TypeScript: Full type safety
• ✅ Documented: Include Storybook stories

Example Component Structure

import { cn } from '@kognitos/lattice/lib/utils';
import { type ReactNode } from 'react';

interface MyComponentProps {
  children: ReactNode;
  className?: string;
  variant?: 'default' | 'outline';
}

export function MyComponent({
  children,
  className,
  variant = 'default',
}: MyComponentProps) {
  return (
    <div
      className={cn(
        'base-styles',
        variant === 'outline' && 'outline-styles',
        className,
      )}
    >
      {children}
    </div>
  );
}

📦 Installation & Setup

Prerequisites

• Node.js 18+
• React 18+
• Tailwind CSS 4+ (required — the theme uses native CSS features from Tailwind v4 such as @theme and OKLCH color tokens; Tailwind v3 is not supported)
• TypeScript 5+

Installation

# Install dependencies
npm install

# Start development server
npm run dev

# Start Storybook
npm run storybook

Configuration

1. Tailwind Config: Ensure @tailwindcss/vite is configured
2. TypeScript: Add design system types to your tsconfig.json
3. CSS Import: Import the theme and font CSS in your main CSS file
4. Theme Provider: Wrap your app with ThemeProvider

import { ThemeProvider } from '@kognitos/lattice';

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

/* Tailwind CSS configuration - index.css file */

@import 'tailwindcss';
@import 'tw-animate-css';

@import '../node_modules/@kognitos/lattice/theme.css';
@import '../node_modules/@kognitos/lattice/fonts.css';
@source '../node_modules/@kognitos/lattice/**/*.{js}';

/* Any customizations goes after this */

🤝 Contributing

See CONTRIBUTING.md for detailed guidelines on:

• Adding new components
• Testing requirements
• Publishing workflow
• Design system philosophy

Quick overview:

1. Follow patterns: Maintain consistency with existing code
2. Add tests: Include Storybook stories and unit tests
3. Update docs: Keep documentation current
4. Update llms.txt: When adding or modifying components, update the LLM documentation in llms.txt with component names, variants, props, and usage patterns
5. Design review: Sync with Figma before implementation
6. TypeScript: Ensure full type safety
7. Stay generic: No feature-specific language—this is a pure design library

📄 License

This design system is built on top of shadcn/ui components which are licensed under the MIT License.

🔗 Resources

• shadcn/ui Documentation
• Tailwind CSS Documentation
• Radix UI Documentation
• Figma Plugin Documentation
• Storybook Documentation

Remember: Use components and utility classes, never inline styles. The design system provides everything you need for consistent, accessible, and maintainable UI development. When in doubt, ask yourself: "Can this be achieved with a pre-built component or Tailwind utilities?"