# Theming & Global Styles # Theming & Global Styles
Relevant source files The following files were used as context for generating this wiki page: - [components.json](components.json) - [postcss.config.js](postcss.config.js) - [src/app.css](src/app.css) - [src/lib/components/AppTopbar.svelte](src/lib/components/AppTopbar.svelte) - [src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte](src/lib/components/entity-list-table/components/EntityListTableHeaderRow.svelte) - [src/lib/components/ui/checkbox/checkbox.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-addon.svelte) - [src/lib/components/ui/input-group/input-group-button.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-input.svelte) - [src/lib/components/ui/input-group/input-group-text.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-textarea.svelte) - [src/lib/components/ui/input-group/input-group.svelte](src/lib/components/ui/input-group/input-group.svelte) - [src/lib/components/ui/textarea/index.ts](src/lib/components/ui/textarea/index.ts)
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 ```mermaid 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](). ```mermaid 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]() ---