SaaS-FrameWork 0.1.3

SaaS-FrameWork - sistema de componentes reutilizaveis para apps SaaS construido com Python e Flet

SaaS-FrameWork

Python 3.13 + Flet design framework for reusable SaaS UI components.

The project provides versioned UI components, isolated use cases, and a navigable component catalog.

Versioning

Library, component, and release branch versions follow the same vv.rr.bb rule.

The library version is declared in pyproject.toml:

[project]
version = "0.1.1"

Use cases and the catalog header read this version through components/project.py. Do not duplicate the project version manually in UI files.

Each public component exposes its own version:

COMPONENT_VERSION = "0.0.1"

Release branches must use the same format as the branch name:

0.1.1

Do not prefix release branch names with v, release/, or any other text.

The accepted format is:

vv.rr.bb
0.0.0 through 99.99.99

Segment meaning:

• vv: version. Increment for large changes that alter visual form, public API, or how the library/component is used.
• rr: release. Increment for small scoped changes, such as a specific behavior or item adjustment.
• bb: bug correction. Increment when a bug is fixed.

Every library or component change must increment the relevant version. Each segment is incremented by one numeral. When bb reaches 99, the next bb increment increments rr and resets bb to 0. When rr reaches 99, the next rr increment increments vv and resets rr to 0.

Version helpers live in components/versioning.py:

• validate_version(version)
• validate_branch_version(branch_name)
• bump_version(version, segment="bugfix")
• ComponentMeta

Catalog metadata lives in components/metadata.py and is the source of truth for component name, group, version, and description.

Package Boundary

The distributable Python library is the components package.

The following folders are repository assets and are intentionally excluded from the wheel:

• catalog/: local visual catalog and inspection tool.
• use_cases/: executable examples for development and documentation.
• Diretrizes/: project guidelines — prompts, design/component documentation, management artifacts, and QA evidence.
• _base/: preserved reference material.

This separation is enforced in pyproject.toml through tool.setuptools.packages.find.

Adding a public component requires all of the following:

• source file under components/**/DEx_<Name>.py
• COMPONENT_VERSION in the source file
• entry in components/metadata.py
• public export in components/__init__.py
• use case use_cases/UC_<Name>_01.py
• documentation Diretrizes/design/components/Documentação/DEx_<Name>.md
• four structure images in Diretrizes/design/components/images/

The repository governance tests fail when this contract is broken.

Folder Structure

SaaS-Framework/
|-- _base/                         preserved original reference
|-- components/
|   |-- buttons/
|   |-- cards/
|   |-- data/
|   |-- feedback/
|   |-- inputs/
|   |-- layout/
|   |-- primitives/
|   |-- theme/
|   |-- metadata.py
|   |-- project.py
|   `-- versioning.py
|-- use_cases/
|   |-- _uc_template.py
|   |-- UC_<Component>_<nn>.py
|   |-- UC_TreeView_01.py
|   `-- UC_ColorThemes_01.py
|-- catalog/
|   `-- catalog.py
|-- Diretrizes/
|   |-- Dados/                     data artifacts (DDL, DML, scripts)
|   |-- Prompt/                    prompt files
|   |-- design/                    design references and component docs/images
|   |   `-- components/
|   |-- gestao/                    roadmap, policies, and management reports
|   `-- qa/                        QA evidence
|-- AGENTS.md
|-- pyproject.toml
`-- README.md

Naming Convention

Type	Pattern	Example
Component file	DEx_<Name>.py	DEx_MetricCard.py
Component factory/class	DEx_<Name>	DEx_MetricCard()
Use case	UC_<Component>_<nn>.py	UC_MetricCard_01.py

Environment

Documented local virtual environment:

C:\Python\venv\.venv_313_FW

Run the catalog as desktop app:

call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
flet run catalog/catalog.py

Run as web catalog only when browser validation is required:

call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
flet run --web --port 8550 catalog/catalog.py

Run a use case:

