{"owner":"longbridge","repo":"gpui-component","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGPUI Component is a UI component library for building desktop applications using [GPUI](https://gpui.rs). It provides 60+ cross-platform desktop UI components, inspired by macOS/Windows controls and combined with shadcn/ui design.\n\nThis is a Rust workspace project with the following main crates:\n\n- `crates/ui` - Core UI component library (published as `gpui-component`)\n- `crates/story` - Gallery application for showcasing and testing components\n- `crates/story-web` - Web version of the story gallery (using WebAssembly)\n- `crates/macros` - Procedural macros (`IntoPlot` derive)\n- `crates/assets` - Static assets\n- `crates/webview` - WebView component support\n- `examples/` - Various example applications\n\n## Common Commands\n\n### Development and Testing\n\n```bash\n# Run Story Gallery (component showcase application)\ncargo run\n\n# Run individual examples\ncargo run --example hello_world\ncargo run --example table\n\n# Build the project\ncargo build\n\n# Lint check\ncargo clippy -- --deny warnings\n\n# Format check\ncargo fmt --check\n\n# Spell check\ntypos\n\n# Check for unused dependencies\ncargo machete\n```\n\n### Testing\n\n**Note**: Per user configuration, tests do not need to be run.\n\nFor pure UI visual or sizing adjustments, do not add automated tests solely to\nassert presentation dimensions. Add tests when the change affects behavior,\ninteraction, data flow, or prevents a meaningful regression.\n\n```bash\n# Run all tests\ncargo test --all\n\n# Run tests for a specific crate\ncargo test -p gpui-component\n\n# Run doc tests\ncargo test -p gpui-component --doc\n```\n\n### Performance Profiling\n\n```bash\n# View FPS on macOS (using Metal HUD)\nMTL_HUD_ENABLED=1 cargo run\n\n# Profile performance using samply\nsamply record cargo run\n```\n\n## Core Architecture\n\n### Architecture Refactoring Constraints\n\nThe implemented foundation architecture is documented in\n`docs/ARCHITECTURE.md`, with styling and motion rules in\n`docs/STYLING-AND-MOTION.md`. Preserve these constraints when designing or\nimplementing this architecture:\n\n- Do not modify `gpui-base` unless the user explicitly requests a Base-layer\n  change. By default, implement component behavior and visual styling in\n  `crates/ui` or the application layer.\n\n- Keep `gpui-component` as the ecosystem and product brand.\n- Name the foundation crate `gpui-base`.\n- Follow the ownership boundary: the framework owns behavior and infrastructure;\n  the application owns component source and visual style.\n- Keep the base layer visually unopinionated. It may provide interaction behavior,\n  accessibility, focus, overlay and popup infrastructure, positioning, animation,\n  virtual lists, dock infrastructure, and semantic design tokens.\n- Theme APIs must expose semantic tokens (colors, spacing, radius, typography, and\n  shadows), not an ever-growing set of component-specific styling fields.\n- Keep source distribution or registry tooling above the `gpui-base` seam; no\n  registry or CLI crate is currently part of the workspace.\n- Preserve 100% backward compatibility for existing consumers, including current\n  imports such as `use gpui_component::button::Button;`.\n\n### Component Initialization\n\n**Critical requirement**: You must call `gpui_component::init(cx)` at your application's entry point before using any GPUI Component features.\n\n```rust\nfn main() {\n    let app = Application::new();\n    app.run(move |cx| {\n        // This must be called first\n        gpui_component::init(cx);\n\n        cx.spawn(async move |cx| {\n            cx.open_window(WindowOptions::default(), |window, cx| {\n                let view = cx.new(|_| MyView);\n                // The first level view in a window must be a Root\n                cx.new(|cx| Root::new(view, window, cx))\n            })\n            .expect(\"Failed to open window\");\n        }).detach();\n    });\n}\n```\n\n### Root View System\n\n`Root` is the top-level view for a window and manages:\n\n- Sheet (side panels)\n- Dialog (dialogs)\n- Notification (notifications)\n- Keyboard navigation (Tab/Shift-Tab)\n\nThe first view of every window must be a `Root`.\n\n### Theme System\n\n- Uses `Theme` global singleton for theme configuration\n- Supports light/dark mode switching\n- Access theme via `ActiveTheme` trait: `cx.theme()`\n- Theme configuration includes:\n  - Colors (`ThemeColor`)\n  - Syntax highlighting theme (`HighlightTheme`)\n  - Font configuration (system font and monospace font)\n  - UI parameters like border radius, shadows\n  - Scrollbar display mode\n\n### Dock System\n\nA complex panel layout system supporting:\n\n- **DockArea**: Main container managing center area and left/bottom/right docks\n- **DockItem**: Tree-based layout structure\n  - `Split`: Split layout (horizontal/vertical)\n  - `Tabs`: Tab layout\n  - `Panel`: Individual panel\n- **Panel**: Defined via `PanelView` trait\n- **PanelRegistry**: Global panel registry for serializing/deserializing layouts\n- **StackPanel**: Resizable split panel container\n- **TabPanel**: Tab panel container\n\nThe Dock system supports:\n\n- Panel drag-and-drop reordering\n- Panel zoom\n- Layout locking\n- Layout serialization/restoration\n\n### Input System\n\nText input system based on Rope data structure:\n\n- **InputState**: Input state management\n- **Rope**: Efficient text storage (from ropey crate)\n- LSP integration support (diagnostics, completion, hover)\n- Syntax highlighting support (Tree-sitter)\n- Multiple input modes:\n  - Regular input (`Input`)\n  - Number input (`NumberInput`)\n  - OTP input (`OtpInput`)\n\n### Component Design Principles\n\n1. **Stateless design**: Use `RenderOnce` trait, components should be stateless when possible\n2. **Size system**: Supports `xs`, `sm`, `md` (default), `lg` sizes via `Sizable` trait.\n3. **Mouse cursor**: Buttons use `default` cursor not `pointer` (desktop app convention), unless it's a link button\n4. **Style system**: Provides CSS-like styling API via `Styled` trait and `ElementExt` extensions\n5. **Base controls are no-style**: Base controls and parts do not install layout,\n   positioning, colors, sizing, gaps, radius, borders, shadows, variants, or animation.\n   Complete presentation belongs to `crates/ui` or the application. The deliberate\n   exception is the foundational Base Input frame, which provides only a semantic\n   one-pixel input border and semantic radius baseline; UI/application layers own\n   its background, sizing, padding, typography, adornments, and richer focus style.\n6. **GPUI builder style**: Keep element construction as one fluent builder chain. Express\n   conditions with `when`, `when_some`, `when_none`, and `map`; do not split a chain into a\n   mutable temporary element followed by imperative reassignment when the builder API can\n   express the same operation.\n7. **No `pub` fields on public data types**: A public struct handed across the\n   `gpui-base`/application seam — a state snapshot, capability set, render context, or\n   option set — keeps its fields private, is constructed with a builder, and is read\n   through methods. Adding a `pub` field is a breaking change; adding one behind a builder\n   is not. Setters and readers must not collide: an all-boolean type names setters after\n   the field and readers `is_`/`has_`/`can_`; a type with non-boolean fields prefixes every\n   setter with `with_` and keeps the field name for readers. Value types whose fields are\n   the definition and cannot grow (`Point`, `Selection`, `Edges`) are exempt. See the\n   \"Public Data Types Across the Seam\" section of `docs/ARCHITECTURE.md`.\n8. **Spell `Context` out**: Name a context type `ComboboxTriggerContext`, never `…Ctx`.\n   `cx` is reserved for GPUI's `App`, `Context<T>`, and `AsyncApp`, so `ctx` for anything\n   else reads as a competing context. A callback receiving both takes the GPUI one as `cx`\n   and names the other after what it holds (`trigger`, `state`).\n\n## Code Style\n\n- Follow naming and organization patterns from existing code\n- Reference macOS/Windows control API design for naming\n- AI-generated code must be refactored to match project style\n- Mark AI-generated portions when submitting PRs\n- When creating a PR, inspect previous PR titles in the repository and match\n  that style. Do not blindly use conventional prefixes like `fix:` or `feat:`\n  unless the existing PR title style uses them.\n- When a PR changes the public API of `crates/ui`, add a `## Breaking Changes`\n  section with `diff` blocks showing the old and new usage. See PR #2691 and\n  `.claude/skills/gpui-component-dev/references/pr-description.md`.\n\n## Icon System\n\nThe `Icon` element does not include SVG files by default. You need to:\n\n- Use [Lucide](https://lucide.dev) or other icon libraries\n- Name SVG files according to the `IconName` enum definition (located in `crates/ui/src/icon.rs`)\n\n## Dependencies\n\n- GPUI: Git version from Zed repository\n- Tree-sitter: For syntax highlighting\n- Ropey: Rope data structure for text, and `RopeExt` trait with more features.\n- Markdown rendering: `markdown` crate\n- HTML rendering: `html5ever` (basic support)\n- Charts: Built-in chart components\n- LSP: `lsp-types` crate\n\n## Internationalization\n\nUses `rust-i18n` crate.\n\n- Localization files are located in `crates/ui/locales/`.\n- Only add `en`, `zh-CN`, `zh-HK` by default.\n\n## Documentation\n\n- The documentation site source is in `website/`.\n- Site docs have two locales: English (`website/docs/`) and Chinese (`website/zh-CN/docs/`).\n- When modifying any documentation file, always sync changes to both `en` and `zh-CN` versions.\n- `docs/` holds internal architecture specifications (RFC, migration status, reviews).\n  These are single-language and are not published to the site; see `docs/README.md`.\n\n## Platform Support\n\n- macOS (aarch64, x86_64)\n- Linux (x86_64)\n- Windows (x86_64)\n\nCI runs full test suite on each platform.\n\n## Skills Reference\n\nThis project has custom Claude Code skills to assist with common development tasks:\n\n- **gpui** (`skills/`) - GPUI framework knowledge: actions/keybindings, async, context, custom elements, entity state, events, focus, global state, layout/styling, testing\n- **gpui-component** (`skills/`) - How to use gpui-component: setup, stateless/stateful patterns, common component APIs, theming\n- **gpui-component-dev** (`.claude/skills/`) - Contributing to gpui-component: creating new components, writing stories, writing documentation, writing PR descriptions\n\nWhen working on tasks related to these areas, Claude Code will automatically use the appropriate skill to provide specialized guidance and patterns.\n\n## Testing Guidelines\n\nSee `.claude/COMPONENT_TEST_RULES.md` for detailed testing principles:\n\n- **Simplicity First**: Focus on complex logic and core functionality, avoid excessive simple tests\n- **Builder Pattern Testing**: Every component should have a `test_*_builder` test covering the builder pattern\n- **Complex Logic Testing**: Test conditional branching, state transitions, and edge cases\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGPUI Component is a UI component library for building desktop applications using [GPUI](https://gpui.rs). It provides 60+ cross-platform desktop UI components, inspired by macOS/Windows controls and combined with shadcn/ui design.\n\nThis is a Rust workspace project with the following main crates:\n\n- `crates/ui` - Core UI component library (published as `gpui-component`)\n- `crates/story` - Gallery application for showcasing and testing components\n- `crates/story-web` - Web version of the story gallery (using WebAssembly)\n- `crates/macros` - Procedural macros (`IntoPlot` derive)\n- `crates/assets` - Static assets\n- `crates/webview` - WebView component support\n- `examples/` - Various example applications\n\n## Common Commands\n\n### Development and Testing\n\n```bash\n# Run Story Gallery (component showcase application)\ncargo run\n\n# Run individual examples\ncargo run --example hello_world\ncargo run --example table\n\n# Build the project\ncargo build\n\n# Lint check\ncargo clippy -- --deny warnings\n\n# Format check\ncargo fmt --check\n\n# Spell check\ntypos\n\n# Check for unused dependencies\ncargo machete\n```\n\n### Testing\n\n**Note**: Per user configuration, tests do not need to be run.\n\nFor pure UI visual or sizing adjustments, do not add automated tests solely to\nassert presentation dimensions. Add tests when the change affects behavior,\ninteraction, data flow, or prevents a meaningful regression.\n\n```bash\n# Run all tests\ncargo test --all\n\n# Run tests for a specific crate\ncargo test -p gpui-component\n\n# Run doc tests\ncargo test -p gpui-component --doc\n```\n\n### Performance Profiling\n\n```bash\n# View FPS on macOS (using Metal HUD)\nMTL_HUD_ENABLED=1 cargo run\n\n# Profile performance using samply\nsamply record cargo run\n```\n\n## Core Architecture\n\n### Architecture Refactoring Constraints\n\nThe implemented foundation architecture is documented in\n`docs/ARCHITECTURE.md`, with styling and motion rules in\n`docs/STYLING-AND-MOTION.md`. Preserve these constraints when designing or\nimplementing this architecture:\n\n- Do not modify `gpui-base` unless the user explicitly requests a Base-layer\n  change. By default, implement component behavior and visual styling in\n  `crates/ui` or the application layer.\n\n- Keep `gpui-component` as the ecosystem and product brand.\n- Name the foundation crate `gpui-base`.\n- Follow the ownership boundary: the framework owns behavior and infrastructure;\n  the application owns component source and visual style.\n- Keep the base layer visually unopinionated. It may provide interaction behavior,\n  accessibility, focus, overlay and popup infrastructure, positioning, animation,\n  virtual lists, dock infrastructure, and semantic design tokens.\n- Theme APIs must expose semantic tokens (colors, spacing, radius, typography, and\n  shadows), not an ever-growing set of component-specific styling fields.\n- Keep source distribution or registry tooling above the `gpui-base` seam; no\n  registry or CLI crate is currently part of the workspace.\n- Preserve 100% backward compatibility for existing consumers, including current\n  imports such as `use gpui_component::button::Button;`.\n\n### Component Initialization\n\n**Critical requirement**: You must call `gpui_component::init(cx)` at your application's entry point before using any GPUI Component features.\n\n```rust\nfn main() {\n    let app = Application::new();\n    app.run(move |cx| {\n        // This must be called first\n        gpui_component::init(cx);\n\n        cx.spawn(async move |cx| {\n            cx.open_window(WindowOptions::default(), |window, cx| {\n                let view = cx.new(|_| MyView);\n                // The first level view in a window must be a Root\n                cx.new(|cx| Root::new(view, window, cx))\n            })\n            .expect(\"Failed to open window\");\n        }).detach();\n    });\n}\n```\n\n### Root View System\n\n`Root` is the top-level view for a window and manages:\n\n- Sheet (side panels)\n- Dialog (dialogs)\n- Notification (notifications)\n- Keyboard navigation (Tab/Shift-Tab)\n\nThe first view of every window must be a `Root`.\n\n### Theme System\n\n- Uses `Theme` global singleton for theme configuration\n- Supports light/dark mode switching\n- Access theme via `ActiveTheme` trait: `cx.theme()`\n- Theme configuration includes:\n  - Colors (`ThemeColor`)\n  - Syntax highlighting theme (`HighlightTheme`)\n  - Font configuration (system font and monospace font)\n  - UI parameters like border radius, shadows\n  - Scrollbar display mode\n\n### Dock System\n\nA complex panel layout system supporting:\n\n- **DockArea**: Main container managing center area and left/bottom/right docks\n- **DockItem**: Tree-based layout structure\n  - `Split`: Split layout (horizontal/vertical)\n  - `Tabs`: Tab layout\n  - `Panel`: Individual panel\n- **Panel**: Defined via `PanelView` trait\n- **PanelRegistry**: Global panel registry for serializing/deserializing layouts\n- **StackPanel**: Resizable split panel container\n- **TabPanel**: Tab panel container\n\nThe Dock system supports:\n\n- Panel drag-and-drop reordering\n- Panel zoom\n- Layout locking\n- Layout serialization/restoration\n\n### Input System\n\nText input system based on Rope data structure:\n\n- **InputState**: Input state management\n- **Rope**: Efficient text storage (from ropey crate)\n- LSP integration support (diagnostics, completion, hover)\n- Syntax highlighting support (Tree-sitter)\n- Multiple input modes:\n  - Regular input (`Input`)\n  - Number input (`NumberInput`)\n  - OTP input (`OtpInput`)\n\n### Component Design Principles\n\n1. **Stateless design**: Use `RenderOnce` trait, components should be stateless when possible\n2. **Size system**: Supports `xs`, `sm`, `md` (default), `lg` sizes via `Sizable` trait.\n3. **Mouse cursor**: Buttons use `default` cursor not `pointer` (desktop app convention), unless it's a link button\n4. **Style system**: Provides CSS-like styling API via `Styled` trait and `ElementExt` extensions\n5. **Base controls are no-style**: Base controls and parts do not install layout,\n   positioning, colors, sizing, gaps, radius, borders, shadows, variants, or animation.\n   Complete presentation belongs to `crates/ui` or the application. The deliberate\n   exception is the foundational Base Input frame, which provides only a semantic\n   one-pixel input border and semantic radius baseline; UI/application layers own\n   its background, sizing, padding, typography, adornments, and richer focus style.\n6. **GPUI builder style**: Keep element construction as one fluent builder chain. Express\n   conditions with `when`, `when_some`, `when_none`, and `map`; do not split a chain into a\n   mutable temporary element followed by imperative reassignment when the builder API can\n   express the same operation.\n7. **No `pub` fields on public data types**: A public struct handed across the\n   `gpui-base`/application seam — a state snapshot, capability set, render context, or\n   option set — keeps its fields private, is constructed with a builder, and is read\n   through methods. Adding a `pub` field is a breaking change; adding one behind a builder\n   is not. Setters and readers must not collide: an all-boolean type names setters after\n   the field and readers `is_`/`has_`/`can_`; a type with non-boolean fields prefixes every\n   setter with `with_` and keeps the field name for readers. Value types whose fields are\n   the definition and cannot grow (`Point`, `Selection`, `Edges`) are exempt. See the\n   \"Public Data Types Across the Seam\" section of `docs/ARCHITECTURE.md`.\n8. **Spell `Context` out**: Name a context type `ComboboxTriggerContext`, never `…Ctx`.\n   `cx` is reserved for GPUI's `App`, `Context<T>`, and `AsyncApp`, so `ctx` for anything\n   else reads as a competing context. A callback receiving both takes the GPUI one as `cx`\n   and names the other after what it holds (`trigger`, `state`).\n\n## Code Style\n\n- Follow naming and organization patterns from existing code\n- Reference macOS/Windows control API design for naming\n- AI-generated code must be refactored to match project style\n- Mark AI-generated portions when submitting PRs\n- When creating a PR, inspect previous PR titles in the repository and match\n  that style. Do not blindly use conventional prefixes like `fix:` or `feat:`\n  unless the existing PR title style uses them.\n- When a PR changes the public API of `crates/ui`, add a `## Breaking Changes`\n  section with `diff` blocks showing the old and new usage. See PR #2691 and\n  `.claude/skills/gpui-component-dev/references/pr-description.md`.\n\n## Icon System\n\nThe `Icon` element does not include SVG files by default. You need to:\n\n- Use [Lucide](https://lucide.dev) or other icon libraries\n- Name SVG files according to the `IconName` enum definition (located in `crates/ui/src/icon.rs`)\n\n## Dependencies\n\n- GPUI: Git version from Zed repository\n- Tree-sitter: For syntax highlighting\n- Ropey: Rope data structure for text, and `RopeExt` trait with more features.\n- Markdown rendering: `markdown` crate\n- HTML rendering: `html5ever` (basic support)\n- Charts: Built-in chart components\n- LSP: `lsp-types` crate\n\n## Internationalization\n\nUses `rust-i18n` crate.\n\n- Localization files are located in `crates/ui/locales/`.\n- Only add `en`, `zh-CN`, `zh-HK` by default.\n\n## Documentation\n\n- The documentation site source is in `website/`.\n- Site docs have two locales: English (`website/docs/`) and Chinese (`website/zh-CN/docs/`).\n- When modifying any documentation file, always sync changes to both `en` and `zh-CN` versions.\n- `docs/` holds internal architecture specifications (RFC, migration status, reviews).\n  These are single-language and are not published to the site; see `docs/README.md`.\n\n## Platform Support\n\n- macOS (aarch64, x86_64)\n- Linux (x86_64)\n- Windows (x86_64)\n\nCI runs full test suite on each platform.\n\n## Skills Reference\n\nThis project has custom Claude Code skills to assist with common development tasks:\n\n- **gpui** (`skills/`) - GPUI framework knowledge: actions/keybindings, async, context, custom elements, entity state, events, focus, global state, layout/styling, testing\n- **gpui-component** (`skills/`) - How to use gpui-component: setup, stateless/stateful patterns, common component APIs, theming\n- **gpui-component-dev** (`.claude/skills/`) - Contributing to gpui-component: creating new components, writing stories, writing documentation, writing PR descriptions\n\nWhen working on tasks related to these areas, Claude Code will automatically use the appropriate skill to provide specialized guidance and patterns.\n\n## Testing Guidelines\n\nSee `.claude/COMPONENT_TEST_RULES.md` for detailed testing principles:\n\n- **Simplicity First**: Focus on complex logic and core functionality, avoid excessive simple tests\n- **Builder Pattern Testing**: Every component should have a `test_*_builder` test covering the builder pattern\n- **Complex Logic Testing**: Test conditional branching, state transitions, and edge cases\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nGPUI Component is a UI component library for building desktop applications using [GPUI](https://gpui.rs). It provides 60+ cross-platform desktop UI components, inspired by macOS/Windows controls and combined with shadcn/ui design.\n\nThis is a Rust workspace project with the following main crates:\n\n- `crates/ui` - Core UI component library (published as `gpui-component`)\n- `crates/story` - Gallery application for showcasing and testing components\n- `crates/story-web` - Web version of the story gallery (using WebAssembly)\n- `crates/macros` - Procedural macros (`IntoPlot` derive)\n- `crates/assets` - Static assets\n- `crates/webview` - WebView component support\n- `examples/` - Various example applications\n\n## Common Commands\n\n### Development and Testing\n\n```bash\n# Run Story Gallery (component showcase application)\ncargo run\n\n# Run individual examples\ncargo run --example hello_world\ncargo run --example table\n\n# Build the project\ncargo build\n\n# Lint check\ncargo clippy -- --deny warnings\n\n# Format check\ncargo fmt --check\n\n# Spell check\ntypos\n\n# Check for unused dependencies\ncargo machete\n```\n\n### Testing\n\n**Note**: Per user configuration, tests do not need to be run.\n\nFor pure UI visual or sizing adjustments, do not add automated tests solely to\nassert presentation dimensions. Add tests when the change affects behavior,\ninteraction, data flow, or prevents a meaningful regression.\n\n```bash\n# Run all tests\ncargo test --all\n\n# Run tests for a specific crate\ncargo test -p gpui-component\n\n# Run doc tests\ncargo test -p gpui-component --doc\n```\n\n### Performance Profiling\n\n```bash\n# View FPS on macOS (using Metal HUD)\nMTL_HUD_ENABLED=1 cargo run\n\n# Profile performance using samply\nsamply record cargo run\n```\n\n## Core Architecture\n\n### Architecture Refactoring Constraints\n\nThe implemented foundation architecture is documented in\n`docs/ARCHITECTURE.md`, with styling and motion rules in\n`docs/STYLING-AND-MOTION.md`. Preserve these constraints when designing or\nimplementing this architecture:\n\n- Do not modify `gpui-base` unless the user explicitly requests a Base-layer\n  change. By default, implement component behavior and visual styling in\n  `crates/ui` or the application layer.\n\n- Keep `gpui-component` as the ecosystem and product brand.\n- Name the foundation crate `gpui-base`.\n- Follow the ownership boundary: the framework owns behavior and infrastructure;\n  the application owns component source and visual style.\n- Keep the base layer visually unopinionated. It may provide interaction behavior,\n  accessibility, focus, overlay and popup infrastructure, positioning, animation,\n  virtual lists, dock infrastructure, and semantic design tokens.\n- Theme APIs must expose semantic tokens (colors, spacing, radius, typography, and\n  shadows), not an ever-growing set of component-specific styling fields.\n- Keep source distribution or registry tooling above the `gpui-base` seam; no\n  registry or CLI crate is currently part of the workspace.\n- Preserve 100% backward compatibility for existing consumers, including current\n  imports such as `use gpui_component::button::Button;`.\n\n### Component Initialization\n\n**Critical requirement**: You must call `gpui_component::init(cx)` at your application's entry point before using any GPUI Component features.\n\n```rust\nfn main() {\n    let app = Application::new();\n    app.run(move |cx| {\n        // This must be called first\n        gpui_component::init(cx);\n\n        cx.spawn(async move |cx| {\n            cx.open_window(WindowOptions::default(), |window, cx| {\n                let view = cx.new(|_| MyView);\n                // The first level view in a window must be a Root\n                cx.new(|cx| Root::new(view, window, cx))\n            })\n            .expect(\"Failed to open window\");\n        }).detach();\n    });\n}\n```\n\n### Root View System\n\n`Root` is the top-level view for a window and manages:\n\n- Sheet (side panels)\n- Dialog (dialogs)\n- Notification (notifications)\n- Keyboard navigation (Tab/Shift-Tab)\n\nThe first view of every window must be a `Root`.\n\n### Theme System\n\n- Uses `Theme` global singleton for theme configuration\n- Supports light/dark mode switching\n- Access theme via `ActiveTheme` trait: `cx.theme()`\n- Theme configuration includes:\n  - Colors (`ThemeColor`)\n  - Syntax highlighting theme (`HighlightTheme`)\n  - Font configuration (system font and monospace font)\n  - UI parameters like border radius, shadows\n  - Scrollbar display mode\n\n### Dock System\n\nA complex panel layout system supporting:\n\n- **DockArea**: Main container managing center area and left/bottom/right docks\n- **DockItem**: Tree-based layout structure\n  - `Split`: Split layout (horizontal/vertical)\n  - `Tabs`: Tab layout\n  - `Panel`: Individual panel\n- **Panel**: Defined via `PanelView` trait\n- **PanelRegistry**: Global panel registry for serializing/deserializing layouts\n- **StackPanel**: Resizable split panel container\n- **TabPanel**: Tab panel container\n\nThe Dock system supports:\n\n- Panel drag-and-drop reordering\n- Panel zoom\n- Layout locking\n- Layout serialization/restoration\n\n### Input System\n\nText input system based on Rope data structure:\n\n- **InputState**: Input state management\n- **Rope**: Efficient text storage (from ropey crate)\n- LSP integration support (diagnostics, completion, hover)\n- Syntax highlighting support (Tree-sitter)\n- Multiple input modes:\n  - Regular input (`Input`)\n  - Number input (`NumberInput`)\n  - OTP input (`OtpInput`)\n\n### Component Design Principles\n\n1. **Stateless design**: Use `RenderOnce` trait, components should be stateless when possible\n2. **Size system**: Supports `xs`, `sm`, `md` (default), `lg` sizes via `Sizable` trait.\n3. **Mouse cursor**: Buttons use `default` cursor not `pointer` (desktop app convention), unless it's a link button\n4. **Style system**: Provides CSS-like styling API via `Styled` trait and `ElementExt` extensions\n5. **Base controls are no-style**: Base controls and parts do not install layout,\n   positioning, colors, sizing, gaps, radius, borders, shadows, variants, or animation.\n   Complete presentation belongs to `crates/ui` or the application. The deliberate\n   exception is the foundational Base Input frame, which provides only a semantic\n   one-pixel input border and semantic radius baseline; UI/application layers own\n   its background, sizing, padding, typography, adornments, and richer focus style.\n6. **GPUI builder style**: Keep element construction as one fluent builder chain. Express\n   conditions with `when`, `when_some`, `when_none`, and `map`; do not split a chain into a\n   mutable temporary element followed by imperative reassignment when the builder API can\n   express the same operation.\n7. **No `pub` fields on public data types**: A public struct handed across the\n   `gpui-base`/application seam — a state snapshot, capability set, render context, or\n   option set — keeps its fields private, is constructed with a builder, and is read\n   through methods. Adding a `pub` field is a breaking change; adding one behind a builder\n   is not. Setters and readers must not collide: an all-boolean type names setters after\n   the field and readers `is_`/`has_`/`can_`; a type with non-boolean fields prefixes every\n   setter with `with_` and keeps the field name for readers. Value types whose fields are\n   the definition and cannot grow (`Point`, `Selection`, `Edges`) are exempt. See the\n   \"Public Data Types Across the Seam\" section of `docs/ARCHITECTURE.md`.\n8. **Spell `Context` out**: Name a context type `ComboboxTriggerContext`, never `…Ctx`.\n   `cx` is reserved for GPUI's `App`, `Context<T>`, and `AsyncApp`, so `ctx` for anything\n   else reads as a competing context. A callback receiving both takes the GPUI one as `cx`\n   and names the other after what it holds (`trigger`, `state`).\n\n## Code Style\n\n- Follow naming and organization patterns from existing code\n- Reference macOS/Windows control API design for naming\n- AI-generated code must be refactored to match project style\n- Mark AI-generated portions when submitting PRs\n- When creating a PR, inspect previous PR titles in the repository and match\n  that style. Do not blindly use conventional prefixes like `fix:` or `feat:`\n  unless the existing PR title style uses them.\n- When a PR changes the public API of `crates/ui`, add a `## Breaking Changes`\n  section with `diff` blocks showing the old and new usage. See PR #2691 and\n  `.claude/skills/gpui-component-dev/references/pr-description.md`.\n\n## Icon System\n\nThe `Icon` element does not include SVG files by default. You need to:\n\n- Use [Lucide](https://lucide.dev) or other icon libraries\n- Name SVG files according to the `IconName` enum definition (located in `crates/ui/src/icon.rs`)\n\n## Dependencies\n\n- GPUI: Git version from Zed repository\n- Tree-sitter: For syntax highlighting\n- Ropey: Rope data structure for text, and `RopeExt` trait with more features.\n- Markdown rendering: `markdown` crate\n- HTML rendering: `html5ever` (basic support)\n- Charts: Built-in chart components\n- LSP: `lsp-types` crate\n\n## Internationalization\n\nUses `rust-i18n` crate.\n\n- Localization files are located in `crates/ui/locales/`.\n- Only add `en`, `zh-CN`, `zh-HK` by default.\n\n## Documentation\n\n- The documentation site source is in `website/`.\n- Site docs have two locales: English (`website/docs/`) and Chinese (`website/zh-CN/docs/`).\n- When modifying any documentation file, always sync changes to both `en` and `zh-CN` versions.\n- `docs/` holds internal architecture specifications (RFC, migration status, reviews).\n  These are single-language and are not published to the site; see `docs/README.md`.\n\n## Platform Support\n\n- macOS (aarch64, x86_64)\n- Linux (x86_64)\n- Windows (x86_64)\n\nCI runs full test suite on each platform.\n\n## Skills Reference\n\nThis project has custom Claude Code skills to assist with common development tasks:\n\n- **gpui** (`skills/`) - GPUI framework knowledge: actions/keybindings, async, context, custom elements, entity state, events, focus, global state, layout/styling, testing\n- **gpui-component** (`skills/`) - How to use gpui-component: setup, stateless/stateful patterns, common component APIs, theming\n- **gpui-component-dev** (`.claude/skills/`) - Contributing to gpui-component: creating new components, writing stories, writing documentation, writing PR descriptions\n\nWhen working on tasks related to these areas, Claude Code will automatically use the appropriate skill to provide specialized guidance and patterns.\n\n## Testing Guidelines\n\nSee `.claude/COMPONENT_TEST_RULES.md` for detailed testing principles:\n\n- **Simplicity First**: Focus on complex logic and core functionality, avoid excessive simple tests\n- **Builder Pattern Testing**: Every component should have a `test_*_builder` test covering the builder pattern\n- **Complex Logic Testing**: Test conditional branching, state transitions, and edge cases\n","category":"root","tokens":2749}]}