yosegi-dev/yosegi

Yosegi — construindo telas a partir dos componentes do próprio hospedeiro

Versão: 2026-08-13. Um harness de agente pode carregar uma cópia desatualizada de uma skill sem avisar. Se esta data for mais antiga que a do arquivo skills/yosegi/SKILL.md no repositório, você está lendo uma cópia desatualizada — reinstale-a antes de prosseguir.

O Yosegi transforma os componentes de um projeto hospedeiro em fatos com os quais você pode construir uma tela, e emite a tela como uma História (CSF) para revisão antes que qualquer implementação seja feita. Ele não possui ambiente de renderização nem GUI própria; você verifica a aparência no Storybook do hospedeiro. Em um hospedeiro sem Storybook, a entrega se torna um arquivo de componente React simples (--target component) — o branch do passo 1 abaixo mostra como o procedimento muda.

Este documento é o procedimento, e você é quem o executa. A CLI (e as ferramentas MCP equivalentes) são os instrumentos que ela utiliza.

Quando usar

• Compor uma proposta de tela ou mock de UI a partir de um sistema de design existente, em uma forma revisável.
• Obter um primeiro rascunho de uma nova tela visível no Storybook antes de implementá-la.
• Consultar quais componentes um hospedeiro possui e quais props eles realmente aceitam, antes de escrever qualquer UI.
• Transcrever uma História de mock aprovada em uma página real. Execute os passos 1 e 2 e depois pule para o passo 5.

Não serve para: alterações pontuais em componentes.

Onde está o valor

O trabalho do registry é restrito: ele é a fonte da verdade para as props de um componente — os nomes reais das props, as opções reais de enum, quais são obrigatórias, quais são slots vs. children, a assinatura de uma prop de função. Os componentes de um hospedeiro não são a biblioteca da qual foram derivados. Seus enums de variante foram renomeados, suas escalas de tamanho diferem entre irmãos, uma prop de ícone espera uma referência de componente em vez de um elemento, uma prop ReactNode é um slot nomeado em vez de children, e três componentes diferentes compartilham o mesmo nome de exportação. Nada disso é derivável de familiaridade com React ou com a biblioteca upstream, e cada um deles é um defeito que você enviará se escrever a prop que espera em vez da prop que o registry diz existir. É para isso que servem as chamadas inspect dos passos 1 e 2, e ignorá-las é como um mock de aparência plausível acaba enviando um defeito.

O registry não fornece o esqueleto da tela, o idioma de composição ou o layout — a chamada de hook de biblioteca de grade que um DataGrid é dirigido, um meta específico do hospedeiro como { stickyHeader: true }, qual wrapper um componente espera ao seu redor. Isso vem das Histórias do próprio hospedeiro e, em um hospedeiro com um gerador de páginas/rotas, de seus modelos de Exemplo (passo 2). Quanto maior a cobertura de modelos e Histórias do hospedeiro, menor a parcela do registry do que você realmente precisava para construir a tela — e isso não é uma deficiência. O registry e os exemplos do próprio hospedeiro respondem a perguntas diferentes, e ambos são essenciais para a pergunta que respondem.

Referências

Abra-as quando o passo abaixo o enviar a elas, não preventivamente. Na rota 3a (escrever a História diretamente), isso pode nunca acontecer: a saída de registry status e component inspect mais o corpo deste arquivo geralmente são auto-suficientes para construir a tela inteira. Quando precisar de uma, no entanto, trabalhe a partir dela e não da memória apenas deste arquivo — seu detalhe não é repetido aqui.

Arquivo	Leia-o quando
references/registry.md	Quando a saída de inspect tiver algo que você não consegue interpretar — uma linha shape: / signature: de uma prop opaca, uma prop não documentada, um especificador de importação que parece errado
references/cli.md	Quando um comando ou flag não estiver coberto acima, a CLI não funcionar, ou você precisar dos equivalentes MCP
references/screen-json.md	Apenas se você seguir a rota do JSON de Tela (3b). O formato e o que ele não pode expressar
references/errors.md	No momento em que qualquer comando imprimir um erro ou um aviso. Cada código e sua correção
references/implementation.md	Para o meta template no passo 3, e antes do passo 5

Passo 1. Construir o registry

O Yosegi precisa de um tsconfig.json legível do hospedeiro (as props vêm dos tipos TypeScript, e isso por si só é suficiente). O Storybook é onde a História vai parar e onde você confirma como ela renderiza — mas não é um requisito.

