Ag Avaliar Ux Design Library

ag-avaliar-ux-design-library — Avaliacao UX contra Design Library

Papel

Avalia a qualidade visual/UX de um projeto comparando o que foi implementado contra o padrao da empresa (Design Library + Design System). Captura screenshots reais, compara contra as solution specs, e produz um UX Compliance Report com score e acoes.

Diferenca de outros skills:

• ag-revisar-ux: Review pontual com heuristicas de Nielsen (generico)
• ag-testar-ux-qualidade: UX-QAT PDCA com design tokens (testes continuos)
• ag-meridian D4-LOOKS: Score visual generico (4 viewports)
• Este skill: Compara contra a PROPRIA Design Library da empresa (padrao interno)

Invocacao

/ag-avaliar-ux-design-library http://localhost:3000
/ag-avaliar-ux-design-library http://localhost:3005 --scope "/dashboard,/consultas"
/ag-avaliar-ux-design-library ~/Claude/GitHub/payroll-app --threshold 80

Pre-requisitos

1. Playwright MCP disponivel (para screenshots)
2. App rodando (localhost ou URL deployada)
3. Design Library acessivel em ~/Claude/assets/design-library/
4. Design System em ~/Claude/assets/design-library/UI_UX/raiz-educacao-design-system.md

Pipeline (5 fases)

DISCOVER → CAPTURE → MATCH → EVALUATE → REPORT

Fase 1: DISCOVER — Mapear telas do projeto

1. Navegar para URL da app via Playwright MCP
2. Capturar snapshot de acessibilidade (browser_snapshot)
3. Identificar rotas/paginas disponiveis na navegacao
4. Se --scope especificado, filtrar rotas
5. Classificar cada tela por tipo: dashboard, form, table, chat, workflow, layout, etc.

Fase 2: CAPTURE — Screenshots de cada tela

Para cada tela identificada:

1. Navegar via browser_navigate
2. Aguardar carregamento completo (browser_wait_for)
3. Capturar screenshot full-page:

`` browser_take_screenshot({ type: "png", filename: "ux-compliance/{slug}-desktop.png", fullPage: true }) ``

1. Capturar em mobile (375px):

`` browser_resize({ width: 375, height: 812 }) browser_take_screenshot({ type: "png", filename: "ux-compliance/{slug}-mobile.png" }) browser_resize({ width: 1440, height: 900 }) # restaurar ``

1. Capturar snapshot de acessibilidade (para analise estrutural)
2. Capturar console errors (browser_console_messages)

Fase 3: MATCH — Associar telas a solucoes da Design Library

Para cada tela capturada:

1. Ler ~/Claude/assets/design-library/catalog.md
2. Identificar qual(is) solution(s) a tela DEVERIA seguir:

| Tipo de tela detectado | Solution esperada | |----------------------|-------------------| | Dashboard com KPIs | 01-dashboard-kpi | | Tabela com dados | 02-table-filters-export | | Formulario multi-step | 03-forms-multistep | | Timeline/historico | 04-status-workflow-timeline | | Layout principal | 05-app-shell-sidebar | | Workflow visual | 06-workflow-builder | | Chat/AI | 07-chat-ai-streaming | | Viewer PDF | 08-pageflip-3d | | Kanban/board | 11-dragdrop-virtual-scroll | | Export/docs | 12-document-generation | | RAG/busca | 13-rag-knowledge-base | | Graficos/BI | 15-bi-data-explorer | | Contratos | 17-contract-lifecycle |

1. Ler a spec da solution matched: ~/Claude/assets/design-library/solutions/NN-id/spec.md
2. Se NENHUMA solution matched → marcar como "sem padrao" (gap na library)

Fase 4: EVALUATE — Pontuar aderencia

Para cada tela, avaliar 6 dimensoes (0-10 cada):

D1: Token Compliance (cores, fonts, spacing)

Ler ~/Claude/assets/design-library/UI_UX/raiz-educacao-design-system.md e verificar no screenshot + snapshot:

