Shift UI Components

/ui — Shift Interface Work

Build interfaces that match the supplied design, use Shift's shared primitives and semantic theme, and remain accessible in every interaction state.

Sources of truth

Read these before editing an unfamiliar UI surface:

1. docs/architecture/index.md for documentation routing.
2. packages/ui/docs/DOCS.md for the shared component boundary.
3. apps/desktop/src/renderer/index.css for Tailwind v4 theme tokens, fonts, and custom utilities.
4. The relevant existing component and its neighboring components for local composition and density.
5. Any supplied Figma frame, screenshot, or product reference. Treat it as the visual target, not merely inspiration.

When library behavior or composition is unclear, inspect the installed Base UI types and current Base UI documentation. Do not guess from Radix, shadcn, or an older Base UI API.

Architecture boundary

• Check whether Base UI has a matching primitive before implementing an interactive control.
• Shared primitives live in packages/ui/src/components/{component}/ and wrap @base-ui-components/react/{component}.
• Application code imports shared controls from @shift/ui; never import Base UI directly in the desktop app.
• Keep application state and domain behavior in the consuming app. Shared wrappers own primitive composition, reusable visual defaults, and widget-local behavior only.
• Use the Base UI component name for its Shift wrapper: Button, Menu, Popover, Tooltip, and so on.
• Re-export every shared component and public prop type through its component barrel and packages/ui/src/index.ts.
• Prefer React.ComponentPropsWithoutRef, React.ElementRef, and React.forwardRef so wrappers preserve the primitive contract. Set displayName on forwarded components.
• Compose Base UI triggers with its render prop. Produce exactly one interactive DOM element: no nested buttons, no trigger-only wrapper spans, and no duplicated event targets.
• Use Base UI state attributes such as data-[disabled], data-[highlighted], data-[active], and data-[starting-style] instead of duplicating primitive state in React.

Tailwind and theme tokens

Shift uses Tailwind CSS v4. The renderer theme is declared in the @theme block in apps/desktop/src/renderer/index.css, and that stylesheet scans shared UI source with:

@source "../../../../packages/ui/src/**/*.tsx";

Follow these rules:

• Use semantic theme utilities before raw Tailwind palette colors or literals: bg-surface, bg-panel, bg-input, bg-hover, text-primary, text-secondary, text-muted, border-line-subtle, ring-accent, and related tokens.
• Remember that Shift overrides Tailwind's typography scale: text-sm is 12px, text-ui is 11px, and text-xs is 10px. Check the theme instead of assuming Tailwind defaults.
• Use opacity modifiers on semantic tokens when appropriate, such as bg-hover/50.
• Do not copy legacy hard-coded hex values or generic palette classes when an existing semantic token expresses the role.
• Add a new theme token only for a stable semantic role that will be reused or themed. Name the role, not the component or current color.
• Reserve literal colors and inline styles for genuinely data-driven graphics, canvas/SVG rendering, or platform-defined colors such as native window controls.
• Use cn from @shift/ui or the package-local utility for conditional classes and consumer overrides. Shared wrappers must merge className through cn so tailwind-merge resolves conflicts.
• Keep reusable visual defaults in the shared wrapper. Do not restyle the same primitive independently at many call sites.

Matching a visual reference

Before changing styles, identify the reference's:

• typography and density;
• foreground, background, border, and shadow roles;
• spacing, dimensions, radius, and alignment;
• hover, focus, pressed, selected, disabled, read-only, open, error, and empty states;
• popup side, offset, collision behavior, layering, and arrow treatment.

Map those roles to existing theme tokens first. Compare the finished implementation with the reference at the app's actual scale. Do not declare a match from class names alone.

If the reference is ambiguous or conflicts with an established interaction pattern, ask which behavior wins before inventing a new one.

Large lists and trees

• Before rendering a collection that can grow with glyph points, catalog entries, or document content, estimate the mounted DOM count at realistic scale. Window or paginate unbounded rows; do not map the entire logical collection into React elements merely because scrolling hides most of it.
• Keep the complete logical order for selection and keyboard navigation, but mount only the viewport and a small overscan. Focus, selection, and mounted rows are distinct; an aria-activedescendant must always identify a mounted row. Scroll a keyboard target into the rendered window before publishing it as active.
• Trees are composite widgets: Tab enters/leaves; arrow keys navigate the visible expanded order. Preserve focus and selection through collapse, edits, and manual scrolling. Check the WAI-ARIA tree pattern before inventing per-row keyboard behavior.
• Test both bounded mounted rows and reaching/selecting an offscreen item. Extract a shared virtualizer only when multiple surfaces actually need the same layout and focus contract.