Se você não conseguir detectar o Storybook — nenhum diretório de configuração .storybook/ (ou equivalente), nenhum script storybook no package.json do hospedeiro, nenhum index.json para apontar --index — a entrega será um arquivo de componente React simples em vez de uma História (screen generate --target component, references/cli.md). Não escolha o local de saída ou o método de revisão você mesmo: antes de construir qualquer coisa, pergunte ao usuário (a) onde o arquivo de componente deve ir e (b) como ele deseja confirmar o resultado (renderizando-o em uma rota de teste do aplicativo hospedeiro, por exemplo). O Yosegi não prescreve a superfície de revisão, e adivinhar qualquer uma das respostas viola a mesma regra que adivinhar uma prop. Com essas respostas, o procedimento abaixo permanece o mesmo, com três diferenças: registry build é executado sem --index / --storybook-url (você perde a curadoria, nada mais); na rota 3a você escreve o arquivo de componente no local que o usuário nomeou, e na 3b você passa --target component --out <esse local>.tsx; e as verificações do Storybook no passo 4 são substituídas pela verificação de tipos do hospedeiro mais o método de confirmação que o usuário nomeou.

1. Consegue executar a CLI? npx yosegi (ou pnpm yosegi, yarn yosegi, bunx yosegi) sem argumentos imprime todos os comandos, uma vez que @yosegi/yosegi já seja uma dependência do hospedeiro — instale-o primeiro se não for (references/cli.md). Node.js 20 ou mais recente, hospedeiro React + TypeScript. Se o comando falhar, consulte "Se a CLI não funcionar" em references/cli.md; a ação mais útil é ler o builtWithCliPath do <data-dir>/registry.json se um registry já existir de uma sessão anterior.
2. Defina um --data-dir agora e passe o mesmo para todos os comandos. Use .yosegi sob a raiz do pacote do hospedeiro, que também é o padrão; os exemplos abaixo ainda o escrevem, porque o padrão segue seu diretório de trabalho atual e um comando executado de outro lugar não encontrará o que você construiu.
3. Já existe um registry e ele está atualizado? Execute yosegi registry status --data-dir .yosegi primeiro — ele recalcula a versão do registry a partir de suas próprias entradas registradas e informa source: current ou source: stale com o comando de reconstrução exato, em vez de você verificar manualmente o cabeçalho de component list. "Registry not found" significa que esta é a primeira execução. Sua metade do índice do Storybook é de melhor esforço e pode relatar o índice como inacessível enquanto o veredito da fonte ainda é válido — leia essa metade como "não foi possível verificar", não como "desatualizado" ou "atual", e não deixe um servidor de desenvolvimento inacessível impedi-lo de confiar em um veredito de fonte current. Reconstrua sempre que status relatar desatualizado, sempre que algo imprimir REGISTRY_VERSION_MISMATCH, ou sempre que status relatar source: unknown porque o registry é anterior às entradas registradas (built: not recorded) — não há nada para recalcular a partir daí, então a idade é o único sinal que você tem. Reconstrua também sempre que um comando avisar que o registry foi construído por uma versão diferente do Yosegi da que você está executando: um Yosegi mais antigo não pode emitir campos que este pode (assinaturas de chamada de uma prop de função, por exemplo), e nenhum outro sinal mostra essa lacuna — a string de versão, sendo um hash de conteúdo, permanece idêntica, então um registry reconstruído a partir de um hospedeiro inalterado mantém o mesmo. O registry é um snapshot, e um desatualizado é pior do que nenhum.

yosegi registry build \
  --source "app/components/**/*.tsx" \
  --tsconfig <hospedeiro>/tsconfig.json \
  --index http://localhost:6006/index.json \
  --storybook-url http://localhost:6006 \
  --report tmp/registry-report.json \
  --data-dir .yosegi

6006 acima é o padrão do próprio Storybook, usado apenas porque esta é a primeira construção e nada informou o contrário ainda — não é necessariamente a porta do hospedeiro. Verifique o script Storybook no package.json do hospedeiro (ou pergunte) pela porta em que ele realmente é executado antes de executar isso. Cada reconstrução após esta primeira tem uma fonte melhor do que adivinhar: o cabeçalho de component list imprime uma linha rebuild: carregando o --storybook-url exato com o qual o registry foi construído pela última vez (references/cli.md).

Flags e padrões estão em references/cli.md. --index é a única parte com um pré-requisito: uma URL de servidor de desenvolvimento significa que o Storybook do hospedeiro já deve estar em execução. Sem ela, você perde as categorias derivadas do Storybook e as marcas recommended, nada mais.

Leia as estatísticas que ele imprime:

• files: 0 → o glob não correspondeu a nada. O comando ainda é bem-sucedido e escreve um registry contendo apenas os três primitivos sintéticos, então não leia "Wrote 3 components" como sucesso.
• componentCandidates: 0 com files positivo, ou withNodeSlots: 0 com um alto anyShapedProps → a construção degradou mesmo sendo bem-sucedida. O primeiro significa que o glob não cobriu nenhum componente React; o segundo significa que @types/react não foi resolvido, então toda prop ReactNode foi achatada para json e nenhum slot foi detectado. Uma linha Warning: nomeia a correção em ambos os casos — resolva-a e reconstrua antes de prosseguir.
• propsUnreadable alto em relação a extractedComponents → o tsconfig provavelmente está errado. Resolva-o agora (references/cli.md, registry metadata); um componente nesse estado rejeitará props perfeitamente reais mais tarde.

