design

Files (3)

• SKILL.md
• design-contract-example.md · examples/
• prototype-handoff-example.md · examples/

SKILL.md (first lines)

Você é a skill de design do Vetor. Cobre três responsabilidades sequenciais do fluxo de frontend
(#213):

1. **Setup** — detectar quais fontes de design já existem no projeto-alvo (protótipo, Design System,
   ou nenhum dos dois) e adaptar o processo: importar/referenciar o Design System existente (nunca
   duplicá-lo) e manter uma Design Direction persistente e específica do produto (#228).
2. **Handoff** — quando o modo é Prototype-first, extrair do protótipo estrutura de telas,
   hierarquia, componentes, tokens observáveis, conteúdo, interações, estados e responsividade, e
   transformar isso em um Design Contract (#227) que preserva
   `prototype intent + dados reais +
   estados reais + restrições técnicas reais` — nunca uma cópia
   de pixels (#229).
3. **Loop** — depois que uma implementação de UI compila e roda, levá-la do Design Contract até um
   estado verificado: corrigindo sozinha o que é objetivo e reversível, escalando ao usuário o que é
   decisão de produto/design (#230).

---

## Sintaxe

```
/vetor:design [<diretório>]
```

- `<diretório>`: opcional — raiz do projeto a varrer para o Setup (modo de operação + import).
  Default: raiz do projeto atual (`.`).

O Loop (self-correction) não é tipicamente invocado por um comando de usuário — é consumido por
`issue-worker`/`fix` (via `frontend-design-enforcement.md`) depois que a implementação de
uma tela/fluxo de UI compila e roda. Também pode ser invocado manualmente com
`Skill({skill: "vetor:design"})` para verificar uma tela de frontend já implementada.

---

## Referências

> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
> prefixe o path absoluto desse diretório ao caminho relativo antes de executar — defina uma vez:
> ```bash
> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
> ```
> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.

- `../shared/references/design-vocabulary.md` — Design System, Design
  Direction, Design Signature e o formato do Design Contract (entrada do Loop, passo 1). Não
  replique as definições aqui — cite os campos. §4.4 aplica os 4 estados de Evidence State às
  Decisões do Design Contract — exemplo completo em
  `skills/design/examples/design-contract-example.md`. §6 documenta a árvore completa de artefatos
  em `.vetor/design/`; §7 o conflito Specification × Design Contract (#231); §8 os pontos de
  extensão futuros — Design Drift, Visual Debt, integração com Guardian (#231, não implementados
  nesta issue).
- `../shared/references/evidence-state.md` — `OPEN_QUESTION` usado em
  `patterns.md` (Setup, passo 2) quando um padrão de interação não é detectável por varredura de
  filesystem.
- `../shared/references/frontend-design-enforcement.md` — direção
  estética/tipográfica via skill nativa `frontend-design`, aplicada **antes** de escrever o código.
  O Loop é complementar e roda **depois**: verifica o que foi construído, não decide como desenhar.
- `../shared/references/mcp-availability.md` — mecanismo de checagem de
  disponibilidade (procurar `mcp__<server>__` ou `mcp__plugin_<plugin>_<server>__` na lista de
  ferramentas, conforme `scripts/lib/mcp.ts` — issue #336). Servidores relevantes aqui: browser
  (`chrome-devtools`, `playwright`) para os passos 4-6 e 9 do Loop, Context7 para qualquer
  comportamento de framework/lib consultado durante o Fix (Loop, passo 8).
- `scripts/lib/design-mode.ts` — lógica de detecção/renderização do Setup (pura, testada em
  `scripts/tests/design-mode_test.ts`).
- `scripts/detect-design-mode.ts` — CLI que orquestra a escrita em disco do Setup a partir da lib
  acima.
- `scripts/lib/design-handoff.ts` — renderiza o Design Contract a partir da extração estruturada do
  protótipo (pura, testada em `scripts/tests/design-handoff_test.ts`). Ver Handoff, abaixo.
- `scripts/handoff-prototype.ts` — CLI que lê a extração (JSON) e grava o Design Contract em
  `.vetor/design/handoff/` via a lib acima.
- `scripts/lib/design-loop-mcp.ts` — `detectBrowserMcpServer`/`reportLoopStep`: formaliza o relato
  de cada passo do Loop dependente de MCP de browser quando ele não está disponível, para nunca
  pular uma etapa em silêncio nem fingir que a inspeção ocorreu (ver Loop §"Sem MCP de browser").
- `scripts/lib/spec-design-conflict.ts` — `detectFieldConflict`/`detectPrimaryActionConflict`:
  compara um valor de decisão já extraído do Design Contract e da Specification e relata a
  divergência sem escolher um lado (design-vocabulary.md §7). Usado no Loop, passo 1 (abaixo) e
  passo 8.
- `../shared/references/tdd-conventions.md` — disciplina de teste aplicada
  ao Fix (Loop, passo 8): reproduza o problema objetivo antes de corrigi-lo, quando o módulo tiver
  suíte.

---

## Artefatos

Toda a árvore gravada em `.vetor/design/` — `system/`, `direction/`, `prototype/`, `handoff/` — está
documentada em `design-vocabulary.md` §6. Resumo:

```text
.vetor/
└── design/
    ├── system/      ← Setup, passo 2 (abaixo)
    ├── direction/   ← Setup, passo 3 (abaixo)
    ├── prototype/   ← origem observada pelo agente (Handoff, passo 1)
    └── handoff/     ← Design Contract gerado (Handoff, passo 4)
```

---

## Setup — Modo de operação, Design System Import, Design Direction

### 1 — Detectar o modo de operação

```bash
deno run -A "$SKILL_DIR/../../scripts/detect-design-mode.ts" <diretório>
```

Saída JSON: `mode`, `hasPrototype`, `evidence`, `written`, `skipped`.

Modos, nesta ordem de prioridade (ver #213 "Modos de operação"):

1. **Prototype-first** — existe `.vetor/design/prototype/`. Prossiga para a seção Handoff, abaixo,
   para transformar o protótipo em Design Contract.
2. **System-first** — não há protótipo, mas há evidência de Design System: `tailwind.config.*`,
   `tokens.*`, `components/`/`ui/` (raiz ou `src/`), `.storybook/`, ou dependência de design em
   `package.json` (`tailwindcss`, `styled-components`, `@mui/material`, `@chakra-ui/react`,
   `@storybook/react`, `@emotion/styled`).
3. **Vetor-first** — nenhuma das fontes acima. A Design Direction (passo 3) é a única fonte visual

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor