move

2026-06-18 22:06:40 -05:00
parent 6c5fda9c3a
commit e78383be1f
24 changed files with 0 additions and 0 deletions
@@ -0,0 +1,134 @@
+---
+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: [./references/architecture-and-styling.md](./references/architecture-and-styling.md)
+- Event and state interaction patterns: [./references/interaction-patterns.md](./references/interaction-patterns.md)
+- Troubleshooting and release gates: [./references/troubleshooting-and-quality-gates.md](./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