John Lancaster
135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
---
|
|
name: nicegui-ui-customization
|
|
description: 'Design and implement production NiceGUI UIs with reusable components, Tailwind-first styling, event-driven interactions, and troubleshooting for uploads, state, and static assets. Use when building or refactoring NiceGUI pages and interaction flows.'
|
|
argument-hint: 'What UI outcome should this workflow produce?'
|
|
---
|
|
|
|
# NiceGUI UI Customization Workflow
|
|
|
|
Create, style, and ship production NiceGUI UI flows with a repeatable process. The workflow keeps structure in Python, favors Tailwind and Quasar APIs for styling, and uses event-driven interaction patterns over ad-hoc polling.
|
|
|
|
## When To Use
|
|
|
|
- Building a new NiceGUI page or dashboard
|
|
- Refactoring a page into reusable components
|
|
- Adding file upload, form submission, live status, or background-job UX
|
|
- Troubleshooting race conditions, stale assets, or inconsistent state updates
|
|
|
|
## Target Outcome
|
|
|
|
Deliver a responsive, accessible UI flow that:
|
|
|
|
- keeps clear boundaries between page adapters, reusable components, and services
|
|
- uses Tailwind-first styling with minimal custom CSS
|
|
- updates UI through events and bindings
|
|
- has validation, user feedback, and failure handling
|
|
- passes a production-readiness check at the end
|
|
|
|
## Progressive Loading References
|
|
|
|
Load these references only when needed:
|
|
|
|
- Architecture and styling rules: [architecture and styling](./references/architecture-and-styling.md)
|
|
- Event and state interaction patterns: [interaction patterns](./references/interaction-patterns.md)
|
|
- Troubleshooting and release gates: [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md)
|
|
|
|
## Procedure
|
|
|
|
### 1. Define the UI Slice
|
|
|
|
- Capture the user-visible outcome for this task in one sentence.
|
|
- Identify route-level page modules to touch.
|
|
- Identify service operations needed by the UI.
|
|
|
|
Completion check:
|
|
|
|
- You can name the target page, component candidates, and service calls before coding.
|
|
|
|
### 2. Choose Component Extraction Strategy
|
|
|
|
Decision point:
|
|
|
|
- If a layout pattern appears in 2 or more pages, extract it to `ui/components/`.
|
|
- If a pattern is page-specific, keep it in the page module.
|
|
|
|
Completion check:
|
|
|
|
- Reused UI patterns are encapsulated as callable components.
|
|
|
|
### 3. Build Responsive Layout First
|
|
|
|
- Use Tailwind utility classes for structure and spacing.
|
|
- Use responsive breakpoints (`sm:`, `md:`, `lg:`).
|
|
- Reserve `.style()` for dynamic values that cannot be expressed with classes.
|
|
|
|
Completion check:
|
|
|
|
- Layout works at mobile and desktop widths without custom CSS overrides.
|
|
|
|
### 4. Add Reactive State And Events
|
|
|
|
- Use bindable dataclasses for local page state.
|
|
- Prefer event handlers (`on_click`, `on_upload`, etc.) over periodic polling.
|
|
- Trigger explicit refreshes with `@ui.refreshable` where needed.
|
|
|
|
Decision point by interaction type:
|
|
|
|
- File upload: validate size/type, delegate storage to a service, notify success/failure.
|
|
- Form submit: bind inputs to dataclass fields, validate in service layer, clear state on success.
|
|
- Real-time status: use SSE or WebSocket for push updates.
|
|
- Long jobs: run in background task, update status endpoint or stream.
|
|
|
|
Completion check:
|
|
|
|
- Every user action has explicit positive and negative feedback via `ui.notify()`.
|
|
|
|
### 5. Apply Styling Strategy
|
|
|
|
Preferred order:
|
|
|
|
1. Tailwind utility classes
|
|
2. Quasar props
|
|
3. Reusable styled component functions
|
|
|
|
Only if absolutely necessary:
|
|
|
|
- Load minimal custom CSS once at startup in `bootstrap.py`.
|
|
- Keep custom CSS tokenized (variables) and documented.
|
|
|
|
Completion check:
|
|
|
|
- Styling is mostly class/props-driven and not dependent on scattered ad-hoc CSS.
|
|
|
|
### 6. Harden Against Common Failures
|
|
|
|
- Prevent duplicate submissions by disabling controls during in-flight operations.
|
|
- Avoid overlapping timers for the same state target.
|
|
- Serialize dependent updates (`await` service call before mutation/render).
|
|
- Verify static mount paths and cache behavior for changed assets.
|
|
|
|
Completion check:
|
|
|
|
- Race conditions and stale asset symptoms are addressed with explicit safeguards.
|
|
|
|
### 7. Final Production Readiness Review
|
|
|
|
Pass all checks:
|
|
|
|
- Structure: pages, components, services follow one-way dependency flow.
|
|
- Responsiveness: tested at small and large viewport widths.
|
|
- Accessibility: labels, button text, and action visibility are clear.
|
|
- Reliability: validation and exception paths produce user-facing notifications.
|
|
- Maintainability: repeated UI patterns are extracted; business logic stays in services.
|
|
|
|
If any check fails, return to the relevant step and iterate.
|
|
|
|
## Completion Contract
|
|
|
|
This workflow is complete when:
|
|
|
|
- the page flow meets the target outcome
|
|
- architecture boundaries are preserved
|
|
- chosen interaction pattern is implemented with explicit success and failure feedback
|
|
- troubleshooting checks pass
|
|
- production-readiness gate passes
|