Especificação de UI a partir do código
O vídeo reconstrói a interface do produto em HTML e CSS em vez de gravá-la, então a interface é tão fiel quanto a especificação da qual foi construída. Aproximações são percebidas: na produção de onde vêm estas skills, um revisor rejeitou ícones e logotipos desenhados à mão na primeira revisão, e um badge construído manualmente com o tamanho e nome errados o deixou furioso. As correções vieram da leitura do código, e o código escondia armadilhas que ninguém vê a olho nu: o tamanho da fonte raiz foi definido em tempo de execução pelo shell do aplicativo (14 px, não os 10 px que a folha de estilo declarava), várias variáveis CSS não existiam em produção e usavam seu fallback, um componente perdeu sua barra de destaque em um commit dois meses antes, e duas "caixas de diálogo" eram pop-ups personalizados, não o diálogo da biblioteca.
Portanto, todo valor em uma especificação é literal e citado, e um valor que não pode ser citado é sinalizado, nunca adivinhado.
Entradas
videos/<video>/SOURCES.mddo source-recon: cada tela, sua rota, componentes e estado. Se estiver faltando, execute source-recon primeiro.sources/<role>/esources.lock. Toda citação usa o sha bloqueado.product.yaml:app_canvas.logical(o viewport no qual a UI é reconstruída),app_canvas.theme,app_canvas.rem_px,sources[].framework.- O adaptador para o framework:
references/adapters/<framework>.md. Leia-o antes de escrever os prompts do subagente; ele diz onde os valores se escondem naquela stack.
| framework em product.yaml | adaptador | status |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | comprovado em produção |
react | references/adapters/react.md | não comprovado |
vue | references/adapters/vue.md | não comprovado |
| qualquer stack usando Tailwind | references/adapters/tailwind.md (com o do próprio framework) | não comprovado |
html, other, templates de servidor | references/adapters/html.md | não comprovado |
Para um adaptador não comprovado, avise o usuário de que ele é não comprovado, siga-o e adicione o que você aprendeu a ele no final (uma seção curta "Aprendido em "), para que o próximo produto comece mais adiantado.
1. Fatos globais de renderização (uma vez por produto)
Antes de qualquer tela, estabeleça os fatos dos quais cada tela depende e escreva-os em
kit/render-facts.md com citações:
- Tamanho da fonte raiz em tempo de execução (pesquise o shell do aplicativo em busca de código que a defina, não apenas o CSS),
para que
remconverta corretamente. Atualizeapp_canvas.rem_pxem product.yaml se for diferente. - Tema: qual seletor ativa o tema do vídeo e se ele está ativo por padrão.
- Arquivos de tokens, a ordem de camadas CSS ou de importação (quais regras vencem), e a biblioteca de componentes com sua versão exata do arquivo de bloqueio e sua predefinição de tema.
- Fontes realmente carregadas (tags link,
@font-face, pacotes de fontes), não apenas nomeadas no CSS. Uma fonte que é declarada, mas nunca carregada, é renderizada como fallback em produção. - O ponto de interrupção (breakpoint) de desktop, para confirmar que
app_canvas.logicalmostra o layout de desktop.
Em seguida, escreva os tokens, resolvidos para literais para o tema do vídeo:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
Ele lê propriedades personalizadas CSS, variáveis SCSS de nível superior e um tema Tailwind v3 (estaticamente)
do diretório sources/<role>/, resolve cada var() e $variable, e escreve kit/tokens.css com
uma citação /* role/path:line@sha */ em cada linha. Linhas sinalizadas como UNDEFINED são variáveis
que a produção não define (provável falha); needs a Sass compile marca valores construídos com funções
Sass, que o subagente deve resolver manualmente a partir da função e suas entradas. Use
--files quando a exportação contém folhas de estilo não relacionadas (sites de documentação, templates de e-mail,
CSS fornecido por terceiros).
2. Um subagente por tela
Inicie um subagente somente leitura por tela (ou por painel de uma tela grande), todos em paralelo, com
references/ui-spec-prompt.md preenchido e a lista de "onde os valores se escondem" do adaptador anexada.
Aponte cada um para sources/<role>/ (não o checkout do usuário) e forneça o contexto de renderização:
tamanho do canvas lógico, tema, rem, fatos de renderização, tokens e o CSS das peças já reconstruídas para
que a nova peça corresponda.
Cada um retorna: geometria dentro do canvas, HTML estático por estado (sem sintaxe de framework), um bloco CSS com valores literais e uma citação por valor, estados hover/focus/active/disabled/loading como classes extras, transições e keyframes com durações e easings exatos, ícones por biblioteca e nome (ou SVG inline na íntegra), cada string visível e uma lista explícita de "não verificado".
O coordenador (você) não extrai especificações por conta própria: uma tela de um aplicativo real pode ocupar dezenas de kilobytes de descobertas, e um coordenador cujo contexto se enche no meio do vídeo perde o controle de toda a construção.
3. Ícones e imagens
Os ícones vêm dos próprios conjuntos e ativos do produto, nunca desenhados e nunca de um perfil de
navegador ou pasta de extensão. Execute references/icon-extraction-prompt.md uma vez por produto (e
novamente para novas telas) para mapear cada ícone que um vídeo precisa para sua biblioteca e nome,
em seguida, passe os nomes para collect_icons.py do product-kit, que copia os SVGs para kit/icons/ com
citações. Para fontes de ícones sem arquivos SVG, a construção escreve os codepoints a partir do CSS
da própria biblioteca e deve falhar em um nome desconhecido em vez de renderizar uma caixa vazia.
4. Escreva as especificações
Para cada tela, videos/<video>/specs/<screen>.md e specs/<screen>.html:
# Spec: <tela>
Fonte: frontend@1a2b3c4 (ver SOURCES.md). Canvas 1440x810, tema claro, rem 16.
## Geometria
| elemento | x | y | w | h | citação |
## Estados
E1 <nome>: <o que é mostrado, dados fictícios>. HTML em <tela>.html, seção E1.
## CSS
<um bloco, valores literais, cada linha com /* role/path:line@sha */>
## Movimento
| o quê | propriedade | de | para | duração | easing | atraso | citação |
## Ícones
| chave | biblioteca | nome | arquivo em kit/icons | citação |
## Strings
| chave | texto | citação |
## Correções (falhas de produção corrigidas no vídeo)
| o quê | produção faz | vídeo faz | por quê |
## Não verificado
- <valor ou comportamento, porquê e a melhor referência disponível>
Mantenha a aparência, corrija as falhas
Reconstrua layout, tokens e comportamento 1:1, incluindo as animações, hovers, estados de digitação e carregamento que o fazem parecer o produto real. Mas corrija defeitos visíveis de produção, porque o vídeo mostra o produto no seu melhor e um revisor perguntará por que um bug está na tela: padding faltando, overflow, texto cortado, um controle nativo do navegador (um player de áudio padrão cinza) onde o produto espera um projetado, uma variável indefinida pintando um fallback, um anel de foco restante após um clique. Liste cada correção na tabela de Correções da especificação e nas notas BRIEF. Mantenha peculiaridades que são decisões de design (um rodapé fixo cobrindo um campo, uma barra lateral que rola com seu conteúdo); alterar isso é redesenho, não uma correção.
Mais duas transformações que a especificação aplica e registra:
- Nomes canônicos. Substitua strings legadas de
product.yaml namespelo nome canônico mesmo quando a UI ativa ainda mostra o antigo, e mantenha todo o resto sobre aquele elemento. - Termos banidos. Se uma tela real mostra um fornecedor ou um termo em
banned_terms(um seletor de modelo, um cartão de integração), deixe essa parte fora do quadro. Ela não deve parecer vazia ou quebrada; escolha um enquadramento ou um estado onde esteja naturalmente ausente.
Dados
As especificações carregam apenas dados fictícios, de product.yaml cast. Fixtures, seeds e capturas de tela
no repositório podem conter nomes reais; use sua forma, nunca seus valores.
Lista de verificação antes de entregar as especificações para a construção
- Commit bloqueado citado; fatos de renderização escritos; tokens resolvidos para o tema do vídeo
- Tamanho do canvas acima do ponto de interrupção de desktop; rem corresponde ao tempo de execução
- Cada
var()resolvido; variáveis indefinidas listadas com seu fallback (ou corrigidas como falha) - Cada string do arquivo de i18n ou template; nomes canônicos aplicados
- Cada ícone das bibliotecas do aplicativo; a construção falha em um glifo ausente
- Logotipos e imagens dos ativos do repositório
- Estados padrão (abas, acordeões, alternâncias) correspondem ao código
- Temporizações de sobreposição, pop-up e transição com easings exatos
- Intervalos de rolagem dentro do conteúdo real; nenhum texto cortado em uma borda
- Nenhum fornecedor, termo banido, ID interno ou dado real de cliente no quadro
- Correções e peculiaridades mantidas listadas; valores não verificados listados para o revisor