Copy page

Frontend

UI Component Library

UI Component Library

Relevant source files

The following files were used as context for generating this wiki page:

• .windsurfintructions
• AGENTS.md
• README.md
• components.json
• docs/ai/README.md
• docs/ai/SKILLS.md
• docs/ai/patterns.md
• docs/gitflow.md
• postcss.config.js
• src/app.css
• src/lib/components/AppTopbar.svelte
• src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte
• src/lib/components/ui/checkbox/checkbox.svelte
• src/lib/components/ui/input-group/input-group-addon.svelte
• src/lib/components/ui/input-group/input-group-button.svelte
• src/lib/components/ui/input-group/input-group-input.svelte
• src/lib/components/ui/input-group/input-group-text.svelte
• src/lib/components/ui/input-group/input-group-textarea.svelte
• src/lib/components/ui/input-group/input-group.svelte
• src/lib/components/ui/textarea/index.ts

The Primebrick frontend employs a two-tier component architecture designed for maximum reusability and maintainability. It separates low-level UI primitives from domain-specific application components, all built using Svelte 5 Runes ($state, $derived, $props) and TailwindCSS v4 AGENTS.md:12-25, README.md:41-48.

Component Hierarchy

The library is organized into two primary directories within src/lib/components/:

Tier	Directory	Description
Primitives	ui/*	Vendored Shadcn-Svelte components (e.g., Button, Input, Checkbox). These are generic, style-focused, and located in src/lib/components/ui/ README.md:37-39.
Domain/App	* (root)	Higher-level components specific to the Primebrick ecosystem (e.g., AppSidebar, CommandPalette, EntityListTable). These wrap primitives to provide business logic README.md:37-39.

UI Primitive Vendor Workflow

Primitives are based on the Shadcn-Svelte registry (Nova style) using Lucide icons components.json:15-17. While vendored, they are often customized to fit the Primebrick design system, such as the Checkbox which includes an indeterminate state src/lib/components/ui/checkbox/checkbox.svelte:11-38.

Data Flow & Coding Standards

All components must follow strict Svelte 5 conventions:

• Props: Passed via $props() with explicit TypeScript interfaces AGENTS.md:16-18.
• Events: Handled via callback functions passed as props (e.g., onclick, onchange) rather than createEventDispatcher AGENTS.md:22-23.
• Composition: Utilizes Snippet for passing HTML or other components as children AGENTS.md:24-25.

Component Architecture Mapping

The following diagram illustrates how "Natural Language" UI requirements map to specific "Code Entities" within the two-tier system.

UI System Entity Mapping

Code
graph TD
    subgraph "Natural Language Space"
        A["'A standard text field'"]
        B["'A grouped input with a prefix'"]
        C["'A toggle for boolean settings'"]
        D["'A complex data grid'"]
    end

    subgraph "Code Entity Space"
        subgraph "UI Primitives (src/lib/components/ui/)"
            A1["Input.svelte"]
            B1["input-group.svelte"]
            B2["input-group-addon.svelte"]
            C1["Switch.svelte"]
        end
        
        subgraph "Domain Components (src/lib/components/)"
            D1["EntityListTable.svelte"]
            D2["AppSidebar.svelte"]
        end
    end

    A --> A1
    B --> B1
    B --> B2
    C --> C1
    D --> D1
    D1 -.-> A1

Sources: README.md:32-40, src/lib/components/ui/input-group/input-group.svelte:1-20, AGENTS.md:27-40

Component Categories

Detailed documentation for specific components is divided into the following child pages:

Form & Input Components

Covers the foundational elements for data entry. This includes standard primitives like Input and Textarea, as well as specialized wrappers like InputGroup for addons and buttons src/lib/components/ui/input-group/input-group-input.svelte:1-22. It also details Checkbox support for indeterminate states src/lib/components/ui/checkbox/checkbox.svelte:1-38 and Zod-integrated error displays.

Date Dropper & Wheel Picker

Documents the custom DateDropper and WheelPicker systems. These components handle complex date/time selections, supporting both CalendarDate and CalendarDateTime types with integrated IANA timezone toggles for global record management.

Navigation & Overlay Components

Focuses on the spatial layout and temporary UI layers. This includes the Sidebar primitive suite (Provider, Trigger, Rail) src/lib/components/AppTopbar.svelte:6-124, DropdownMenu enhancements for row-chrome styling, and the CommandPalette for global keyboard-driven navigation src/lib/components/AppTopbar.svelte:5-128.

Feedback & Display Components

Details how the system communicates state to the user. This covers Alert variants mapped to ImpactLevel (CRITICAL, HIGH, etc.) src/lib/components/AppTopbar.svelte:24-89, Badge color mapping, and the Sonner toast integration. It also includes data visualization tools like the JsonTableViewer and drag-and-drop Sortable utilities.

Theming and Design Tokens

The UI library is powered by a dual-layer CSS variable system defined in src/app.css. It maps standard HSL/OKLCH values to semantic Tailwind v4 tokens like --color-primary, --color-critical, and --color-sidebar-chrome src/app.css:9-71.

Component Style Relationship

Code
graph LR
    subgraph "Design Tokens (src/app.css)"
        T1["--color-primary"]
        T2["--color-critical"]
        T3["--radius-md"]
    end

    subgraph "UI Primitives"
        P1["Button.svelte"]
        P2["Alert.svelte"]
        P3["Input.svelte"]
    end

    subgraph "Domain Logic"
        L1["appErrors Store"]
        L2["ImpactLevel"]
    end

    T1 --> P1
    T2 --> P2
    T3 --> P3
    L1 --> L2
    L2 --> P2

Sources: src/app.css:9-71, src/lib/components/AppTopbar.svelte:24-89, src/lib/errors/app-errors.ts:20

Sources:

• AGENTS.md:12-40
• README.md:20-53
• src/app.css:1-71
• components.json:1-21
• src/lib/components/AppTopbar.svelte:1-180
• src/lib/components/ui/checkbox/checkbox.svelte:1-38
• src/lib/components/ui/input-group/input-group-input.svelte:1-22

---