+
+
+A radius must govern the entire visible surface, not just its border. Exposed
+corners remain transparent to the surface behind them; child backgrounds,
+selection fills, and scrolling content must also follow the boundary. In GPUI,
+do not assume a rounded parent clips its descendants. Give inner surfaces their
+own radius or an appropriate clip, then inspect the composition against a
+contrasting background in both themes. Preserve outward focus rings when
+choosing a clip.
+
+Use a compact spacing scale and repeat it. Related label/control pairs should
+be closer than separate groups; separate groups should be closer than separate
+sections. Prefer component sizes (`xsmall`, `small`, default medium, `large`)
+over one-off heights. Use compact variants for toolbars and data-dense screens,
+not to squeeze an unclear layout into less space.
+
+The shared semantic scale is intentionally small: spacing progresses through
+roughly 2, 4, 8, 12, 16, 24, and 32 pixels, while typography stays near 12,
+14, 16, 18, and 20 pixels. Treat these as relationships rather than permission
+to scatter their current values through feature code. GPUI Component currently
+projects a fixed default `SpacingTokens` scale from its global `Theme`; unlike
+colors and radii, `Theme::apply_semantic_tokens` does not persist a custom
+spacing scale. An application that needs different spacing must own that full
+token snapshot and use it consistently in its application components.
+
+### Spatial grammar
+
+Spacing expresses relationship. Choose a gap from the semantic scale by asking
+what the two things mean to each other:
+
+| Relationship | Typical token | Current scale | Examples |
+| --- | --- | --- | --- |
+| Optical correction | `xxs` | 2 px | icon baseline, compact separator |
+| Parts of one control | `xs` | 4 px | menu icon/label, title/description |
+| Closely related controls | `sm` | 8 px | button icon/label, dialog actions |
+| One content group | `md` | 12 px | notification columns, compact form rows |
+| Separate groups in one section | `lg` | 16 px | panel padding, form groups |
+| Separate sections | `xl` | 24 px | major blocks in a page or inspector |
+| Major region boundary | `xxl` | 32 px | empty-state breathing room, page bands |
+
+These values describe the current default scale, not literals to repeat. Use
+`cx.theme().spacing_tokens()` or the corresponding GPUI scale helpers for the
+ecosystem default. A product-owned scale should preserve the ordering and
+relationships and must be passed through the application's own design-system
+context rather than assumed to persist in the global GPUI Component theme.
+
+Use these rules when resolving horizontal and vertical space:
+
+1. **Inside before outside.** A component's padding belongs to the component;
+ the gap between components belongs to their parent.
+2. **Vertical rhythm shows grouping.** The gap between a title and its
+ description is smaller than the gap from that description to the next
+ section. Equal gaps imply equal relationships.
+3. **Horizontal space supports scanning.** Repeated rows keep icons, labels,
+ values, badges, and trailing actions on stable columns.
+4. **Leading and trailing are semantic.** Think in reading-order edges even
+ when the current API uses left/right; this keeps future RTL adaptation
+ possible.
+5. **Do not double padding.** A card placed in an already padded panel should
+ not automatically add another full panel inset.
+6. **Use optical alignment sparingly.** A one- or two-pixel correction is valid
+ for icon or glyph geometry, but document why it differs from the scale.
+
+Common compositions in the current system illustrate the relationships:
+
+- button contents use 4 px at small sizes and 8 px at normal sizes;
+- dialog headers and footers use an 8 px internal gap;
+- compact list and menu rows use 4 px vertical and 8–12 px horizontal padding;
+- sheet headers use about 16 px leading and 12 px trailing space, leaving room
+ for a close affordance, while footers use 16 px horizontal and 12 px vertical
+ space;
+- notifications use 16 px horizontal padding and a 12 px column gap because
+ icon, message, and action are distinct groups.
+
+Do not treat these as copy-and-paste recipes for every surface. They reveal the
+system: controls are tighter internally, rows optimize scanning, and
+containers spend more space at their boundary than between their contents.
+
+### Proportion and layer hierarchy
+
+Start with content requirements, then set proportions. Avoid arbitrary halves
+when one pane has a clearly different role.
+
+- A navigation sidebar should be wide enough for stable labels but visibly
+ subordinate to the work area. Give it a minimum, preferred, and maximum
+ width rather than a percentage alone.
+- In master–detail layouts, let the collection remain scannable and give the
+ detail pane the surplus. A roughly one-third/two-thirds starting point is
+ often useful, but content constraints are authoritative.
+- Inspectors and auxiliary sheets should not cover the primary object by
+ default. They should be resizable or dismissible when their content grows.
+- Dialog width comes from the decision: short confirmation, medium form, or a
+ dedicated window/page for complex work. Do not enlarge a dialog simply to
+ create whitespace.
+- Reserve the strongest elevation for the topmost decision layer. Within a
+ layer, use background and hairlines—not successively larger shadows—to show
+ hierarchy.
+
+Define three size constraints for every major region: the minimum at which its
+task still works, a comfortable default, and how it consumes surplus. Persist
+user-controlled splits when they represent workflow preference, and clamp
+restored values against the current window.
+
+### Alignment details
+
+Alignment is a structural system, not a final polish pass. Establish a small
+set of alignment spines for each surface: shared leading and trailing edges,
+text baselines, center lines, and fixed functional lanes. Elements at the same
+level should attach to the same spine from top to bottom or leading to trailing,
+even when they are different component types.
+
+
+
+
+Vertical red lines sit beside shared edges or control centers for content,
+status, time, and trailing actions. Horizontal lines sit beneath text baselines
+or pass through a row center to show bottom and vertical-center alignment. The
+compact comparison isolates a one-rendered-pixel drift that must be corrected
+at its structural owner.
+
+- Give sibling regions a shared content inset. A heading, toolbar, list row,
+ empty state, and footer that describe the same level should not each invent a
+ slightly different leading edge.
+- Repeat column geometry through the whole region. Headers, rows, summaries,
+ loading states, and inline editors should reserve the same lanes for identity,
+ metadata, status, numbers, and actions.
+- Align related controls across rows and sections. Form labels, fields,
+ descriptions, and validation messages should reveal a stable vertical grid
+ when the page is scanned from top to bottom.
+- Keep horizontal bands coherent. Items sharing a toolbar, title bar, status
+ bar, or row should use one baseline or center line instead of individually
+ tuned offsets.
+- Introduce indentation only for real hierarchy, containment, or disclosure.
+ Decorative indentation makes siblings look subordinate and breaks the
+ surface's reading line.
+- When a nested level ends, return exactly to the parent spine. Do not let
+ accumulated padding drift across nested containers.
+- Preserve the spine through optional content. Missing icons, badges,
+ descriptions, or trailing actions must not move the remaining labels; use
+ intentional slots or lanes when cross-row comparison matters.
+- Align major regions with one another where their hierarchy matches. Sidebar
+ headers, content titles, split panes, toolbars, and bottom bars need not share
+ every coordinate, but coincident levels should form visible continuous lines.
+
+Not every edge should align. A child can indent, a primary value can lead its
+supporting metadata, and a destructive decision can gain separation. Such
+exceptions must communicate hierarchy or meaning; they must not result from
+uncoordinated component padding. Start with the shared spine, then make the
+exception explicit.
+
+Treat exact alignment and repeated gaps as quality invariants. When two edges
+or spaces are intended to be equal, a one-rendered-pixel difference is a defect,
+not an acceptable optical approximation. Inspect resolved bounds with a
+measurement tool at representative window sizes, zoom levels, and display scale
+factors. Compare coordinates and distances; do not approve alignment only from
+a casual screenshot.
+
+The rendered-pixel tolerance is a verification rule, not permission to patch
+the code with raw pixel offsets. Equal relationships should resolve from the
+same `rem` helper, spacing token, grid definition, or shared component inset.
+Fix the common owner when they differ. Account for fractional layout and device
+rounding so intended spines land on the same physical pixel instead of drifting
+at particular zoom levels.
+
+- Align text by baselines, not by bounding-box centers, when mixed sizes share
+ a row.
+- Center icons in a fixed slot so labels do not move when icons differ in
+ intrinsic width.
+- Right-align comparable numbers; left-align prose and identifiers unless the
+ locale requires otherwise.
+- Keep trailing row actions and disclosure indicators in fixed-width lanes.
+- Align form controls by their interactive frame, not by help text below them.
+- Use `justify_between` only when the two sides truly own opposite edges; it
+ should not disguise missing structure in the middle.
+- Hairlines belong on the boundary owner. Two adjacent regions must not each
+ draw the same separator.
+- A scrollbar belongs to the region that scrolls and sits against that panel,
+ editor, or window's trailing edge. Content padding may inset text and rows;
+ it must not pull the scrollbar into the middle of the surface. Reserve a
+ deliberate scrollbar gutter when content needs clearance.
+
+### Density tiers
+
+Medium is the ecosystem default. Change density for the whole local context,
+not one isolated control:
+
+- **comfortable / large:** onboarding, sparse forms, prominent decisions;
+- **standard / medium:** most application chrome and workflows;
+- **compact / small:** toolbars, menus, tables, and repeated professional data;
+- **extra compact / xsmall:** exceptional high-density utilities, never the
+ automatic choice for an entire application.
+
+The current controls demonstrate a bounded scale rather than arbitrary sizing:
+buttons commonly move through approximately 20, 24, and 32 px frames; input
+and data controls may extend to about 44 px at large size; table rows use about
+26, 30, 32, and 40 px. Use the component's `Size` API so typography, icon,
+padding, and hit target change together. A custom height that changes only the
+outer box is usually incomplete.
+
+### Zoom, base font, and `rem`
+
+A well-designed `rem` system preserves hierarchy while the interface zooms.
+Zoom is successful when the relationship between title and body, control and
+icon, inner and outer spacing, primary and secondary regions still feels the
+same at every scale—not merely when every object becomes larger.
+
+GPUI Component adopts the relative-scale idea familiar from Tailwind. The
+theme's base `font_size` becomes the window's `rem` through `Root`, and GPUI
+scale helpers such as `text_sm()`, `gap_2()`, `p_4()`, `h_8()`, and `size_4()`
+resolve against it. This gives typography, spacing, controls, and icons one
+shared zoom axis.
+
+Design in ratios:
+
+- type steps keep the same hierarchy around the base body size;
+- spacing steps keep the same grouping relationships around the type;
+- control frames, icons, and hit targets scale with their labels;
+- pane minima and comfortable widths account for the scaled content;
+- corner radii and focus treatment remain optically consistent with the
+ control frame.
+
+Do not implement zoom by changing text size alone. A larger label inside a
+fixed-height button, a larger document inside fixed pane minima, or larger rows
+inside a stale virtual-list measurement destroys the original rhythm and can
+clip content. Conversely, multiplying every physical pixel—including
+hairlines—can make the interface visually heavy.
+
+As a rule, application layout should not call `px(...)` directly. Use GPUI's
+rem-based scale helpers (`p_2`, `gap_3`, `w_64`, `text_sm`, and related
+builders) or semantic component sizes. Use fixed pixels only when the value
+represents a physical or raster boundary:
+a one-device-pixel hairline, platform window inset, bitmap dimension, minimum
+hit-test tolerance, or geometry that must match an external surface. These are
+audited, documented exceptions. Product spacing, typography, icon size, and
+ordinary control geometry stay on the relative scale.
+
+Test interface zoom at several base-font values, not just the default. Verify
+hierarchy, wrapping, truncation, minimum window size, pane resizing, focus-ring
+clearance, popup placement, and virtualized row measurement. Also distinguish
+interface zoom from Dock's panel zoom: Dock zoom makes one container fill its
+area while retaining its chrome; it does not change `rem` or application scale.
+
+### Surfaces and elevation
+
+Use elevation to explain stacking, not importance. The base window surface is
+flat; separators and background contrast define its regions. Popovers, menus,
+dialogs, and notifications may use progressively stronger shadows because they
+sit above other content. Do not put a shadow on every card.
+
+All surfaces of the same kind should share one treatment. GPUI Component, for
+example, deliberately gives popup families one themed popover surface so
+Popover, Select, Combobox, DatePicker, and menus do not drift apart. When an
+application invents another anchored surface, reuse that semantic treatment
+instead of approximating it with unrelated border and shadow literals.
+
+### Typography and icons
+
+Use the platform UI font for interface text and monospace only for code,
+identifiers, shortcuts, and aligned numeric data. Keep body text readable and
+avoid excessive uppercase or letter spacing, especially for CJK text.
+
+Use one icon family in a product. Icons supplement labels; they should not
+replace unfamiliar actions with guesswork. Icon-only buttons always need an
+accessible name. Their visual explanation follows the tooltip policy below.
+Use filled or colored icons to communicate a state, not merely to make a
+toolbar lively.
+
+## Layout patterns
+
+### Choose a stable shell
+
+Most applications should use one of these shells:
+
+- **single workspace:** toolbar or title bar above one primary view;
+- **sidebar workspace:** persistent navigation beside a changing detail view;
+- **master–detail:** resizable collection and detail panes;
+- **document workspace:** tabs or a dock area for multiple long-lived objects;
+- **utility window:** one focused task with a short, fixed action path.
+
+Keep global navigation stable while content changes. Give the primary work area
+the remaining space with `flex_1()` and `min_w_0()` / `min_h_0()` where
+overflowing children must shrink. Use `Scrollable`, `VirtualList`, `Table`, or
+`DockArea` for their intended behavior instead of rebuilding scrolling or pane
+management from nested `div`s.
+
+The title bar is window chrome first. Preserve its drag region and avoid
+binding ordinary title clicks to infrequent editing commands. Rename belongs
+behind an explicit object command, with a keyboard path where appropriate.
+
+### Responsive desktop windows
+
+Desktop does not mean fixed-size. Decide what happens as a window narrows:
+
+1. preserve the primary task;
+2. allow resizable regions to reach a documented minimum;
+3. collapse secondary labels or inspectors;
+4. move low-frequency actions into a menu;
+5. scroll only the region whose content actually overflows.
+
+Do not hide an action without providing another path to it. Avoid making the
+entire window scroll when only a list or document body should scroll.
+
+GPUI flex layouts have the same intrinsic-size pressure found in other layout
+systems: a `flex_1()` child may still refuse to shrink around long content.
+Design and implementation must agree on which panes may shrink, truncate, wrap,
+or scroll. A clipped region also clips an outward focus ring; never trade away
+keyboard visibility merely to simplify overflow.
+
+### Forms and settings
+
+Use a visible label for each field and place help or validation next to the
+field it describes. Align related fields, but do not force long labels into a
+narrow fixed column. Use the appropriate control: `Checkbox` for independent
+choices, `RadioGroup` for a small visible set, `Select` for a longer set, and
+`Switch` for a setting that takes effect immediately.
+
+Disable submission while an operation is in flight, keep the user's input, and
+show the result near the action. Reserve dialogs for short, focused decisions;
+use a full page or sheet for workflows that need exploration or many fields.
+
+A loading treatment must represent actual waiting. Switching between settings
+panels whose content is already available should be immediate; a skeleton is
+appropriate only while content is genuinely loading and its shape is known.
+
+## Components and composition
+
+Follow the Shadcn principle that components are building material rather than a
+sealed design system. GPUI Component supplies coherent defaults, while the
+application owns composition and product semantics.
+
+- Use component variants by meaning. Primary is reserved for the explicit
+ default commit in a decision area—normally the action invoked by Enter. A
+ lone, frequent, or desirable action is not automatically primary. An `Add`
+ command in a management toolbar normally uses a default Button; a form's
+ default `Create` commit may use primary. Use `danger` for destructive
+ commitment and `ghost` for quiet toolbar actions.
+- Prefer explicit compound parts and render callbacks over styling arbitrary
+ descendants.
+- Keep a repeated pattern consistent across the product. Wrap it in an
+ application component when it carries domain language or policy.
+- Use the standard component for its semantic role. A menu, dropdown menu,
+ popover, select, and command palette are not interchangeable boxes; each owns
+ different selection, focus, keyboard, dismissal, and layout contracts.
+- Preserve the component family's geometry. Menu rows share vertical and
+ horizontal padding, height, icon and checkmark slots, separators, radius, and
+ state treatment. Do not imitate one menu with a custom popup whose spacing
+ only approximates the system.
+- Do not wrap a library component merely to rename every method or freeze all
+ of its capabilities.
+- Move reusable behavior without product styling to `gpui-base`; keep themed,
+ opinionated presentation in GPUI Component or the application.
+
+## Interaction states
+
+### Make the result understandable before the click
+
+A control should predict its result. Use familiar desktop controls and
+placement so people can act without learning the interface first. Its label
+names the action and object, its state shows availability, and its feedback
+confirms the same outcome.
+
+Do not label a Button `Save` if it opens a configuration flow, or `Delete` if
+it only removes an item from a group. Name the scope when context does not make
+it clear. Respond immediately to activation, prevent duplicate submission
+during longer work, and show the result near the object that changed. Add a
+success message only when the result itself is not visible.
+
+Every interactive control should be designed for:
+
+| State | Design requirement |
+| --- | --- |
+| Rest | Clear affordance without visual noise |
+| Hover | Subtle pointer feedback, never the only cue |
+| Pressed | Immediate press feedback |
+| Open / pressed | Persistent feedback while an attached popup is open |
+| Focus visible | High-contrast keyboard focus ring |
+| Selected / checked | Persistent state distinct from hover |
+| Disabled | Lower emphasis and no misleading hover/pressed response |
+| Loading | Preserve context, prevent duplicate action, explain long waits |
+| Error | State what happened and how to recover |
+
+Use GPUI's focus system and Actions for commands that should work from the
+keyboard. Match familiar desktop shortcuts, expose shortcuts in menus or
+tooltips, and keep focus in a logical place after opening or dismissing an
+overlay.
+
+Selection is part of the information model, not optional polish. Tabs,
+segmented choices, selectable rows, filters, and navigation destinations must
+show a persistent selected state. A Button that owns a dropdown must remain
+visibly pressed or open until the popup closes; hover alone cannot explain the
+relationship between trigger and surface.
+
+In a segmented control, the selected fill and unselected surface must share
+the container's silhouette. Neither may square off an end corner or make a
+boundary appear heavier than its peers.
+
+Show a selected navigation item, list row, or tab through the item's own
+surface: a selected fill, stronger foreground, or heavier weight. Do not add a
+leading-edge bar or one-sided border as the selection marker. It is a web
+template habit, not a desktop convention; it breaks the item's rounded
+silhouette and adds a second, competing edge to a column that already aligns
+on its text.
+
+For destructive actions, distinguish between reversible and irreversible work.
+Prefer undo or a temporary notification for reversible changes. Use an
+`AlertDialog` when the consequence is serious and cannot be undone; name the
+specific object and consequence in the confirmation copy.
+
+### Pointer conventions
+
+Use the default arrow cursor for buttons, checkboxes, menu items, tabs, and
+other native controls. Use a pointing hand for links and content that behaves
+as a link. Use text, resize, grab, and prohibited cursors only when they
+describe the active manipulation. A cursor reinforces an affordance; it does
+not replace the control's visible state or accessible role.
+
+Keep hover effects modest because keyboard and accessibility interaction has no
+hover. Do not reveal the only copy of a destructive or essential action on
+hover. Contextual row actions may become quieter at rest if the same commands
+remain available through selection, keyboard, or a context menu.
+
+### Prefer desktop command surfaces over hover toolbars
+
+Use command frequency and scope to choose where an action lives:
+
+- keep the primary or frequent action visible as a labeled Button or familiar
+ toolbar control;
+- put secondary actions for the current region behind a visible
+ `DropdownMenu` trigger;
+- put commands that act on the object under the pointer in a `ContextMenu`;
+- expose the same important command through an Action/key binding when it has a
+ natural keyboard form;
+- use a hover-revealed icon only as a shortcut to a command that remains
+ reachable elsewhere.
+
+This is more than a visual preference. GPUI Component's menu system already
+owns directional keyboard navigation, confirmation and cancellation, disabled
+items, separators, submenus, shortcut presentation, focus transfer and
+restoration, and nested-menu dismissal. A custom strip of hover buttons must
+rebuild those behaviors and is invisible to keyboard-only and many assistive
+technology workflows.
+
+Choose `DropdownMenu` when users need a visible indication that more commands
+exist—for example a toolbar overflow, document actions, or account menu. Choose
+`ContextMenu` for selection- or object-scoped commands such as rename,
+duplicate, reveal, or remove. The context menu must not be the only way to
+perform an essential command; provide a menu-bar, toolbar, keyboard, or detail
+view path as appropriate.
+
+Do not put every action into a menu to make a screen look minimal. Discovery
+and speed matter: the main action stays visible, dangerous items remain clearly
+labeled and separated, and a menu item should use the same verb, icon, shortcut,
+enabled state, and result everywhere it appears.
+
+### Button means application action; Link means external resource
+
+Use a Button when activation changes application state, confirms a decision,
+opens a tool, submits data, or runs a command. Choose its treatment by local
+hierarchy:
+
+- primary Button for the one emphasized commitment in a decision area;
+- default Button for ordinary visible actions;
+- outline Button when an action needs a clear boundary with less emphasis;
+- ghost Button for familiar, low-emphasis toolbar and inline actions;
+- icon Button only for a well-known symbol, with an accessible name and a
+ tooltip when meaning or scope is unclear.
+
+Do not assign primary because a Button is the only action on screen, because it
+is placed at the top right, or because the team wants more clicks. Primary
+communicates default commitment and keyboard behavior. If activation is merely
+an ordinary command such as adding an item, opening a tool, or refreshing a
+view, use a default, outline, or ghost Button according to its local hierarchy.
+
+Use an underlined Link only for an external resource target: a URL, web page,
+online documentation, or email address. It uses the pointing-hand cursor
+because its contract is leaving the current application context for that
+resource. Do not use Link styling to make a functional command look quiet. A
+link-shaped Delete, Save, Refresh, Add, Open-menu, or in-app navigation action
+hides the control's affordance and exposes the wrong accessibility role.
+
+“View” does not make an in-app destination a Link. A full report, analysis,
+details panel, or local record still opens through a Button, row, card, tab, or
+disclosure control. Use concise context-aware labels such as `Full analysis`
+when the containing card already establishes what opens; reserve underlining
+for a resource that actually opens in a browser or mail client.
+
+All internal navigation—sidebar rows, tabs, breadcrumbs, list items, opening a
+local view, or switching workspaces—must use the corresponding native component
+or a Button/Action. Visual emphasis is chosen through Button variant or the
+navigation component's selected state, never by lying about semantics.
+
+## Feedback and overlays
+
+Choose the smallest surface that fits the decision:
+
+- tooltip: a short explanation or shortcut;
+- popover: contextual controls that do not interrupt the task;
+- menu: a compact list of actions;
+- notification: asynchronous status that does not require a decision;
+- dialog: a focused decision or short form;
+- alert dialog: explicit confirmation of a consequential action;
+- sheet: supplementary work that benefits from more persistent space.
+
+A tooltip supplies missing meaning; it does not restate an obvious action.
+Reserve it for an unfamiliar symbol, ambiguous scope, or a useful shortcut
+that is otherwise hidden. Repeated, recognizable commands such as Copy and
+Download in a message footer need accessible names and keyboard access, but
+their hover labels add interruption rather than clarity.
+
+An Alert interrupts the visual hierarchy even when it does not open a modal.
+Use it for important, exceptional information that needs attention in the
+current task, not as a decorated container for ordinary descriptions, tips, or
+empty space. Prefer inline help, muted text, or a normal section when the
+content does not require immediate notice or action.
+
+Avoid stacking overlays. Escape should dismiss the topmost dismissible layer,
+and focus should return to the trigger or the next logical target.
+
+An overlay action must refer to an object or state the overlay actually shows.
+For example, expose `Clear history` only when a distinct recent-history section
+is visible and contains entries. Search results, recent items, and favorites
+are different collections; label and separate them instead of merging them
+into one unexplained list. Hide an inapplicable action or disable it with a
+useful reason—do not park an ambiguous trash icon in a footer.
+
+Footer space is not a catch-all for capabilities that lacked a place in the
+design. A footer may present shortcuts, status, or actions that apply to the
+whole surface, but each item must answer: what is its object, why is it
+available now, what scope does it affect, and what visible state changes after
+activation?
+
+## Motion
+
+Motion explains change; it is not ambient decoration. Use short transitions for
+appearance, dismissal, expansion, and spatial continuity. Avoid animating large
+layout changes when opacity or transform communicates the same relationship.
+Honor reduced-motion preferences, never require animation to understand state,
+and do not add a default animation to every component.
+
+Motion policy belongs to the styled or application layer. Base may own the
+lifecycle mechanism or geometry needed for a transition, but it should not
+decide that every product fades or slides. Give independently animated values
+stable identity, and make interruption reverse smoothly from the currently
+sampled value rather than restarting from an old endpoint.
+
+Motion follows the continuity of the interaction. While a pointer or scroll
+position moves among related targets, keep the preview surface stable and
+update its content or position in place. Dismiss it only after the interaction
+ends; repeated fade-out and re-entry on each update reads as flicker.
+
+## Designing data-heavy interfaces
+
+Dense does not mean cramped. In tables, trees, command palettes, editors, and
+docks:
+
+- keep headers and primary row identity visually stable;
+- align comparable values and use tabular numerals where appropriate;
+- distinguish focus, hover, active row, and multi-selection;
+- keep sorting and filtering visible and reversible;
+- preserve selection by domain identity across filtering and reordering;
+- virtualize large collections without changing keyboard semantics;
+- use progressive disclosure for secondary columns and inspectors;
+- provide a useful empty state that explains the next action.
+
+Choose a table for comparison across consistent fields, a list for scanning
+heterogeneous items, a tree for real hierarchy, and a dock only when users need
+to arrange long-lived tools or documents. Do not use a complex data component
+as a visual style.
+
+## Interface language
+
+Words are part of the interface architecture. Write the vocabulary for a
+feature as a system—destinations, objects, commands, states, and outcomes—not as
+isolated translations of implementation features. Prefer the shortest wording
+that remains accurate in its actual context.
+
+### Let context carry context
+
+Do not repeat information that the surrounding surface already establishes. A
+sidebar destination is usually the object or domain itself: use `Users`, not
+`User Management`; `Shortcuts`, not `Shortcut Configuration Management`. A
+column whose rows already contain actions can omit a generic `Operation`
+heading. A dialog titled `Delete “Roadmap”?` does not need body text that asks
+the same question again.
+
+This is context economy, not deletion for its own sake. Add text when it changes
+the decision: identify the affected scope, an irreversible consequence, an
+unusual prerequisite, or a way to recover. Every extra word should answer a
+question the current layout does not already answer.
+
+Use nouns for destinations and objects (`Users`, `Appearance`, `Orders`), verbs
+for commands (`Save`, `Duplicate`, `Export`), and adjectives or short phrases
+for states (`Offline`, `Up to date`, `Pending review`). Avoid wrappers such as
+`Management`, `Module`, `Page`, `Function`, `Operation`, and `System` unless the
+word distinguishes a real domain concept.
+
+### Write each language, do not translate its shape
+
+Start from shared intent, hierarchy, and terminology, then compose each locale
+as natural interface language. Do not preserve the source language's word
+order, number of words, politeness filler, or grammatical category. English
+`Users` can express a Chinese feature concept that would literally expand to
+“user management”; fidelity means preserving purpose, not preserving tokens.
+
+Remove words supplied by the enclosing information architecture. Inside a
+`Settings` surface, a destination is often simply `Account`, not `Account
+Settings` and never the unnatural singular `Account Setting`. The correct
+English label is chosen from its role and neighbors, not from the standalone
+source phrase.
+
+Maintain a small product lexicon for recurring objects, commands, and states.
+Use the same term in the toolbar, menu, context menu, dialog, shortcut search,
+and documentation unless the context genuinely changes its meaning. Review
+copy in the rendered surface: neighboring labels often reveal repetition or
+inconsistent scope that a locale file cannot.
+
+In localized technical writing, preserve an established framework term when a
+translation would be less precise. Keep API identifiers in their original form
+and format them as code. Do not retain ordinary foreign words merely to sound
+technical. Explain a retained term on first use when needed, then use the same
+form throughout the interface, documentation, and API examples.
+
+### Buttons and confirmation dialogs
+
+Button labels are short by default—usually one or two words—and describe the
+result, not the gesture or the component. Prefer `Save`, `Move`, or `Delete` to
+`Click to save`, `Perform move`, or `Confirm deletion`. Use `Cancel` consistently
+for the action that leaves without committing. Reserve `OK` for acknowledging
+purely informational content.
+
+Short is a default, not a character limit. A deliberately longer label is
+better when its words expose a consequence or distinguish choices that users
+could otherwise confuse, for example `Delete from this group` versus `Delete
+everywhere`, or `Restart without saving`. Length must buy decision-critical
+information; it must not restate the dialog title or body.
+
+Use the most specific concise result as the confirmation label when possible:
+
+| Context | Weak | Prefer |
+| --- | --- | --- |
+| Delete dialog | `Yes`, `Sure`, `Confirm deletion` | `Delete` |
+| Unsaved changes | `Confirm`, `Yes` | `Discard changes` |
+| Pure acknowledgement | `Confirm operation` | `OK` or `Done` |
+| Complex consent whose result has no clear verb | `Yes` | `Confirm` |
+
+`Confirm` is a useful fallback when the surrounding dialog fully names a
+complex commitment and no shorter result verb is accurate. It should not
+replace a clear command. `Sure` is conversational rather than a stable English
+command and is too ambiguous for the standard vocabulary.
+
+A confirmation dialog should form one compact decision:
+
+- title: the decision or condition, such as `Delete “Roadmap”?`;
+- body: only new scope, consequence, or recovery information;
+- actions: `Cancel` and the result, such as `Delete`;
+- destructive styling: applied to the destructive result, not substituted for
+ precise wording.
+
+Avoid generic titles such as `Notice`, `Warning`, `Error`, and `Confirmation`
+when the actual condition can be named. Avoid ritual phrases such as “Are you
+sure you want to…”, “Would you like to…”, “Please note that…”, and “successfully”
+when the structure or state already communicates them. Courtesy should come
+from a calm, respectful tone, not repeated `please`.
+
+### Capitalization, punctuation, and symbols
+
+Use sentence case for English UI by default: `Reset layout`, not `Reset Layout`
+or `RESET LAYOUT`. Preserve proper nouns and established acronyms. Follow a
+platform convention such as title case for native menu commands only when the
+platform integration benefits from it, and apply that convention consistently
+within the component class.
+
+ALL CAPS can provide restrained typographic emphasis for very short section
+labels, eyebrows, statuses, established acronyms, and code-like identifiers.
+Its compact shape and measured tracking can form a level similar to bold type,
+but it does not belong on Buttons, long headings, sentences, or dense lists. Do
+not combine uppercase, strong color, and bold weight in the same region, and do
+not transform every string automatically: product names, acronyms, and localized
+content must preserve their intended casing.
+
+Labels, buttons, menu items, tabs, headings, placeholders, and short states do
+not take a final period. Complete explanatory, warning, and error sentences do.
+Avoid exclamation marks in routine success and failure messages. In Chinese,
+use full-width punctuation in sentences and omit terminal punctuation from
+short control labels by the same semantic rule.
+
+Use the single ellipsis character (`…`), not three periods. Append it to every
+Button or MenuItem that opens a dialog, sheet, or separate window, and to a
+command that requires more input or choices before it can complete, such as
+`Settings…` or `Export…`. An immediately executed command does not take an
+ellipsis. Use an indeterminate progress indicator, not decorative dots, to
+communicate ongoing work.
+
+Errors should say what happened and, when useful, the next recovery action.
+Success feedback should name the resulting state only when that state is not
+already visible. Prefer `Couldn’t save. Check your connection and try again.`
+to a technical code or a long apology; omit a `Saved successfully` toast when
+the document visibly becomes saved.
+
+## Internationalization and platform fit
+
+Copy must survive expansion, CJK typography, and different shortcut notation.
+Do not size a control from one English label. Keep text out of raster assets,
+avoid concatenating translated fragments, and let labels wrap or truncate only
+where the product defines a recovery path such as a tooltip.
+
+Respect platform differences that carry meaning: Command versus Control,
+native window decorations, system appearance, scrollbar behavior, menus, and
+notification capabilities. Keep the product's information architecture stable
+across platforms, but do not erase familiar platform behavior for superficial
+pixel equality.
+
+## Guidance for AI-generated interfaces
+
+An AI changing a GPUI interface should first inspect the nearest feature,
+theme tokens, and component documentation. It should state the primary task,
+state owner, component composition, and keyboard path before generating code.
+It must not infer an API from React/Shadcn examples or invent a GPUI method
+because the name seems plausible.
+
+AI output is incomplete until a human can explain why the hierarchy, density,
+component choice, and exceptional literal values belong in this product. A
+visually plausible screenshot is not proof: keyboard behavior, focus, dynamic
+content, themes, resizing, and failure states are part of the design.
+
+## Accessibility checklist
+
+Before considering a screen complete, verify that:
+
+- every action is reachable and operable by keyboard;
+- focus order follows visual and task order;
+- focus remains visible and is restored after overlays;
+- controls have accessible names; icon-only controls use tooltips when their
+ meaning, scope, or shortcut needs explanation;
+- text and meaningful boundaries have sufficient contrast;
+- status is not communicated by color alone;
+- disabled and read-only states are distinguishable;
+- labels, errors, and descriptions remain near their controls;
+- content remains usable with longer translations and larger text;
+- pointer targets are comfortably sized even in a dense layout.
+
+## Design review checklist
+
+A review does not inventory components; it judges whether the interface made
+the right decisions. Ask, in order:
+
+1. **Is the task clear?** Can a new user recognize the purpose, primary action,
+ and next step without learning, guessing, or experimenting?
+2. **Does every action keep its promise?** Do the label, control, state, scope,
+ feedback, and result describe one consistent outcome?
+3. **Is hierarchy decisive and restrained?** Does the core feature receive the
+ space it deserves while strong color, bold type, badges, alerts, and primary
+ Buttons remain scarce?
+4. **Could the interface do less, better?** Can an entry point, option, or state
+ be removed, combined, or deferred without weakening the complete task?
+5. **Is the structure exact?** Do peers share alignment spines, equal gaps stay
+ equal to the rendered pixel, and scrollbars sit at the edge of their actual
+ scrolling region?
+6. **Does it follow the component system?** Do standard controls retain their
+ geometry, states, keyboard behavior, and dismissal model, with appearance
+ supplied by theme and scale tokens?
+7. **Does it remain usable in every state and constraint?** Verify keyboard and
+ focus behavior, empty/loading/failure/permission states, longer translations,
+ zoom, minimum window size, and reduced motion.
+8. **Has it been tested in a real window?** Complete the task with real
+ components, copy, and representative content—not only an ideal screenshot.
+
+Continue with [Coding Guides](./coding-guides.md) to translate these design
+decisions into GPUI architecture and code.
diff --git a/.agents/skills/gpui-kit/SKILL.md b/.agents/skills/gpui-kit/SKILL.md
new file mode 100644
index 0000000..a67265b
--- /dev/null
+++ b/.agents/skills/gpui-kit/SKILL.md
@@ -0,0 +1,277 @@
+---
+name: gpui-kit
+description: 'How to build desktop applications with GPUI Kit, the Rust framework published as the gpui-kit crate (GPUI plus gpui_kit::component, gpui_kit::base, gpui_kit::assets). Use when setting up a gpui-kit app, choosing or using a component (Button, Input, Select, Dialog, Sheet, Tabs, Sidebar, List, DataTable, Tree, Chart, etc.), handling component state, theming, or window overlays, and for GPUI mechanics: actions and keybindings, async tasks, contexts, custom elements, entities, events, focus, global state, layout and styling, ElementId, and tests including UI integration testing. Holds the normative Coding Guides: read them before any architecture, state-ownership, public API, naming, or testing decision. Pairs with the gpui-kit-design-guides skill for the Design Guides.'
+---
+
+# GPUI Kit
+
+Applications depend on one crate, `gpui-kit`. GPUI is `use gpui_kit::*;`, and
+each layer is reachable by name: `gpui_kit::component` (styled components),
+`gpui_kit::base` (unstyled behavior), `gpui_kit::assets` (default icons),
+`gpui_kit::platform`.
+
+Start with [component-family conventions](references/conventions.md) to choose the constructor, state owner, event, and layout contract for the task. Learn the family once, then verify the specific component supports the capability.
+
+For a complete compiled view with retained state, subscriptions, and overlay
+layers, read [the tested application recipe](references/recipes.md).
+
+## Read the Guides First
+
+Two guides hold the rules this skill assumes. They are requirements, not
+inspiration. Read the guide file itself; do not answer from this page, from a
+similar file in the codebase, or from training data.
+
+| Guide | Read before |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| Design Guides, skill `gpui-kit-design-guides` | Choosing components, layout, spacing, hierarchy, color, density, interaction states, overlays, motion, interface copy |
+| [Coding Guides](references/coding-guides.md) | Crate layering, `RenderOnce` vs `Entity
+
+
+Dependencies point downward. Higher layers own domain meaning and orchestration;
+lower layers own reusable presentation or behavior. Do not make a reusable
+component depend on an application screen, or make `gpui-base` depend on a
+theme from GPUI Component.
+
+Use these boundaries:
+
+- **app shell:** compose windows and feature crates while keeping feature logic out;
+- **feature crate:** keep one capability's model, services, views, commands, dialogs,
+ and workflow behind one public boundary;
+- **app component:** a repeated domain-aware pattern;
+- **gpui-component:** themed, general-purpose UI;
+- **gpui-base:** reusable behavior and geometry without product presentation.
+
+### Organize large applications by capability
+
+In a large Rust application, a feature should usually be a crate, not another
+file in a global `views`, `models`, or `modals` directory. Keep the model,
+views, commands, dialogs, and workflow for one capability together. A dialog
+that edits a workspace belongs to the workspace feature; only the reusable
+dialog primitive belongs to the UI library.
+
+```text
+crates/
+├── app/
+│ └── src/main.rs # Compose windows and features
+├── workspace/
+│ └── src/
+│ ├── lib.rs # The feature's public boundary
+│ ├── model.rs
+│ ├── commands.rs
+│ ├── workspace_view.rs
+│ └── rename_dialog.rs
+├── search/
+│ └── src/
+│ ├── lib.rs
+│ ├── model.rs
+│ ├── commands.rs
+│ ├── search_view.rs
+│ └── filters.rs
+├── settings/
+│ └── src/
+│ ├── lib.rs
+│ ├── model.rs
+│ ├── settings_view.rs
+│ └── account_dialog.rs
+└── shared/
+ └── src/
+ ├── lib.rs
+ └── recent_items.rs # A stable capability with multiple owners
+```
+
+Do not invert this into global `models/`, `views/`, `modals/`, and `commands/`
+directories. Those folders classify files by implementation role while
+scattering every feature across the application.
+
+The application shell composes feature crates but contains little feature
+logic. A feature may depend on stable shared capabilities and UI foundations;
+it must not depend on the shell or reach into a sibling feature's internals.
+When two features need to communicate, prefer an explicit command, event, data
+type, or small shared service over a dependency between their views. Extract a
+shared crate only after the capability has a coherent name and more than one
+real owner.
+
+Crate boundaries are engineering boundaries. They let Cargo rebuild and test a
+smaller dependency subgraph, make ownership visible in `Cargo.toml`, and limit
+the review and regression surface of a change. They also make removal honest:
+a feature that cannot be detached without searching through global view and
+modal directories was never isolated.
+
+Do not create a crate for every screen or helper. Split where a capability has
+its own state and lifecycle, a stable public seam, or enough implementation to
+benefit from independent compilation and tests. Keep dependencies acyclic and
+pointing toward smaller, more stable crates.
+
+## Bootstrap and root ownership
+
+Initialize GPUI Component once, before creating component-backed views, and put
+`Root` at the first level of each window:
+
+```rust
+app.run(move |cx| {
+ gpui_kit::init(cx);
+
+ gpui_kit::open_window(WindowOptions::default(), cx, |window, cx| {
+ cx.new(|cx| Workspace::new(window, cx))
+ })
+ .expect("failed to open window");
+});
+```
+
+`Root` coordinates window-level component facilities such as overlays and
+notifications. Do not create a separate root for each page inside one window.
+It also coordinates modal focus restoration, focus traps, tooltip/menu layers,
+and window-scoped text selection. Bypassing it can produce behavior that looks
+correct at rest but fails when overlays nest or focus changes quickly.
+
+## Understand GPUI's phases and contexts
+
+GPUI is retained state with declarative rendering. An entity survives across
+frames; the element tree returned by `render` is a fresh description of the
+current frame. Keep that distinction explicit.
+
+- `Context`:
+
+```rust
+div().id("my-element") // ElementId from &str
+div().id(42usize) // ElementId from usize
+div().id(ElementId::from(idx)) // Explicit
+```
+
+Without `.id()`, a div cannot receive mouse events or store state.
+
+## Accepted Types
+
+```rust
+impl Into for &str // "my-id"
+impl Into for String // String::from("my-id")
+impl Into for usize // 0, 1, 2, ...
+impl Into for u64
+impl Into for SharedString
+```
+
+## Uniqueness Rules
+
+IDs must be unique within the same **stateful parent's scope** — not globally. GPUI builds a `GlobalElementId` by chaining parent IDs:
+
+```rust
+div().id("app").child(
+ div().id("list1").children(vec![
+ div().id(1usize).child("Item 1"), // GlobalId: ["app", "list1", 1]
+ div().id(2usize).child("Item 2"), // GlobalId: ["app", "list1", 2]
+ ])
+).child(
+ div().id("list2").children(vec![
+ div().id(1usize).child("Item 1"), // GlobalId: ["app", "list2", 1] — no conflict
+ ])
+)
+```
+
+Items in different parent scopes can reuse simple IDs (integers, short strings).
+
+## In Component Structs
+
+Components always store `id: ElementId` and pass it in `new()`:
+
+```rust
+#[derive(IntoElement)]
+pub struct Button {
+ id: ElementId,
+ base: Stateful
,
+ // ...
+}
+
+impl Button {
+ pub fn new(id: impl Into) -> Self {
+ let id = id.into();
+ Self {
+ id: id.clone(),
+ base: div().id(id), // id applied to base
+ // ...
+ }
+ }
+}
+
+impl RenderOnce for Button {
+ fn render(self, _: &mut Window, _: &mut App) -> impl IntoElement {
+ self.base // already has .id() applied
+ .on_click(/* ... */)
+ }
+}
+```
+
+## Usage at Call Sites
+
+```rust
+// Use unique string IDs for named components
+Button::new("save-btn").label("Save")
+Button::new("cancel-btn").label("Cancel")
+
+// Use index-based IDs in lists
+for (i, item) in items.iter().enumerate() {
+ div().id(i) // unique within this parent
+}
+
+// Use descriptive IDs for debugging
+Input::new("search-input")
+Select::new("country-select")
+```
diff --git a/.agents/skills/gpui-kit/references/gpui/element-patterns.md b/.agents/skills/gpui-kit/references/gpui/element-patterns.md
new file mode 100644
index 0000000..31c9e2f
--- /dev/null
+++ b/.agents/skills/gpui-kit/references/gpui/element-patterns.md
@@ -0,0 +1,509 @@
+# Common Element Patterns
+
+**Contents:** [Text Rendering Elements](#text-rendering-elements) · [Container Elements](#container-elements) · [Interactive Elements](#interactive-elements) · [Composite Elements](#composite-elements) · [Scrollable Elements](#scrollable-elements) · [Pattern Selection Guide](#pattern-selection-guide)
+
+## Text Rendering Elements
+
+Elements that display and manipulate text content.
+
+### Pattern Characteristics
+
+- Use `StyledText` for text layout and rendering
+- Handle text selection in `paint` phase with hitbox interaction
+- Create hitboxes for text interaction in `prepaint`
+- Support text highlighting and custom styling via runs
+
+### Implementation Template
+
+```rust
+pub struct TextElement {
+ id: ElementId,
+ text: SharedString,
+ style: TextStyle,
+}
+
+impl Element for TextElement {
+ type RequestLayoutState = StyledText;
+ type PrepaintState = Hitbox;
+
+ fn request_layout(&mut self, .., window: &mut Window, cx: &mut App)
+ -> (LayoutId, StyledText)
+ {
+ let styled_text = StyledText::new(self.text.clone())
+ .with_style(self.style);
+ let (layout_id, _) = styled_text.request_layout(None, None, window, cx);
+ (layout_id, styled_text)
+ }
+
+ fn prepaint(&mut self, .., bounds: Bounds, styled_text: &mut StyledText,
+ window: &mut Window, cx: &mut App) -> Hitbox
+ {
+ styled_text.prepaint(None, None, bounds, &mut (), window, cx);
+ window.insert_hitbox(bounds, HitboxBehavior::Normal)
+ }
+
+ fn paint(&mut self, .., bounds: Bounds, styled_text: &mut StyledText,
+ hitbox: &mut Hitbox, window: &mut Window, cx: &mut App)
+ {
+ styled_text.paint(None, None, bounds, &mut (), &mut (), window, cx);
+ window.set_cursor_style(CursorStyle::IBeam, hitbox);
+ }
+}
+```
+
+### Use Cases
+
+- Code editors with syntax highlighting
+- Rich text displays
+- Labels with custom formatting
+- Selectable text areas
+
+## Container Elements
+
+Elements that manage and layout child elements.
+
+### Pattern Characteristics
+
+- Manage child element layouts and positions
+- Handle scrolling and clipping when needed
+- Implement flex/grid-like layouts
+- Coordinate child interactions and event delegation
+
+### Implementation Template
+
+```rust
+pub struct ContainerElement {
+ id: ElementId,
+ children: Vec,
+ direction: FlexDirection,
+ gap: Pixels,
+}
+
+impl Element for ContainerElement {
+ type RequestLayoutState = Vec;
+ type PrepaintState = Vec>;
+
+ fn request_layout(&mut self, .., window: &mut Window, cx: &mut App)
+ -> (LayoutId, Vec)
+ {
+ let child_layout_ids: Vec<_> = self.children
+ .iter_mut()
+ .map(|child| child.request_layout(window, cx).0)
+ .collect();
+
+ let layout_id = window.request_layout(
+ Style {
+ flex_direction: self.direction,
+ gap: self.gap,
+ ..default()
+ },
+ child_layout_ids.clone(),
+ cx
+ );
+
+ (layout_id, child_layout_ids)
+ }
+
+ fn prepaint(&mut self, .., bounds: Bounds, layout_ids: &mut Vec,
+ window: &mut Window, cx: &mut App) -> Vec>
+ {
+ let mut child_bounds = Vec::new();
+
+ for (child, layout_id) in self.children.iter_mut().zip(layout_ids.iter()) {
+ let child_bound = window.layout_bounds(*layout_id);
+ child.prepaint(child_bound, window, cx);
+ child_bounds.push(child_bound);
+ }
+
+ child_bounds
+ }
+
+ fn paint(&mut self, .., child_bounds: &mut Vec>,
+ window: &mut Window, cx: &mut App)
+ {
+ for (child, bounds) in self.children.iter_mut().zip(child_bounds.iter()) {
+ child.paint(*bounds, window, cx);
+ }
+ }
+}
+```
+
+### Use Cases
+
+- Panels and split views
+- List containers
+- Grid layouts
+- Tab containers
+
+## Interactive Elements
+
+Elements that respond to user input (mouse, keyboard, touch).
+
+### Pattern Characteristics
+
+- Create appropriate hitboxes for interaction areas
+- Handle mouse/keyboard/touch events properly
+- Manage focus and cursor styles
+- Support hover, active, and disabled states
+
+### Implementation Template
+
+```rust
+pub struct InteractiveElement {
+ id: ElementId,
+ content: AnyElement,
+ on_click: Option>,
+ hover_style: Option