ui-components

UI Component Standardization Rules

Overview

All UI components (buttons, text, forms) MUST use standardized components from Client/packages/ui/ (import via packages/ui, @/components/ui, or @ui per Client/tsconfig.base.json). Custom implementations are FORBIDDEN unless explicitly approved.

Standardized Components

Layout Primitives (Box / View)

• Use a unified layout primitive (e.g. Box or View) for block-level layout instead of raw <div> or framework-specific containers. <div> (block) vs RN <View> (flex column by default) is a major source of layout bugs when sharing or migrating code.
• Rule: Prefer a shared Box (or equivalent) that standardizes flex defaults and behavior across web and (when present) React Native, so one mental model applies and moving folders does not break layout.

Buttons

Location: Client/packages/ui/components/button/

Available Components:

• Button - Main button component with variants (primary, secondary, outline, ghost, danger, success, warning, cancel)
• CancelButton - Standardized cancel button (wrapper around Button with outline/ghost variant)
• CloseButton - Standardized close button with X icon (for modals/dialogs)
• IconButton - Icon-only buttons
• CircularButton - Circular button variant
• NavigationButton - Link-like navigation buttons
• NavigationButtons - Navigation button groups
• RefreshButton - Specialized refresh button

Rules:

• ❌ NEVER create custom <button> elements with inline className styles
• ❌ NEVER use raw button elements with custom padding, colors, or hover states
• ✅ ALWAYS use Button component for standard buttons
• ✅ ALWAYS use CancelButton for cancel actions
• ✅ ALWAYS use CloseButton for closing modals/dialogs
• ✅ ALWAYS use IconButton for icon-only buttons
• ✅ ALWAYS import from packages/ui (barrel), @/components/ui, or @ui — not ad-hoc paths under apps/web

Examples:

// ❌ WRONG: Custom button implementation
<button
  onClick={handleClick}
  className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
>
  Click me
</button>

// ✅ CORRECT: Use Button component
import { Button } from "../ui";

<Button variant="primary" size="md" onClick={handleClick}>
  Click me
</Button>

// ❌ WRONG: Custom cancel button
<button
  onClick={onCancel}
  className="px-4 py-2 border border-gray-300 bg-white rounded hover:bg-gray-50"
>
  Cancel
</button>

// ✅ CORRECT: Use CancelButton
import { CancelButton } from "../ui";

<CancelButton onClick={onCancel} size="md">
  Cancel
</CancelButton>

// ❌ WRONG: Custom close button
<button onClick={onClose} className="absolute right-2 top-2 text-gray-400">
  <X className="w-5 h-5" />
</button>

// ✅ CORRECT: Use CloseButton
import { CloseButton } from "../ui";

<CloseButton onClick={onClose} size="sm" className="absolute right-2 top-2" />