nice-vibes 0.1.2

Developing beautiful NiceGUI applications with AI

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.

✨ Features

• 📚 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 (~22K tokens) for context injection
• ✅ Validated - All class references and URLs verified
• 🧩 Modular - Pick what you need or use the full prompt

🚀 Quick Start

Use Pre-Built Prompts (Recommended)

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

Copy the content into your AI assistant's context or system prompt. When using tools such as Windsurf use Opus 4.5 as model and paste one of the URLs above to let it "teach itself" the principles of NiceGUI.

Build From Source (Optional)

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.py

📋 Requirements

For building from source:

• Python 3.12+
• Poetry

📖 Documentation

Folder	Description
docs/	Main documentation
docs/events/	Event handling patterns
docs/mechanics/	Core patterns (SPA, authentication, styling)
docs/classes/	UI element reference by category

📂 Other Folders

Folder	Description
samples/	Working example applications
output/	Generated master prompts
scripts/	Build and validation tools
tests/	Example NiceGUI tests

🧪 Testing

poetry run pytest -v

🤖 Prompt Variants

Each 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	✓
Sample references	✓	✓	✓

ref = Not included but referenced with summary (AI knows where to look)

Configure file order and summaries in docs/prompt_config.yaml.

🖥️ Command Line Interface

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

🔌 MCP Server (Optional)

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.

🙏 Credits

Created by Michael Ikemann

Built for use with NiceGUI - a Python UI framework by Zauberzeug.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Free to use, modify, and distribute.