@polymorphism-tech/morph-spec 1.0.4 → 2.1.0

package/content/.morph/templates/ui-components.md

@@ -0,0 +1,276 @@
+# UI Components - {{FEATURE_NAME_TITLE}}
+
+> Especificação dos componentes Fluent UI / MudBlazor utilizados nesta feature.
+> Mapeia cada elemento visual para um componente concreto da biblioteca escolhida.
+
+---
+
+## Decisão de Biblioteca UI
+
+### Biblioteca Escolhida: {Fluent UI Blazor | MudBlazor | Híbrida}
+
+**Justificativa:**
+{Por que esta biblioteca foi escolhida para ESTA feature específica?}
+
+**Critérios de decisão:**
+- ✅ **{Critério 1}**: {Explicação}
+- ✅ **{Critério 2}**: {Explicação}
+- ⚠️ **{Trade-off}**: {O que foi sacrificado e por quê}
+
+**Referência ADR**: Ver `decisions.md` - ADR-{número}: {Título da decisão}
+
+---
+
+## Componentes Mapeados
+
+### {Nome do Elemento Visual}
+
+**Biblioteca**: {Fluent UI | MudBlazor}
+**Componente**: `{ComponentName}`
+
+#### Props Principais
+```csharp
+<{ComponentName}
+    Prop1="{valor ou @binding}"
+    Prop2="{valor ou @binding}"
+    Prop3="{valor ou @binding}"
+    OnClick="@{Handler}" />
+```
+
+#### Propriedades Detalhadas
+| Prop | Tipo | Valor | Descrição |
+|------|------|-------|-----------|
+| `Prop1` | `string` | `"{valor}"` | {Para que serve} |
+| `Prop2` | `bool` | `true` | {Para que serve} |
+| `Prop3` | `EventCallback` | `@Handler` | {Quando dispara} |
+
+#### Estados
+
+**1. Default (Estado Inicial)**
+```razor
+<{ComponentName}
+    Appearance="Appearance.Neutral"
+    Disabled="false">
+    {Conteúdo padrão}
+</{ComponentName}>
+```
+
+**2. Loading**
+```razor
+@if (_isLoading)
+{
+    <FluentSkeleton Width="100%" Height="40px" />
+    <!-- OU -->
+    <FluentProgress />
+}
+else
+{
+    <{ComponentName} ... />
+}
+```
+
+**3. Error**
+```razor
+@if (!string.IsNullOrEmpty(_error))
+{
+    <FluentMessageBar Intent="MessageIntent.Error">
+        @_error
+    </FluentMessageBar>
+}
+<{ComponentName} ... />
+```
+
+**4. Empty (Sem Dados)**
+```razor
+@if (!_items.Any())
+{
+    <FluentStack Orientation="Orientation.Vertical" HorizontalAlignment="HorizontalAlignment.Center">
+        <FluentLabel>Nenhum item encontrado</FluentLabel>
+        <FluentButton Appearance="Appearance.Accent" OnClick="@Create">
+            Criar Novo
+        </FluentButton>
+    </FluentStack>
+}
+```
+
+**5. Success (Feedback Positivo)**
+```razor
+<FluentToast Intent="ToastIntent.Success" Timeout="3000">
+    Operação realizada com sucesso!
+</FluentToast>
+```
+
+#### Eventos
+
+| Evento | Handler | Ação |
+|--------|---------|------|
+| `OnClick` | `HandleClick` | {O que acontece ao clicar} |
+| `OnChange` | `HandleChange` | {O que acontece ao mudar valor} |
+| `OnSubmit` | `HandleSubmit` | {O que acontece ao submeter} |
+
+#### Exemplo de Código Completo
+
+```razor
+<!-- {Nome do Componente}.razor -->
+<{ComponentName}
+    Items="@_items"
+    Loading="@_isLoading"
+    OnClick="@HandleClick">
+
+    @if (_isLoading)
+    {
+        <FluentProgress />
+    }
+    else
+    {
+        @foreach (var item in _items)
+        {
+            <{ChildComponent} Data="@item" />
+        }
+    }
+</{ComponentName}>
+
+@code {
+    [Parameter] public List<ItemType> Items { get; set; } = new();
+
+    private bool _isLoading;
+    private string? _error;
+
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadDataAsync();
+    }
+
+    private async Task LoadDataAsync()
+    {
+        _isLoading = true;
+        try
+        {
+            _items = await _service.GetItemsAsync();
+        }
+        catch (Exception ex)
+        {
+            _error = ex.Message;
+        }
+        finally
+        {
+            _isLoading = false;
+        }
+    }
+
+    private async Task HandleClick(ItemType item)
+    {
+        // Ação ao clicar
+    }
+}
+```
+
+#### Acessibilidade
+
+**ARIA Attributes:**
+- `role="{role}"`: {Propósito}
+- `aria-label="{label}"`: {Descrição para screen readers}
+- `aria-describedby="{id}"`: {Descrição adicional}
+
+**Keyboard Navigation:**
+- `Tab`: {Foca no elemento}
+- `Enter/Space`: {Ativa o elemento}
+- `Escape`: {Cancela/fecha}
+- `Arrow Keys`: {Navega entre opções}
+
+**Focus Management:**
+- **Foco inicial**: {Onde o foco deve ir quando o componente aparece}
+- **Focus trap**: {Se aplicável, como manter o foco dentro do componente (modals)}
+
+---
+
+## {Próximo Componente}
+
+{Repita a estrutura acima para cada componente}
+
+---
+
+## Componentes Customizados
+
+### {Nome do Componente Custom}
+
+Se você precisar criar um componente que NÃO existe em Fluent UI ou MudBlazor:
+
+**Composição:**
+```razor
+<!-- Components/{ComponentName}.razor -->
+<div class="custom-component">
+    <FluentCard>
+        <FluentStack Orientation="Orientation.Vertical">
+            <!-- Composição de componentes existentes -->
+        </FluentStack>
+    </FluentCard>
+</div>
+
+@code {
+    // Lógica do componente
+}
+```
+
+**Quando usar:**
+- {Situação 1 que justifica componente custom}
+- {Situação 2}
+
+---
+
+## Packages Necessários
+
+### Fluent UI Blazor
+```xml
+<PackageReference Include="Microsoft.FluentUI.AspNetCore.Components" Version="4.0.0" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddFluentUIComponents();
+```
+
+```razor
+// _Imports.razor
+@using Microsoft.FluentUI.AspNetCore.Components
+```
+
+### MudBlazor (se híbrido)
+```xml
+<PackageReference Include="MudBlazor" Version="6.11.0" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddMudServices();
+```
+
+```razor
+// _Imports.razor
+@using MudBlazor
+```
+
+---
+
+## Mapa de Componentes
+
+Resumo visual de quais componentes são usados onde:
+
+| Tela/Feature | Componente | Biblioteca | Complexidade |
+|--------------|------------|------------|--------------|
+| {Tela 1} | FluentDataGrid | Fluent UI | Média |
+| {Tela 1} | FluentCard | Fluent UI | Baixa |
+| {Tela 2} | MudChart | MudBlazor | Alta |
+| {Tela 2} | FluentDialog | Fluent UI | Média |
+
+---
+
+## Referências
+
+- [Fluent UI Components](https://www.fluentui-blazor.net/Components)
+- [MudBlazor Components](https://mudblazor.com/components/list)
+- [Guia Fluent UI Setup](../.morph/standards/fluent-ui-setup.md)
+
+---
+
+*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*

package/content/.morph/templates/ui-design-system.md

@@ -0,0 +1,286 @@
+# UI Design System - {Project Name}
+
+> Design system do projeto: cores, tipografia, espaçamento e padrões visuais.
+> Este arquivo é a fonte da verdade para todos os aspectos visuais do projeto.
+
+---
+
+## 🎨 Paleta de Cores
+
+### Cores Principais
+
+| Uso | Cor | Hex | RGB | Preview |
+|-----|-----|-----|-----|---------|
+| **Primária** | {Nome da cor} | `#{hex}` | `rgb({r}, {g}, {b})` | ███ |
+| **Secundária** | {Nome da cor} | `#{hex}` | `rgb({r}, {g}, {b})` | ███ |
+
+**Exemplo:**
+| Uso | Cor | Hex | RGB | Preview |
+|-----|-----|-----|-----|---------|
+| **Primária** | Blue | `#3b82f6` | `rgb(59, 130, 246)` | 🔵 |
+| **Secundária** | Gray | `#6b7280` | `rgb(107, 114, 128)` | ⚫ |
+
+### Cores de Estado
+
+| Estado | Cor | Hex | RGB | Uso |
+|--------|-----|-----|-----|-----|
+| **Sucesso** | {Cor} | `#{hex}` | `rgb({r}, {g}, {b})` | Confirmações, operações bem-sucedidas |
+| **Erro** | {Cor} | `#{hex}` | `rgb({r}, {g}, {b})` | Erros, validações falhas |
+| **Warning** | {Cor} | `#{hex}` | `rgb({r}, {g}, {b})` | Avisos, atenção necessária |
+| **Info** | {Cor} | `#{hex}` | `rgb({r}, {g}, {b})` | Informações, dicas |
+
+**Exemplo (Tailwind):**
+| Estado | Cor | Hex | RGB | Uso |
+|--------|-----|-----|-----|-----|
+| **Sucesso** | Green | `#10b981` | `rgb(16, 185, 129)` | Confirmações |
+| **Erro** | Red | `#ef4444` | `rgb(239, 68, 68)` | Erros |
+| **Warning** | Amber | `#f59e0b` | `rgb(245, 158, 11)` | Avisos |
+| **Info** | Cyan | `#06b6d4` | `rgb(6, 182, 212)` | Informações |
+
+### Escala de Neutros (Cinzas)
+
+| Shade | Hex | RGB | Uso |
+|-------|-----|-----|-----|
+| **50** | `#{hex}` | `rgb({r}, {g}, {b})` | Fundos muito claros |
+| **100** | `#{hex}` | `rgb({r}, {g}, {b})` | Fundos claros |
+| **200** | `#{hex}` | `rgb({r}, {g}, {b})` | Bordas suaves |
+| **300** | `#{hex}` | `rgb({r}, {g}, {b})` | Bordas padrão |
+| **400** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto desabilitado |
+| **500** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto secundário |
+| **600** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto placeholder |
+| **700** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto principal |
+| **800** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto ênfase |
+| **900** | `#{hex}` | `rgb({r}, {g}, {b})` | Texto super ênfase |
+
+**Exemplo (Tailwind Gray):**
+| Shade | Hex | RGB |
+|-------|-----|-----|
+| **50** | `#f9fafb` | `rgb(249, 250, 251)` |
+| **100** | `#f3f4f6` | `rgb(243, 244, 246)` |
+| **500** | `#6b7280` | `rgb(107, 114, 128)` |
+| **900** | `#111827` | `rgb(17, 24, 39)` |
+
+---
+
+## 🔤 Tipografia
+
+### Fontes
+
+| Tipo | Font Family | Stack Completo | Uso |
+|------|-------------|----------------|-----|
+| **Sans-serif** | {Font} | `'{Font}', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` | Texto principal, UI |
+| **Serif** | {Font} | `'{Font}', Georgia, serif` | Títulos, ênfase (opcional) |
+| **Monospace** | {Font} | `'{Font}', 'Courier New', monospace` | Código, dados técnicos |
+
+**Exemplo:**
+| Tipo | Font Family | Stack | Uso |
+|------|-------------|-------|-----|
+| **Sans-serif** | Inter | `'Inter', -apple-system, sans-serif` | Texto principal |
+| **Monospace** | Fira Code | `'Fira Code', 'Courier New', monospace` | Código |
+
+### Escala de Tamanhos
+
+| Size | Valor | Line Height | Uso |
+|------|-------|-------------|-----|
+| **xs** | `{size}` | `{height}` | Texto muito pequeno, labels |
+| **sm** | `{size}` | `{height}` | Texto pequeno, captions |
+| **base** | `{size}` | `{height}` | Texto padrão, body |
+| **lg** | `{size}` | `{height}` | Texto grande, leads |
+| **xl** | `{size}` | `{height}` | Títulos H4 |
+| **2xl** | `{size}` | `{height}` | Títulos H3 |
+| **3xl** | `{size}` | `{height}` | Títulos H2 |
+| **4xl** | `{size}` | `{height}` | Títulos H1 |
+| **5xl** | `{size}` | `{height}` | Display text |
+
+**Exemplo (Tailwind):**
+| Size | Valor | Line Height |
+|------|-------|-------------|
+| **xs** | `0.75rem` (12px) | `1rem` (16px) |
+| **sm** | `0.875rem` (14px) | `1.25rem` (20px) |
+| **base** | `1rem` (16px) | `1.5rem` (24px) |
+| **lg** | `1.125rem` (18px) | `1.75rem` (28px) |
+| **xl** | `1.25rem` (20px) | `1.75rem` (28px) |
+| **4xl** | `2.25rem` (36px) | `2.5rem` (40px) |
+
+### Pesos (Font Weight)
+
+| Weight | Valor | Uso |
+|--------|-------|-----|
+| **Light** | `300` | Texto decorativo, opcional |
+| **Regular** | `400` | Texto padrão |
+| **Medium** | `500` | Texto com ênfase leve |
+| **Semibold** | `600` | Botões, labels importantes |
+| **Bold** | `700` | Títulos, ênfase forte |
+
+---
+
+## 📏 Espaçamento
+
+### Sistema Base
+
+**Unidade base:** `{value}` (ex: 4px, 8px)
+**Escala:** Múltiplos da unidade base
+
+| Token | Valor | Pixels | Uso |
+|-------|-------|--------|-----|
+| **0** | `0` | 0px | Sem espaçamento |
+| **1** | `{base * 1}` | {px} | Espaço mínimo |
+| **2** | `{base * 2}` | {px} | Espaço pequeno |
+| **3** | `{base * 3}` | {px} | Espaço médio-pequeno |
+| **4** | `{base * 4}` | {px} | Espaço médio |
+| **5** | `{base * 5}` | {px} | Espaço médio-grande |
+| **6** | `{base * 6}` | {px} | Espaço grande |
+| **8** | `{base * 8}` | {px} | Espaço muito grande |
+| **10** | `{base * 10}` | {px} | Espaço extra grande |
+| **12** | `{base * 12}` | {px} | Espaço gigante |
+
+**Exemplo (base 4px = 0.25rem):**
+| Token | Valor | Pixels | Uso |
+|-------|-------|--------|-----|
+| **1** | `0.25rem` | 4px | Gap mínimo entre ícones |
+| **2** | `0.5rem` | 8px | Padding interno de botões |
+| **4** | `1rem` | 16px | Padding padrão de cards |
+| **6** | `1.5rem` | 24px | Margin entre seções |
+| **8** | `2rem` | 32px | Margin grande entre blocos |
+
+---
+
+## 🔲 Border Radius
+
+| Size | Valor | Uso |
+|------|-------|-----|
+| **none** | `0` | Sem arredondamento |
+| **sm** | `{value}` | Arredondamento sutil |
+| **md** | `{value}` | Arredondamento padrão |
+| **lg** | `{value}` | Arredondamento pronunciado |
+| **xl** | `{value}` | Muito arredondado |
+| **full** | `9999px` | Circular (botões redondos, avatares) |
+
+**Exemplo:**
+| Size | Valor | Uso |
+|------|-------|-----|
+| **sm** | `0.125rem` (2px) | Inputs, tabelas |
+| **md** | `0.375rem` (6px) | Botões, cards |
+| **lg** | `0.5rem` (8px) | Modais, containers |
+| **full** | `9999px` | Avatares, badges circulares |
+
+---
+
+## 🌑 Sombras (Shadows)
+
+| Size | Valor | Uso |
+|------|-------|-----|
+| **sm** | `{shadow}` | Sombra sutil (hover) |
+| **md** | `{shadow}` | Sombra padrão (cards) |
+| **lg** | `{shadow}` | Sombra pronunciada (modals) |
+| **xl** | `{shadow}` | Sombra forte (dropdowns) |
+
+**Exemplo (Tailwind):**
+| Size | Valor |
+|------|-------|
+| **sm** | `0 1px 2px 0 rgba(0, 0, 0, 0.05)` |
+| **md** | `0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)` |
+| **lg** | `0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)` |
+
+---
+
+## 📱 Breakpoints (Responsive)
+
+| Breakpoint | Min Width | Dispositivos |
+|------------|-----------|--------------|
+| **xs** | `0px` | Mobile portrait (padrão) |
+| **sm** | `{value}` | Mobile landscape / Tablet pequeno |
+| **md** | `{value}` | Tablet |
+| **lg** | `{value}` | Desktop pequeno |
+| **xl** | `{value}` | Desktop grande |
+| **2xl** | `{value}` | Desktop muito grande |
+
+**Exemplo (Tailwind):**
+| Breakpoint | Min Width |
+|------------|-----------|
+| **sm** | `640px` |
+| **md** | `768px` |
+| **lg** | `1024px` |
+| **xl** | `1280px` |
+| **2xl** | `1536px` |
+
+---
+
+## 🎯 Aplicação no Código
+
+### CSS Variables (Recomendado)
+
+Ver template: `design-system.css`
+
+```css
+:root {
+  /* Cores */
+  --color-primary: #{hex};
+  --color-secondary: #{hex};
+
+  /* Tipografia */
+  --font-sans: '{Font}', sans-serif;
+  --text-base: 1rem;
+
+  /* Espaçamento */
+  --space-4: 1rem;
+}
+```
+
+### Fluent UI Theme (se Fluent UI)
+
+Ver template: `FluentDesignTheme.cs`
+
+```csharp
+public static class FluentDesignTheme
+{
+    public static DesignThemePalette GetPalette() => new()
+    {
+        Primary = "#{cor primária}",
+        // ...
+    };
+}
+```
+
+### MudBlazor Theme (se MudBlazor)
+
+Ver template: `MudTheme.cs`
+
+```csharp
+public static MudTheme Theme => new()
+{
+    Palette = new PaletteLight
+    {
+        Primary = "#{cor primária}",
+        // ...
+    }
+};
+```
+
+---
+
+## 📋 Checklist de Consistência
+
+- [ ] Todas as cores têm hex + rgb documentados
+- [ ] Escala de neutros completa (50-900)
+- [ ] Fontes têm fallback stacks completos
+- [ ] Escala de tamanhos cobre todos os casos (xs até 5xl)
+- [ ] Espaçamento usa múltiplos da unidade base
+- [ ] Border radius tem tamanhos sm, md, lg, full
+- [ ] Sombras têm variações de intensidade
+- [ ] Breakpoints cobrem mobile até desktop grande
+- [ ] Design system será implementado na FASE 5 (arquivos CSS/C#)
+
+---
+
+## 🔗 Referências
+
+- [Fluent Design System](https://fluent2.microsoft.design/)
+- [Material Design](https://m3.material.io/)
+- [Tailwind CSS Palette](https://tailwindcss.com/docs/customizing-colors)
+- [Type Scale](https://type-scale.com/)
+- [Modular Scale](https://www.modularscale.com/)
+
+---
+
+*Template MORPH-SPEC v2.1.1 by Polymorphism Tech*