---
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?'
x-personal-mcp:
  id: nicegui-ui-customization
  version: 1.0.0
  tags:
    - nicegui
    - ui
    - customization
    - frontend
  capabilities:
    - resource://skills/nicegui-ui-customization/document
  depends_on: []
  references:
    architecture-and-styling:
      path: references/architecture-and-styling.md
      mime_type: text/markdown
      title: Architecture and Styling
    interaction-patterns:
      path: references/interaction-patterns.md
      mime_type: text/markdown
      title: Interaction Patterns
    troubleshooting-and-quality-gates:
      path: references/troubleshooting-and-quality-gates.md
      mime_type: text/markdown
      title: Troubleshooting and Quality Gates
---

# 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