@casinogate/ui 1.0.0 → 1.1.0

package/README.md

@@ -1,171 +1,967 @@
-# @cg/ui
+# @casinogate/ui
 
-A modern, type-safe UI component library built with Svelte 5, TypeScript, and TailwindCSS. Designed for building beautiful, accessible, and performant user interfaces.
+A modern, type-safe UI component library built with Svelte 5, TypeScript, and TailwindCSS. Designed for building beautiful, accessible, and performant user interfaces with a comprehensive theming system powered by CSS variables.
 
-## ✨ Features
+## 🎨 [View Live Component Documentation](https://static.casinogate.dev/components/master/)
 
-- 🚀 **Svelte 5** - Built with the latest Svelte features including runes and modern APIs
+Explore our complete component library, interactive examples, and design guidelines in Storybook.
+
+---
+
+## 📚 Table of Contents
+
+- [Overview](#overview)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Theming with CSS Variables](#-theming-with-css-variables)
+  - [Understanding the Theming System](#understanding-the-theming-system)
+  - [How to Customize Your Theme](#how-to-customize-your-theme)
+  - [Dark Mode Support](#dark-mode-support)
+- [Complete CSS Variables Reference](#-complete-css-variables-reference)
+  - [Color System](#color-system)
+  - [Typography](#typography)
+  - [Spacing & Layout](#spacing--layout)
+  - [Effects](#effects)
+- [Integration Examples](#-integration-examples)
+- [Component Usage](#-component-usage)
+- [Development](#-development)
+- [Contributing](#-contributing)
+
+---
+
+## Overview
+
+**@casinogate/ui** is the shared component library for CasinoGate applications, providing:
+
+- **🎯 Purpose**: Unified UI components across all CasinoGate products
+- **📦 Where Used**: Web applications, admin panels, and customer-facing interfaces
+- **🎨 Design System**: Complete design token system with CSS variables for full customization
+- **♿ Accessibility**: WCAG 2.1 AA compliant components built on [bits-ui](https://bits-ui.com)
+- **🚀 Performance**: Optimized for production with tree-shaking and minimal bundle size
+
+### Key Features
+
+- ✨ **Svelte 5** - Built with the latest Svelte features including runes
 - 📝 **TypeScript** - Fully typed with comprehensive type definitions
-- 🎨 **TailwindCSS** - Utility-first styling with custom design tokens
-- ♿ **Accessible** - Built on top of [bits-ui](https://bits-ui.com) for robust accessibility
-- 🎭 **Variants** - Flexible styling with [tailwind-variants](https://www.tailwind-variants.org/)
-- 📚 **Storybook** - Comprehensive component documentation and examples
-- 🔧 **Developer-friendly** - Excellent IntelliSense and autocompletion support
+- 🎨 **CSS Variables** - Complete theming control without rebuilding
+- 🌓 **Dark Mode** - Built-in dark theme support
+- 🎭 **Variants** - Flexible component styling with [tailwind-variants](https://www.tailwind-variants.org/)
+- 📚 **Documented** - Comprehensive Storybook documentation
+- 🔧 **Developer Experience** - Excellent IntelliSense and autocompletion
+
+---
 
 ## 📦 Installation
 
+### Using pnpm (Recommended)
+
+```bash
+pnpm add @casinogate/ui
+```
+
+### Using npm
+
 ```bash
-# Using pnpm (recommended)
-pnpm add @cg/ui
+npm install @casinogate/ui
+```
 
-# Using npm
-npm install @cg/ui
+### Using yarn
 
-# Using yarn
-yarn add @cg/ui
+```bash
+yarn add @casinogate/ui
 ```
 
 ### Peer Dependencies
 
-Make sure you have Svelte 5 installed:
+Ensure you have Svelte 5 installed:
 
 ```bash
-pnpm add svelte@^5.0.0
+pnpm add svelte@^5.36.1
 ```
 
-## 🎨 Styling & Customization
+---
+
+## 🚀 Quick Start
 
-### Using Tailwind Variants
+### 1. Import Styles
 
-Components are built with `tailwind-variants` for powerful styling:
+Import the CSS file in your root layout or main entry point:
 
 ```svelte
+<!-- +layout.svelte or app.html -->
 <script>
-  import { Button } from '@cg/ui';
-
-  // Access the styles function directly
-  const customButtonStyles = Button.styles({
-    variant: 'primary',
-    size: 'lg',
-    // Override with custom classes
-    class: 'my-custom-class',
+  import '@casinogate/ui/styles.css';
+</script>
+```
+
+### 2. Use Components
+
+```svelte
+<script lang="ts">
+  import { Button, Input, DataTable } from '@casinogate/ui';
+</script>
+
+<div class="app">
+  <Button variant="primary" size="lg">Click Me</Button>
+  <Input placeholder="Enter your name..." />
+</div>
+```
+
+### 3. Customize Theme (Optional)
+
+Override CSS variables to match your brand:
+
+```css
+/* app.css or global stylesheet */
+:root {
+  --cg-ui-primary-hue: 280; /* Purple theme */
+  --cg-ui-primary-saturation: 85%;
+}
+```
+
+---
+
+## 🎨 Theming with CSS Variables
+
+### Understanding the Theming System
+
+The component library uses a **two-tier CSS variable system** for maximum flexibility:
+
+#### 1. **Palette Variables** (Low-level)
+
+Base color definitions in `:root` that you can override:
+
+```css
+:root {
+  /* Control primary color palette */
+  --cg-ui-primary-hue: 220;
+  --cg-ui-primary-saturation: 80%;
+
+  /* These generate shades automatically */
+  --cg-ui-palette-primary-100: hsla(220, 80%, 38%, 1);
+  --cg-ui-palette-primary-80: hsla(220, 80%, 50%, 1);
+  --cg-ui-palette-primary-60: hsla(220, 80%, 64%, 1);
+}
+```
+
+#### 2. **Semantic Variables** (High-level)
+
+Purpose-driven variables that reference palette colors:
+
+```css
+@theme inline {
+  /* Components use semantic names */
+  --color-surface-primary: var(--cg-ui-palette-primary-80);
+  --color-fg-primary: var(--cg-ui-palette-primary-80);
+  --color-stroke-primary: var(--cg-ui-palette-primary-80);
+}
+```
+
+### How to Customize Your Theme
+
+#### Method 1: Override Hue & Saturation (Recommended)
+
+Change just two variables to rebrand the entire interface:
+
+```css
+/* Your global CSS file */
+:root {
+  /* Change primary color to purple */
+  --cg-ui-primary-hue: 280;
+  --cg-ui-primary-saturation: 85%;
+
+  /* Change neutral gray tones */
+  --cg-ui-neutral-hue: 270;
+  --cg-ui-neutral-saturation: 15%;
+}
+```
+
+#### Method 2: Override Specific Palette Colors
+
+For precise control over individual shades:
+
+```css
+:root {
+  /* Override specific primary shades */
+  --cg-ui-palette-primary-100: #2d1b69;
+  --cg-ui-palette-primary-80: #4c2a9f;
+  --cg-ui-palette-primary-60: #7c5ac7;
+
+  /* Override system colors */
+  --cg-ui-palette-system-success-100: #00a86b;
+  --cg-ui-palette-system-error-100: #ff3b30;
+}
+```
+
+#### Method 3: Override Semantic Variables
+
+Target specific component contexts:
+
+```css
+:root {
+  /* Change button backgrounds without affecting other primary uses */
+  --color-surface-primary: #ff6b6b;
+  --color-surface-primary-active: #ff5252;
+
+  /* Customize form field borders */
+  --color-stroke-default: #d1d5db;
+  --color-stroke-focus: #3b82f6;
+}
+```
+
+#### Method 4: Scoped Theming
+
+Apply different themes to specific sections:
+
+```css
+/* Default theme */
+:root {
+  --cg-ui-primary-hue: 220;
+}
+
+/* Special section with different branding */
+.promotional-section {
+  --cg-ui-primary-hue: 340; /* Red theme */
+  --cg-ui-primary-saturation: 90%;
+}
+```
+
+```svelte
+<div class="promotional-section">
+  <!-- Buttons here will use the red theme -->
+  <Button variant="primary">Special Offer</Button>
+</div>
+```
+
+### Dark Mode Support
+
+The library includes a complete dark theme that activates with `.dark` class or `data-theme="dark"` attribute.
+
+#### Method 1: Using Class Toggle
+
+```svelte
+<script lang="ts">
+  import { Button } from '@casinogate/ui';
+  import '@casinogate/ui/styles.css';
+
+  let isDark = $state(false);
+
+  function toggleTheme() {
+    isDark = !isDark;
+    document.documentElement.classList.toggle('dark', isDark);
+  }
+</script>
+
+<body class:dark={isDark}>
+  <Button onclick={toggleTheme}>
+    {isDark ? '☀️ Light Mode' : '🌙 Dark Mode'}
+  </Button>
+</body>
+```
+
+#### Method 2: Using Data Attribute
+
+```svelte
+<script lang="ts">
+  let theme = $state<'light' | 'dark'>('light');
+
+  function toggleTheme() {
+    theme = theme === 'light' ? 'dark' : 'light';
+    document.documentElement.setAttribute('data-theme', theme);
+  }
+</script>
+
+<html data-theme={theme}>
+  <!-- Your app -->
+</html>
+```
+
+#### Method 3: Respecting System Preference
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+
+  onMount(() => {
+    const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    document.documentElement.classList.toggle('dark', isDark);
+
+    // Listen for system changes
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+      document.documentElement.classList.toggle('dark', e.matches);
+    });
   });
 </script>
+```
+
+#### Customizing Dark Mode Colors
 
-<button class={customButtonStyles.root()}> Custom Styled Button </button>
+Override dark theme colors specifically:
+
+```css
+.dark,
+[data-theme='dark'] {
+  /* Custom dark mode primary color */
+  --cg-ui-primary-hue: 160; /* Teal in dark mode */
+  --cg-ui-primary-saturation: 80%;
+
+  /* Adjust neutral darkness */
+  --cg-ui-palette-neutral-100: hsla(220, 50%, 5%, 1);
+  --cg-ui-palette-neutral-80: hsla(220, 50%, 10%, 1);
+}
 ```
 
-### CSS Custom Properties
+---
+
+## 📋 Complete CSS Variables Reference
+
+### Color System
+
+#### Primary Colors
+
+Control the main brand color used throughout the interface.
+
+| Variable                      | Default (Light)          | Dark Mode                | Description               |
+| ----------------------------- | ------------------------ | ------------------------ | ------------------------- |
+| `--cg-ui-primary-hue`         | `220`                    | `160`                    | Primary color hue (0-360) |
+| `--cg-ui-primary-saturation`  | `80%`                    | `80%`                    | Primary color saturation  |
+| `--cg-ui-palette-primary-100` | `hsla(220, 80%, 38%, 1)` | `hsla(160, 80%, 28%, 1)` | Darkest primary shade     |
+| `--cg-ui-palette-primary-80`  | `hsla(220, 80%, 50%, 1)` | `hsla(160, 80%, 40%, 1)` | Standard primary color    |
+| `--cg-ui-palette-primary-60`  | `hsla(220, 80%, 64%, 1)` | `hsla(160, 80%, 64%, 1)` | Light primary shade       |
+| `--cg-ui-palette-primary-40`  | `hsla(220, 80%, 94%, 1)` | `hsla(160, 80%, 94%, 1)` | Very light primary        |
+| `--cg-ui-palette-primary-10`  | `hsla(220, 80%, 97%, 1)` | `hsla(160, 80%, 97%, 1)` | Subtlest primary tint     |
+
+**Usage in components:** Buttons, links, focus states, active selections
+
+#### Neutral Colors
+
+Grayscale palette for text, borders, backgrounds, and UI elements.
 
-Components support CSS custom properties for theming:
+| Variable                      | Default (Light)          | Dark Mode                | Description                   |
+| ----------------------------- | ------------------------ | ------------------------ | ----------------------------- |
+| `--cg-ui-neutral-hue`         | `230`                    | `225`                    | Neutral color hue             |
+| `--cg-ui-neutral-saturation`  | `20%`                    | `50%`                    | Neutral color saturation      |
+| `--cg-ui-palette-neutral-100` | `hsla(230, 20%, 12%, 1)` | `hsla(225, 50%, 8%, 1)`  | Darkest gray (text)           |
+| `--cg-ui-palette-neutral-80`  | `hsla(230, 20%, 20%, 1)` | `hsla(225, 50%, 12%, 1)` | Dark gray                     |
+| `--cg-ui-palette-neutral-60`  | `hsla(230, 20%, 40%, 1)` | `hsla(225, 50%, 16%, 1)` | Medium gray                   |
+| `--cg-ui-palette-neutral-50`  | `hsla(230, 20%, 58%, 1)` | `hsla(225, 50%, 28%, 1)` | Mid-tone gray                 |
+| `--cg-ui-palette-neutral-40`  | `hsla(230, 20%, 78%, 1)` | Fixed                    | Light gray (borders)          |
+| `--cg-ui-palette-neutral-20`  | `hsla(230, 20%, 95%, 1)` | Fixed                    | Very light gray (backgrounds) |
+| `--cg-ui-palette-neutral-10`  | `hsla(230, 20%, 98%, 1)` | Fixed                    | Subtlest gray                 |
+| `--cg-ui-palette-neutral-0`   | `hsla(0, 0%, 100%, 1)`   | Fixed                    | Pure white                    |
+| `--cg-ui-palette-neutral-01`  | `hsla(0, 0%, 100%, 0.1)` | Fixed                    | Transparent white overlay     |
+
+**Usage in components:** Text, borders, dividers, card backgrounds, disabled states
+
+#### System Colors
+
+Semantic colors for states and notifications.
+
+##### Error Colors
+
+| Variable                           | Default                 | Description           |
+| ---------------------------------- | ----------------------- | --------------------- |
+| `--cg-ui-palette-system-error-100` | `hsla(2, 100%, 40%, 1)` | Error text and icons  |
+| `--cg-ui-palette-system-error-10`  | `hsla(3, 67%, 93%, 1)`  | Error background tint |
+
+##### Warning Colors
+
+| Variable                             | Default (Light)          | Dark Mode               | Description             |
+| ------------------------------------ | ------------------------ | ----------------------- | ----------------------- |
+| `--cg-ui-palette-system-warning-100` | `hsla(52, 100%, 50%, 1)` | `hsla(32, 98%, 40%, 1)` | Warning text and icons  |
+| `--cg-ui-palette-system-warning-10`  | `hsla(18, 88%, 94%, 1)`  | `hsla(18, 88%, 94%, 1)` | Warning background tint |
+
+##### Success Colors
+
+| Variable                             | Default                   | Description             |
+| ------------------------------------ | ------------------------- | ----------------------- |
+| `--cg-ui-palette-system-success-100` | `hsla(162, 100%, 25%, 1)` | Success text and icons  |
+| `--cg-ui-palette-system-success-10`  | `hsla(162, 64%, 94%, 1)`  | Success background tint |
+
+##### Info Colors
+
+| Variable                          | Default                  | Description          |
+| --------------------------------- | ------------------------ | -------------------- |
+| `--cg-ui-palette-system-info-100` | `hsla(232, 22%, 29%, 1)` | Info text and icons  |
+| `--cg-ui-palette-system-info-10`  | `hsla(240, 12%, 93%, 1)` | Info background tint |
+
+**Usage in components:** Alerts, toasts, validation messages, status badges
+
+#### Semantic Color Variables
+
+Purpose-driven variables used directly by components (defined in `@theme inline`).
+
+##### Surface Colors (Backgrounds)
+
+| Variable                               | References                    | Description                  |
+| -------------------------------------- | ----------------------------- | ---------------------------- |
+| `--color-surface-primary`              | `--cg-ui-palette-primary-80`  | Primary button background    |
+| `--color-surface-primary-active`       | `--cg-ui-palette-primary-60`  | Primary button hover/active  |
+| `--color-surface-primary-light`        | `--cg-ui-palette-primary-40`  | Light primary surface        |
+| `--color-surface-primary-light-active` | `--cg-ui-palette-primary-10`  | Light primary surface active |
+| `--color-surface-darkest`              | `--cg-ui-palette-neutral-100` | Darkest surface              |
+| `--color-surface-dark`                 | `--cg-ui-palette-neutral-80`  | Dark surface                 |
+| `--color-surface-regular`              | `--cg-ui-palette-neutral-50`  | Regular surface              |
+| `--color-surface-semilight`            | `--cg-ui-palette-neutral-40`  | Semi-light surface           |
+| `--color-surface-light`                | `--cg-ui-palette-neutral-20`  | Light surface (cards)        |
+| `--color-surface-lightest`             | `--cg-ui-palette-neutral-10`  | Lightest surface             |
+| `--color-surface-white`                | `--cg-ui-palette-neutral-0`   | White surface                |
+| `--color-surface-hover`                | `--cg-ui-palette-neutral-01`  | Hover overlay                |
+
+##### Background Colors (Page-level)
+
+| Variable           | References                    | Description          |
+| ------------------ | ----------------------------- | -------------------- |
+| `--color-bg-white` | `--cg-ui-palette-neutral-0`   | White background     |
+| `--color-bg-main`  | `--cg-ui-palette-neutral-20`  | Main page background |
+| `--color-bg-dark`  | `--cg-ui-palette-neutral-100` | Dark background      |
+
+##### Foreground Colors (Text)
+
+| Variable               | References                           | Description          |
+| ---------------------- | ------------------------------------ | -------------------- |
+| `--color-fg-darkest`   | `--cg-ui-palette-neutral-100`        | Primary text color   |
+| `--color-fg-dark`      | `--cg-ui-palette-neutral-80`         | Dark text            |
+| `--color-fg-medium`    | `--cg-ui-palette-neutral-60`         | Medium text          |
+| `--color-fg-regular`   | `--cg-ui-palette-neutral-50`         | Regular text         |
+| `--color-fg-semilight` | `--cg-ui-palette-neutral-40`         | Light text           |
+| `--color-fg-primary`   | `--cg-ui-palette-primary-80`         | Primary colored text |
+| `--color-fg-white`     | `--cg-ui-palette-neutral-0`          | White text           |
+| `--color-fg-error`     | `--cg-ui-palette-system-error-100`   | Error text           |
+| `--color-fg-success`   | `--cg-ui-palette-system-success-100` | Success text         |
+
+##### Stroke Colors (Borders)
+
+| Variable                 | References                         | Description          |
+| ------------------------ | ---------------------------------- | -------------------- |
+| `--color-stroke-default` | `--cg-ui-palette-neutral-40`       | Default border color |
+| `--color-stroke-minimum` | `--cg-ui-palette-neutral-10`       | Minimal border       |
+| `--color-stroke-focus`   | `--cg-ui-palette-primary-60`       | Focus ring border    |
+| `--color-stroke-primary` | `--cg-ui-palette-primary-80`       | Primary border       |
+| `--color-stroke-divider` | `--cg-ui-palette-neutral-20`       | Divider lines        |
+| `--color-stroke-error`   | `--cg-ui-palette-system-error-100` | Error border         |
+
+##### Icon Colors
+
+| Variable               | References                   | Description        |
+| ---------------------- | ---------------------------- | ------------------ |
+| `--color-icon-regular` | `--cg-ui-palette-neutral-50` | Regular icon color |
+| `--color-icon-default` | `--cg-ui-palette-neutral-40` | Default icon color |
+| `--color-icon-primary` | `--cg-ui-palette-primary-80` | Primary icon color |
+| `--color-icon-focus`   | `--cg-ui-palette-primary-60` | Focused icon color |
+| `--color-icon-white`   | `--cg-ui-palette-neutral-0`  | White icon         |
+
+##### State Colors
+
+| Variable                      | References                           | Description        |
+| ----------------------------- | ------------------------------------ | ------------------ |
+| `--color-state-error`         | `--cg-ui-palette-system-error-100`   | Error state        |
+| `--color-state-error-light`   | `--cg-ui-palette-system-error-10`    | Error background   |
+| `--color-state-warning`       | `--cg-ui-palette-system-warning-100` | Warning state      |
+| `--color-state-warning-light` | `--cg-ui-palette-system-warning-10`  | Warning background |
+| `--color-state-success`       | `--cg-ui-palette-system-success-100` | Success state      |
+| `--color-state-success-light` | `--cg-ui-palette-system-success-10`  | Success background |
+| `--color-state-info`          | `--cg-ui-palette-system-info-100`    | Info state         |
+| `--color-state-info-light`    | `--cg-ui-palette-system-info-10`     | Info background    |
+
+### Typography
+
+Font sizes and line heights defined relative to a base size of 16px.
+
+| Variable               | Default                | Computed Value    | Description                   |
+| ---------------------- | ---------------------- | ----------------- | ----------------------------- |
+| `--cg-ui-fz-base`      | `16`                   | —                 | Base font size multiplier     |
+| `--cg-ui-fz-heading`   | `calc(16 / 16 * 1rem)` | `1rem` (16px)     | Heading font size             |
+| `--cg-ui-lh-heading`   | `calc(22 / 16 * 1rem)` | `1.375rem` (22px) | Heading line height           |
+| `--cg-ui-fz-heading-2` | `calc(16 / 16 * 1rem)` | `1rem` (16px)     | Secondary heading size        |
+| `--cg-ui-lh-heading-2` | `calc(18 / 16 * 1rem)` | `1.125rem` (18px) | Secondary heading line height |
+| `--cg-ui-fz-body`      | `calc(14 / 16 * 1rem)` | `0.875rem` (14px) | Body text size                |
+| `--cg-ui-lh-body`      | `calc(18 / 16 * 1rem)` | `1.125rem` (18px) | Body line height              |
+| `--cg-ui-fz-body-2`    | `calc(14 / 16 * 1rem)` | `0.875rem` (14px) | Secondary body size           |
+| `--cg-ui-lh-body-2`    | `calc(16 / 16 * 1rem)` | `1rem` (16px)     | Secondary body line height    |
+| `--cg-ui-fz-caption`   | `calc(12 / 16 * 1rem)` | `0.75rem` (12px)  | Caption text size             |
+| `--cg-ui-lh-caption`   | `calc(18 / 16 * 1rem)` | `1.125rem` (18px) | Caption line height           |
+| `--cg-ui-fz-caption-2` | `calc(12 / 16 * 1rem)` | `0.75rem` (12px)  | Secondary caption size        |
+| `--cg-ui-lh-caption-2` | `calc(16 / 16 * 1rem)` | `1rem` (16px)     | Secondary caption line height |
+
+**Semantic Typography Variables** (for component use)
+
+| Variable                        | References             | Usage                          |
+| ------------------------------- | ---------------------- | ------------------------------ |
+| `--text-heading`                | `--cg-ui-fz-heading`   | Headings font size             |
+| `--text-heading--line-height`   | `--cg-ui-lh-heading`   | Headings line height           |
+| `--text-heading-2`              | `--cg-ui-fz-heading-2` | Secondary headings             |
+| `--text-heading-2--line-height` | `--cg-ui-lh-heading-2` | Secondary headings line height |
+| `--text-body`                   | `--cg-ui-fz-body`      | Body text                      |
+| `--text-body--line-height`      | `--cg-ui-lh-body`      | Body line height               |
+| `--text-body-2`                 | `--cg-ui-fz-body-2`    | Secondary body text            |
+| `--text-body-2--line-height`    | `--cg-ui-lh-body-2`    | Secondary body line height     |
+| `--text-caption`                | `--cg-ui-fz-caption`   | Captions                       |
+| `--text-caption--line-height`   | `--cg-ui-lh-caption`   | Caption line height            |
+| `--text-caption-2`              | `--cg-ui-fz-caption-2` | Secondary captions             |
+| `--text-caption-2--line-height` | `--cg-ui-lh-caption-2` | Secondary caption line height  |
+
+### Spacing & Layout
+
+#### Base Numbers
+
+Foundation spacing values used to generate other measurements.
+
+| Variable              | Value (px) | Description           |
+| --------------------- | ---------- | --------------------- |
+| `--cg-ui-number-null` | `0`        | Zero spacing          |
+| `--cg-ui-number-xxxs` | `2`        | 2px                   |
+| `--cg-ui-number-xxs`  | `4`        | 4px                   |
+| `--cg-ui-number-xs`   | `6`        | 6px                   |
+| `--cg-ui-number-sm`   | `8`        | 8px                   |
+| `--cg-ui-number-md`   | `12`       | 12px                  |
+| `--cg-ui-number-lg`   | `16`       | 16px                  |
+| `--cg-ui-number-xl`   | `20`       | 20px                  |
+| `--cg-ui-number-2xl`  | `24`       | 24px                  |
+| `--cg-ui-number-xxl`  | `40`       | 40px                  |
+| `--cg-ui-number-2xxl` | `48`       | 48px                  |
+| `--cg-ui-number-max`  | `360`      | Maximum value (360px) |
+
+#### Border Radius
+
+| Variable        | Formula           | Computed | Usage            |
+| --------------- | ----------------- | -------- | ---------------- |
+| `--radius-null` | `calc(0 * 1px)`   | `0px`    | No rounding      |
+| `--radius-xxxs` | `calc(2 * 1px)`   | `2px`    | Minimal rounding |
+| `--radius-xxs`  | `calc(4 * 1px)`   | `4px`    | Very small       |
+| `--radius-xs`   | `calc(6 * 1px)`   | `6px`    | Small            |
+| `--radius-sm`   | `calc(8 * 1px)`   | `8px`    | Default buttons  |
+| `--radius-md`   | `calc(12 * 1px)`  | `12px`   | Cards, panels    |
+| `--radius-lg`   | `calc(16 * 1px)`  | `16px`   | Large cards      |
+| `--radius-xl`   | `calc(20 * 1px)`  | `20px`   | Extra large      |
+| `--radius-2xl`  | `calc(24 * 1px)`  | `24px`   | Very round       |
+| `--radius-xxl`  | `calc(40 * 1px)`  | `40px`   | Super round      |
+| `--radius-2xxl` | `calc(48 * 1px)`  | `48px`   | Maximum rounding |
+| `--radius-max`  | `calc(360 * 1px)` | `360px`  | Pill shape       |
+
+#### Breakpoints
+
+Responsive design breakpoints for media queries.
+
+| Variable                  | Value    | Device Target                 |
+| ------------------------- | -------- | ----------------------------- |
+| `--breakpoint-phone-sm`   | `320px`  | Small phones                  |
+| `--breakpoint-phone`      | `375px`  | Standard phones               |
+| `--breakpoint-phone-lg`   | `425px`  | Large phones                  |
+| `--breakpoint-tablet-sm`  | `640px`  | Small tablets                 |
+| `--breakpoint-tablet`     | `768px`  | Standard tablets              |
+| `--breakpoint-tablet-lg`  | `1024px` | Large tablets / small laptops |
+| `--breakpoint-desktop-sm` | `1280px` | Small desktops                |
+| `--breakpoint-desktop`    | `1440px` | Standard desktops             |
+| `--breakpoint-desktop-lg` | `1920px` | Large desktops                |
+
+### Effects
+
+#### Shadows
+
+| Variable                      | Value                                   | Usage                 |
+| ----------------------------- | --------------------------------------- | --------------------- |
+| `--cg-ui-shadow-toast`        | `0px 0px 8px 0px hsla(0, 0%, 0%, 0.2)`  | Toast notifications   |
+| `--cg-ui-shadow-switch-thumb` | `0px 1px 1px 0px hsla(0, 0%, 0%, 0.25)` | Switch toggle thumb   |
+| `--cg-ui-shadow-segment-item` | `0px 0px 4px 0px hsla(0, 0%, 0%, 0.1)`  | Segment control items |
+
+##### Semantic Shadow Variables
+
+| Variable                 | References                    | Usage             |
+| ------------------------ | ----------------------------- | ----------------- |
+| `--shadow-toast`         | `--cg-ui-shadow-toast`        | Toast component   |
+| `--shadow-switch-thumb`  | `--cg-ui-shadow-switch-thumb` | Switch component  |
+| `--shadow-segment-thumb` | `--cg-ui-shadow-segment-item` | Segment component |
+
+#### Blur Effects
+
+| Variable     | Formula          | Computed | Usage            |
+| ------------ | ---------------- | -------- | ---------------- |
+| `--blur-xxs` | `calc(4 * 1px)`  | `4px`    | Minimal blur     |
+| `--blur-xs`  | `calc(6 * 1px)`  | `6px`    | Extra small blur |
+| `--blur-sm`  | `calc(8 * 1px)`  | `8px`    | Small blur       |
+| `--blur-md`  | `calc(12 * 1px)` | `12px`   | Medium blur      |
+| `--blur-lg`  | `calc(16 * 1px)` | `16px`   | Large blur       |
+| `--blur-xl`  | `calc(20 * 1px)` | `20px`   | Extra large blur |
+| `--blur-2xl` | `calc(24 * 1px)` | `24px`   | Maximum blur     |
+
+---
+
+## 💡 Integration Examples
+
+### Example 1: Basic Brand Customization
 
 ```css
+/* styles/theme.css */
 :root {
-  --color-primary: #3b82f6;
-  --color-secondary: #6b7280;
-  /* Override default colors */
+  /* Rebrand to purple */
+  --cg-ui-primary-hue: 280;
+  --cg-ui-primary-saturation: 85%;
+
+  /* Adjust border roundness */
+  --cg-ui-number-sm: 12; /* Makes buttons more rounded */
 }
 ```
 
-### Custom Classes
+```svelte
+<!-- App.svelte -->
+<script lang="ts">
+  import { Button } from '@casinogate/ui';
+  import '@casinogate/ui/styles.css';
+  import './styles/theme.css';
+</script>
+
+<Button variant="primary">Branded Button</Button>
+```
+
+### Example 2: Component-Specific Overrides
+
+```svelte
+<script lang="ts">
+  import { Button, Card } from '@casinogate/ui';
+</script>
+
+<div class="custom-section">
+  <Card>
+    <h2>Special Offer</h2>
+    <Button variant="primary">Claim Now</Button>
+  </Card>
+</div>
+
+<style>
+  .custom-section {
+    /* Override just for this section */
+    --color-surface-primary: #ff6b6b;
+    --color-surface-primary-active: #ff5252;
+    --radius-sm: 16px;
+  }
+</style>
+```
+
+### Example 3: Dynamic Theme Switching
+
+```svelte
+<script lang="ts">
+  import { Button } from '@casinogate/ui';
+
+  type Theme = 'blue' | 'purple' | 'green';
+
+  let currentTheme = $state<Theme>('blue');
+
+  const themes = {
+    blue: { hue: 220, sat: 80 },
+    purple: { hue: 280, sat: 85 },
+    green: { hue: 160, sat: 80 },
+  };
+
+  function applyTheme(theme: Theme) {
+    const { hue, sat } = themes[theme];
+    document.documentElement.style.setProperty('--cg-ui-primary-hue', String(hue));
+    document.documentElement.style.setProperty('--cg-ui-primary-saturation', `${sat}%`);
+    currentTheme = theme;
+  }
+</script>
+
+<div>
+  <h2>Select Theme</h2>
+  <Button onclick={() => applyTheme('blue')}>Blue</Button>
+  <Button onclick={() => applyTheme('purple')}>Purple</Button>
+  <Button onclick={() => applyTheme('green')}>Green</Button>
+</div>
+```
 
-Add custom classes using the `class` prop:
+### Example 4: CSS-in-JS with Inline Styles
 
 ```svelte
-<Button class="my-4 transition-transform hover:scale-105">Custom Button</Button>
+<script lang="ts">
+  import { DataTable } from '@casinogate/ui';
+
+  const customColors = {
+    '--color-surface-light': '#f0f9ff',
+    '--color-stroke-default': '#bae6fd',
+    '--radius-md': '12px',
+  };
+</script>
+
+<div
+  style={Object.entries(customColors)
+    .map(([k, v]) => `${k}:${v}`)
+    .join(';')}
+>
+  <DataTable {table} />
+</div>
+```
+
+---
+
+## 📦 Component Usage
+
+### Available Components
+
+```typescript
+import {
+  // Form Controls
+  Button,
+  Input,
+  Checkbox,
+  Switch,
+  Select,
+
+  // Data Display
+  DataTable,
+  DataTablePrimitive,
+
+  // Navigation
+  Pagination,
+  Segment,
+
+  // Feedback
+  Toast,
+  Spinner,
+  Skeleton,
+
+  // Layout
+  Collapsible,
+
+  // Icons
+  Icons, // All icon components
+} from '@casinogate/ui';
 ```
 
+### Component Documentation
+
+Each component has detailed documentation in Storybook:
+
+- **Interactive Examples**: [View in Storybook](https://static.casinogate.dev/components/master/)
+- **Props API**: TypeScript definitions with JSDoc
+- **Variants**: All available style variants
+- **Accessibility**: ARIA attributes and keyboard support
+
+### Example: Button Component
+
+```svelte
+<script lang="ts">
+  import { Button } from '@casinogate/ui';
+</script>
+
+<!-- Variants -->
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+
+<!-- Sizes -->
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+
+<!-- Custom styling -->
+<Button class="custom-class" style="--color-surface-primary: #ff6b6b;">Custom Color</Button>
+```
+
+### Example: DataTable Component
+
+See the complete [DataTable Guide](./src/components/data-table/README.md) for advanced usage.
+
+```svelte
+<script lang="ts">
+  import { DataTable, createTable, rowModels } from '@casinogate/ui';
+  import type { ColumnDef } from '@casinogate/ui';
+
+  type User = {
+    id: number;
+    name: string;
+    email: string;
+  };
+
+  const data: User[] = [
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
+  ];
+
+  const columns: ColumnDef<User>[] = [
+    { accessorKey: 'id', header: 'ID' },
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+  ];
+
+  const table = createTable({
+    get data() {
+      return data;
+    },
+    columns,
+    getCoreRowModel: rowModels.coreRowModel(),
+  });
+</script>
+
+<DataTable {table} />
+```
+
+---
+
 ## 🔧 Development
 
 ### Prerequisites
 
-- Node.js >= 22.14.0
-- pnpm >= 9.5.0
+- **Node.js**: >= 22.14.0
+- **pnpm**: >= 9.5.0
 
 ### Setup
 
 ```bash
-# Clone and install dependencies
+# Clone the repository
 git clone <repo-url>
 cd cg-components/packages/cg-ui
+
+# Install dependencies
 pnpm install
 ```
 
 ### Available Scripts
 
-```bash
-# Development
-pnpm dev                    # Start development server
-pnpm storybook              # Start Storybook
-
-# Building
-pnpm build                  # Build the library
-pnpm prepack                # Prepare for publishing
-
-# Quality Assurance
-pnpm check                  # Type checking
-pnpm check:watch            # Type checking in watch mode
-pnpm lint                   # Lint code
-pnpm format                 # Format code
-
-# Documentation
-pnpm build-storybook        # Build Storybook for deployment
-```
+| Command                | Description                        |
+| ---------------------- | ---------------------------------- |
+| `pnpm dev`             | Start development server with HMR  |
+| `pnpm build`           | Build library for production       |
+| `pnpm storybook`       | Start Storybook on port 6006       |
+| `pnpm build-storybook` | Build static Storybook site        |
+| `pnpm check`           | Run TypeScript type checking       |
+| `pnpm check:watch`     | Type checking in watch mode        |
+| `pnpm lint`            | Lint code with ESLint and Prettier |
+| `pnpm format`          | Format code with Prettier          |
+| `pnpm prepack`         | Prepare package for publishing     |
 
 ### Project Structure
 
-```
+```text
 packages/cg-ui/
 ├── src/
 │   ├── components/         # UI components
-│   │   └── button/
-│   │       ├── button.component.svelte
-│   │       └── index.ts
+│   │   ├── button/
+│   │   ├── data-table/
+│   │   └── ...
+│   ├── assets/
+│   │   └── css/
+│   │       ├── root.css    # Main entry point
+│   │       └── theme.css   # CSS variables
 │   ├── internal/           # Internal utilities
-│   │   ├── types/          # TypeScript type definitions
-│   │   └── utils/          # Utility functions
-│   ├── stories/            # Storybook stories
-│   ├── assets/             # CSS and static assets
+│   │   ├── types/          # TypeScript definitions
+│   │   └── utils/          # Helper functions
 │   └── index.ts            # Main export file
 ├── dist/                   # Built output (generated)
-├── build/                  # SvelteKit build output
+│   ├── components/         # Compiled components
+│   └── assets/
+│       └── css/
+│           └── root.css    # Bundled CSS
 └── storybook-static/       # Built Storybook (generated)
 ```
 
-## 📚 Documentation
-
-- **Storybook**: Run `pnpm storybook` to explore components interactively
-- **Type Definitions**: Comprehensive TypeScript definitions included
-- **Examples**: Check the `src/stories/` directory for usage examples
+---
 
 ## 🤝 Contributing
 
-1. **Create a new component** in `src/components/`
-2. **Add TypeScript types** and exports
-3. **Create Storybook stories** in `src/stories/`
-4. **Write tests** (coming soon)
-5. **Update documentation**
+### Adding a New Component
+
+1. **Create component directory**
+
+   ```bash
+   mkdir -p src/components/my-component
+   ```
+
+2. **Create component files**
+
+   ```text
+   src/components/my-component/
+   ├── my-component.svelte          # Main component
+   ├── my-component.stories.svelte  # Storybook stories
+   ├── index.ts                     # Exports
+   └── README.md                    # Documentation (optional)
+   ```
+
+3. **Export from main index**
+
+   ```typescript
+   // src/index.ts
+   export { default as MyComponent } from './components/my-component/my-component.svelte';
+   ```
+
+4. **Add to Storybook**
+
+   Create stories showcasing all variants and use cases.
+
+### Component Guidelines
+
+- ✅ **Accessibility First**: Use bits-ui primitives when available
+- ✅ **Type Safety**: Provide comprehensive TypeScript definitions
+- ✅ **CSS Variables**: Use semantic variables, not hardcoded colors
+- ✅ **Documentation**: Add Storybook stories with examples
+- ✅ **Consistency**: Follow patterns from existing components
+- ✅ **Testing**: (Coming soon) Write unit and integration tests
+
+### Adding New CSS Variables
+
+1. **Add to palette** (`:root` in `theme.css`)
+
+   ```css
+   :root {
+     --cg-ui-palette-accent-100: hsla(180, 80%, 40%, 1);
+   }
+   ```
 
-### Component Development Guidelines
+2. **Add semantic variable** (`@theme inline` in `theme.css`)
 
-1. **Accessibility First**: Use bits-ui primitives when possible
-2. **Type Safety**: Provide comprehensive TypeScript definitions
-3. **Consistent API**: Follow established patterns from existing components
-4. **Documentation**: Every component should have Storybook stories
-5. **Styling**: Use tailwind-variants for flexible styling options
+   ```css
+   @theme inline {
+     --color-accent: var(--cg-ui-palette-accent-100);
+   }
+   ```
+
+3. **Document in README** (this file)
+
+4. **Use in components**
+
+   ```svelte
+   <style>
+     .my-component {
+       background-color: var(--color-accent);
+     }
+   </style>
+   ```
+
+### Submitting Changes
+
+1. Create a feature branch
+2. Make your changes
+3. Run `pnpm check` and `pnpm lint`
+4. Test in Storybook
+5. Create a pull request
+6. Request review from UI team
+
+---
+
+## 📚 Additional Resources
+
+- **Live Storybook**: [https://static.casinogate.dev/components/master/](https://static.casinogate.dev/components/master/)
+- **Monorepo Documentation**: [Root README](../../README.md)
+- **DevOps Guide**: [Publishing & Deployment](../../docs/DEVOPS.md)
+- **Svelte 5 Docs**: [https://svelte.dev/docs](https://svelte.dev/docs)
+- **TailwindCSS**: [https://tailwindcss.com](https://tailwindcss.com)
+- **bits-ui**: [https://bits-ui.com](https://bits-ui.com)
+
+---
 
 ## 📄 License
 
 ISC
 
-## 🔗 Links
+---
+
+## 🙋 Support
 
-- [Svelte 5 Documentation](https://svelte.dev/docs/svelte/overview)
-- [TailwindCSS](https://tailwindcss.com/)
-- [bits-ui](https://bits-ui.com/) - Accessible component primitives
-- [tailwind-variants](https://www.tailwind-variants.org/) - Styling utilities
-- [Storybook](https://storybook.js.org/) - Component documentation
+- **Questions?** Check the [Storybook documentation](https://static.casinogate.dev/components/master/)
+- **Issues?** Contact the UI team or file an issue
+- **Feature Requests?** Submit a proposal through the team channels
 
 ---
 
-Made with ❤️ by the CG team
+Made with ❤️ by the CasinoGate team