shadcn-slint/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Slint UI component library inspired by shadcn/ui, implementing a comprehensive set of reusable UI components with theme support (light/dark mode), smooth animations, and a modern design system. The project is written in Rust with Slint for the UI layer.

## Build and Development Commands

### Building and Running
```bash
# Build and run the application
cargo run

# Build in release mode
cargo run --release

# Build only (without running)
cargo build

# Clean build artifacts
cargo clean
```

### Development Workflow
- The build process uses `slint-build` (configured in `build.rs`) to compile `.slint` files
- Entry point: `ui/demo.slint` (specified in `build.rs:2`)
- Rust entry point: `src/main.rs`
- Changes to `.slint` files require a rebuild to take effect

## Architecture

### Project Structure

```
ui/
├── demo.slint              # Main application entry point
├── appwindow.slint         # Basic window component (not used in demo)
├── components/             # Reusable UI components
│   ├── badge.slint
│   ├── button.slint
│   ├── card.slint
│   ├── dialog.slint
│   ├── input.slint
│   ├── item.slint
│   ├── sidebar.slint
│   └── toast.slint
├── theme/                  # Design system
│   ├── colors.slint        # Color palettes (light/dark)
│   ├── spacing.slint       # Spacing and sizing system
│   ├── theme.slint         # Global theme manager
│   └── typography.slint    # Font system
└── utils/
    └── animations.slint    # Animation utilities

src/
└── main.rs                 # Rust application logic
```

### Theme System

The theme system is centralized through a global `Theme` singleton (`ui/theme/theme.slint`):

- **Theme Manager**: `Theme` global provides reactive theme state
  - `Theme.is-dark-mode`: Boolean controlling current theme
  - `Theme.colors`: Reactive color palette that switches between light/dark
  - `Theme.toggle-theme()`: Callback to switch themes

- **Color Palettes**: Defined in `ui/theme/colors.slint`
  - `LightColors.palette`: Light mode colors (shadcn zinc theme)
  - `DarkColors.palette`: Dark mode colors
  - All colors follow the `ColorPalette` struct with semantic naming (primary, secondary, destructive, muted, etc.)

- **Design Tokens**:
  - `Typography`: Font sizes, weights, and line heights
  - `SpacingSystem`: Consistent spacing scale and border radii
  - `Animations`: Duration and easing presets

### Component Architecture

All components follow shadcn/ui design patterns:

1. **Variant-based styling**: Components accept `variant` property (e.g., "default", "destructive", "outline", "secondary", "ghost")
2. **Size variants**: Most components support `size` property ("sm", "md", "lg")
3. **State management**: Visual states (hover, pressed, disabled) use Slint's `states` blocks with sm transitions
4. **Theming**: All components reference `Theme.colors` for reactive theme switching

### Rust-Slint Integration

The Rust code (`src/main.rs`) handles:

- **Component instantiation**: `Demo::new()` creates the UI
- **Callback handlers**: Rust implements callbacks defined in Slint (e.g., `on_add_task`, `on_show_toast`)
- **State management**: Complex state like toast notifications managed via `VecModel` and `ModelRc`
- **Timers**: Auto-dismiss functionality for toasts using `slint::Timer::single_shot()`

Key pattern: Use weak references (`ui.as_weak()`) in callbacks to avoid circular references.

## Component Development Guidelines

### Creating New Components

1. Create `.slint` file in `ui/components/`
2. Import theme system: `import { Theme, Typography, SpacingSystem } from "../theme/theme.slint";`
3. Define component with:
   - Public properties (`in property`, `in-out property`)
   - Callbacks for interactions
   - Private properties for computed values
   - Main container with theme-aware styling
   - State blocks for interactive feedback

4. Use consistent patterns:
   - Border radius: `SpacingSystem.radius.md`
   - Spacing: `SpacingSystem.spacing.s2`, `s3`, `s4`, etc.
   - Colors: Always reference `Theme.colors.*`
   - Animations: Use `Animations.durations.*` and `Animations.ease-*`

### Visual Feedback Pattern

Components use overlay rectangles for hover/press states (see `ui/components/button.slint:59-78`):
- `hover-overlay`: Light overlay (#ffffff15) on hover
- `press-overlay`: Dark overlay (#00000040) on press
- Animate with `Animations.durations.fast` for smooth transitions

### Adding Rust Callbacks

1. Define callback in Slint: `callback my-action(string);`
2. Implement in Rust:
   ```rust
   let ui_weak = ui.as_weak();
   ui.on_my_action(move |param| {
       let ui = ui_weak.unwrap();
       // Handle action
   });
   ```

## Design System Values

### Color Semantic Naming
- `background` / `foreground`: Base colors
- `primary` / `primary-foreground`: Primary actions
- `secondary` / `secondary-foreground`: Secondary actions
- `destructive` / `destructive-foreground`: Dangerous actions
- `muted` / `muted-foreground`: Subtle/disabled states
- `border`, `input`, `ring`: UI element colors

### Spacing Scale
- `s1` through `s12`: Incremental spacing (s1 = 4px, s2 = 8px, etc.)
- `radius`: Border radius variants (sm, md, lg, full)

### Typography Scale
- Sizes: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`
- Weights: `normal`, `medium`, `semibold`, `bold`

## Current Demo Application

The demo (`ui/demo.slint`) showcases a task manager with three views:
- **Tasks**: Add/manage tasks with cards, badges, and toasts
- **Components**: Visual showcase of all component variants
- **Settings**: Theme toggle and app information

The sidebar navigation uses a collapsible pattern with icon + label layout.