ToshqulovLaziz/naqsh

O que naqsh faz?

v0.6. <skill> abaixo indica o diretório base desta habilidade. Os scripts precisam de Node ≥ 22 e um Chrome/Edge local; nada para instalar.

1. Rota

Declare a superfície e o modo em uma linha antes de qualquer outra coisa.

Superfície	Sinais	Leia
page	landing, portfólio, marketing, produto, one-pager	references/page.md
app	ERP, admin, dashboard, tabela, formulário, configurações, CRUD	references/app.md

Modo	Mexe no código?	Saída
build	sim, nova UI	UI + DESIGN.md
redesign	sim; mantenha comportamento, dados e texto	UI + DESIGN.md
audit	não	achados ranqueados com arquivo:linha e correção

Sempre leia references/rules.md antes de executar verificações. Se ninguém puder responder perguntas, decida e registre o motivo.

2. Contexto

• Stack, estilização, tokens existentes, fontes e como são carregadas, alternância de tema (+ sua chave localStorage), i18n (+ chave de localidade), rotas, comando de build.
• O que pode mudar e o que não deve (outras páginas, componentes compartilhados, lógica de negócio).
• Localidades: se alguma usa cirílico, cada tipo de letra escolhido deve cobri-lo.

3. Linha de base

Execute ambas as verificações no estado atual e mantenha a saída: é o "antes" do relatório e frequentemente revela bugs reais (fontes nunca carregando, contraste, estouro).

node <skill>/scripts/lint.mjs <projectRoot>
node <skill>/scripts/inspect.mjs http://localhost:PORT --surface <surface> --routes ... --locales ... --themes ...

Modo audit: siga references/audit.md daqui e pare. Não edite arquivos do projeto.

4. Inventário

• Assunto: 8–12 coisas que só este produto ou pessoa tem (nomes, lugares, números reais, trabalhos reais).
• Material: para cada espaço visual marque real, picture (honestamente encontrável) ou absent. Nunca invente prova: sem logotipos, depoimentos, métricas ou capturas de tela falsos.
• Público e tarefa: quem olha, o que devem fazer ou aprender primeiro.

5. Direção (distribuída, orientada pelo gosto)

node <skill>/scripts/deal.mjs --surface <page|app> --options 3 --project <projectRoot>

O script pontua a biblioteca contra o perfil de gosto do usuário (~/.naqsh/taste.json, substituível por projeto em <project>/.naqsh/taste.json) e escolhas recentes, e distribui 3 direções de famílias diferentes.

• Se o usuário estiver presente, mostre as três (ideia, tipo, paleta, herói) e deixe-o escolher. Caso contrário, escolha a melhor adequação para o conteúdo e diga por quê.
• deal.mjs --pick <id> imprime a folha completa (seções, movimento, importação de fonte, tokens claro/escuro) e registra a escolha. Construa a partir da folha: seu tipo, paleta e herói são o contrato. Adapte tamanhos e seções ao conteúdo real; desvie apenas com um motivo escrito (ex.: material ausente).
• page: leia também references/page.md. app: leia também references/app.md; o bloco system da folha decide shell, densidade, KPI, tabela, status e estilo de gráfico.

Brief vs. gosto. Adjetivos em um brief ("calmo", "mínimo", "profissional") descrevem o trabalho, não a aparência. Atenda-os por meio de clareza, densidade e moderação no movimento, não escolhendo uma direção que o perfil de gosto evita. Nunca descarte uma direção apenas porque é mais ousada que o adjetivo do brief; se brief e gosto realmente entrarem em conflito, escolha pelo gosto e anote em DESIGN.md.

Feedback de gosto. Quando o usuário diz o que gosta ou não gosta em um resultado, atualize ~/.naqsh/taste.json (boldness 1–5, temperature warm|cool|neutral|any, typeStyles, likes, avoid, notes) e informe-o. Preferências que valem apenas para uma superfície vão no bloco page ou app, que substitui as chaves gerais.

6. Piso (nunca dispensado; scripts verificam a maior parte)

• Texto visível de i18n em cada localidade; nenhum texto inventado.
• Fontes carregam e cobrem todos os scripts de localidades; a localidade mais longa cabe em 375 px.
• @import de fontes acima de @import "tailwindcss"; estilos de elemento dentro de @layer base.
• Sem rolagem horizontal na página; overflow-x: clip, nunca hidden/100vw.
• Contraste ≥ 4,5:1 (3:1 para grande) em cada tema; foco visível; alvos ≥ 24 px (44 recomendado).
• prefers-reduced-motion respeitado; sem transition: all; anime transform/opacity.
• Novos tokens com escopo para que páginas não tocadas não mudem.

7. Indícios de UI gerada (reflexo: dispensar apenas quando a folha distribuída permitir)

Índigo/violeta padrão do Tailwind; brilho, vidro, blobs aurora, ícones orbitando, botões cintilantes, texto gradiente; sobrancelhas em caixa alta espaçadas acima de cada título; grades de cartão idênticas com bordas arredondadas e sombra; uma faixa herói de métricas redondas; o mesmo nome ou título repetido em uma tela. Escala ousada, cor forte e contraste serifa/sans-serif não são indícios — timidez também é uma falha: se o resultado puder passar por um modelo, force mais a ideia da folha.

8. Loop de construção

1. Tokens (com escopo) → tela principal / herói → o resto.
2. Após cada etapa: lint. Após a tela principal: construa, visualize, inspect apenas naquela rota (largura máxima + mínima, primeira localidade, ambos os temas). No final: a matriz completa. Abra as capturas de tela e examine cada vez. Corrija, repita — no máximo 3 rodadas após a primeira passagem completa. Leia apenas os arquivos que você altera; mantenha as iterações curtas.
3. Passagem de detalhes: leia references/components.md; todo controle é construído de acordo (nenhum native-control deixado sem dispensa), o momento marcante existe. Execute inspect ... --details e abra cada recorte em <out>/details/; corrija até que cada um pareça intencional em 2x.
4. Quando a passagem de detalhes estiver concluída e o build estiver com 0 falha de piso, escreva DESIGN.md (rascunho) e inicie o revisor em um novo contexto — Ferramenta Agent, subagent_type: "naqsh:naqsh-reviewer" — com: raiz do projeto, superfície, modo, id da direção, caminho <skill>, pasta de capturas de tela (com details/), URL de visualização e as flags do inspect. Aplique suas correções de floor, idea e fidelity (outras a seu critério), reexecute as verificações. Uma rodada de revisão; uma segunda apenas se o veredito foi rework. Se nenhuma Ferramenta Agent estiver disponível, faça a revisão você mesmo a partir de agents/naqsh-reviewer.md após reler as capturas de tela.
5. Finalize com 0 falha de piso, todo reflexo corrigido ou dispensado, e o build do projeto passando. Pare o servidor de visualização.

9. Relatório

Escreva DESIGN.md na raiz do projeto (ou onde o usuário disser): opções distribuídas e a escolha, frase de ideia, tokens, tipo, decisões principais, o momento marcante, contagens de antes → depois das verificações, dispensas com motivos, verificações julgadas, itens em aberto. Termine perguntando ao usuário o que gostou e não gostou, para que o perfil de gosto melhore.