Skip to content

UI Component Library & Styles

Jump to bottom
Chazona Baum edited this page Jun 24, 2026 · 1 revision

Relevant source files

This section covers the Lodestar UI system, which is built on Svelte 5 and a "Vesper" design language. The system emphasizes a warm, editorial aesthetic using serif typography and a structured CSS architecture that separates design tokens, element defaults, and component-specific styles.

Design Tokens & Theme

The visual identity of Lodestar is centralized in src/lib/styles/tokens.css. The "Vesper" theme is characterized by:

Global Elements

Global defaults for standard HTML elements are defined in src/lib/styles/elements.css. This ensures that all h1, h2, and form inputs share a baseline style without needing per-component overrides src/lib/styles/elements.css#1-4

Token Category Usage Example Variable
Surfaces Main background and card colors --bg, --card
Text Hierarchical ink colors --ink, --muted, --faint
Semantic Success, Warning, and Danger states --good, --warn, --danger
Space T-shirt scale for padding/margins --sp-1 to --sp-6

Sources:src/lib/styles/tokens.css#1-107src/lib/styles/elements.css#1-48

Core UI Components

Combobox

The Combobox.svelte component is a keyboard-accessible, searchable dropdown. It supports fuzzy matching against both labels and aliases (e.g., searching "AI" matches "Artificial Intelligence") src/lib/combobox.ts#1-20

DomainPicker

A specialized wrapper around the Combobox for managing a list of domain slugs. It renders selected domains as removable chips and filters the available options to exclude already-selected items src/lib/DomainPicker.svelte#8-13

Component Styles

Shared component styles are modularized in src/lib/styles/components/:

Sources:src/lib/Combobox.svelte#1-225src/lib/DomainPicker.svelte#1-39src/lib/combobox.ts#1-20src/lib/highlight.ts#1-15src/lib/labels.ts#48-51

Utility Libraries

Label Humanization

The labels.ts library provides display-only transformations for raw data. It includes a lookup for common industry acronyms (SaaS, API, AI) to ensure they are capitalized correctly src/lib/labels.ts#1-21

Markdown & Security

Lodestar uses marked for Markdown parsing and dompurify for sanitization. This is critical for rendering LLM-generated content or user notes safely src/lib/markdown.ts#4-16

  • renderMarkdown(md): Standard sanitized HTML output.
  • renderNotes(md): Specifically strips the redundant ## Notes header often found in vault files src/lib/markdown.ts#21-24

UI State & Interaction

  • Portal: A Svelte action (use:portal) that moves an element to a target container (defaulting to body) while maintaining Svelte's lifecycle src/lib/portal.ts#1-10
  • Highlight: A utility that splits a string into segments of text and mark: boolean for rendering <mark> tags around search hits src/lib/highlight.ts#5-15

Sources:src/lib/labels.ts#1-51src/lib/markdown.ts#1-25src/lib/highlight.ts#1-15src/lib/portal.ts#1-10

Architecture & Data Flow

Component Interaction Diagram

The following diagram illustrates how the DomainPicker coordinates between the global domainsStore and the generic Combobox component.

flowchart LR
    subgraph subGraph2 ["Utility Space"]
        HL["highlight.ts"]
        LB["labels.ts"]
    end
    subgraph subGraph1 ["Component Space"]
        DP["DomainPicker.svelte"]
        CB["Combobox.svelte"]
    end
    subgraph subGraph0 ["Svelte State Space"]
        DS["domainsStore (Svelte Store)"]
        PICK["pick (Local State)"]
        VAL["value (Bindable Prop)"]
    end
    DS --> DP
    DP --> CB
    CB --> DP
    DP --> VAL
    CB --> HL
    DP --> LB
Loading

Sources:src/lib/DomainPicker.svelte#3-13src/lib/Combobox.svelte#6-22src/lib/highlight.ts#1-5

CSS Architecture & BEM

Lodestar follows a modified BEM (Block Element Modifier) convention for layout styles to prevent leakage between surfaces.

flowchart LR
    subgraph subGraph2 ["Layout Scope (companies.css)"]
        C_BLK[".companies"]
        C_HDR[".companies__header"]
        C_LST[".companies__list"]
        C_ROW[".company-row__name"]
    end
    subgraph subGraph1 ["Component Scope (combobox.css / chip.css)"]
        CBX[".cbx"]
        CHP[".chip"]
    end
    subgraph subGraph0 ["Global Scope (elements.css / tokens.css)"]
        T["--primary"]
        H1["h1"]
        IN["input#91;type='text'#93;"]
    end
    T -.-> CBX
    H1 -.-> C_BLK
    IN -.-> C_HDR
    CBX -.-> C_HDR
    CHP -.-> C_LST
Loading

Sources:src/lib/styles/layout/companies.css#1-15src/lib/styles/elements.css#1-11src/lib/styles/components/combobox.css#10-15

Formatting & Display Logic

The labels.ts utility handles temporal and textual humanization.

Function Input Output
humanize "series_c_plus" "Series C+"
relativeDate "2026-06-10", "2026-06-15" "5d ago"
monogram "Stripe" "St"

Sources:src/lib/labels.ts#1-51src/lib/labels.test.ts#1-45

Clone this wiki locally