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

# 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:

   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.