• [ ] Cores da marca (Orange #F7941D, Teal #5BB5A2) presentes?
• [ ] IBM Plex Sans como font principal?
• [ ] Spacing consistente com escala 4px?
• [ ] Border radius padrao (8px)?
• [ ] Dark mode funcional (se aplicavel)?

D2: Solution Adherence (comparacao com spec)

Se solution matched:

• [ ] Layout segue o diagrama ASCII da spec?
• [ ] Props obrigatorias implementadas?
• [ ] Features-chave presentes (ex: sparkline no KPI, filtros na tabela)?
• [ ] CSS patterns alinhados com a spec?

D3: Component Quality (componentes base)

• [ ] Usa shadcn/ui ou componentes do catalog? (vs HTML raw)
• [ ] Botoes com estados (hover, disabled, loading)?
• [ ] Inputs com labels e validacao visual?
• [ ] Cards com estrutura consistente?
• [ ] Icones do mesmo set (Lucide)?

D4: Responsividade

• [ ] Desktop (1440px) legivel e alinhado?
• [ ] Mobile (375px) funcional sem scroll horizontal?
• [ ] Elementos nao sobrepostos?
• [ ] Touch targets >= 44px em mobile?

D5: Acessibilidade Visual

• [ ] Contraste suficiente (WCAG AA 4.5:1)?
• [ ] Focus states visiveis?
• [ ] Nao depende apenas de cor para transmitir info?
• [ ] Alt text em imagens (via snapshot)?

D6: Consistencia Cross-Tela

• [ ] Mesma sidebar/nav em todas as paginas?
• [ ] Mesma paleta de cores (sem cores random)?
• [ ] Mesma tipografia (sem fonts diferentes)?
• [ ] Espacamentos uniformes entre paginas?

Score UXC (UX Compliance)

UXC = D1*0.20 + D2*0.25 + D3*0.20 + D4*0.15 + D5*0.10 + D6*0.10

| UXC | Status | Significado | |-----|--------|-------------| | 90-100 | Excelente | Totalmente alinhado com Design Library | | 80-89 | Bom | Pequenos desvios, aceitavel (threshold default) | | 65-79 | Regular | Desvios significativos, precisa ajustes | | 50-64 | Fraco | Implementacao diverge bastante do padrao | | < 50 | Critico | Nao segue o padrao da empresa |

Fase 5: REPORT — Gerar relatorio

Salvar em docs/ux-compliance-{date}.md:

# UX Compliance Report — {Projeto}

**Data**: YYYY-MM-DD
**URL**: {url}
**Telas avaliadas**: N
**UXC Score**: XX/100

## Resumo por Tela

| Tela | Solution Ref | D1 | D2 | D3 | D4 | D5 | D6 | Score | Status |
|------|-------------|----|----|----|----|----|----|-------|--------|
| /dashboard | dashboard-kpi | 8 | 7 | 9 | 8 | 7 | 9 | 79 | Regular |
| /usuarios | table-filters | 9 | 8 | 8 | 7 | 8 | 9 | 82 | Bom |

## Desvios Criticos (P0)

- [screenshot] Tela X usa cor #FF0000 em vez de #F7941D (token violation)
- [screenshot] Form sem labels (a11y violation)

## Desvios Importantes (P1)

- Tela Y nao usa KPI card padrao (reinventou componente)
- Spacing inconsistente no header (12px vs 16px padrao)

## Gaps na Design Library

- Tela Z nao tem solution equivalente → sugerir criacao de solution spec #25

## Screenshots

- `ux-compliance/dashboard-desktop.png`
- `ux-compliance/dashboard-mobile.png`
- ...

## Acoes Recomendadas

1. [P0] Corrigir cores para tokens do design system
2. [P1] Substituir KPI custom por `dashboard-kpi` solution
3. [P2] Adicionar nova solution spec para tela Z

Integracoes

Com ag-1-construir

Pode ser chamado na fase REVIEW para verificar compliance antes de SHIP:

REVIEW = ag-revisar-codigo + ag-avaliar-ux-design-library (se UI)

Com ag-7-qualidade (MERIDIAN)

Complementa D4-LOOKS com verificacao contra padrao interno:

• MERIDIAN D4: "a tela parece boa?" (generico)
• Este skill: "a tela segue NOSSO padrao?" (especifico)

Com ag-2-corrigir

Desvios P0/P1 podem ser passados como input para correcao automatica:

/ag-2-corrigir lista: [desvios do UX Compliance Report]

Regras

1. SEMPRE capturar screenshots REAIS — nunca avaliar sem evidencia visual
2. SEMPRE comparar contra a Design Library — nao usar padrao generico
3. Se solution nao existe → e um GAP na library, nao um erro do projeto
4. Score e relativo ao padrao interno — 100 = perfeitamente alinhado, nao "bonito"
5. Mobile e obrigatorio — se nao cabe em 375px, e desvio
6. Report com screenshots como evidencia — desvio sem screenshot nao conta

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andregusman-raiz
• Source: andregusman-raiz/a-gusman-claude
• License: MIT

Install and usage instructions live in the source repository linked above.