ui: design principle for primitive ui components

[meashgrey]

UI Design Principles for Primitive Components

Motivation

As Chitin evolves into an AI-native scientific computing platform, the UI layer needs to remain maintainable and extensible across different domains, including computational chemistry, bioinformatics, materials science, and future workflow-driven applications.

Primitive UI components are the foundation of the entire UI system. Components such as Button, TextInput, Select, Checkbox, and NumberInput will be reused throughout the application and will become long-lived APIs.

This discussion proposes design principles for primitive components to keep the UI architecture stable, composable, and easy to extend.

Core Principle

Primitive components should own interaction behavior, while appearance should remain customizable.

Primitive components should provide reliable behavior and semantic events. Composite components and applications should control composition, layout, and domain-specific meaning.

1. Primitive Components Own Interaction Behavior

Primitive components should encapsulate their own interaction logic, internal state, and semantic events.

For example, TextInput should own:

• text editing behavior
• cursor movement
• selection handling
• keyboard interaction
• IME composition
• focus management

Button should own:

• pressed state
• activation behavior
• keyboard interaction
• focus behavior

Users of these components should not need to handle raw GPUI events such as keyboard or mouse events to implement normal behavior.

For example, consumers should react to semantic events such as:

TextInputEvent::Change
TextInputEvent::Submit
TextInputEvent::Focus

rather than interpreting low-level events themselves. And composite components should use cx.subscribe
to subscribe and react to the events.

Raw GPUI events are implementation details of primitive components.

2. Primitive APIs Should Remain Small and Stable

Primitive components should avoid accumulating scenario-specific configuration flags.

Avoid designs like:

Button {
  toolbar: true,
  window_control: true,
  disable_focus_border: true,
}

or:

TextInput {
  search_mode: true,
  command_mode: true,
}

These usually indicate that the component boundary is incorrect.

Instead, specialized use cases should be implemented through composition.

For example, a window control button should be a composite component built using the Button primitive, rather than adding window-specific behavior into Button.

3. Appearance Should Be Customizable Through Styles

Primitive components should provide predefined theme-based styles for common cases.

Examples:

• Primary
• Secondary
• Transparent

and predefined sizes:

• Small
• Medium
• Large

However, users should also be able to provide custom styles when needed.

For example:

Button::new(state)
  .style(custom_style)

Styles should control appearance only:

• colors
• borders
• radius
• spacing
• typography
• hover appearance
• pressed appearance
• focus appearance

Styles should not change component behavior.

4. State and Events Belong to Primitive Components

Primitive components should own their interaction state.

For example:

TextInputState may contain:

• current text
• selection
• focus state

The state should be the source of truth for the component.

Events should describe semantic changes caused by user interaction.

Examples:

• text changed
• selection changed
• submitted
• cancelled
• focused
• blurred

Events should not expose implementation details such as:

• key pressed
• mouse position
• internal rendering changes

5. Focus Should Be a Shared Capability

Focus management is a common behavior across many interactive components.

Components such as:

• Button
• TextInput
• Select
• TreeView
• Editor

should share a common focus abstraction.

However, focus behavior and focus appearance should remain separate.

A component may support focus behavior but choose a different visual representation.

For example:

• a text input may use a focused border;
• a window control button may not display a focus border;
• a canvas viewport may use another focus indicator.

This difference should be represented through styling rather than additional boolean flags.

6. Primitive Components Should Be Domain-Agnostic

Primitive components should not contain scientific or application-specific concepts.

Examples that do not belong in primitive UI:

• ProteinSequenceInput
• TemperatureInput
• MoleculeSelector
• SimulationParameterEditor

These should be composite or domain-level components built on top of primitives.

For example:

TemperatureInput can be built using NumberInput, adding:

• unit handling
• validation
• scientific semantics

while NumberInput only provides numeric editing behavior.

7. Prefer Composition Over Configuration

When a primitive component accumulates many options, it usually means a composite component should be introduced.

Prefer creating:

• SearchBox built from TextInput
• CommandPaletteInput built from TextInput
• WindowControlButton built from Button

instead of continuously extending the primitive API.

Composition keeps primitives reusable and prevents API growth from becoming unmanageable.

8. Long-Term Goal

Primitive components should form a small, stable foundation for building complex interfaces.

Their responsibilities should remain limited:

• Primitive components define interaction behavior, state, and semantic events.
• Composite components define layout, composition, and reusable UI patterns.
• Domain components define scientific meaning, validation, and workflow behavior.

This separation allows Chitin UI to support complex scientific workflows while keeping the underlying component system maintainable over the long term.

[meashgrey]

The important idea is that Select should not become a "large configurable dropdown widget". Instead, it should be a small primitive with clear responsibilities:

• own selection interaction behavior;
• own keyboard navigation;
• own focus handling;
• emit semantic selection events;
• provide theme-based default styles.

The primitive should not know about the domain meaning of the values.

A possible structure:

Select
 ├── SelectTrigger
 └── SelectContent
      ├── SelectGroup
      │    ├── SelectLabel
      │    └── SelectItem
      └── SelectItem

Similar to shadcn/ui, composition should be preferred over configuration.

For example:

Select::new(state)
  .trigger(
    SelectTrigger::new()
      .placeholder("Select timezone")
  )
  .content(
    SelectContent::new()
      .group(
        SelectGroup::new("Asia")
          .item("China Standard Time")
          .item("Japan Standard Time")
      )
  )

The primitive Select state should own:

• current selected value;
• open/closed state;
• highlighted item;
• keyboard navigation state;
• focus state.

The events should be semantic:

SelectEvent::Change {
    value: T
}
SelectEvent::Open
SelectEvent::Close
SelectEvent::Focus
SelectEvent::Blur

It should not expose:

KeyDown
MouseMove
ClickedItemIndex

because these are GPUI implementation details.

For example, the timezone selector from the desktop settings should not be implemented by adding timezone-specific options into Select. It should compose Select and provide timezone data.

This keeps Select small enough to become a stable foundation component, while still allowing Chitin applications to build complex scientific interfaces on top of it.