O que Isometrics (Estilo Linha) faz?
Você transforma um brief curto ("galeria isométrica", "estado de caixa de entrada vazia") em um objeto desenhado e animado que é entregue como um estado completo: a ilustração, um título, uma linha de texto e um botão. Cada objeto é construído a partir de primitivas 3D em unidades de mundo e projetado em isometria verdadeira, de modo que compartilha um grid, um contorno e uma aparência com todos os outros objetos feitos com esta skill.
A aparência, em uma linha: um objeto, de frente se for plano ou no ângulo isométrico verdadeiro se for volumoso, um contorno de 1 px sobre faces brancas como papel, uma pequena marca da cor da marca, sem sombra, sem brilho, um "beat" de movimento e depois imobilidade.
Você não pula etapas. Você não considera um objeto pronto até que o verificador passe e você tenha olhado para sua folha.
Conteúdo
| Arquivo | Leia-o |
|---|---|
SKILL.md | sempre: o fluxo de trabalho e as regras |
references/brief-to-concept.md | estágio 1–2: transformando um brief vago em três conceitos |
references/motion.md | estágio 4: escolhendo e cronometrando o "beat" |
references/line-style.md | estágio 3–5: todas as regras de desenho, o que fazer e não fazer, com a razão |
references/engine-api.md | durante a construção: o motor e o kit Line |
references/isometric-math.md | quando uma forma precisa de matemática que o motor não tem |
examples/*.tsx | antes de construir: comece pelo mais próximo |
engine/iso-core.tsx, engine/iso-line.tsx | copiado para o projeto do usuário uma vez |
scripts/check.mjs | estágio 5: a verificação rigorosa de renderização |
Configuração (uma vez por projeto)
Os objetos são componentes React client para um projeto com Tailwind CSS
e shadcn/ui (eles usam @/lib/utils cn e @/components/ui/button)
e o pacote motion.
-
Verifique se
components/isometrics/iso-core.tsxexiste. Se estiver faltando, copieengine/iso-core.tsxeengine/iso-line.tsxdesta skill paracomponents/isometrics/(ou a pasta que o usuário preferir; os objetos os importam relativamente, então todos vivem em uma pasta). -
Se o projeto não tiver
motion: instale-o (npm i motion, ou o gerenciador de pacotes do projeto). Se não tiver o shadcn Button:npx shadcn@latest add button. -
Para o verificador, Playwright:
npm i -D playwrightenpx playwright install chromium(ou ele usa um Chrome instalado). -
Uma página para renderizar um objeto sozinho, envolto em
PlayOnHover(o verificador o executa passando o mouse), por exemplo,app/isometrics-preview/<nome>/page.tsxno Next.js, ou uma rota no roteador do próprio projeto:import { PlayOnHover } from "@/components/isometrics/iso-line"; import { MapPin } from "@/components/isometrics/map-pin"; export default function Page() { return ( <main className="flex min-h-svh items-center justify-center p-10"> <PlayOnHover><MapPin /></PlayOnHover> </main> ); }Crie-a por objeto; informe ao usuário que é uma página de pré-visualização que ele pode excluir.
Nunca edite o motor para fazer um objeto funcionar. Se uma forma estiver realmente faltando, adicione um auxiliar dentro do próprio arquivo do objeto, construído a partir de 3D, e informe ao usuário.
O fluxo de trabalho
Estágio 1 · Leia o brief
Transforme a solicitação em três respostas antes de qualquer outra coisa:
- Assunto: a coisa ou tópico ("galeria" → fotos, álbuns, imagens).
- Uso: qual estado ele serve: vazio (nada aqui ainda), bloqueado (sem acesso, desligado, não conectado, não encontrado), nada encontrado (pesquisa, filtros), sucesso / tudo limpo, ou uma ilustração pontual em um cartão de recurso.
- Mensagem: uma frase simples que o estado diz ("Você ainda não tem fotos").
Se o uso não for declarado, o brief geralmente se encaixa em mais de um; é para isso
que servem os conceitos. Veja references/brief-to-concept.md.
Estágio 2 · Três conceitos, então espere
A menos que o brief já nomeie um objeto e um estado, mostre ao usuário três conceitos como uma tabela e pare e espere pela escolha dele:
| Objeto | Mensagem (título) | O único "beat" | |
|---|---|---|---|
| A ★ | ... | ... | ... |
| B | ... | ... | ... |
| C | ... | ... | ... |
Cada conceito deve passar em todos os quatro testes:
- Lê-se em contorno a 120 px. Uma silhueta que as pessoas reconhecem sem cor.
- Arredondado supera volumoso. Objetos arredondados são lidos como mais amigáveis em linha; uma caixa simples parece um pacote ou um wireframe.
- Um objeto. Não uma cena, não uma pilha. Uma segunda parte pequena é aceitável apenas se pertencer ao objeto (uma tampa, uma bandeira, uma mão).
- O "beat" diz a mensagem. O movimento é o verbo da frase
(veja
references/motion.md). Se você não consegue nomear o "beat", é o objeto errado.
Marque sua recomendação com ★ e diga o porquê em uma linha. Varie os três: diferentes objetos, diferentes "beats". Quando o brief for específico ("um estado de caixa de entrada vazia com uma bandeja"), pule a tabela, declare sua escolha e o "beat", e continue.
Estágio 3 · Divida o objeto em partes
Escreva uma tabela de partes em unidades de mundo antes do código: cada parte, a
primitiva da qual é construída (Extrude, Slice, Ring, FacePath, Box...), seu
tamanho e posição no grid de 0,5, se se move, e qual parte é a
marca da marca. Em seguida, o texto: título (≤ 28 caracteres), uma ou duas
frases, rótulo do botão (≤ 22 caracteres) e seu ícone (o ícone segue
o verbo: um sinal de mais apenas onde a ação adiciona).
Regras que decidem partes (todas em references/line-style.md):
- Escolha a vista primeiro. Coisas planas ou finas (uma página, um crachá, um disco)
são
view="front"; coisas volumosas ou profundas (uma impressora, uma caixa, um servidor, uma bandeja, um bastão sobre uma mesa) sãoview="isometric". Caixas de frente são lidas como adesivos planos com linhas duplicadas. - Construa voltado para +y em torno de x = 0, apoiado em z = 0.
- Três níveis de detalhe: forma, as partes pelas quais as pessoas o reconhecem, e marcas sutis (parafusos, aberturas, costuras, uma etiqueta).
- Linhas limpas: um sólido visto de frente não tem profundidade ou tem uma clara (faixa ≥ ~4 px); uma parte é nivelada ou ≥ 0,5 saliente; pilhas redondas compartilham um raio com uma linha de costura.
- Coisas planas (papel, etiquetas, telas) são faces, não sólidos.
- Sólidos redondos são fatias entre círculos nivelados, pintados de baixo para cima.
- Um contorno que não é convexo precisa que sua borda distante seja desenhada.
- Uma parte que desliza para fora de um invólucro é cortada no invólucro, não flutuada.
- Uma marca da marca (paleta
main); todo o resto é papel (surface).
Estágio 4 · Escolha e escreva o "beat"
Escolha o movimento a partir da mensagem (references/motion.md), depois escreva o
comentário do storyboard no topo do arquivo antes do código de desenho:
tempos, o que se move, a que distância, por quê. Cada valor em uma constante nomeada. O
"beat" espera 400 ms depois que a arte rolar para a vista, dura 1,2–2,4 s e
se reproduz uma vez. Quando o código do usuário passa active, ele se reproduz cada vez
que active se torna verdadeiro (atraso de 80 ms), nunca por conta própria. Movimento
reduzido mostra a pose de descanso.
Estágio 5 · Construa, renderize, verifique, olhe, corrija
-
Comece pelo exemplo mais próximo em
examples/(tabela abaixo). Mantenha sua estrutura: storyboard, TIMING, geometria, trilhas, poses, peças,LineState. -
Renderize-o em sua página de pré-visualização e execute o verificador:
node <skill>/scripts/check.mjs http://localhost:3000/<caminho-preview>/<nome> --duration <espera+beat ms>Ele renderiza claro e escuro, reproduz o "beat" passando o mouse sobre a arte em um relógio falso (então a página de pré-visualização deve envolver o objeto em
<PlayOnHover>), salva quadros em 0, 25, 50, 75, 100 % e depois, e verifica:- sem erros de hidratação ou console, no claro, escuro e movimento reduzido;
- que se reproduz quando ativo, e que não há botão dentro da arte;
- que o "beat" se assenta exatamente de volta à sua pose de descanso;
- que o movimento reduzido está parado, mostra a pose de descanso, ignora
active; - que cada contorno tem cerca de 1 px; sem filtros, brilho, sombras ou pintura gradiente;
- que o desenho em repouso cabe em seu quadro;
- que o desenho está centralizado no título dentro de 2 px;
- linhas limpas: no máximo 6% do contorno em duplas sustentadas (duas
linhas a 0,5–2 px de distância ao longo de um comprimento real; pequenas bolhas onde as linhas
se encontram não contam), no
escuro a 4× (
lines.png, duplas em vermelho emlines-marked.png); - que seu tamanho óptico corresponde ao conjunto (√(l×a) 140–175 px).
-
Olhe para
sheet.pngelines.png(abra ambos) e percorra a lista de verificação abaixo. O verificador não pode ver o design; você pode. -
Corrija e execute novamente. No máximo três rodadas. Se algo ainda estiver aquém após três, pare e informe ao usuário exatamente o quê, com a folha.
-
Relate: o conceito, o storyboard, o resultado do verificador, o que você corrigiu depois de olhar, o que ainda está aquém e o caminho da folha.
Olhe para a folha: a lista de verificação
Legibilidade
- Sem o título, um estranho nomearia o objeto no tamanho de uma miniatura?
- Nada parece um rosto acidentalmente (duas partes redondas sobre uma curva).
- A marca da marca é uma pequena parte, e é a parte na qual o olho deve pousar.
Descanso reto
- Em repouso, cada vertical é vertical e cada borda é nivelada; nada se inclina, nada pende torto, segundas chapas são deslocadas, não viradas.
- A pose de descanso é igual à pose de movimento reduzido (o verificador compara pixels; você verifica se parece intencional).
Linhas (olhe para lines.png: escuro, 4×)
- Um peso de contorno em toda parte; sem bordas duplicadas, sem costuras finas entre preenchimentos, sem bordas distantes faltando em contornos curvos, sem preenchimento ultrapassando um contorno, sem linha terminando no ar.
- Cada parte é nivelada ou claramente saliente (≥ 0,5); sem faixas finas.
Realismo
- A vista certa: coisas planas de frente, coisas volumosas em isométrica.
- Três níveis: forma, partes reconhecíveis, marcas sutis. Alguém que possui um diria "sim, isso é uma impressora"?
- A faixa superior (espessura vista de 30° acima) está presente em sólidos e ausente em faces finas.
Movimento
- O "beat" diz a mensagem; cada movimento é causado pelo anterior (um atraso, um acompanhamento, um assentamento).
- Partes articuladas nunca balançam através de seu invólucro; pontas nunca cruzam o repouso; balanços permanecem pequenos (≤ 6° em uma parte pendurada, ≤ 25° em uma aba).
- Nada aparece ou desaparece gradualmente; coisas que aparecem crescem com escala.
Ajusta-se à página
- Centralizado no texto; o quadro não está preenchido com espaço morto.
- Parece correto no escuro: faces de papel tornam-se papel escuro, a marca da marca permanece a marca.
Nunca mais: erros que esta skill já cometeu
Cada um destes foi enviado uma vez, foi pego na revisão e agora é uma regra. Antes de relatar um objeto, verifique-o contra cada linha.
| Erro | Regra agora |
|---|---|
| Caixas desenhadas de frente pareciam adesivos planos | Escolha a vista primeiro: coisas planas de frente, coisas volumosas view="isometric" (line-style.md) |
| Faixas superiores finas, partes mal salientes e anéis escalonados desenhavam linhas duplicadas e sujas | Sem faixas finas; nivelado ou ≥ 0,5 saliente; pilhas redondas em um raio; o teste de linhas limpas do verificador deve passar, e você olha para lines.png (escuro, 4×) |
| Objetos eram apenas um contorno ("não realistas") | Três níveis de detalhe: forma, partes reconhecíveis, marcas sutis |
| Tamanhos variavam entre objetos em um conjunto | Tamanho óptico 140–175 px via defaultArtClassName |
| Páginas voavam 3 unidades para fora do quadro | O movimento permanece no espaço aéreo da arte; no máximo um pouco além da borda do quadro |
| Duas travas, uma faixa de largura total como "uma marca da marca" | Uma pequena marca, realmente uma |
| Uma ranhura sobre um ponto, duas travas sobre uma costura pareciam um rosto | Procure por rostos acidentais no tamanho de miniatura |
| Uma virada de canto em direção ao espectador era invisível de frente | Voltas em direção ao espectador são lidas em uma fração de seu ângulo; prefira movimentos no plano da imagem, ou vá grande (motion.md) |
| Uma página inclinada em seu plano cisalhava no ângulo isométrico | Na vista isométrica, vire uma parte apenas em torno de sua própria normal ou de uma dobradiça em sua borda (motion.md) |
| Uma parte piscava sua pose inicial por um quadro na primeira reprodução | Partes acionadas pelo estado do relógio reiniciam quando o clipe muda e começam em repouso quando seguradas (engine-api.md) |
| Paredes finas de bandeja pareciam plástico fino | Paredes robustas recebem espessura (≥ 0,5); faces finas são para papel |
| Cada objeto parecia bom sozinho, o conjunto não | Revise o lote inteiro lado a lado, claro e escuro, antes de relatar |
| Corpo de um sino, uma alça, um ponteiro de agulha desenhavam contornos duplicados ao longo de suas curvas | De frente, uma parte curva é uma face plana (ou uma claramente profunda); dê a um ponteiro lados paralelos, nunca um afunilamento |
| Areia desenhada no contorno do vidro criava um borrão grosso | O conteúdo fica dentro de uma parede interna, nunca no contorno do recipiente |
| Uma porta 0,25 saliente de sua caixa duplicava o arco | Uma porta com a forma de sua abertura compartilha um contorno em repouso |
| Uma porta de cofre a 32° em isométrica parecia de perfil | Portas isométricas e tampas abrem ~24–26° para que sua face ainda seja legível |
| Um chaveiro ficava sobre as chaves em vez de através de seus furos ("o anel não está dentro do chaveiro") | Partes encadeadas se entrelaçam: o anel passa atrás de cada parte em um lado de seu furo e na frente do outro (line-style.md) |
| Reduzir um objeto ao seu tamanho trazia as linhas duplicadas de volta | Defina a largura padrão primeiro, depois faça faixas ≥ 0,5 para objetos desenhados pequenos |
| Um crachá "!!!" falhava na verificação de linha | Desenhe marcas como formas com lacunas claras; evite glifos de lacuna em texto |
Regras inegociáveis
- Isometria verdadeira apenas. Eixos a 30° da horizontal, 120° de distância, escala igual. Nunca a projeção 2:1 de "jogo" (26,565°).
- Geometria primeiro. Coloque primitivas em unidades de mundo. Nunca escreva um caminho de tela projetado à mão.
- Um grid. Posições e tamanhos em 0,5 unidades de mundo; detalhes de face em 0,25.
- Uma aparência.
variant="ink"(padrão) ou"line"; nunca misture aparências em um objeto. Contorno de 1 px, paredes de papel, sem sombra, sem brilho, sem gradiente. - Tema a partir de tokens. As cores vêm apenas do tema shadcn do usuário
através das variáveis
--iso-*. Sem hex, sem oklch em um arquivo de objeto. A marca da marca seguetone(padrãoprimary). - Props, não forks. Cópia, tom, variante, espessura do traço, interruptores
de movimento são props com comentários de documentação (
LineStateProps). Nunca nomeie uma prop de conteúdotitle: é o nome acessível. - Acessível e incorporável. A arte é decorativa a menos que
titleseja fornecido. Quando fornecido, o SVG temrole="img"e um<title>. O objeto ocupa a largura de seu contêiner, centralizado. DevclassNamesubstitui os padrões. - Um "beat", uma vez. Um movimento (o "beat") em uma direção por objeto, tocado
uma vez após 400 ms atrasado, nunca em loop.
activedo pai permite a reprodução sob demanda com um atraso de 80 ms. Movimento reduzido o impede. - Entregue com a folha. O verificador produz
sheet.png,lines.pngelines-marked.png. Olhe para eles. O objeto não está pronto sem eles. - A forma segue o briefing. A mensagem decide o "beat". O assunto dita o objeto. O uso decide o texto. O tema shadcn / da marca do usuário dita a marca.
Tabela de exemplo
| Nome do arquivo | Objeto | Vista | "Beat" |
|---|---|---|---|
examples/map-pin.tsx | Mapa com pino | Isométrica | Pino balança 2,5° |
examples/empty-box.tsx | Caixa de presente vazia | Isométrica | Tampa abre 24°, depois assenta |
examples/search-page.tsx | Lupa e folha de papel | Frente | Lupa inclina 3° |
Veja examples/ para mais.
Notas técnicas
- Motor:
iso-core.tsxforneceProjector,Face,IsoSvg, e primitivas (Extrude,Slice, etc.).iso-line.tsxforneceLineState,PlayOnHover, e o processo de pintura em linha. - Verificador:
check.mjsusa Playwright para renderizar, capturar e analisar saída. Ele requernode 18+eplaywrightinstalado. - Tamanho em repouso: Defina
defaultArtClassNamepara definir uma largura base; o verificador confirma √(largura × altura) entre 140–175 px. - Edição de motor: Nunca edite
iso-core.tsxouiso-line.tsxpara fazer um único objeto funcionar. Se uma primitiva estiver faltando, construa um auxiliar no arquivo do objeto.