@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

package/framework/skills/level-1-workflows/phase-uiux/SKILL.md

@@ -1,246 +1,247 @@
----
-name: phase-uiux
-description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Figma/Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# MORPH UI/UX Design - FASE 1.5
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera wireframes, specs de componentes e fluxos de usuário.
-
-## Pré-requisitos
-
-- [ ] FASE 1 (Setup) concluída
-- [ ] Feature tem keywords de UI detectadas (blazor, ui, component, page, dashboard, wizard, form, chart)
-- [ ] `uiux-designer` agent ativado
-
-## Ferramentas Recomendadas
-
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
-
-| Ação | Ferramenta | Alternativa |
-|------|------------|-------------|
-| Verificar design system existente | **Read** `.morph/context/design-system.md` | — |
-| Ler screenshots do usuário | **Read** (arquivo de imagem) | — |
-| Buscar variáveis CSS existentes | **Grep** `--root:` em `*.css,*.scss` | — |
-| Encontrar componentes existentes | **Glob** `**/Components/**/*.razor` ou `**/components/**/*.tsx` | — |
-| Extrair design tokens do Figma | **Figma MCP** `get_file({ fileKey })` | Read CSS/SCSS variables |
-| Documentação de componentes UI | **Context7 MCP** `query_docs({ libraryId, query })` | **WebSearch** + **WebFetch** |
-| Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
-| Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
-| Testar layout responsivo | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
-| Referências de design externas | **WebSearch** + **WebFetch** | — |
-| Renderizar templates UI | **Bash** `npx morph-spec template render docs/ui-mockups ...` | — |
-| Gerar design system de CSS existente | **Bash** `npx morph-spec generate design-system --scan` | — |
-| Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
-
-**MCPs desta fase:** Figma (design tokens), Playwright (preview, inspeção, responsividade), Context7 (docs de componentes).
-
-**Anti-padrões:**
-- ❌ WebSearch para docs MudBlazor (use Context7 MCP — mais preciso)
-- ❌ Task agent para ler um screenshot (use Read direto na imagem)
-- ❌ Adivinhar props de componentes (use Context7 para API real)
-
----
-
-## Workflow
-
-### Passo 0: Verificar Design System Existe
-
-**CRITICAL:** Antes de iniciar a FASE UI/UX, verifique se um design system existe:
-
-```bash
-npx morph-spec detect-agents "{feature description}"
-```
-
-Se nenhum design system for detectado (verificar output):
-
-1. **Opção A - Scaffold automático:**
-   - O sistema criará automaticamente um design system ao avançar para implementação
-   - Você pode gerar manualmente agora: `npx morph-spec generate design-system`
-
-2. **Opção B - Criar manualmente:**
-   - Crie `.morph/context/design-system.md` (project-level, compartilhado)
-   - Ou `.morph/features/$ARGUMENTS/2-ui/design-system.md` (feature-specific)
-
-3. **Opção C - Scan existing CSS:**
-   - Se o projeto já tem CSS com variáveis: `npx morph-spec generate design-system --scan`
-
-**⚠️ IMPORTANTE:**
-- Design system é **obrigatório** para features UI
-- Gate automático bloqueará implementação (FASE 5) se design system não existir
-- Melhor criar agora para garantir consistência visual
-
-### Passo 1: Detectar Se Fase É Necessária
-
-Verifique se agentes ativos incluem `uiux-designer`:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Se `uiux-designer` NÃO estiver nos `activeAgents`, pule esta fase e continue para FASE 2 (Design).
-
-### Passo 2: Coletar Input do Usuário
-
-**SEMPRE perguntar ao usuário PRIMEIRO:**
-
-1. **Layout e estilo**:
-   - Você tem alguma ideia de layout em mente?
-   - Tem alguma referência visual? (sites, apps, screenshots)
-   - Como imagina o fluxo do usuário?
-
-2. **Componentes e interações**:
-   - Quais os principais componentes desta tela/página?
-   - Quais estados precisam ser considerados? (loading, error, empty, success)
-
-3. **Imagens de referência**:
-   - Tem imagens de exemplo que eu possa analisar?
-   - Se SIM: use Read tool para ler screenshots e extrair padrões
-
-### Passo 3: Decidir Biblioteca UI
-
-Escolha entre **Fluent UI Blazor** (recomendado para AI-first) ou **MudBlazor** (componentes complexos):
-
-**Critérios:**
-- Fluent UI: Para dashboards, forms simples, AI components, Microsoft design language
-- MudBlazor: Para data grids avançadas, charts complexos, material design
-
-**Documente a decisão em `decisions.md`.**
-
-### Passo 4: Gerar Deliverables
-
-Crie os seguintes arquivos em `.morph/features/$ARGUMENTS/`:
-
-> **Use templates:** Utilize `npx morph-spec template render` para gerar os arquivos a partir dos templates em `.morph/framework/templates/docs/`. Templates disponíveis: `ui-design-system`, `ui-mockups`, `ui-components`, `ui-flows`.
-
-#### 4.1. `ui-design-system.md`
-
-**Se design system project-level existe (`.morph/context/design-system.md`):**
-- Referencie-o nos specs: "Uses project design system at .morph/context/design-system.md"
-- Crie `ui-design-system.md` apenas se houver cores/componentes **específicos** da feature
-
-**Se não existe:**
-- Crie design system feature-level completo com:
-  - Paleta de cores (primary, secondary, accent, semantic)
-  - Tipografia (heading scales, body text, code)
-  - Spacing e layout (grid, margins, paddings)
-  - Componentes base (buttons, inputs, cards)
-
-#### 4.2. `ui-mockups.md`
-
-Wireframes ASCII + descrições:
-- Layout geral de cada tela/página
-- Posicionamento de componentes
-- Responsividade (desktop, tablet, mobile)
-- Estados (loading, error, empty, success)
-
-#### 4.3. `ui-components.md`
-
-Specs técnicas de componentes Fluent UI/MudBlazor:
-- Componente a usar (FluentButton, MudDataGrid, etc.)
-- Props e configurações
-- Eventos e bindings
-- Validações e estados
-
-#### 4.4. `ui-flows.md`
-
-Fluxos de usuário completos:
-- User stories
-- Diagramas de fluxo (texto/ASCII)
-- Edge cases (o que acontece se...?)
-- Validações e feedback
-
-### CHECKPOINT: Validar Deliverables UI
-
-**⏸️ PAUSE - Antes de prosseguir para acessibilidade:**
-
-- [ ] Design system definido (project-level ou feature-level)?
-- [ ] Wireframes cobrem TODOS os estados (loading, error, empty, success)?
-- [ ] Componentes especificados com props reais da biblioteca UI escolhida?
-- [ ] Fluxos de usuário completos com edge cases?
-- [ ] Biblioteca UI escolhida documentada como ADR em `decisions.md`?
-
-**❌ Se alguma checkbox NÃO estiver marcada:**
-→ Voltar e completar o deliverable faltante
-
-**✅ Se TODAS as checkboxes estiverem marcadas:**
-→ Prosseguir para validação de acessibilidade
-
----
-
-### Passo 5: Validar Acessibilidade e Responsividade
-
-Documente nos arquivos UI:
-- **WCAG 2.1 Level AA** compliance
-  - Contraste de cores adequado
-  - Labels acessíveis para screen readers
-  - Navegação por teclado
-- **Responsive breakpoints**
-  - Desktop (>1200px)
-  - Tablet (768px - 1199px)
-  - Mobile (<768px)
-
-### Passo 6: Atualizar State
-
-```bash
-npx morph-spec state set $ARGUMENTS phase uiux-design
-npx morph-spec state mark-output $ARGUMENTS ui-design-system
-npx morph-spec state mark-output $ARGUMENTS ui-mockups
-npx morph-spec state mark-output $ARGUMENTS ui-components
-npx morph-spec state mark-output $ARGUMENTS ui-flows
-```
-
-> **Nota sobre formatos:** Os comandos `mark-output` aceitam TANTO kebab-case (`ui-design-system`)
-> QUANTO camelCase (`uiDesignSystem`). Ambos os formatos funcionam igualmente! Use o que for mais
-> confortável para você. Exemplos:
-> - `npx morph-spec state mark-output my-feature uiDesignSystem` ✅
-> - `npx morph-spec state mark-output my-feature ui-design-system` ✅
-
-## Outputs Gerados
-
-- `.morph/features/$ARGUMENTS/2-ui/design-system.md`
-- `.morph/features/$ARGUMENTS/2-ui/mockups.md`
-- `.morph/features/$ARGUMENTS/2-ui/components.md`
-- `.morph/features/$ARGUMENTS/2-ui/flows.md`
-- `.morph/features/$ARGUMENTS/1-design/decisions.md` (atualizado com ADR UI library)
-
-## PAUSA OBRIGATÓRIA
-
-Apresente ao usuário 3 ações sugeridas:
-
-1. **Aprovar UI/UX e prosseguir para design técnico**
-2. **Ajustar wireframes/componentes de telas específicas**
-3. **Revisar biblioteca UI escolhida (Fluent UI / MudBlazor)**
-
-## Critérios de Avanço
-
-- [x] Input do usuário coletado (layout, referências)
-- [x] Biblioteca UI escolhida e justificada (ADR)
-- [x] 4 deliverables criados (design-system, mockups, components, flows)
-- [x] Acessibilidade WCAG 2.1 documentada
-- [x] Responsividade especificada
-- [x] State atualizado
-- [x] Usuário aprovou UI/UX
-
----
-
-## Outputs desta Fase
-
-<!-- morph:outputs:uiux -->
-| Output | Caminho |
-|--------|---------|
-| `uiDesignSystem` | `.morph/features/{feature}/2-ui/design-system.md` |
-| `uiMockups` | `.morph/features/{feature}/2-ui/mockups.md` |
-| `uiComponents` | `.morph/features/{feature}/2-ui/components.md` |
-| `uiFlows` | `.morph/features/{feature}/2-ui/flows.md` |
-<!-- /morph:outputs -->
-
----
-
+---
+name: phase-uiux
+description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Figma/Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+cliVersion: "4.8.1"
+---
+
+# MORPH UI/UX Design - FASE 1.5
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Fase condicional para features com front-end. Coleta requisitos de UI/UX, gera wireframes, specs de componentes e fluxos de usuário.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] Feature tem keywords de UI detectadas (blazor, ui, component, page, dashboard, wizard, form, chart)
+- [ ] `uiux-designer` agent ativado
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Verificar design system existente | **Read** `.morph/context/design-system.md` | — |
+| Ler screenshots do usuário | **Read** (arquivo de imagem) | — |
+| Buscar variáveis CSS existentes | **Grep** `--root:` em `*.css,*.scss` | — |
+| Encontrar componentes existentes | **Glob** `**/Components/**/*.razor` ou `**/components/**/*.tsx` | — |
+| Extrair design tokens do Figma | **Figma MCP** `get_file({ fileKey })` | Read CSS/SCSS variables |
+| Documentação de componentes UI | **Context7 MCP** `query_docs({ libraryId, query })` | **WebSearch** + **WebFetch** |
+| Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
+| Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
+| Testar layout responsivo | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
+| Referências de design externas | **WebSearch** + **WebFetch** | — |
+| Renderizar templates UI | **Bash** `npx morph-spec template render docs/ui-mockups ...` | — |
+| Gerar design system de CSS existente | **Bash** `npx morph-spec generate design-system --scan` | — |
+| Atualizar state | **Bash** `npx morph-spec state mark-output ...` | — |
+
+**MCPs desta fase:** Figma (design tokens), Playwright (preview, inspeção, responsividade), Context7 (docs de componentes).
+
+**Anti-padrões:**
+- ❌ WebSearch para docs MudBlazor (use Context7 MCP — mais preciso)
+- ❌ Task agent para ler um screenshot (use Read direto na imagem)
+- ❌ Adivinhar props de componentes (use Context7 para API real)
+
+---
+
+## Workflow
+
+### Passo 0: Verificar Design System Existe
+
+**CRITICAL:** Antes de iniciar a FASE UI/UX, verifique se um design system existe:
+
+```
+Read: .morph/context/design-system.md
+```
+
+Se o arquivo não existir (design system não encontrado):
+
+1. **Opção A - Scaffold automático:**
+   - O sistema criará automaticamente um design system ao avançar para implementação
+   - Você pode gerar manualmente agora: `npx morph-spec generate design-system`
+
+2. **Opção B - Criar manualmente:**
+   - Crie `.morph/context/design-system.md` (project-level, compartilhado)
+   - Ou `.morph/features/$ARGUMENTS/2-ui/design-system.md` (feature-specific)
+
+3. **Opção C - Scan existing CSS:**
+   - Se o projeto já tem CSS com variáveis: `npx morph-spec generate design-system --scan`
+
+**⚠️ IMPORTANTE:**
+- Design system é **obrigatório** para features UI
+- Gate automático bloqueará implementação (FASE 5) se design system não existir
+- Melhor criar agora para garantir consistência visual
+
+### Passo 1: Detectar Se Fase É Necessária
+
+Verifique se agentes ativos incluem `uiux-designer`:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Se `uiux-designer` NÃO estiver nos `activeAgents`, pule esta fase e continue para FASE 2 (Design).
+
+### Passo 2: Coletar Input do Usuário
+
+**SEMPRE perguntar ao usuário PRIMEIRO:**
+
+1. **Layout e estilo**:
+   - Você tem alguma ideia de layout em mente?
+   - Tem alguma referência visual? (sites, apps, screenshots)
+   - Como imagina o fluxo do usuário?
+
+2. **Componentes e interações**:
+   - Quais os principais componentes desta tela/página?
+   - Quais estados precisam ser considerados? (loading, error, empty, success)
+
+3. **Imagens de referência**:
+   - Tem imagens de exemplo que eu possa analisar?
+   - Se SIM: use Read tool para ler screenshots e extrair padrões
+
+### Passo 3: Decidir Biblioteca UI
+
+Escolha entre **Fluent UI Blazor** (recomendado para AI-first) ou **MudBlazor** (componentes complexos):
+
+**Critérios:**
+- Fluent UI: Para dashboards, forms simples, AI components, Microsoft design language
+- MudBlazor: Para data grids avançadas, charts complexos, material design
+
+**Documente a decisão em `decisions.md`.**
+
+### Passo 4: Gerar Deliverables
+
+Crie os seguintes arquivos em `.morph/features/$ARGUMENTS/`:
+
+> **Use templates:** Utilize `npx morph-spec template render` para gerar os arquivos a partir dos templates em `.morph/framework/templates/docs/`. Templates disponíveis: `ui-design-system`, `ui-mockups`, `ui-components`, `ui-flows`.
+
+#### 4.1. `ui-design-system.md`
+
+**Se design system project-level existe (`.morph/context/design-system.md`):**
+- Referencie-o nos specs: "Uses project design system at .morph/context/design-system.md"
+- Crie `ui-design-system.md` apenas se houver cores/componentes **específicos** da feature
+
+**Se não existe:**
+- Crie design system feature-level completo com:
+  - Paleta de cores (primary, secondary, accent, semantic)
+  - Tipografia (heading scales, body text, code)
+  - Spacing e layout (grid, margins, paddings)
+  - Componentes base (buttons, inputs, cards)
+
+#### 4.2. `ui-mockups.md`
+
+Wireframes ASCII + descrições:
+- Layout geral de cada tela/página
+- Posicionamento de componentes
+- Responsividade (desktop, tablet, mobile)
+- Estados (loading, error, empty, success)
+
+#### 4.3. `ui-components.md`
+
+Specs técnicas de componentes Fluent UI/MudBlazor:
+- Componente a usar (FluentButton, MudDataGrid, etc.)
+- Props e configurações
+- Eventos e bindings
+- Validações e estados
+
+#### 4.4. `ui-flows.md`
+
+Fluxos de usuário completos:
+- User stories
+- Diagramas de fluxo (texto/ASCII)
+- Edge cases (o que acontece se...?)
+- Validações e feedback
+
+### CHECKPOINT: Validar Deliverables UI
+
+**⏸️ PAUSE - Antes de prosseguir para acessibilidade:**
+
+- [ ] Design system definido (project-level ou feature-level)?
+- [ ] Wireframes cobrem TODOS os estados (loading, error, empty, success)?
+- [ ] Componentes especificados com props reais da biblioteca UI escolhida?
+- [ ] Fluxos de usuário completos com edge cases?
+- [ ] Biblioteca UI escolhida documentada como ADR em `decisions.md`?
+
+**❌ Se alguma checkbox NÃO estiver marcada:**
+→ Voltar e completar o deliverable faltante
+
+**✅ Se TODAS as checkboxes estiverem marcadas:**
+→ Prosseguir para validação de acessibilidade
+
+---
+
+### Passo 5: Validar Acessibilidade e Responsividade
+
+Documente nos arquivos UI:
+- **WCAG 2.1 Level AA** compliance
+  - Contraste de cores adequado
+  - Labels acessíveis para screen readers
+  - Navegação por teclado
+- **Responsive breakpoints**
+  - Desktop (>1200px)
+  - Tablet (768px - 1199px)
+  - Mobile (<768px)
+
+### Passo 6: Atualizar State
+
+```bash
+npx morph-spec state set $ARGUMENTS phase uiux-design
+npx morph-spec state mark-output $ARGUMENTS ui-design-system
+npx morph-spec state mark-output $ARGUMENTS ui-mockups
+npx morph-spec state mark-output $ARGUMENTS ui-components
+npx morph-spec state mark-output $ARGUMENTS ui-flows
+```
+
+> **Nota sobre formatos:** Os comandos `mark-output` aceitam TANTO kebab-case (`ui-design-system`)
+> QUANTO camelCase (`uiDesignSystem`). Ambos os formatos funcionam igualmente! Use o que for mais
+> confortável para você. Exemplos:
+> - `npx morph-spec state mark-output my-feature uiDesignSystem` ✅
+> - `npx morph-spec state mark-output my-feature ui-design-system` ✅
+
+## Outputs Gerados
+
+- `.morph/features/$ARGUMENTS/2-ui/design-system.md`
+- `.morph/features/$ARGUMENTS/2-ui/mockups.md`
+- `.morph/features/$ARGUMENTS/2-ui/components.md`
+- `.morph/features/$ARGUMENTS/2-ui/flows.md`
+- `.morph/features/$ARGUMENTS/1-design/decisions.md` (atualizado com ADR UI library)
+
+## PAUSA OBRIGATÓRIA
+
+Apresente ao usuário 3 ações sugeridas:
+
+1. **Aprovar UI/UX e prosseguir para design técnico**
+2. **Ajustar wireframes/componentes de telas específicas**
+3. **Revisar biblioteca UI escolhida (Fluent UI / MudBlazor)**
+
+## Critérios de Avanço
+
+- [x] Input do usuário coletado (layout, referências)
+- [x] Biblioteca UI escolhida e justificada (ADR)
+- [x] 4 deliverables criados (design-system, mockups, components, flows)
+- [x] Acessibilidade WCAG 2.1 documentada
+- [x] Responsividade especificada
+- [x] State atualizado
+- [x] Usuário aprovou UI/UX
+
+---
+
+## Outputs desta Fase
+
+<!-- morph:outputs:uiux -->
+| Output | Caminho |
+|--------|---------|
+| `uiDesignSystem` | `.morph/features/{feature}/2-ui/design-system.md` |
+| `uiMockups` | `.morph/features/{feature}/2-ui/mockups.md` |
+| `uiComponents` | `.morph/features/{feature}/2-ui/components.md` |
+| `uiFlows` | `.morph/features/{feature}/2-ui/flows.md` |
+<!-- /morph:outputs -->
+
+---
+
 Continuar automaticamente para FASE 2 (Design) após aprovação.

