Architecture and Styling Reference

Project Boundaries

Use this dependency direction:

pages import components and services
components contain presentation logic only
services contain business logic and do not import UI
static assets are mounted and loaded once at bootstrap

Suggested module split:

src/app/
  ui/pages/
  ui/components/
  ui/static/
  services/
  api/
  bootstrap.py

Component Extraction Rules

Extract to ui/components when a pattern appears in two or more pages.

Keep in-page if the layout is specific to a single route.

def card_section(title: str, content: str) -> ui.card:
    with ui.card().classes("w-full max-w-md") as card:
        ui.label(title).classes("text-lg font-bold")
        ui.label(content).classes("text-gray-600")
    return card

Tailwind-First Layout Pattern

Use Tailwind utility classes for structure and spacing. Use breakpoint classes for responsive behavior. Use .style() only for values that must be computed dynamically.

with ui.column().classes("w-full"):
    with ui.row().classes("w-full gap-4 flex-wrap sm:flex-nowrap"):
        ui.card().classes("flex-1 min-w-64")
        ui.card().classes("flex-1 min-w-64")

Styling Decision Order

Tailwind utility classes
Quasar props
Reusable styled component functions
Minimal custom CSS loaded once at bootstrap (only when needed)

from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="src/app/static"), name="static")
ui.add_css(open("src/app/static/css/base.css").read())

Static Asset Rules

Keep custom CSS small and tokenized with variables.
Avoid per-page CSS injection.
Verify static mount paths and reverse proxy rewrites.

Links

!!! info "Primary sources" - NiceGUI elements - NiceGUI binding properties - Tailwind utility-first styling - Quasar components

2.1 KiB Raw Blame History