prompts/src/personal_mcp/docs/skills/nicegui/SKILL.md

name, description

name	description
nicegui	Reference hub for NiceGUI and FastAPI application structure, typed configuration, ASGI and Uvicorn startup, UI composition, styling, bindable state, interactions, troubleshooting, testing, and source documentation. Use when planning, implementing, reviewing, deploying, or debugging NiceGUI applications; load only the references relevant to the task.

NiceGUI Reference

Use this skill as a progressive reference for NiceGUI applications built with FastAPI. Start with the routing map, load only the material needed for the current question, and reconcile it with the target project's NiceGUI version and established conventions.

When to Use

• Planning or reviewing NiceGUI application structure and FastAPI composition.
• Building or refactoring pages, components, layouts, and static assets.
• Creating editable tables with Python-authoritative state, validation, and persistence.
• Modeling UI state with bindings or bindable dataclasses.
• Implementing forms, uploads, refreshes, live updates, or background work.
• Diagnosing UI state, concurrency, navigation, or asset problems.
• Verifying framework behavior against primary documentation.

How to Use This Skill

1. Classify the request using the discovery map below.
2. Load the smallest relevant reference, or at most two references for a mixed concern.
3. Inspect the target repository before applying guidance; preserve its sound local patterns.
4. Check the pinned NiceGUI and integration versions before relying on version-specific APIs.
5. Validate the changed behavior with focused tests and, for UI work, relevant viewport checks.

Progressive Discovery Map

Application Architecture

Load application architecture for:

• FastAPI app factories and lifespan ownership
• package boundaries and dependency direction
• page registration and health routes
• optional persistence, LangGraph, or mounted documentation
• async responsiveness and baseline tests

FastAPI And Uvicorn Startup

Load FastAPI and Uvicorn startup for:

• choosing between ui.run() and ui.run_with()
• understanding the parent FastAPI app and NiceGUI's internal app
• composing ASGI lifespan and mounted routes
• loading one typed settings snapshot for server and application configuration
• serving an app instance or factory with Uvicorn
• exposing programmatic startup through [project.scripts]
• reload, worker, and process-local state constraints

Styling And Customization

Load styling and customization for:

• app-wide and page-level color themes, dark mode, and semantic CSS tokens
• Tailwind and Quasar utility classes
• scoped CSS properties and stable application classes
• responsive page composition and static asset loading
• cosmetic treatment of controls, surfaces, typography, and visual states
• visual validation at supported viewport sizes

Component Mechanics

Load component mechanics for:

• the NiceGUI Python wrapper, element bridge, Quasar component, and Vue runtime boundaries
• deciding between constructors, bindings, Quasar props, events, slots, and frontend methods
• controlled values, model events, transformed payloads, and server-authoritative edit proposals
• server-client state and event flow, validation timing, and commit policy
• detached content and external icon assets
• source research against the installed NiceGUI and bundled Quasar versions
• ui.select and ui.icon mechanics and caveats
• scoped component slots and their interaction contracts

Editable Tables

Load editable tables for:

• Python-authoritative editable ui.table state
• rendering dataframe records into row-scoped bindable dataclasses
• stable row identity across sorting, filtering, and pagination
• NiceGUI editors in Quasar body-cell-* scoped slots
• QTable row refresh and selection preservation after edits
• the full body slot required when escalating to QPopupEdit

Bindable State

Load bindable dataclasses for:

• typed local UI state
• propagation, serializable projections, persistence, and rollback behavior
• nested structures and strict bindings
• mutable defaults, performance, and version notes

Interaction Patterns

Load interaction patterns for:

• uploads and form submission
• explicit refreshes
• server-sent events and WebSockets
• background work and duplicate-submission guards

Troubleshooting And Quality

Load troubleshooting and quality gates for:

• upload failures and UI race conditions
• stale assets and navigation drift
• responsiveness, accessibility, reliability, and maintainability checks

Primary Sources

Load source documentation when:

• behavior is version-sensitive or uncertain
• an integration recommendation needs verification
• upstream NiceGUI, FastAPI, Tailwind, Quasar, SQLAlchemy, Pydantic, or LangGraph documentation is required

Common Discovery Paths

New Application Or Architecture Review

1. Load application architecture.
2. Add FastAPI and Uvicorn startup when FastAPI owns the application or startup must be exposed as a project command.
3. Add styling and customization only when page layout or visual customization is in scope.

Page Or Component Work

1. Load application architecture for page and component ownership decisions.
2. Load styling and customization for themes, layout, responsive presentation, utility classes, or CSS.
3. Load component mechanics when behavior must be mapped across NiceGUI, Quasar, and Vue, or when detached content and component-specific behavior are involved.
4. Load editable tables when table cells accept user changes or QPopupEdit is being considered.
5. Add interaction patterns or bindable dataclasses according to the page behavior.

Debugging Or Production Review

1. Start with troubleshooting and quality gates.
2. Follow the symptom to one detailed reference.
3. Confirm uncertain behavior in source documentation.

General Defaults

• Keep composition, transport, services, pages, and components directionally separated.
• Keep business logic out of UI components and event handlers.
• Avoid blocking I/O and CPU-heavy work in the UI event loop.
• Prefer event-driven updates and explicit refreshes over unrelated polling.
• Discover component capabilities through NiceGUI docs and constructors, then the wrapped Quasar API.
• Keep editable table records authoritative in Python; send stable row keys with edit proposals and reassert canonical rows after validation.
• Research the current NiceGUI and Quasar source documentation before generating component-specific code or CSS.
• Prefer constructor arguments and native Quasar features through NiceGUI; use Tailwind for structure and scoped static CSS for stable fine tuning.
• Provide loading, success, and failure states for user-triggered work.
• Treat version-specific guidance as a prompt to verify the project's dependency version.

Reference Use Contract

When applying this skill:

• return only guidance relevant to the current task
• distinguish repository facts from reference recommendations
• cite the appropriate source reference for framework-level claims
• state assumptions when application requirements are missing
• report the focused checks used to validate implementation changes