Kuat Design System

A comprehensive design system for Equal Experts, providing React and Vue component libraries built on shadcn/ui and shadcn-vue, with centralized design tokens for brand consistency across applications.

What is Kuat?

Kuat is Equal Experts' design system that:

• Provides ready-to-use component libraries for React and Vue applications
• Ensures brand consistency through centralized design tokens and CSS variables
• Accelerates development with pre-built, accessible components
• Built on industry standards using shadcn/ui, shadcn-vue, and Tailwind CSS v4
• Published to npm as @equal-experts/kuat-react and @equal-experts/kuat-vue

The design system includes brand color palettes (EE Blue, Tech Blue, Transform Teal, Equal Ember), typography scales, spacing systems, and a growing library of accessible UI components.

Structure

packages/
├── kuat-core/     # Shared CSS variables and Tailwind configuration
├── kuat-react/    # React component library using shadcn/ui
└── kuat-vue/      # Vue component library using shadcn-vue

apps/
├── storybook-react/  # Interactive component documentation for React
└── storybook-vue/    # Interactive component documentation for Vue

Getting Started

For Application Developers

If you want to use the Kuat Design System in your React or Vue application:

• Setup (tokens + imports): Consumer setup and Choosing components (Kuat vs shadcn)
• React: @equal-experts/kuat-react README
• Vue: @equal-experts/kuat-vue README

For Contributors

If you want to develop components for the Kuat Design System:

1. Prerequisites

   • Node.js >= 18
   • pnpm >= 8

2. Clone and Install

   git clone <repository-url>
   cd kuat-mono
   pnpm install

3. Start Development

   # Start React Storybook (http://localhost:6006)
   pnpm --filter storybook-react dev
   
   # Start Vue Storybook (http://localhost:6007)
   pnpm --filter storybook-vue dev

4. Read the Contributor Guide

   • CONTRIBUTING.md - Complete development workflow guide

Quick Commands

# Build all packages
pnpm build

# Lint all packages
pnpm lint

# Run all packages in development mode
pnpm dev

Project status

Current workspace / package version: 0.6.0 (see package.json in the repo root and under packages/*).

Published libraries combine @equal-experts/kuat-core (tokens), @equal-experts/kuat-react or @equal-experts/kuat-vue (primitives and blocks), and shadcn / shadcn-vue in your app for components Kuat does not ship (for example Dialog, DropdownMenu).

Illustrative coverage in @equal-experts/kuat-react / @equal-experts/kuat-vue: actions and grouping (Button, ButtonGroup, Badge), form controls (Field, Input, Textarea, Select, Checkbox, Radio, Switch, Toggle), surfaces (Accordion, AlertDialog, Breadcrumb, Sonner), blocks (KuatHeader, KuatCarousel, KuatLogoLockup, KuatRadialProgress, ContentCard), and more. See each package README and public API inventory for the authoritative list.

Storybook in this repo documents interactive behaviour and is the primary reference for component API details.

Packages

@equal-experts/kuat-core

Shared CSS variables and Tailwind configuration for consistent theming across React and Vue packages.

Key Features:

• Brand color palettes (EE Blue, Tech Blue, Transform Teal, Equal Ember)
• Typography system (Lexend, Lora, JetBrains Mono)
• Spacing and layout utilities
• Dark mode support

@equal-experts/kuat-react

React component library built with shadcn/ui, Radix UI primitives, and Tailwind CSS v4.

Install: pnpm add @equal-experts/kuat-core @equal-experts/kuat-react

Usage: packages/kuat-react/README.md, consumer setup

@equal-experts/kuat-vue

Vue component library built with shadcn-vue, Radix Vue primitives, and Tailwind CSS v4.

Install: pnpm add @equal-experts/kuat-core @equal-experts/kuat-vue

Usage: packages/kuat-vue/README.md, consumer setup

Tech Stack

• Monorepo: Turborepo
• Package Manager: pnpm workspaces
• Styling: Tailwind CSS v4
• React: shadcn/ui
• Vue: shadcn-vue
• Build Tool: Vite
• Documentation: Storybook 8

Documentation

Docs Audience Contract

Kuat documentation is intentionally split by audience:

• Contributor docs (repo-internal): guidance for maintainers/agents changing Kuat itself (architecture, coding standards, testing, accessibility gates, release process, agent workflow).
• Consumer docs (usage-focused): guidance for application teams using published Kuat packages (install, setup, component selection, composition, design foundations).

Contributor-focused docs are not included in published package payloads unless explicitly added to a package files list.

For users

• Consumer setup — install order, Tailwind, imports
• Choosing components — Kuat packages vs shadcn vs custom
• @equal-experts/kuat-react README
• @equal-experts/kuat-vue README
• Design system documentation — index of rules and examples
• Rule ownership matrix — local vs upstream source of truth

For Contributors

• CONTRIBUTING.md - Development workflow and component guidelines
• ARCHITECTURE.md - Monorepo architecture and design decisions
• Component Guidelines - Component development patterns
• Contribution guides - React/Vue implementation standards
• Local agent rules - Contributor-focused local overlay rules

For Maintainers

• PUBLISHING.md - Publishing packages to npm
• Version management and release process

For AI Agents

• Agent Documentation - Navigation index for AI agent documentation
• Local canonical agent rules: AGENTS.md (generated from scripts/agent-rules/templates/)
• Cursor agents under .cursor/agents/ — kuat-qa, kuat-component-dev, kuat-verify, kuat-documentation (see CONTRIBUTING.md Development Workflow)
• Rules index — EE canonical paths (external/kuat-agent-rules) and Kuat implementation
• Integration Guide - How to integrate docs into your project

Contributing

We welcome contributions! Please read CONTRIBUTING.md for:

• Development environment setup
• Adding new components
• Creating Storybook stories
• Submitting pull requests

License

[License information to be added]