# UI Kit admin Matdash + TIIX

## Objetivo

Padronizar a criacao e a refatoracao de telas em `pages/admin` usando o maximo do Matdash como base e deixando o CSS customizado concentrado em wrappers compartilhados e identidade visual TIIX.

## Base oficial

- Template principal: `assets/matdash/css/styles.css`
- Camada TIIX compartilhada: `public/assets/app/css/shared/custom.css`
- Helpers PHP compartilhados: `includes/helpers/MatdashComponents.php`
- Tela de referencia viva: `pages/admin/ui-kit.php`

## Regra de ouro

1. Primeiro procurar o equivalente no Matdash.
2. Depois encaixar no wrapper TIIX compartilhado.
3. So por ultimo criar CSS especifico de pagina, e apenas quando houver necessidade real de dominio.
4. Se houver filtros relevantes, eles devem subir para os `$botoes` do topo e abrir em offcanvas.
5. Breadcrumb nao e opcional: toda tela admin deve nascer com trilha de navegacao clara.
6. JavaScript de pagina unica deve ficar embedado na propria tela, salvo quando o tamanho, reuso ou complexidade justificarem arquivo dedicado.
7. Presets de filtro e atalhos de recorte devem morar no mesmo offcanvas ou no topo, nunca duplicados no corpo da pagina.
8. Tabelas devem ocupar largura total quando nao houver necessidade real de scroll horizontal.
9. Cards analiticos secundarios podem correr em linha abaixo da tabela, em vez de competir com ela em sidebar fixa.
10. Configuracoes tecnicas e formularios auxiliares podem ir para offcanvas quando nao forem o foco primario da leitura.
11. Controles booleanos devem preferir `switch` nativo com `form-check form-switch` em vez de checkbox cru.
12. Radios com poucas opcoes e leitura mais visual podem usar `btn-check` com labels estilo segmentado; radios simples ficam para escolhas lineares.
13. Quando houver valor operacional claro, dashboards administrativos podem usar `ApexCharts` do Matdash com polling leve para leitura quase em tempo real.
14. Graficos operacionais precisam explicitar a fonte dos dados e, quando houver amostragem, isso deve aparecer no proprio contexto da tela.

## Demos Matdash prioritarios

### Formularios

- `form-basic.html`
- `form-vertical.html`
- `form-select2.html`
- `form-wizard.html`
- `form-repeater.html`
- `form-dropzone.html`

### Tabelas

- `table-basic.html`
- `table-datatable-basic.html`
- `table-datatable-advanced.html`

### Cards e widgets

- `ui-cards.html`
- `widgets-cards.html`
- `widgets-banners.html`
- `widgets-charts.html`
- `widgets-data.html`
- `widgets-feeds.html`

### Feedback e notificacao

- `component-sweetalert.html`
- `component-toastr.html`
- `ui-notification.html`

## Componentes oficiais do projeto

### PHP

- `md_card()`: cartao simples
- `md_kpi_card()`: KPI padrao TIIX
- `md_alert()`: alerta persistente no corpo da pagina
- `md_data_card()`: casca padrao para blocos de dados
- `md_form_section()`: secao de formulario
- `md_empty_state()`: estado vazio com contexto e CTA

### CSS compartilhado

- `tiix-page-hero`: hero principal de modulo
- `tiix-kpi-card`: KPI padrao
- `tiix-soft-card`: card suave para blocos estrategicos
- `tiix-data-card`: card de conteudo/tabela
- `tiix-form-section`: secao de formulario
- `tiix-table-shell`: casca de tabelas
- `tiix-filter-card`: filtros e barras de recorte
- `tiix-context-alert`: alertas de contexto
- `tiix-empty-state`: estado vazio oficial
- `tiix-lite-chip`, `tiix-status-chip`, `tiix-meta-grid`, `tiix-list-card`: utilitarios de apoio

## Padrao por tipo de tela

### CRUD administrativo

- Hero curto com objetivo da tela
- Breadcrumb obrigatorio
- Barra de acoes no topo
- Filtros acionados pelos `$botoes` e exibidos em offcanvas
- Formulario com `md_form_section()`
- Tabela com `md_data_card()` + `tiix-table-shell`

### Central operacional

- Breadcrumb obrigatorio
- Hero com leitura executiva
- Linha de KPIs com `md_kpi_card()`
- Filtros no topo com offcanvas quando existirem recortes
- Blocos de dados em `tiix-data-card`
- Alerts persistentes com `md_alert()`
- SweetAlert para confirmacoes e acoes sensiveis

### Dashboard

- Hero + KPIs
- Widgets em grid
- Cards suaves para resumos
- Tabela apenas quando houver necessidade de detalhe operacional

## O que evitar

- `<style>` grande dentro de pagina quando o padrao puder entrar no `custom.css`
- `style=""` inline para layout recorrente
- Recriar card, tabela ou alerta do zero sem consultar o kit
- Duplicar acao de atualizar ou filtrar no topo e dentro do corpo da tela
- Deixar filtros abertos ocupando a area principal quando eles puderem viver em offcanvas
- Criar arquivo `.js` dedicado para uma unica tela sem necessidade clara
- Variar botoes e espacos de DataTable fora da configuracao compartilhada
- Misturar linguagem visual antiga com componentes novos na mesma area sem motivo claro

## Fluxo recomendado para nova tela

1. Escolher o demo Matdash mais proximo.
2. Montar a tela usando `ui-kit.php` como referencia estrutural.
3. Reaproveitar os helpers PHP compartilhados.
4. Se faltar um wrapper visual, adiciona-lo no `custom.css` de forma generica.
5. So depois tratar ajustes muito especificos do modulo.