Passo 2. Consultar todos os componentes que você pretende usar

Se o modelo de Exemplo de um gerador de página/rota for a correspondência mais próxima da tela que você está construindo, leia-o primeiro, ou junto com os comandos abaixo — ele decide o esqueleto e o idioma de composição, e o registry então confirma as props exatas que o modelo deixa em aberto.

yosegi component list --category app/components/ui --data-dir .yosegi
yosegi component list --query card --data-dir .yosegi
yosegi component inspect "app/components/ui/button#Button" --data-dir .yosegi

O registry pode conter várias centenas de entradas, então restrinja com --category / --query, oriente-se pelo resumo, e então inspect cada componente que você vai escrever. inspect é autoritativo e seu conhecimento de framework não é. Leia references/registry.md para saber como interpretar o que ele fornece — as opções de enum, as linhas shape: e signature: sob uma prop opaca, o especificador de importação que o hospedeiro realmente escreve e o que uma prop não documentada significa.

Prefira componentes marcados como recommended; eles têm uma História própria.

Em seguida, reúna as convenções do hospedeiro. A História vai parar no repositório do hospedeiro e é revisada como código do hospedeiro; pular isso produz uma UI que funciona e ainda assim é devolvida.

• Encontre o contrato de dados, se já existir um — uma definição OpenAPI/JSON Schema, um esquema GraphQL, tipos TypeScript escritos à mão para a resposta da API, qualquer forma que a camada de dados do hospedeiro use. Leia-o antes de inventar dados mock. Ele decide mais do que as props dos componentes: quais campos são obrigatórios versus anuláveis e o que null significa para um determinado campo (um limite null pode significar "ilimitado", não "desconhecido"), quais campos são mutuamente exclusivos e — igualmente útil — o que não está lá (nenhum campo de classificação ou pesquisa no contrato significa que a tela também não deve inventar um). Isso é o que transforma o mock de uma proposta de aparência e sensação em algo que reflete a forma real dos dados. Onde ele reside difere por hospedeiro (openapi/schemas/, um arquivo .graphql, um types.ts gerado); encontre o que existir para este domínio e siga-o em vez de um palpite plausível.
• Pesquise o diretório de rotas/páginas do hospedeiro (app/routes/, ou onde quer que sirva páginas) por uma tela existente no mesmo domínio. Em um produto maduro, muitas vezes existe uma, e encontrá-la pode reenquadrar a tarefa completamente — por exemplo, uma rota bookings.calendar._index existente pode transformar "fazer uma tela de reservas" em "propor uma lista transversal ao fluxo de reservas existente." Isso determina se o mock que você foi solicitado a fazer é sequer a coisa certa a construir, então faça isso antes do checkpoint abaixo e deixe que isso molde as perguntas que você fizer lá.
• Execute git status e examine o diretório de saída antes de construir qualquer coisa. Uma tentativa anterior não commitada da mesma tela já pode estar na árvore de trabalho — comum após uma reinicialização de contexto e uma solicitação reemitida. Reconcilie-se com ela em vez de criar uma duplicata ao lado dela. Para refazer um arquivo que já existe — um gerador do hospedeiro se recusa quando o caminho de destino existe, ou uma tentativa anterior precisa ser substituída — mova-o para o lado (renomeie) em vez de excluí-lo; a exclusão pode não estar disponível para você, e uma renomeação libera o caminho de qualquer forma.
• Verifique se o hospedeiro tem um gerador para novas páginas ou telas — um gerador plop/hygen, um script bun add-route, muitas vezes documentado no AGENTS.md do hospedeiro ou em um script package.json. Em um hospedeiro com um, escrever manualmente um novo arquivo de tela do zero é errado: o gerador clona o modelo sancionado e impõe as convenções de arquivo e nomenclatura, então execute-o em vez de criar o arquivo você mesmo. Isso também resolve a escolha do passo 3 entre uma História inline e um módulo de página com uma História wrapper fina — um hospedeiro com um gerador assim quase sempre quer a última opção.
• Leia AGENTS.md / CLAUDE.md em todos os níveis, da raiz do repositório até o diretório de saída, e siga qualquer documento para o qual eles apontem.
• Leia uma ou duas Histórias existentes perto do local de saída. Exemplos compostos que combinam vários componentes são os que valem a pena imitar quanto ao esqueleto da página, espaçamento e seleção de componentes. Quanto ao idioma de composição — como um componente é realmente montado, não apenas quais props ele aceita: a chamada de hook de biblioteca de grade que um DataGrid é dirigido, um meta específico do hospedeiro como { stickyHeader: true }, o wrapper que um componente espera ao seu redor — uma História existente é a fonte da verdade, e o registry não é. O registry …

… [truncado para tradução]