prompts/skills/nicegui-ui-customization/SKILL.md

name, description, argument-hint

name	description	argument-hint
nicegui-ui-customization	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.	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
• Event and state interaction patterns: ./references/interaction-patterns.md
• Troubleshooting and release 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