lexigram-ui

HTMX/htpy component library for Lexigram web applications.

Overview

lexigram-ui provides server-rendered UI primitives — components, layouts, HTMX helpers, and rendering utilities — built on htpy for plain Python templates. It ships with atoms (Button, TextInput, Badge), molecules (Card, Modal, Tabs), organisms (Form, SlideOver), and layouts, all integrated via UIModule for DI wiring and config-driven defaults.

The library ships with ShadCN-compatible CSS variable design tokens in oklch color space, a polymorphic asChild pattern for slot-based composition, and a component CLI (lexigram-ui add) for scaffolding components into your project.

Install

uv add lexigram-ui

Quick Start

from lexigram.di.module import Module, module
from lexigram.ui.module import UIModule
from lexigram.ui.config import UIConfig
from lexigram.ui.atoms import Button
from lexigram.ui.core.base import Component, el, render_to_string


@module(imports=[UIModule.configure(UIConfig(default_theme="default"))])
class AppModule(Module):
    pass


class SavePanel(Component):
    def render(self) -> object:
        return el(
            "section",
            el("h2", "Profile"),
            Button("Save", hx_post="/profile/save"),
            class_="bg-card text-card-foreground p-6 rounded-lg shadow-sm",
        )


html = render_to_string(SavePanel())

Configuration

Zero-config usage: Call UIModule.configure() with no arguments to use all defaults.

flowchart LR
    subgraph Input["Configuration Sources"]
        Y["application.yaml<br/>ui: section"]
        E["Environment vars<br/>LEX_UI__*"]
        P["Python API<br/>UIConfig(...)"]
    end
    UC["UIConfig<br/>merged + validated"]
    UM["UIModule.configure"]
    App["Application"]

    Y --> UC
    E --> UC
    P --> UC
    UC --> UM
    UM --> App

Option 1 — YAML file

# application.yaml
ui:
  default_theme: "default"
  auto_escape: true
  htmx_version: "2.0.4"
  debug_components: false
  theme: light
  enable_sse: false
  enable_realtime: false

Option 2 — Profiles + Environment Variables (recommended)

export LEX_UI__DEFAULT_THEME=default
export LEX_UI__DEBUG_COMPONENTS=false
export LEX_UI__THEME=dark

Option 3 — Python

from lexigram.ui.module import UIModule
from lexigram.ui.config import UIConfig

UIModule.configure(
    UIConfig(
        default_theme="default",
        theme="dark",
        enable_sse=True,
    )
)

Config reference

Module Factory Methods

Key Features

• Core rendering primitives — Component, Element, RawHTML, el, raw, render_to_string
• Polymorphic asChild pattern — slot-based composition via as_child parameter on Component, Button, Link, Card
• ShadCN design tokens — CSS variable system in oklch color space: SHADCN_DEFAULT_COLORS, SHADCN_DARK_COLORS, shadcn_css() generator, SEMANTIC_CLASSES
• Theme system — shadcn_css() generates complete :root / .dark CSS blocks with overridable primary, background, foreground, radius, status colors
• Component CLI — lexigram-ui add <component> scaffolds components into your project (12 components in registry: button, card, modal, input, select, tabs, toast, tooltip, skeleton, form, badge, pagination)
• HTMX helpers — hx_get, hx_post, hx_target, hx_swap, and higher-level helpers
• Server-Sent Events — SSEMessage and SSEStream for realtime UI
• Component library — atoms, molecules, organisms, and layouts organized by usage layer
• Context and swap zones — UIContext, Zone, Zones, SwapMode
• Error and response helpers — validation_error, render_validation_errors, htmx_error_response
• Accessibility — AriaAttrs, SkipLink, announce, ARIA role helpers
• Performance — RenderCache, ResponseOptimizer, MetricsCollector
• CSP requirements — UI_CSP_REQUIREMENTS for Content Security Policy configuration

Testing

async with Application.boot(modules=[UIModule.stub()]) as app:
    # your test code
    ...

Key Source Files