call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
flet run use_cases/UC_MetricCard_01.py

Validation

Quick syntax validation:

python -m compileall components use_cases catalog

Run the automated test suite:

C:\Python\venv\.venv_313_FW\Scripts\python.exe -m pytest -q

Run optional visual screenshots:

C:\Python\venv\.venv_313_FW\Scripts\python.exe -m playwright install chromium
$env:DEX_RUN_VISUAL_TESTS="1"
C:\Python\venv\.venv_313_FW\Scripts\python.exe -m pytest tests/test_visual_screenshots.py -q

Build and validate package metadata:

C:\Python\venv\.venv_313_FW\Scripts\python.exe -m build
C:\Python\venv\.venv_313_FW\Scripts\python.exe -m twine check dist/*

Publish the package:

.\tools\publish_package.ps1 --test
.\tools\publish_package.ps1 --prod
.\tools\publish_package.ps1 --both
.\tools\publish_package.ps1

Without flags, the script asks:

1. teste
2. prod
3. ambos

The script builds the package, checks the artifacts, and uploads to TestPyPI or PyPI based on the chosen destination.

With the documented Flet environment:

C:\Python\venv\.venv_313_FW\Scripts\python.exe -c "import catalog.constants as c; print(c.PROJECT_VERSION)"

Catalog

The catalog entry point is catalog/catalog.py.

It follows the project window structure:

• header with project name, project version, and current branch
• left menu with component groups
• group context area with name and description
• component cards showing name, group, and component version

The catalog uses components/metadata.py; adding a component without adding metadata means it will not appear in the catalog.

Design System

Main design tokens live in components/theme/DEx_Theme.py.

Token	Hex	Use
ACCENT	#6C63FF	Primary actions and active navigation
DATA	#00E5C3	Data highlights and metric accents
BG_DEEP	#0D0F14	Root background
BG_SURFACE	#151820	Cards and sidebar surfaces
BG_ELEVATED	#1C2030	Hover states, inputs, elevated surfaces
BORDER	#1E2230	Borders and dividers
SUCCESS	#22C55E	Positive status
DANGER	#EF4444	Error or negative status
WARNING	#F59E0B	Warning status

Signature elements:

• numbered cyan eyebrows through DEx_SectionEyebrow
• 3px violet active indicator in DEx_NavItem

Color Themes

Accessible 60-30-10 color themes live in components/theme/DEx_ColorThemes.py.

Each theme defines:

• background: 60% dominant color for windows, frames, and base containers
• text: 30% foreground color for typography, borders, cards, and tables
• accent: 10% highlight color for primary CTAs, badges, critical links, progress, and chart highlights
• contrast_ratio: documented text/background contrast
• accessibility: WCAG target such as AAA or AA

Available themes:

Theme	Background	Text	Accent	Contrast	Status
Minimalismo Corporativo	#FFFFFF	#000000	#0071E3	21:1	AAA
Dark Mode de Alta Performance	#111111	#FFFFFF	#FF6A13	18.88:1	AAA
Confianca e Fintech	#141432	#F4F5F7	#0079C1	16.37:1	AAA
Organico e Bem-Estar	#006241	#FFFFFF	#00A86B	7.44:1	AAA
Alimentacao e Food Delivery	#FAFAFA	#222222	#EA1D2C	15.24:1	AAA
Area Automotiva	#1E2229	#F3F4F6	#FFB800 / #FF5500	14.50:1	AAA
Tradicao e Robustez	#F4F6F9	#003399	#003399 / #FFFF00	10.03:1	AAA
Modernidade Digital	#FFFFFF	#820AD1	#820AD1	7.21:1	AAA
Solidez e Dinamismo	#FAFAFA	#0038A8	#FF6200	9.44:1	AAA
Presenca Global e Energia	#FFFFFF	#1C1C1C	#EC0000	17.04:1	AAA

Use:

from components.theme.DEx_ColorThemes import get_color_theme

theme = get_color_theme("food_delivery")
page.bgcolor = theme.bg_primary
button.bgcolor = theme.accent_primary

Export CSS-style variables:

theme.css_variables()

Use Case Theme Switcher

The shared use case template in use_cases/_uc_template.py adds a palette button to the header.

Each click cycles through the current DEx_ColorThemes presets:

Minimalismo Corporativo -> Dark Mode de Alta Performance -> Confianca e Fintech -> Organico e Bem-Estar -> Alimentacao e Food Delivery -> Area Automotiva -> Tradicao e Robustez -> Modernidade Digital -> Solidez e Dinamismo -> Presenca Global e Energia

The switcher applies the selected 60-30-10 theme to the page and retints mounted controls that use DEx token colors.

Components

Total registered components: 67.

theme

Cores, espaçamento, tipografia e construção de tema compartilhados.

Component	Version	Description
DEx_Theme	0.0.1	Tokens de design e construtor de tema Flet.
DEx_ColorThemes	0.0.1	Temas de cor acessíveis 60-30-10 para aplicações DEx.

primitives

Elementos visuais atômicos para composição de controles maiores.

Component	Version	Description
DEx_Badge	0.0.1	Rótulo compacto de status e categoria.
DEx_Divider	0.0.1	Separador horizontal sutil.
DEx_SectionEyebrow	0.0.1	Marcador de seção numerado em ciano.
DEx_StatusDot	0.0.1	Indicador de estado colorido em miniatura.
DEx_Avatar	0.0.1	Avatar circular com iniciais coloridas e grupo com overflow.
DEx_Image	0.0.1	Imagem com bordas arredondadas e placeholder de estado vazio.
DEx_Icon	0.0.1	Ícone com tokens de tamanho SM/MD/LG/XL e badge overlay.
DEx_Markdown	0.0.1	Renderizador Markdown com suporte a tabelas e código.

cards

Superfícies reutilizáveis para métricas, entidades e conteúdo agrupado.

Component	Version	Description
DEx_Card	0.0.1	Superfície base para conteúdo agrupado.
DEx_MetricCard	0.0.1	Card de KPI com valor, ícone e variação.
DEx_ContactCard	0.0.1	Card de entidade com iniciais, metadados e rodapé.

buttons

Controles de ação: primário, secundário e somente ícone.

Component	Version	Description
DEx_BtnPrimary	0.1.0	Botão de ação primária.
DEx_BtnGhost	0.0.1	Botão de ação secundária com borda.
DEx_BtnIcon	0.0.1	Botão de ação somente com ícone.
DEx_BtnFilled	0.0.1	Botão preenchido de alta ênfase.
DEx_BtnTonal	0.0.1	Botão tonal de ênfase secundária.
DEx_BtnText	0.0.1	Botão textual de menor ênfase.
DEx_BtnFAB	0.0.1	Botão de ação flutuante para criação de registros.
DEx_BtnSegmented	0.0.1	Alternador de múltiplas opções mutuamente exclusivas.
DEx_MenuBar	0.0.1	Barra de menus horizontal com submenus.
DEx_PopupMenu	0.0.1	Menu de contexto acionado por ícone.

inputs

Controles de formulário e busca estilizados para o sistema visual DEx.

Component	Version	Description
DEx_TextField	0.0.1	Campo de texto estilizado.
DEx_SearchField	0.0.1	Campo de busca com ícone de lupa.
DEx_Dropdown	0.0.1	Seletor de opções estilizado.
DEx_Checkbox	0.0.1	Caixa de seleção booleana ou tristate estilizada.
DEx_Switch	0.0.1	Toggle switch para configurações binárias.
DEx_Radio	0.0.1	Opção de rádio e grupo para seleção mutuamente exclusiva.
DEx_Slider	0.0.1	Slider de valor único e de intervalo para entrada numérica.
DEx_Chip	0.0.1	Chip selecionável para filtros e multi-seleção.
DEx_AutoComplete	0.0.1	Campo de texto com dropdown de sugestões predefinidas.
DEx_SearchBar	0.0.1	Barra de pesquisa expansível com overlay de sugestões.
DEx_DateField	0.0.1	Campo de data estilizado com ícone e range opcional.
DEx_TimeField	0.0.1	Campo de horário com máscara hh:mm e range opcional.
DEx_FilePicker	0.1.0	Seletor de arquivo nativo com filtro de extensões.

data

Controles para tabelas, pipelines e visualizações de dados operacionais.

Component	Version	Description
DEx_DataTable	0.0.1	Tabela de dados estilizada.
DEx_PipelineColumn	0.0.1	Coluna de pipeline/Kanban por etapa.
DEx_TreeView	0.0.1	Árvore hierárquica com busca, expansão e seleção.
DEx_ListTile	0.0.1	Item de lista com título, subtítulo, leading e trailing.
DEx_ExpansionTile	0.0.1	Tile expansível que revela controles filhos.
DEx_ExpansionPanel	0.0.1	Painel acordeão agrupado em ExpansionPanelList.
DEx_ListView	0.0.1	Lista vertical com scroll e divisores automáticos.
DEx_GridView	0.0.1	Grade responsiva para cards e itens repetidos.

layout

Frame da aplicação, navegação e controles de estrutura de página.

Component	Version	Description
DEx_AppShell	0.0.1	Shell da aplicação com sidebar e área de conteúdo.
DEx_Sidebar	0.0.1	Sidebar de navegação vertical.
DEx_Header	0.0.1	Cabeçalho de página com busca e ações.
DEx_NavItem	0.1.0	Item de navegação com acento de estado ativo.
DEx_Tabs	0.0.1	Barra de abas horizontal com indicador em ACCENT.
DEx_NavigationBar	0.0.1	Barra de navegação inferior estilo mobile.
DEx_NavigationRail	0.0.1	Rail de navegação vertical compacto para desktop.
DEx_NavigationDrawer	0.0.1	Drawer lateral de navegação secundária.
DEx_AppBar	0.0.1	Barra superior de aplicação com título e ações.
DEx_BottomAppBar	0.0.1	Barra inferior com ações e suporte a FAB.
DEx_Stack	0.0.1	Stack com posicionamento absoluto, overlay e badge.
DEx_ResponsiveRow	0.0.1	Grade responsiva de 12 colunas com DEx_Col.
DEx_GestureDetector	0.0.1	Detector de tap, double-tap, long-press, hover e pan.
DEx_Draggable	0.0.1	Drag-and-drop: Draggable + DragTarget por grupo.
DEx_AnimatedSwitcher	0.0.1	Troca de conteúdo animada (FADE/SCALE/ROTATION).

feedback

Controles de feedback do usuário para estados transitórios.

Component	Version	Description
DEx_Notify	0.0.1	Notificação temporária tipo snackbar.
DEx_AlertDialog	0.0.1	Diálogo modal para confirmações e alertas.
DEx_BottomSheet	0.0.1	Painel deslizante que emerge da borda inferior.
DEx_Banner	0.0.1	Banner persistente abaixo do AppBar para avisos.
DEx_Tooltip	0.0.1	Dica contextual ao hover ou long-press.
DEx_ProgressBar	0.0.1	Barra de progresso horizontal determinada ou indeterminada.
DEx_ProgressRing	0.0.1	Indicador circular de progresso com label opcional.
DEx_Shimmer	0.0.1	Esqueletos de carregamento: ShimmerCard, ShimmerList.

Adding a Component

1. Create the component under the correct components/<group>/ folder.
2. Add COMPONENT_VERSION = "0.0.1" for a new component.
3. Add a docstring to the public component factory or class.
4. Add metadata to components/metadata.py.
5. Create an isolated use case in use_cases/.
6. Run python -m compileall components use_cases catalog.

Skipping metadata is not harmless: the component will exist in code but disappear from the catalog.