Nice Vibes - Teach AI agents to build beautiful NiceGUI applications
A comprehensive toolkit of prompts, patterns, and examples that help AI coding assistants generate correct, idiomatic NiceGUI code.
- 📚 Complete Documentation - Events, mechanics, styling, and class references
- 🔐 Authentication Patterns - Signed cookie persistence, role-based permissions, login flows
- 🧭 SPA Navigation -
ui.sub_pages, header/drawer visibility, back button handling - 🧪 Working Samples - Full multi-dashboard app, stock analysis, custom components
- 🤖 AI-Optimized - Single master prompt (~23K tokens) for context injection
- ✅ Validated - All class references and URLs verified
- 🧩 Modular - Pick what you need or use the full prompt
Just download and use the pre-built master prompt directly:
| Variant | Tokens | Use Case | Download |
|---|---|---|---|
| Compact | ~14K | Quick tasks, simple UI | nice_vibes_compact.md |
| Optimum | ~23K | Most use cases | nice_vibes.md |
| Extended | ~34K | Custom components, deployment | nice_vibes_extended.md |
When using tools such as Windsurf or Claude Code, point it to the master prompt of your choice before providing the task description.
Choose of one the urls above depending on the complexity of the task.
Alternatively, you can add the global and local rules below to your tool of choice to let it fetch the corresponding master prompt automatically.
Only needed if you want to customize or extend the documentation:
git clone https://github.com/Alyxion/nice-vibes.git
cd nice-vibes
poetry install
poetry run python scripts/build_master_prompt.pyFor building from source:
- Python 3.12+
- Poetry
| Folder | Description |
|---|---|
| docs/ | Main documentation |
| docs/events/ | Event handling patterns |
| docs/mechanics/ | Core patterns (SPA, authentication, styling) |
| docs/classes/ | UI element reference by category |
| Folder | Description |
|---|---|
| samples/ | Working example applications |
| output/ | Generated master prompts |
| scripts/ | Build and validation tools |
| tests/ | Example NiceGUI tests |
poetry run pytest -vEach variant is available in online (GitHub URLs) and offline (local paths) versions:
| Content | Compact | Optimum | Extended |
|---|---|---|---|
| Main guide | ✓ | ✓ | ✓ |
| Core mechanics | ✓ | ✓ | ✓ |
| Events | ref | ✓ | ✓ |
| Class reference | ref | ✓ | ✓ |
| Custom components | ref | ref | ✓ |
| Configuration & deployment | ref | ref | ✓ |
| Testing | ✓ | ✓ | ✓ |
| Sample references | ✓ | ✓ | ✓ |
ref = Not included but referenced with summary (AI knows where to look)
Configure file order and summaries in docs/prompt_config.yaml.
Nice Vibes includes a CLI to explore and run sample applications:
# Install the package
pip install nice-vibes
# Interactive sample selector
nice-vibes
# List available samples
nice-vibes list
# Run a sample
nice-vibes run dashboard
# Copy sample source code to current directory
nice-vibes copy dashboard
nice-vibes copy video_custom_component -o my_video_app
NiceVibes includes an optional Model Context Protocol server that gives AI assistants dynamic access to:
- Guided project creation - Step-by-step questionnaire with best practices
- Documentation search - Find topics without loading everything into context
- Source code inspection - Read NiceGUI component source directly
- Visual debugging - Capture screenshots of running or newly created applications
- Sample exploration - Browse and copy working examples
Get your configuration with nice-vibes mcp-config:
{
"mcpServers": {
"nice-vibes": {
"command": "/path/to/python",
"args": ["-m", "nice_vibes.mcp"]
}
}
}Add this to your MCP client config (Windsurf, Claude Desktop, etc.).
This is how it works:
See nice_vibes/mcp/README.md for detailed setup instructions.
Use the snippets below as Global Rules / Global Instructions and Local Rules / Local Instructions.
When I ask you to build a new Python dashboard or web UI, default to NiceGUI and Poetry (Python 3.12+).
Assume the app runs on http://localhost:8080. If the nice-vibes MCP server is available, you can refer
to it for sample apps and initial project setup.
This repository uses NiceGUI and Poetry.
Rules:
- Always use `poetry run ...`.
- Keep NiceGUI on port 8080. If the port is blocked you can kill the process using nice-vibes MCP tools.
- NiceGUI hot-reloads on file-changes, you do usually not need to restart the server.
- Do not open a browser automatically.
- Prefer the nice-vibes MCP tools for docs, samples, and NiceGUI component details.
- If you want to verify visual impact of your changes you can use the nice-vibes MCP tools to capture screenshots using `capture_url_screenshot` (defaults to http://localhost:8080).
When I ask you to build a new Python dashboard or web UI, default to NiceGUI and Poetry (Python 3.12+).
For documentation, samples, and NiceGUI component details use the Nice Vibes GitHub markdown prompts.
They are available in the following variants:
- https://raw.githubusercontent.com/Alyxion/nice-vibes/refs/heads/main/output/nice_vibes_compact.md
- https://raw.githubusercontent.com/Alyxion/nice-vibes/refs/heads/main/output/nice_vibes.md
- https://raw.githubusercontent.com/Alyxion/nice-vibes/refs/heads/main/output/nice_vibes_extended.md
This repository uses NiceGUI and Poetry.
Rules:
- Always use `poetry run ...`.
- Keep NiceGUI on port 8080. Do not open a browser automatically.
- Use the Nice Vibes GitHub markdown prompts as your primary reference for NiceGUI component details.
- NiceGUI hot-reloads on file-changes, you do usually not need to restart the server.
Created by Michael Ikemann
Built for use with NiceGUI - a Python UI framework by Zauberzeug.
This project is licensed under the MIT License - see the LICENSE file for details.
Free to use, modify, and distribute.