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

name, description, x-personal-mcp

name	description	x-personal-mcp
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.	id version tags capabilities nicegui-ui-customization 1.0.0 nicegui ui customization frontend resource://skills/nicegui-ui-customization/document

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
• Event and state interaction patterns: interaction patterns
• Troubleshooting and release gates: troubleshooting and quality gates

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