@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/skills/level-2-domains/frontend/nextjs-expert.md

@@ -0,0 +1,154 @@
+# .NET + Next.js Stack
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** nextjs, next.js, react, api, frontend, spa, typescript
+
+| Aspect | Technology |
+|--------|------------|
+| **Backend** | .NET 10 Web API / C# 14 |
+| **Frontend** | Next.js 15+ / React 19 |
+| **Database** | EF Core 10 + Azure SQL |
+| **API** | REST + OpenAPI |
+| **Hosting** | Azure Container Apps |
+
+## Project Structure
+
+```
+/
+├── backend/
+│   ├── src/{Api,Application,Domain,Infrastructure}/
+│   ├── tests/
+│   └── Backend.sln
+├── frontend/
+│   ├── src/{app,components,lib,hooks}/
+│   ├── package.json
+│   └── next.config.js
+├── docker-compose.yml
+└── infra/main.bicep
+```
+
+---
+
+## Backend (.NET Minimal API)
+
+```csharp
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+builder.Services.AddCors(o => o.AddPolicy("Frontend", p =>
+    p.WithOrigins(builder.Configuration["Frontend:Url"]!)
+     .AllowAnyHeader().AllowAnyMethod().AllowCredentials()));
+builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(connString));
+
+var app = builder.Build();
+if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }
+app.UseCors("Frontend");
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapOrderEndpoints();
+app.Run();
+```
+
+### Minimal API Endpoints
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void MapOrderEndpoints(this WebApplication app)
+    {
+        var group = app.MapGroup("/api/orders").WithTags("Orders").RequireAuthorization();
+        group.MapGet("/", GetAll);
+        group.MapGet("/{id:int}", GetById);
+        group.MapPost("/", Create);
+        group.MapPut("/{id:int}", Update);
+        group.MapDelete("/{id:int}", Delete);
+    }
+    // Each handler: inject IService + params → return Results.Ok/NotFound/Created/NoContent
+}
+```
+
+---
+
+## Frontend (Next.js)
+
+### API Client
+
+```typescript
+const API_URL = process.env.NEXT_PUBLIC_API_URL!;
+
+async function fetchApi<T>(endpoint: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${API_URL}${endpoint}`, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...options?.headers },
+    credentials: 'include',
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
+export const api = {
+  orders: {
+    getAll: (params?) => fetchApi<PaginatedResult<Order>>(`/api/orders?${new URLSearchParams(params)}`),
+    getById: (id: number) => fetchApi<Order>(`/api/orders/${id}`),
+    create: (data) => fetchApi<Order>('/api/orders', { method: 'POST', body: JSON.stringify(data) }),
+  },
+};
+```
+
+### Types (generated from OpenAPI)
+
+```typescript
+export interface Order { id: number; orderNumber: string; total: number; status: OrderStatus; }
+export type OrderStatus = 'Pending' | 'Processing' | 'Completed' | 'Cancelled';
+export interface PaginatedResult<T> { items: T[]; totalCount: number; page: number; totalPages: number; }
+```
+
+### Server Component (App Router)
+```tsx
+export default async function OrdersPage() {
+  const orders = await api.orders.getAll();
+  return <OrderList initialOrders={orders} />;
+}
+```
+
+### Client Component
+```tsx
+'use client';
+// Use useState + api calls for client-side pagination/interaction
+```
+
+---
+
+## Docker Compose
+
+```yaml
+services:
+  backend:
+    build: { context: ./backend }
+    ports: ["5000:8080"]
+    environment:
+      - ConnectionStrings__Default=Server=db;Database=App;User=sa;Password=Pass!;TrustServerCertificate=true
+      - Frontend__Url=http://localhost:3000
+  frontend:
+    build: { context: ./frontend }
+    ports: ["3000:3000"]
+    environment: [NEXT_PUBLIC_API_URL=http://localhost:5000]
+  db:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    environment: [ACCEPT_EULA=Y, SA_PASSWORD=YourStrong!Passw0rd]
+    ports: ["1433:1433"]
+```
+
+## Checklist
+- [ ] Backend with Minimal APIs
+- [ ] OpenAPI/Swagger configured
+- [ ] CORS configured for frontend
+- [ ] Frontend with App Router (Next.js 15+)
+- [ ] API client typed
+- [ ] Types generated from OpenAPI
+- [ ] Docker Compose for dev
+- [ ] Environment variables configured
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/frontend/ui-ux-designer.md

@@ -0,0 +1,191 @@
+# UI/UX Designer
+
+Especialista em design de interfaces, UX e componentes Blazor. Domina **Fluent UI Blazor** e **MudBlazor**.
+
+> **FASE 1.5: UI/UX DESIGN** - Obrigatória para features com front-end.
+> Gera wireframes, specs de componentes e fluxos ANTES do design técnico.
+> **Ref:** `framework/standards/fluent-ui-blazor.md` para API details e armadilhas.
+
+## Triggers
+
+Keywords: `blazor`, `component`, `page`, `ui`, `ux`, `design`, `layout`, `wizard`, `dashboard`, `form`, `chart`, `table`, `dialog`, `modal`, `tela`, `interface`, `formulário`
+
+---
+
+## Design Moderno (2025+)
+
+### Visual Trends
+- **Glassmorphism**: `backdrop-filter: blur(10px)`, semi-transparent backgrounds
+- **Gradients**: Purple (#667eea → #764ba2), Blue-Purple (#4facfe → #00f2fe)
+- **Soft Shadows**: `box-shadow: 0 4px 6px rgba(0,0,0,0.1)`
+- **Rounded Corners**: `border-radius: 12px-16px`
+- **Micro-interactions**: Hover effects, transitions (transform, scale, opacity)
+
+### Component Patterns
+- Cards with elevation + hover lift
+- Skeleton loaders (not just spinners)
+- Toast notifications (bottom-right, auto-dismiss)
+- Empty states with illustration + CTA
+- Dark mode support (always design for both)
+
+### Layout Principles
+- Whitespace: 32px-48px container padding
+- Grid: 12-column, gap 24px-32px
+- Typography: xs:12, sm:14, base:16, lg:18, xl:20, 2xl:24
+- Contrast: WCAG AA (4.5:1 text, 3:1 UI)
+
+### Design References
+Linear (linear.app), Vercel (vercel.com), Stripe (stripe.com), Dribbble dashboards
+
+---
+
+## FASE 1.5 Workflow
+
+### Step 1: Collect User Input (ALWAYS ask first)
+
+1. Layout ideas or reference sites?
+2. Visual references (screenshots, mockups)?
+3. User flow expectations?
+4. Design system defined (colors, fonts, spacing)?
+5. Image examples to analyze?
+
+If user provides screenshots → Read tool → extract patterns (layout, components, colors).
+If HTML prototype exists → extract patterns automatically, skip wireframes, map HTML → Blazor.
+
+### Step 2: Generate Deliverables
+
+| File | Content |
+|------|---------|
+| `ui-design-system.md` | Colors, typography, spacing |
+| `ui-mockups.md` | ASCII wireframes + descriptions per screen |
+| `ui-components.md` | Component specs (library-agnostic first, library choice in FASE 2) |
+| `ui-flows.md` | User flow diagrams + edge cases |
+
+**Important:** Generate specs AGNOSTIC of UI library. Use generic names ("primary button", "card", "table"). Library choice happens in FASE 2: DESIGN.
+
+### Step 3: Present for Approval
+
+Show deliverable summary → **⛔ PAUSE** with 3 options (approve / adjust wireframes / add flows).
+
+---
+
+## Fluent UI vs MudBlazor Decision Matrix
+
+| Criterion | Fluent UI Blazor | MudBlazor |
+|-----------|------------------|-----------|
+| AI-first projects | Ideal (native components) | Requires customization |
+| Performance | ~200KB | ~500KB |
+| Microsoft Stack | Perfect integration | Works well |
+| Complex components | Limited | Very complete |
+| Community | Smaller (newer) | Larger |
+| Maturity | v4.0 (recent) | v6.x (stable) |
+
+**Use Fluent UI if:** AI-first, Microsoft stack, modern M365 design, performance critical.
+**Use MudBlazor if:** Complex dashboards, Material Design, need TreeView/advanced DataGrid, larger community.
+**Hybrid:** Fluent UI (base) + MudBlazor (specific complex components).
+
+---
+
+## Fluent UI Quick Reference
+
+> **Full details:** `framework/standards/fluent-ui-blazor.md`
+
+### Common Pitfalls
+
+| Issue | Wrong | Correct |
+|-------|-------|---------|
+| Icon sizes | `Size16`, `Size14` | `Size20`, `Size24`, `Size28`, `Size32`, `Size48` |
+| Icon namespace | `@using ...Icons` | `@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons` |
+| Toast methods | `await ShowSuccessAsync()` | `ToastService.ShowSuccess()` (sync!) |
+| Dialog show | `await _dialog.ShowAsync()` | `_dialog.Show()` (sync!) |
+| Dialog close | `_dialog.Hide()` | `await _dialog.CloseAsync()` (async!) |
+| Dialog init | `<FluentDialog>` | `<FluentDialog Hidden="true">` (must hide initially!) |
+
+### Key Components
+
+| Component | Use Case |
+|-----------|----------|
+| `FluentCard` + `FluentStack` | Containers, dashboards |
+| `FluentDataGrid` | Data tables with sorting |
+| `FluentWizard` | Multi-step flows |
+| `FluentDialog` | Modals, confirmations |
+| `FluentMessageBar` | Chat, notifications |
+| `FluentProgress` | Loading, streaming |
+| `FluentTextField` | Text inputs |
+| `FluentToast` | System feedback |
+
+---
+
+## MudBlazor Key Components
+
+| Component | Advantage over Fluent |
+|-----------|----------------------|
+| `MudDataGrid` | Grouping, advanced filtering |
+| `MudTreeView` | More complete hierarchies |
+| `MudChart` | Native charts (Fluent has none) |
+| `MudFileUpload` | More upload features |
+| `MudAutocomplete` | Better performance |
+
+---
+
+## Design System Defaults
+
+```css
+/* Colors */
+--primary: #3b82f6; --secondary: #6b7280;
+--success: #10b981; --warning: #f59e0b;
+--danger: #ef4444;  --info: #06b6d4;
+
+/* Spacing (4px system) */
+--space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem;
+--space-6: 1.5rem;  --space-8: 2rem;
+```
+
+---
+
+## Generating Deliverables
+
+### ui-mockups.md Structure
+
+Per screen: ASCII wireframe + description (purpose, components, interactions, states) + responsiveness (desktop/mobile).
+
+### ui-components.md Structure
+
+Per component: Library, component name, main props, events, states (default/loading/error/empty), accessibility (ARIA, keyboard).
+
+### ui-flows.md Structure
+
+Per flow: Trigger, steps, happy path, edge cases, ASCII flowchart diagram.
+
+---
+
+## Accessibility (A11y)
+
+- Contrast: 4.5:1 text minimum (WCAG AA)
+- Focus visible: Outline on focusable elements
+- Labels: Every input with associated label
+- ARIA: Roles and labels where needed
+- Keyboard nav: Logical tab order
+
+---
+
+## Checklist
+
+### FASE 1.5 Deliverables
+- [ ] `ui-mockups.md`: Wireframes for ALL screens + states (loading, error, empty) + responsiveness
+- [ ] `ui-components.md`: Library justified + all components mapped with props/events/states
+- [ ] `ui-flows.md`: Happy paths + edge cases + ASCII diagrams
+- [ ] `decisions.md`: Updated with UI library ADR
+
+### UI Quality
+- [ ] Visual hierarchy clear
+- [ ] Consistent spacing (4px multiples)
+- [ ] Responsive (mobile-first)
+- [ ] States: hover, focus, disabled, error
+- [ ] Loading states (skeleton/spinner)
+- [ ] Empty states with CTA
+- [ ] WCAG AA accessibility
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/infrastructure/azure-architect.md

@@ -0,0 +1,142 @@
+# Azure Architect
+
+Especialista em infraestrutura Azure com foco em Infrastructure as Code (Bicep).
+
+## Responsabilidades
+
+1. **Desenhar infraestrutura Azure** para projetos
+2. **Criar templates Bicep** para provisionar recursos
+3. **Estimar custos** antes de aprovar recursos
+4. **Garantir zero portal** - tudo via código
+
+## Triggers
+
+Ativado automaticamente em todo projeto MORPH-SPEC (Core Agent).
+
+Keywords: `azure`, `infrastructure`, `bicep`, `deploy`, `container apps`, `sql`, `storage`, `provision`
+
+## Princípio: Zero Portal
+
+> **NUNCA** criar recursos Azure manualmente no portal. Tudo via Bicep.
+
+## Estrutura IaC
+
+```
+infra/
+├── main.bicep                # Entry point
+├── parameters.dev.json       # Ambiente dev
+├── parameters.prod.json      # Ambiente prod
+└── modules/
+    ├── container-app.bicep   # Container Apps
+    ├── sql-database.bicep    # Azure SQL
+    ├── storage.bicep         # Storage Account
+    ├── key-vault.bicep       # Key Vault
+    ├── app-insights.bicep    # Monitoring
+    └── service-bus.bicep     # Mensageria
+```
+
+## Template Bicep Base
+
+```bicep
+// infra/main.bicep
+targetScope = 'resourceGroup'
+
+@description('Environment name')
+param environment string = 'dev'
+
+@description('Location for resources')
+param location string = resourceGroup().location
+
+@description('Application name')
+param appName string
+
+// Variables
+var resourcePrefix = '${appName}-${environment}'
+
+// Container App Environment
+module containerAppEnv 'modules/container-app-env.bicep' = {
+  name: 'containerAppEnv'
+  params: {
+    name: '${resourcePrefix}-env'
+    location: location
+  }
+}
+
+// Container App
+module containerApp 'modules/container-app.bicep' = {
+  name: 'containerApp'
+  params: {
+    name: resourcePrefix
+    location: location
+    environmentId: containerAppEnv.outputs.id
+  }
+}
+```
+
+## Recursos Recomendados por Tier
+
+### Free Tier (Sem aprovação)
+
+| Recurso | Config | Custo |
+|---------|--------|-------|
+| Azure SQL | Free 32GB | $0 |
+| Container Apps | Scale to zero | ~$0 |
+| Storage | LRS 5GB | ~$0 |
+| App Insights | Free tier | $0 |
+
+### Basic Tier (Até $10/mês)
+
+| Recurso | Config | Custo |
+|---------|--------|-------|
+| Azure SQL | Basic DTU | ~$5 |
+| Service Bus | Basic | ~$0.05 |
+| Key Vault | Standard | ~$0.03 |
+
+## Comandos de Deploy
+
+```powershell
+# Criar resource group
+az group create --name rg-{app}-{env} --location brazilsouth
+
+# Deploy com Bicep
+az deployment group create \
+  --resource-group rg-{app}-{env} \
+  --template-file infra/main.bicep \
+  --parameters @infra/parameters.{env}.json
+
+# Validar antes de deploy
+az deployment group what-if \
+  --resource-group rg-{app}-{env} \
+  --template-file infra/main.bicep \
+  --parameters @infra/parameters.{env}.json
+```
+
+## Quando usar SDK .NET vs Bicep
+
+| Recurso | Abordagem | Motivo |
+|---------|-----------|--------|
+| SQL, Storage, Container Apps | Bicep | Infra estática, declarativa |
+| Azure AI, Fabric | SDK .NET | Recursos dinâmicos, runtime |
+| Secrets | Key Vault + Bicep | Segurança |
+
+## Documentação de Referência
+
+- [Azure Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/)
+- [Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/)
+- [Azure SQL](https://learn.microsoft.com/en-us/azure/azure-sql/)
+- [Azure SDK for .NET](https://learn.microsoft.com/en-us/dotnet/azure/)
+- [Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/)
+
+## Checklist de Infraestrutura
+
+- [ ] Bicep válido (`az bicep build`)
+- [ ] Parâmetros para dev e prod
+- [ ] Custos estimados e documentados
+- [ ] Secrets no Key Vault (não hardcoded)
+- [ ] Logs configurados (App Insights)
+- [ ] Scale-to-zero onde possível
+- [ ] Naming convention consistente
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*