Frontend

Theming & Global Styles

Relevant source files

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

The Primebrick frontend utilizes a dual-layer CSS token system built on Tailwind CSS v4 and PostCSS. This architecture separates raw color definitions (HSL/OKLCH) from semantic application tokens, enabling dynamic dark mode, high-contrast accessibility, and brand-specific "chrome" customization.

1. Dual-Layer Token System

The system is defined in src/app.css. It separates raw color values from the Tailwind theme mapping.

Layer 1: Raw CSS Variables

Raw values are stored as CSS variables within the :root and .dark selectors.

HSL Tokens: Used for standard UI components. They are stored as raw space-separated channels (e.g., 200 98% 39%) to allow Tailwind to apply opacity modifiers src/app.css:114-146.
OKLCH Tokens: Specifically used for Sidebar components to ensure perceptually uniform brightness across the navigation interface src/app.css:148-157.

Layer 2: Tailwind @theme Mapping

The @theme block maps these raw variables to Tailwind utility classes. This allows developers to use standard Tailwind classes like bg-primary or text-critical while the underlying color responds to the current theme src/app.css:9-71.

Tailwind Token	Variable Mapping	Purpose
`primary`	`hsl(var(--primary))`	Main brand color (Sky-700 ish)
`critical`	`hsl(var(--critical))`	High-severity errors (vivid red)
`success`	`hsl(var(--success))`	Validations and positive audits
`sidebar-chrome`	`hsl(var(--sidebar-chrome))`	Branding for the sidebar background
`topbar-chrome`	`hsl(var(--topbar-chrome))`	Branding for the top navigation bar

Sources: src/app.css:9-71, src/app.css:102-165, postcss.config.js:1-6

2. Semantic Color Tokens

The application defines specific semantic tokens to ensure consistency across feedback components like Toasts, Badges, and Alerts.

Critical vs Destructive

Destructive: Standard error state used for "Delete" buttons or destructive actions src/app.css:126-127.
Critical: A more vivid red (--critical: 0 86% 57%) used for system-level failures, high-impact errors, and the "Critical" impact level in the error pipeline src/app.css:132-133.

Chrome Customization

The "Chrome" tokens allow for independent styling of the application shell without affecting the content area:

sidebar-chrome: Controls the sidebar's background and foreground src/app.css:159-160.
topbar-chrome: Controls the top navigation bar's background src/app.css:161-162.

Sources: src/app.css:126-141, src/app.css:159-163

3. Dark Mode Implementation

Dark mode is triggered by a .dark class on the html or body element. The system uses the color-scheme property to signal browser-level adjustments src/app.css:168.

Component Adaptation

Many components include specific logic for dark mode visibility:

Checkboxes/Inputs: In light mode, these use a solid bg-background to maintain visibility on tinted table cells. In dark mode, they shift to bg-input/30 to blend with the darker interface src/lib/components/ui/checkbox/checkbox.svelte:22.
Backdrop Blurs: The Topbar uses backdrop-blur-xs with a semi-transparent bg-muted/25 in dark mode to provide depth src/lib/components/AppTopbar.svelte:119.

Color Token Flow

Code
graph TD
    subgraph "Global CSS (src/app.css)"
        Root[":root (Light)"] -- "--primary: 200 98% 39%" --> Theme
        Dark[".dark (Dark)"] -- "--primary: 210 40% 98%" --> Theme
        Theme["@theme Block"] -- "primary: hsl(var(--primary))" --> TW[Tailwind Utilities]
    end

    subgraph "Component Usage"
        TW -- ".bg-primary" --> Button["Button.svelte"]
        TW -- ".text-critical" --> Badge["Badge.svelte"]
    end

Sources: src/app.css:167-217, src/lib/components/ui/checkbox/checkbox.svelte:22, src/lib/components/AppTopbar.svelte:119

4. Shell & Layout Styling

Topbar Layering

The AppTopbar is defined as a sticky element with a z-index of 30. It implements a 3-column grid (1fr auto 1fr) to ensure the CommandPalette remains perfectly centered regardless of the number of icons in the right-hand track src/lib/components/AppTopbar.svelte:118-122.

Table Header Layering

To maintain usability during scrolling, the EntityListTable headers use complex layering:

Header Row: sticky top-0 with z-80 src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte:61.
Sticky Columns: Checkbox columns and primary keys use sticky left-0 with z-70 to remain visible while scrolling horizontally src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte:66.

Toast & Overlay Z-Index

Toasts: Managed by svelte-sonner.
Sheets/Dialogs: Utilize high z-index values to overlay the Shell.
Z-Index Hierarchy:
1. Table Cells (z-10)
2. Topbar (z-30)
3. Sticky Table Headers (z-80)

Sources: src/lib/components/AppTopbar.svelte:118-122, src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte:61-66

5. Utility Classes & UI Primitives

The codebase includes several specialized utility classes for common UI patterns:

Sortable Drag-Mode

The system utilizes a .sortable-drag utility (integrated via SortableJS) to style elements while they are being moved. This is primarily used in the ColumnsPanel for reordering table columns.

Avatar Hexagon

A custom utility avatar-hex uses clip-path to create a pointy-top hexagon shape, used for organization or user avatars src/app.css:91-94.

Input Groups

The InputGroup system provides a containerized approach to inputs with addons (icons, buttons, or text). It uses has-[:focus-visible] selectors on the parent container to highlight the entire group border when the internal input is focused src/lib/components/ui/input-group/input-group.svelte:18.

Code
graph LR
    IG["InputGroup (Container)"] --> IGA["InputGroupAddon (Icon/Kbd)"]
    IG --> IGC["InputGroupControl (Native Input)"]
    IG --> IGB["InputGroupButton (Action)"]

    subgraph "Styling Logic"
        IGC -- "focus-visible" --> IG
        IG -- "border-ring / ring-3" --> IG
    end

Sources: src/app.css:91-94, src/lib/components/ui/input-group/input-group.svelte:13-24, src/lib/components/ui/input-group/input-group-addon.svelte:3-17

Last modified on July 13, 2026

Table Rendering & View Modes Translation System & Locale Configuration