package/framework/templates/examples/design-system-examples.md

@@ -354,4 +354,4 @@
 
 ---
 
-*Template MORPH-SPEC v2.2.0 by Polymorphism Tech*
+*Template MORPH-SPEC by Polymorphism Tech*

package/framework/templates/ui/FluentDesignTheme.cs

@@ -7,7 +7,7 @@ namespace {Namespace}.Themes;
 /// Gerado automaticamente baseado em ui-design-system.md
 /// </summary>
 /// <remarks>
-/// Template MORPH-SPEC v2.1.1 by Polymorphism Tech
+/// Template MORPH-SPEC by Polymorphism Tech
 /// </remarks>
 public static class FluentDesignTheme
 {

package/framework/templates/ui/MudTheme.cs

@@ -7,7 +7,7 @@ namespace {Namespace}.Themes;
 /// Gerado automaticamente baseado em ui-design-system.md
 /// </summary>
 /// <remarks>
-/// Template MORPH-SPEC v2.1.1 by Polymorphism Tech
+/// Template MORPH-SPEC by Polymorphism Tech
 /// </remarks>
 public static class AppTheme
 {

package/framework/templates/ui/design-system.css

@@ -4,7 +4,7 @@
  * CSS Variables generated from ui-design-system.md
  * Use estas variáveis em todo o projeto para manter consistência visual.
  *
- * Template MORPH-SPEC v2.1.1 by Polymorphism Tech
+ * Template MORPH-SPEC by Polymorphism Tech
  */
 
 :root {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.7.1",
+  "version": "4.8.1",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",
@@ -47,7 +47,9 @@
     "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
     "docs": "jsdoc -c jsdoc.json",
     "docs:watch": "jsdoc -c jsdoc.json --watch",
-    "docs:serve": "npx http-server docs/api -p 8080 -o"
+    "docs:serve": "npx http-server docs/api -p 8080 -o",
+    "version:bump": "node scripts/bump-version.js",
+    "postinstall": "node src/scripts/global-install.js"
   },
   "dependencies": {
     "ajv": "^8.12.0",