Build Modern. Build Fast. Build Once. Reuse Everywhere.
A modern, scalable and reusable Desktop UI Framework built on top of Qt for Python (PySide6), designed for creating consistent, production-ready desktop applications with a single unified design system.
Status
✅ Step 5 Forensic Audit Passed — Pre-Development Baseline Frozen
Vibrix is a next-generation Desktop UI Framework developed by Vib Tools.
The primary goal of Vibrix is not simply to provide another collection of UI widgets.
Instead, Vibrix aims to provide a complete Desktop Application Framework where every application follows the same architecture, the same design language, the same component system and the same development workflow.
Modern desktop applications should not require rebuilding the same Button, Table, Sidebar, Form, Dialog and Theme system for every new project.
Those problems have already been solved.
Vibrix exists so developers can focus on solving business problems instead of rebuilding user interfaces.
Most Python desktop projects eventually suffer from the same problems.
- Different UI style in every project
- Inconsistent component behavior
- Duplicated code
- Hardcoded colors
- Difficult maintenance
- Weak scalability
- Tight coupling
- No reusable design system
Every new project starts almost from zero.
Developers recreate the same layout.
Recreate the same button.
Recreate the same table.
Recreate the same dialogs.
Recreate the same theme.
Recreate the same navigation.
Again.
And again.
Vibrix eliminates this repetition.
Our vision is to build one of the most complete and professional open-source Desktop UI Frameworks for Python.
A framework where developers can create applications ranging from small utility software to large enterprise desktop systems without redesigning the user interface every time.
We believe a framework should be stable for years—not only for a single project.
Our mission is simple.
Create a single framework that allows developers to:
- Build faster
- Write less code
- Reuse everything
- Keep every application visually consistent
- Reduce maintenance cost
- Improve long-term scalability
- Separate design from business logic
Vibrix follows a very simple philosophy.
Build Once. Reuse Everywhere.
Everything inside the framework is designed around this principle.
A component should never be rebuilt if it already exists.
Instead,
Create once.
Test once.
Document once.
Reuse forever.
Vibrix is built around several important engineering principles.
Applications should never start from scratch.
Developers should build applications on top of a reusable framework.
Every visual element is a reusable component.
Buttons.
Inputs.
Tables.
Dialogs.
Cards.
Sections.
Navigation.
Everything.
Every application should use the same:
- Colors
- Typography
- Icons
- Radius
- Borders
- Spacing
- Animation
- Shadows
Consistency is more important than customization.
Components never contain hardcoded visual styles.
Everything comes from the Theme Engine.
This allows an entire application to change appearance from a single centralized theme configuration.
Code should never come before architecture.
Planning.
Architecture.
Design.
Implementation.
Testing.
Documentation.
Release.
Every project should follow this order.
Vibrix is not being developed for a single software project.
It is being developed as the foundation of every future Desktop Application created by Vib Tools.
Whether the application is:
- SMTP Manager
- Email Sender
- Automation Platform
- AI Tool
- File Manager
- Validator
- Developer Utility
- Enterprise Desktop Software
Every application should share the same foundation.
The same components.
The same design language.
The same user experience.
Vibrix is:
- A Desktop UI Framework
- A Design System
- A Theme Engine
- A Component Library
- A Layout Framework
- A Template Framework
- A Development Standard
- A Foundation for future desktop applications
Vibrix is not:
- A widget collection
- A CSS theme
- A template pack
- A dashboard template
- A visual editor
It is a complete Desktop Framework built for long-term software development.
Vib Tools
Building professional software through reusable architecture, modern design systems and long-term maintainable development practices.
Vibrix is designed as a complete Desktop Application Framework rather than a traditional UI library.
Every feature inside the framework is built with one objective:
Reduce repetitive development while maintaining a consistent and professional user experience.
Every application built with Vibrix automatically shares the same design language.
Including:
- Typography
- Color System
- Icon System
- Spacing
- Radius
- Border
- Shadows
- Animation
- Window Design
Developers never need to redesign these elements for every new application.
The entire framework is controlled by a centralized Theme Engine.
Every component automatically receives:
- Colors
- Fonts
- Radius
- Border
- Padding
- Margin
- Animation
- Shadow
Changing the theme updates the entire application consistently.
Vibrix provides reusable components for modern desktop applications.
Examples include:
- Buttons
- Forms
- Inputs
- Tables
- Cards
- Navigation
- Sidebar
- Dialogs
- Status Components
- Overlay Components
- Feedback Components
- Identity Components
- Layout Components
Every component follows the same API, behavior and styling standards.
Applications do not start from an empty window.
Instead, developers start from ready-made templates.
Example templates include:
- Blank Application
- Dashboard
- Utility Tool
- Settings Application
- Wizard Application
This significantly reduces development time.
Every component follows predefined engineering standards.
Including:
- Component Standards
- Coding Standards
- Theme Standards
- Naming Standards
- Architecture Standards
- Development Workflow
This guarantees consistency across the entire framework.
Vibrix is designed to scale from small utilities to enterprise desktop software.
Whether an application contains:
- 20 Components
- 100 Components
- 500 Components
- 1000+ Components
The architecture remains unchanged.
The framework is designed to be predictable and easy to learn.
Developers should spend their time solving business problems—not learning framework internals.
Vibrix is built entirely on modern, stable and production-ready technologies.
| Layer | Technology |
|---|---|
| Programming Language | Python 3.12+ |
| UI Framework | PySide6 (Qt for Python) |
| GUI Engine | Qt 6 |
| Icons | QtAwesome |
| Async Engine | qasync |
| Logging | Loguru |
| JSON Engine | orjson |
| Platform Paths | platformdirs |
| Windows Integration | pywin32 (Optional) |
| Build System | Nuitka |
Each technology has been carefully selected for long-term maintainability rather than short-term convenience.
Vibrix follows an acyclic layered architecture. The framework is a directed architecture graph rather than a reversible linear chain.
Qt / Python / approved dependencies
│
▼
Core + Utilities + Resources
│
┌────────┼────────┐
▼ ▼ ▼
Theme Services Plugin/Extension Infrastructure
│ │
└────┬───┘
▼
Widgets
▼
Layouts
▼
Business Components
▼
Templates
▼
Application Bootstrap
Dependencies must follow the approved package dependency matrix and must never create a cycle. Internal packages communicate through explicit contracts; public consumers use the stable root API.
The Design System is the visual foundation of the framework.
Every application automatically follows the same design language.
The Design System includes:
- Color System
- Typography
- Iconography
- Layout Grid
- Window Style
- Sidebar Style
- Button Style
- Form Style
- Table Style
- Section Style
- Navigation Style
- Feedback Style
- Overlay Style
- Accessibility Rules
No component should introduce its own visual language.
Everything comes from the Design System.
The Theme Engine acts as the single source of truth for all visual styling.
Instead of storing visual properties inside individual components,
components simply request values from the Theme Engine.
The Theme Engine controls:
- Primary Colors
- Surface Colors
- Typography
- Radius
- Border
- Elevation
- Shadow
- Animation
- Transition
- Spacing
- Component States
This architecture makes global visual changes simple and predictable.
Every visible element inside Vibrix is a reusable component.
Components are organized by purpose, not by individual widget type.
Official component categories include:
Actions
Containers
Data
Feedback
Forms
Identity
Media
Navigation
Overlay
Sections
Status
Window
Every component is:
- Reusable
- Independent
- Theme-aware
- Documented
- Tested
- Production Ready
Vibrix exposes a clean and minimal public API.
Developers interact only with public components.
Example:
from vibrix import (
VibApplication,
VibWindow,
VibButton,
VibInput,
VibTable,
VibDialog,
)Internal package structure remains hidden from application developers.
This keeps applications stable even if the internal framework evolves.
Every decision inside Vibrix follows four fundamental principles.
Flat Public API
↓
Purpose-based Component Organization
↓
Qt + Python Naming Standard
↓
Layered Package Architecture
These principles influence every part of the framework, from architecture to implementation.
Vibrix follows one fundamental rule:
If a component already exists, build with it—not around it.
Components are created once, reviewed once, documented once and reused across every future application.
This approach minimizes duplication, improves maintainability and ensures a consistent user experience.
Vibrix is designed with long-term software engineering practices in mind.
The framework emphasizes:
- Stable Architecture
- Predictable APIs
- Consistent User Experience
- Reusable Components
- Long-Term Maintenance
- Documentation-Driven Development
- Framework-First Development
- Template-Based Applications
Vibrix is organized around a clear separation of responsibilities.
Every directory inside the project has a single purpose.
The project does not organize code by individual applications.
Instead, it organizes the framework into reusable architectural layers.
This approach keeps the framework maintainable as it grows over time.
vibrix/
│
├── .github/
├── assets/
├── config/
├── data/
├── docs/
├── examples/
├── project/
├── scripts/
├── src/
├── tests/
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml
Each directory exists for a specific responsibility.
Nothing should be placed in the project root unless it belongs there.
All production source code lives inside the canonical installable package root:
src/vibrix/
The root directory is never used to store implementation code.
Keeping all source code inside src/ provides:
- Cleaner project organization
- Better packaging
- Simpler testing
- Clear separation between source code and project files
The project/ directory is the internal development workspace.
It contains:
- Architecture Decision Records
- Planning Documents
- Framework Architecture
- Design References
- Internal Specifications
- Research Notes
This directory is intended only for framework development.
It is excluded from Git and is never included in public releases.
User-facing documentation lives inside:
docs/
Examples include:
- Installation
- Tutorials
- API Documentation
- User Guides
- Release Notes
- Frequently Asked Questions
Unlike project/, this directory is intended for framework users.
The assets/ directory stores framework resources.
Examples include:
- Fonts
- Icons
- Images
- Theme Assets
Assets should remain independent from application logic.
Framework configuration belongs inside:
config/
Typical configuration includes:
- Application Configuration
- Theme Configuration
- Logging Configuration
- Environment Profiles
Configuration should never be hardcoded inside components.
The data/ directory is reserved for development and testing data.
Typical contents include:
- Cache
- Sample Data
- Demo Data
- Import Files
- Export Files
- Temporary Data
Production applications should manage runtime data independently.
The examples/ directory demonstrates how to use Vibrix.
Each example should be:
- Small
- Focused
- Self-contained
- Easy to understand
Examples are educational—not production applications.
Every automated test belongs inside:
tests/
Typical categories include:
- Unit Tests
- Integration Tests
- UI Tests
- Performance Tests
- Regression Tests
Testing is considered part of development—not an optional step.
Development automation lives inside:
scripts/
Examples include:
- Build Scripts
- Release Scripts
- Code Generation
- Formatting
- Linting
- Packaging
- Automation Utilities
Scripts should never contain application business logic.
Vibrix follows several organizational principles.
Every directory has exactly one responsibility.
Responsibilities should never overlap.
Developers should immediately know where a file belongs.
No guessing.
No duplicated locations.
Adding hundreds of components should never require reorganizing the project.
Growth should happen inside existing architectural boundaries.
Planning.
Documentation.
Source Code.
Assets.
Tests.
Resources.
Each belongs in its own dedicated location.
Vibrix follows a documentation-driven development process.
Every feature passes through the same lifecycle.
Idea
↓
Planning
↓
Architecture
↓
Design
↓
Implementation
↓
Testing
↓
Documentation
↓
Review
↓
Release
↓
Maintenance
No phase should be skipped.
Every new feature follows this process.
Requirement
↓
Planning
↓
Architecture
↓
Component Design
↓
Implementation
↓
Testing
↓
Documentation
↓
Review
↓
Merge
↓
Release
Framework consistency is more important than development speed.
Every reusable component follows the same development lifecycle.
Specification
↓
Design
↓
Implementation
↓
Theme Integration
↓
Testing
↓
Documentation
↓
Framework Review
↓
Public Release
Components are never released without documentation and testing.
Every change must be reviewed before becoming part of the framework.
The review process verifies:
- Architecture
- Naming
- Component Standards
- Theme Integration
- Documentation
- Testing
- Public API
- Backward Compatibility
Only stable code reaches an official release.
Development Complete
↓
All Tests Pass
↓
Documentation Complete
↓
Review Approved
↓
Version Updated
↓
Release
↓
Publish
Every source file follows the same engineering standards.
Vibrix adopts:
- Python 3.12+
- PEP 8
- PEP 257
- Type Hints
- Explicit Imports
- Consistent Naming
Developer preference never overrides framework standards.
The framework follows a predictable naming strategy.
VibButton
VibDialog
VibTable
VibSidebar
button.py
dialog.py
table.py
sidebar.py
forms/
navigation/
feedback/
containers/
Imports are always organized in the following order.
Python Standard Library
↓
Third-party Libraries
↓
PySide6
↓
Vibrix
↓
Local Modules
Wildcard imports are never allowed.
Components never define their own appearance.
Visual properties always come from the Theme Engine.
Examples include:
- Colors
- Typography
- Radius
- Border
- Shadows
- Animation
- Spacing
This guarantees a consistent visual language across every application.
Every public component must be:
- Reusable
- Theme-aware
- Independent
- Documented
- Tested
- Accessible
- Production Ready
Components are designed to be reused—not copied.
Quality is built into the development process.
It is not something added at the end.
Every public component must satisfy:
- Architecture Review
- Coding Standards
- Component Standards
- Theme Standards
- Documentation Review
- Unit Testing
- Integration Testing
- Accessibility Validation
- Performance Validation
Only components that satisfy every quality gate become part of the framework.
Testing is considered part of implementation.
A component is not complete until it has been tested.
Testing includes:
- Functional Behavior
- Component States
- Theme Integration
- Keyboard Navigation
- Public API
- Error Handling
- Regression Protection
Documentation is written during development—not after release.
Every public component should include:
- Description
- Usage
- Properties
- Methods
- Signals
- Examples
Good documentation is considered part of the component itself.
Every engineering decision inside Vibrix prioritizes long-term maintenance over short-term convenience.
The framework is expected to evolve for years without requiring major architectural changes.
That is only possible through:
- Stable Architecture
- Predictable Standards
- Consistent Components
- Clear Documentation
- Strict Development Workflow
The goal of Vibrix is not simply to make desktop applications easier to build.
The goal is to create a framework that remains clean, understandable and maintainable as it grows from dozens of components to hundreds of components and from a single application to an entire ecosystem of professional desktop software.
Vibrix is currently under active development.
At this stage, the framework architecture, design system, component standards and development workflow are being established to provide a stable foundation for future releases.
Once the first stable version becomes available, developers will be able to install Vibrix directly from PyPI.
Example:
pip install vibrix| Requirement | Version |
|---|---|
| Python | 3.12+ |
| Qt | Qt 6 |
| UI Framework | PySide6 |
| Operating System | Windows (Primary) |
Support for additional operating systems may be expanded in future releases.
Vibrix has completed its controlled pre-development reconciliation and frozen the approved baseline. Theme Foundation Batch 1 is implemented as the first internal framework capability; no stable public release is available.
- ✅ Framework vision and philosophy documented
- ✅ Step 1: missing public, governance and repository documents restored
- ✅ Step 2: documentation status, index coverage and broken reference artifacts reconciled
- ✅ Accepted ADR-001 through ADR-022 preserved and architecture baseline reconciled
- ✅ Design and runtime specifications inventoried
- ✅ Step 3: package, folder, component and dependency architecture reconciled
- ✅ ADR-007 through ADR-021 completed and frozen
- ✅ Step 4: canonical package root, build, test and CI baseline applied
- ✅ Step 5: full forensic re-audit passed and updated baseline frozen
- ⏳ Core Framework — Architecture frozen; implementation pending
- ✅ Theme Foundation Batch 1 — Immutable typed tokens and frozen dark snapshot implemented
- ⏳ Theme Engine — Validation, schema loading, Qt adapters and atomic switching pending
- ⏳ Base Components — Pending
- ⏳ Layout System — Pending
- ⏳ Component Library — Pending
- ⏳ Plugin System — Architecture documented; implementation pending
- Public Alpha
- Public Beta
- Stable Release (v1.0)
- Documentation Website
- Component Gallery
- API Reference
The Vibrix roadmap is divided into multiple milestones.
- Framework Planning
- Architecture
- Design System
- Theme System
- Standards
- Documentation
Status
Theme Foundation Batch 1 Implemented — Development Certification Required
- Core Engine
- Theme Engine
- Base Components
- Window System
- Layout System
Status
Not Started
Development of reusable components.
Including:
- Buttons
- Forms
- Inputs
- Tables
- Navigation
- Dialogs
- Cards
- Overlay
- Feedback
- Identity
Professional application templates.
Examples:
- Blank Application
- Dashboard
- Utility Application
- Settings Application
- Wizard Application
- User Guide
- API Reference
- Tutorials
- Examples
- Best Practices
First production-ready release of Vibrix.
Future releases may include:
- Plugin Ecosystem Implementation
- Extension Ecosystem Implementation
- Component Marketplace
- Theme Marketplace
- Visual Theme Editor
- Internationalization Improvements
- Advanced Accessibility
- High-DPI Optimizations
- Multi-Platform Enhancements
- Enterprise Components
The roadmap will evolve as the framework matures.
Vibrix is designed as a long-term engineering project.
Constructive feedback, issue reports and improvement suggestions are always valuable.
Future public releases will include:
- Issue Tracking
- Feature Requests
- Community Discussions
- Contribution Guidelines
Contribution guidelines will be published once the framework reaches its first public development milestone.
The future contribution process will include:
- Issue Discussion
- Proposal Review
- Implementation
- Testing
- Documentation
- Code Review
- Merge Approval
Every contribution should follow the official Vibrix standards.
Every contribution should preserve the core philosophy of Vibrix.
- Framework First
- Component First
- Theme Driven
- Build Once
- Reuse Everywhere
- Documentation Driven
- Long-Term Maintainability
These principles take priority over individual implementation preferences.
Vibrix follows Semantic Versioning.
MAJOR.MINOR.PATCH
Examples:
1.0.0
1.1.0
1.1.3
2.0.0
Breaking architectural or public API changes.
Backward-compatible new functionality.
Bug fixes and stability improvements.
Public APIs should remain stable whenever possible.
Breaking changes are introduced only when absolutely necessary and will be clearly documented.
Framework stability is considered a primary design objective.
The project maintains two separate documentation systems.
docs/
Contains:
- Installation
- Tutorials
- API Documentation
- User Guides
- Release Notes
- Frequently Asked Questions
project/
Contains:
- Planning
- Architecture
- ADR
- Research
- Internal Specifications
- Design References
This directory is used only during framework development and is not included in public releases.
The repository is intentionally organized into clearly separated responsibilities.
Source Code
↓
Documentation
↓
Assets
↓
Testing
↓
Development Resources
This organization helps maintain clarity as the project grows.
The licensing model will be finalized before the first public release.
The chosen license will clearly define:
- Usage Rights
- Distribution
- Modification
- Attribution
- Commercial Use
Until then, all rights remain reserved by the project owner.
Vibrix is not intended to become just another Python GUI library.
Its long-term objective is to become a comprehensive desktop application platform that enables developers to build modern, consistent and maintainable software using a unified architecture and reusable component ecosystem.
As the framework evolves, every new feature will continue to follow the same engineering philosophy that shaped its foundation.
The success of a framework is not measured by how many widgets it provides.
It is measured by how consistently developers can build reliable software with it.
Vibrix is being built with that philosophy from the very beginning.
Vibrix is developed and maintained by Vib Tools.
The framework is inspired by decades of software engineering practices, modern desktop application architecture and the broader open-source ecosystem.
Rather than replicating existing frameworks, Vibrix seeks to combine proven engineering principles with a consistent design system, reusable components and a long-term architectural vision.
Designed & Developed by Vib Tools
Status: Completed on 2026-07-31.
The target package architecture, dependency matrix, public API, component lifecycle, theme, state, event, plugin/extension, resource/configuration, concurrency and window contracts are approved. The physical package, build, test and CI baseline is frozen.
Status: Completed on 2026-07-31.
The repository now uses the canonical src/vibrix/ package root, uv-managed dependency resolution,
Hatchling wheel/source packaging, automated structure and import-boundary checks,
baseline tests, artifact verification and a GitHub Actions quality workflow.
Theme Foundation Batch 1 is implemented inside vibrix.theme. The root public API still
exposes only vibrix.__version__; Theme Foundation is accessed through its subordinate package.
Further feature development requires the authoritative dev certification and verified package gate.
Status: Passed on 2026-07-31.
The clean repository tree, all Steps 1–4 changes, documentation index, ADR sequence,
architecture boundaries, package skeleton, tests, archive safety and reference-image
inventory were re-audited. Baseline VIBRIX-PREDEV-BASELINE-2026-07-31-PY312 is frozen.
ADR-022 sets Python 3.12+ as the minimum runtime. The reviewed uv.lock, frozen environment
sync, aggregate quality gate, package verification and isolated-wheel smoke test now define the
authoritative development certification. The project remains version 0.0.0 and is not a stable
or supported public release.