-

2026-01-26 21:37:09 +08:00
parent 2c22685b68
commit 2b8f0892f4
5 changed files with 234 additions and 452 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,164 @@
+# 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.
+