front matter

docs/prompts/nicegui.md

@@ -1,3 +1,8 @@
+---
+name: nicegui
+description: Build and scaffold production-ready NiceGUI + FastAPI app architecture.
+---
+
 # NiceGUI
 
 Build a production-ready, multi-page NiceGUI application that follows modern FastAPI project layout and architecture practices.
@@ -236,6 +241,56 @@ If your app needs multi-step AI workflows, tool-calling loops, or human-in-the-l
 - Add tests ensuring `thread_id` reuse resumes correctly and new IDs start fresh sessions.
 - Add regression tests for state-schema evolution and serialization compatibility.
 
+## Extending This Pattern with a Static Docs Site via Zensical (Optional)
+
+If the app should also host a static documentation site, mount the generated docs output directory under a configurable route (default: `/docs`).
+
+### Recommended docs workflow
+
+- Initialize docs in the project root:
+	- `uv run zensical new .`
+- Keep source markdown in Zensical's `docs_dir` (default: `docs/`).
+- Build docs as part of release or startup pipeline:
+	- `uv run zensical build`
+- Serve the generated static output from Zensical's `site_dir` (default: `site/`).
+
+### Config to include in app settings
+
+- `docs_enabled: bool = true`
+- `docs_mount_path: str = "/docs"`
+- `docs_site_dir: str = "site"`
+- Optional for local/dev convenience:
+	- `docs_require_build: bool = false` (if true, fail startup when `site/` is missing)
+
+### FastAPI/NiceGUI integration pattern
+
+- Keep docs mounting in the app composition layer (`bootstrap.py`), not in page modules.
+- Use FastAPI static serving to mount the built directory (for example via `StaticFiles(..., html=True)`).
+- Ensure `docs_mount_path` is normalized (leading slash, no trailing slash) and does not conflict with app/API routes.
+- If docs are disabled or build artifacts are missing, log a clear warning and continue (unless `docs_require_build=true`).
+
+### Suggested project additions
+
+```text
+.
+├─ zensical.toml
+├─ docs/
+│  ├─ index.md
+│  └─ ...
+├─ site/                    # generated by `uv run zensical build`
+└─ src/
+	 └─ app/
+			├─ config.py          # docs_enabled/docs_mount_path/docs_site_dir
+			└─ bootstrap.py       # mount static docs route
+```
+
+### Deployment notes for docs mounting
+
+- In CI/CD, run `uv run zensical build` before packaging/deploying the app image.
+- If `project.site_dir` in `zensical.toml` is changed, keep `docs_site_dir` in app settings aligned.
+- If hosting behind a reverse proxy with a path prefix, verify docs links and static assets with the final external base path.
+- Add a test asserting requests to `docs_mount_path` return the built index page when docs are enabled.
+
 ## Implementation Notes
 
 - Prefer an explicit page registration function pattern, for example:
@@ -246,6 +301,18 @@ If your app needs multi-step AI workflows, tool-calling loops, or human-in-the-l
 - Prefer FastAPI lifespan hooks where appropriate for startup/shutdown behavior.
 - Prefer type hints throughout.
 
+### Styling architecture notes
+
+- Prefer class-first UI composition for structure and layout using normal NiceGUI mechanics (`.classes(...)` on containers/components).
+- Keep structural concerns in Python page/component modules (layout grids, spacing systems, responsive breakpoints, alignment).
+- Keep cosmetic concerns in static CSS files (colors, gradients, shadows, border polish, typography fine-tuning, transitions).
+- Avoid large inline `style(...)` strings except for one-off dynamic values that must be computed at runtime.
+- Centralize CSS entrypoints in a small, predictable set (for example `ui/static/css/base.css`, `ui/static/css/theme.css`, `ui/static/css/components.css`).
+- Include CSS once at app bootstrap/startup so pages share the same style contract; avoid per-page ad hoc includes.
+- Prefer semantic class names for reusable patterns (`app-shell`, `page-section`, `card-surface`) and utility classes only for local layout tweaks.
+- If using design tokens, define them as CSS custom properties in `:root` and reference them from component classes.
+- Keep page modules focused on structure and behavior; reusable visual patterns should live in shared UI components plus shared CSS.
+
 ### Database-specific notes (only if your app needs a DB)
 
 - Prefer settings via `pydantic-settings` and read `DATABASE_URL` from environment/dotenv.