Kirky-X/maliang (马良)

maliang (马良) —— Skill de Sistema de Design

Convenção de chamada de script: caminhos relativos em python3 scripts/… são baseados no diretório de instalação deste skill (CWD assumido). Ao executar em projetos do usuário, sempre use o caminho absoluto {SKILL_DIR}, ex: python3 {SKILL_DIR}/scripts/ui-graph.py …; parâmetros de entrada como --target/--framework-file devem apontar explicitamente para o caminho do projeto do usuário, proibindo o uso de examples/ do próprio skill como alvo de análise.

Treze subcomandos cobrem todo o ciclo de vida de UI/UX (Pesquisa → Definição → Design → Implementação → Verificação → Entrega → Iteração, diagrama geral em references/meta/lifecycle.md): design-md (criar DESIGN.md, com exploração de domínio e livro-razão de decisões) → redesign (reformular UI existente) → explore (divergência-comparação-convergência de múltiplas opções quando a direção é indefinida) → draw-md (UI markdown no nível de página) · component (brief de componente individual) → preview (verificação de pré-visualização) → critique (revisão de usabilidade) → draw-harmony/draw-flutter/draw-element (código do framework) → ui-graph (gerenciamento de relacionamento de UI) · ip (personagem IP) / ip-handbook (manual visual de IP).

• design-md (montante) — Produz DESIGN.md em prosa-primeiro (YAML token + razões de design em Markdown, formato agent-first do Google Labs). Suporta quatro ações: "criar, aplicar, verificar, exportar". Resolve "o que é e por que" do sistema de design.
• redesign (via paralela a montante) — Reformula UI existente, auditoria de 10 dimensões (incluindo SEO e rastreamento, consistência do artefato) + regras retidas. Suporta quatro modos: Refresh / Restructure / Rebuild / Deslop. Resolve "como melhorar o design existente".
• draw-md (meio do fluxo) — Produz UI markdown com tokens rígidos no nível de página a partir do DESIGN.md (seções de layout + tabela de parâmetros de componentes, cores/fontes/espaçamento todos referenciando tokens, RGBA + HEX). Resolve "como implementar especificamente cada página/componente".
• preview (verificação) — Usa o framework Element Plus para pré-visualização em tempo real do output do draw-md, suporta shells de dispositivo iOS/Android. Resolve "se o efeito está correto".
• critique (verificação · avaliação profunda) — Pontuação 0-4 das 10 heurísticas de Nielsen + walkthrough de persona + lista de carga cognitiva, produz instantâneo de pontuação/tendência/backlog. Resolve "se é fácil de usar". Lista de conformidade de UI/acessibilidade lê references/meta/web-interface-guidelines.md; disciplina de craft de UI de produto e revisão rigorosa/processo profundo de remoção de 'slop' em references/interface-design/ (anteriormente um skill independente, agora incorporado)
• draw-harmony (jusante) — Converte UI lógica do draw-md em implementação de framework HarmonyOS (ArkTS). Resolve "como escrever o código para HarmonyOS".
• draw-flutter (jusante) — Converte UI lógica do draw-md em implementação de framework Flutter. Resolve "como escrever o código para Flutter".
• draw-element (jusante) — Converte UI lógica do draw-md em implementação de framework Element Plus. Resolve "como escrever o código para Element Plus".
• ui-graph (gerenciamento de relacionamento) — A partir de ui-markdown/, produz ui-relationships.json (hierarquia + navegação) + ui-hash-state.json (linha de base de hash) + ui-implementation-map.json (mapeamento UI lógica ↔ implementação). Resolve "como gerenciar relacionamentos de página, como rastrear mudanças, onde estão as lacunas de implementação".
• ip (personagem IP) — Constrói prompt com base no tom do DESIGN.md, prioriza chamada de API text_to_image para gerar imagem, fallback para output de documento de prompt estruturado. Resolve "como gerar a imagem do personagem IP do projeto".
• ip-handbook (manual visual de IP) — 8 módulos produzem especificações (vistas de três ângulos/extensão de ação/emojis/fontes/cores/ layout/materiais periféricos/requisitos gerais), HD 2K 3:4. Resolve "como implementar o sistema visual do IP".

Roteamento de Subcomandos

🔴 CHECKPOINT: Sem DESIGN.md, é estritamente proibido entrar diretamente em subcomandos downstream draw-md / draw-* — primeiro passe pelo design-md para estabelecer o sistema de design, caso contrário, o UI markdown e o código do framework produzidos não terão tokens para referência.

Intenção do Usuário	Subcomando	Fluxo Completo
Criar / Gerar DESIGN.md (a partir de código/captura de tela/entrevista)	design-md	references/commands/design-md.md
Aplicar DESIGN.md ao código front-end	design-md	references/commands/design-md.md
Lint / Diff / Exportar / Verificar DESIGN.md	design-md	references/commands/design-md.md
🔷 Reformular / Redesenhar UI existente (Refresh/Restructure/Rebuild/Deslop remover cheiro de IA)	redesign	references/commands/redesign.md
🔷 Ajuste direcional (bolder mais ousado / quieter mais silencioso / distill mais refinado, mantendo o mundo visual inalterado, redesign como pré-etapa leve)	redesign	references/commands/redesign.md
🔷 Brief de componente individual (fazer um botão / uma caixa de entrada / toast etc., porta rígida de 8 estados)	component	references/commands/component.md
Produzir UI markdown no nível de página (tabela de tokens + especificação de página)	draw-md	references/commands/draw-md.md
Especificar componentes reutilizáveis entre páginas (barra de navegação / dock)	draw-md	references/commands/draw-md.md
🔷 Direção indefinida, comparar múltiplos esquemas antes de finalizar (layout/densidade/personalidade/modelo de interação realmente diferentes, padrão 3 no máximo 5)	explore	references/commands/explore.md
🔴 Pré-visualizar efeito de UI markdown (shell de dispositivo + Element)	preview	references/commands/preview.md
🔷 Revisão de usabilidade / Pontuação (Nielsen+persona walkthrough+carga cognitiva)	critique	references/commands/critique.md
🔴 Converter UI markdown em código HarmonyOS (ArkTS)	draw-harmony	references/commands/draw-harmony.md
🔴 Converter UI markdown em código Flutter (Dart)	draw-flutter	references/commands/draw-flutter.md
🔴 Converter UI markdown em código Element Plus (Vue 3)	draw-element	references/commands/draw-element.md
🔷 Gerar / Consultar gráfico de relacionamento de UI (hierarquia + navegação + hash + mapeamento de implementação)	ui-graph	references/commands/ui-graph.md
🔷 Consultar destinos de navegação não gerados / navegação anômala / páginas não implementadas / deriva semântica especificação↔código (funcionalidade faltante/valores codificados/desvio de arquitetura)	ui-graph	references/commands/ui-graph.md
🔷 Gerar personagem IP baseado em DESIGN.md (API primeiro, fallback prompt)	ip	references/commands/ip.md
🔷 Gerar manual visual de IP (vistas de três ângulos/ação/emoji/fonte/cor/layout/periféricos)	ip-handbook	references/commands/ip-handbook.md

Linhas marcadas com 🔴 requerem confirmação da existência do output do draw-md; preview/draw-* sem entrada de UI markdown devem, dentro do fluxo do subcomando, cair em fallback guiando o usuário de volta ao draw-md. Quando o usuário não especifica um framework alvo, draw-* primeiro verifica a stack front-end existente do projeto do usuário (se existir → segue a stack e explica a suposição; se não existir → segue o guia de seleção de framework por cenário em framework/INDEX.md, após confirmação do usuário). Linhas marcadas com 🔷 pertencem a capacidades novas; critique precisa primeiro do output do preview ou de uma página acessível; ui-graph precisa primeiro do output do draw-md; ip/ip-handbook precisa primeiro do DESIGN.md.

Ao entrar em um subcomando, execute de acordo com seu documento de fluxo. Pontos de verificação, casos de borda e listas de verificação de entrega estão todos dentro dos documentos de cada subcomando — Este roteador não contém o corpo do fluxo.

Tamanho da Tarefa (Leve / Completo)

Tamanho	Critério	Fluxo
Leve	Projeto já possui DESIGN.md, e o escopo da mudança = componente único (subcomando component) ou ajuste local de página única	Não refaz design-md e fluxo de lista de verificação de página completa: diretamente draw-md altera a página alvo (componente único passa pelo component) + preview verifica essa página/esse componente
Completo	Novo projeto / Novo tipo de página / Mudança em múltiplas páginas / Direção indefinida (primeiro explore) / Sem DESIGN.md	Cadeia completa design-md → draw-md → preview → draw-*

Leve não é isenção de portaria. Os seguintes itens não cortáveis são executados integralmente em qualquer tamanho:

1. Verificação de a11y — aria-label, alvo de toque ≥44px, contraste, preferências prefers-* (classe CRITICAL, veja references/meta/rules-priority.md regra de resolução de conflitos 4, não negociável);
2. Portaria rígida do preview — verificação validate-draw-md e revisão disposition do preview normalmente; o "spot check" do leve significa apenas executar na página alterada, não pular ou reduzir o limiar. Única exceção: quando o usuário explicitamente diz que não precisa de pré-visualização, siga a "condição de pulo (opt-out explícito)" em preview.md para pular a renderização e revisão, a verificação validate ainda é executada, e a nota de entrega inclui um banner DEGRADED;
3. Restrições rígidas do draw-md (referência de token / referência de modo escuro / animação ≤400ms) são verificadas item por item na página alterada (veja resumo de restrições em references/commands/draw-md.md).

Solicitações de tamanho leve sem DESIGN.md são tratadas conforme a primeira linha de "modo de falha e fallback": guie primeiro para design-md, o tamanho não oferece exceção.

Modo Não Supervisionado e Degradação de CHECKPOINT

Critério: Quando o usuário explicitamente diz "você decide / faça diretamente", ou a sessão está não supervisionada (usuário ausente, sem resposta), CHECKPOINT não bloqueia ponto por ponto. Apenas quando "a informação faltante mudaria a direção central e não pode ser inferida" é que se pergunta uma vez concentrada; detalhes que podem ser corrigidos depois, o próprio skill decide e explica a suposição.

Categoria de CHECKPOINT	Ação padrão em modo não supervisionado
Confirmação de direção / proposta (design-md 0b/0c, lista de direções do explore)	Avance diretamente com base em evidências e recomendação; explore ainda materializa 3 direções, três primeiras telas reduzidas a 480px lado a lado com auto-seleção e razão escrita; quando a tarefa claramente requer apenas uma direção, não pergunta nem faz páginas de comparação
Confirmação de extração / inventário (extração de token, lista de páginas)	Tome valores com base em evidências do local e marque confiança (✅/⚠️/❓, formato veja "marcador de confiança de caminho de extração" no design-md); lista gerada por regras padrão
Confirmação pré-entrega (confirmação de ação do preview / critique)	Avance com base na portaria e resultado de evidência, a nota de entrega começa com banner de degradação; pular preview não é uma ação de autoescolha — apenas quando o usuário explicitamente diz, siga a "condição de pulo (opt-out explícito)" em preview.md, em modo não supervisionado sempre execute
Confirmação de material / API (ip etc.)	API indisponível usa fallback existente; artefato salvo no novo caminho sem sobrescrever

Disciplina de apresentação: A primeira linha da nota de entrega começa com ⚠️ DEGRADED: não supervisionado (<motivo>) (usando a forma DEGRADED existente do critique/preview, sem introduzir um segundo modo); decisões de autoescolha e razões escritas item por item na descrição do design; quando não pode ver a imagem, escreva "visual real não verificado", não dê nota visual; quando não há ambiente executável, não diga que a interação passou. Após o retorno do usuário, revise conforme sua opinião, a revisão segue a reescrita de decisão.

Runtime Fraco e Degradação Entre Agentes

Complementar à seção anterior: a tabela de modo não supervisionado lida com o eixo de ausência do usuário, esta tabela lida com o eixo de capacidade de runtime (sem subagente / modelo não mainstream / contexto pequeno).

Degradação gradual conforme o nível de aperto, a degradação sacrifica o fluxo, não sacrifica restrições rígidas (verificação de a11y, referência de token, portas CRÍTICAS G01–G46, protocolo de ativo real não isento):

1. explore múltiplas direções paralelas → serial: antes de iniciar cada direção, leia apenas o contrato DESIGN.md e seu próprio cartão de direção, não referencie direções já feitas;
2. Ainda apertado → 1 especificação completa da direção principal + cartões leves para as direções restantes (apenas 7 colunas do cartão de direção + esqueleto da primeira tela), página de comparação reduzida a cartões de direção lado a lado;
3. references leia apenas a coluna obrigatória do "tempo de carregamento do documento meta" do subcomando atual, não leia tudo;
4. draw-md em lote grande: primeiro entregue páginas P0 (veja default-pages), o restante das páginas após confirmação da direção em lotes;
5. Perguntas de checkpoint substituídas por lista de suposições no artefato (arquivo gate e semântica de degradação de CHECKPOINT permanecem as mesmas — veja seção anterior, ambas compartilham).

Verificação de Versão

Esta seção informa o usuário se há uma nova versão do skill maliang. Lógica determinística (julgamento de throttling / comparação de versão / registro) em scripts/version-check.py, arquivo de estado padrão ~/.maliang/version-check (alterável com --state); o agente apenas executa comandos e git ls-remote.

Ao usar este skill, primeiro execute python3 {SKILL_DIR}/scripts/version-check.py due; output skip:* pula esta seção diretamente. Quando output due:

1. Execute git -C {SKILL_DIR} ls-remote --tags --refs --sort=-v:refname origin 'v*', pegue a primeira tag e passe para python3 {SKILL_DIR}/scripts/version-check.py compare <tag> (padrão --current lê frontmatter do SKILL.md deste repositório);
2. Output compare same (incluindo tag não no formato vX.Y.Z — tratado como sem tag) não precisa mencionar; quando output newer, primeiro complete a tarefa do usuário, no final informe "maliang tem nova versão vX.Y.Z, atualização veja https://github.com/Kirky-X/maliang/releases , quando precisar execute git -C {SKILL_DIR} pull --ff-only; se não quiser mais receber lembretes, execute python3 {SKILL_DIR}/scripts/version-check.py record off";
3. Independentemente do que for encontrado, termine com o resultado real: python3 {SKILL_DIR}/scripts/version-check.py record ok (encontrado) ou record failed (sem rede/sandbox sem rede, tentar novamente após 7 dias).

A decisão de atualizar é do usuário, não executa atualização automaticamente, não baixa nenhum arquivo.

Tempo de Carregamento de Documentos Meta (Fase × Obrigatório)

A camada de norma references/meta/ não requer leitura completa de uma vez — carregue de acordo com a fase atual, trabalho de planejamento não carrega documentos de fase de execução:

Fase (subcomando)	Leitura obrigatória antes de começar	Consulta sob demanda
design-md (criar sistema)	product-reasoning.md, philosophy.md (obrigatório antes da prosa da Fase 1), principles.md, ux-laws.md (camada de leis "por que")	token-provenance.md (tabela de decisão da Fase 0d + rastreamento de token), dials.md, spec-schema.md, analytics-events.md (tabela de eventos de rastreamento), content-guide.md, templates/README.md (quatro passos de seleção), data-floor.md (produto de dados Fase 0a obrigatório: tabela de ligação + script de inicialização a frio), workbench-structures.md (11 julgamentos de estrutura)
redesign (reformular)	ai-tells.md, rules-priority.md	dials.md, accessibility.md, surface-modes.md, ux-rules.md
explore (múltiplos esquemas de direção indefinida)	dials.md, surface-modes.md, token.md	ai-tells.md (princípio geral de isenção), ux-rules.md, workbench-structures.md (antes de divergir interface de dados, julgar estrutura principal/secundária); antes de começar python3 {SKILL_DIR}/scripts/style-ledger.py check (livro-razão de aparência entre projetos, evitar ativamente fundo/família de fonte repetidos, não bloqueia)
draw-md (produzir especificação de página)	token.md, ai-tells.md	surface-modes.md, visual-assets.md, copy-strategy.md (estratégia de texto para páginas Persuade), templates/INDEX.md, ux-rules.md, llm-behavior.md (anti-corte em artefatos longos), performance.md, alignment.md (eixo de alinhamento/mesma linha mesma altura, G44/G45), workbench-structures.md (julgamento de estrutura passo 2.7), data-floor.md (tabela de ligação de base de dados passo 2.7), app-screen-floor.md (piso de tela de dados para modos Operate/Data); antes de começar python3 {SKILL_DIR}/scripts/style-ledger.py check (livro-razão de aparência entre projetos, não bloqueia)
preview (verificação e entrega)	numbered-gates.md (portas numeradas G01–G46, camada de entrega ou rejeição), ai-tells.md (princípio geral de isenção), performance.md	token-provenance.md (julgamento de rastreamento do grupo A mantido), ux-rules.md, accessibility.md, content-guide.md, hardening.md (endurecimento para produção)
critique (avaliação profunda de usabilidade)	surface-modes.md, principles.md	accessibility.md, ux-rules.md, day-two-blacklist.md (quarta pergunta·auditoria de nível de definição)
draw-harmony/flutter/element	performance.md, accessibility.md, polish-craft.md (artesanato de micro-polimento, maioria dos itens web-only)	token.md (preenchimento de nome), ux-rules.md
ip / ip-handbook	product-reasoning.md	content-guide.md

Meta-regras: rules-priority.md e philosophy.md são camadas de julgamento em todas as fases, têm precedência sobre documentos de fase específica em caso de conflito; lifecycle.md é o diagrama geral de todo o ciclo de vida (sete estágios × portadores × pontos de verificação); theory-router.md é a camada auxiliar de julgamento teórico (classificação automática + pacote de modelo teórico por estágio + condições de gatilho + regras compostas), carregue sob demanda quando qualquer estágio precisar usar modelo teórico para raciocinar/atribuir/persuadir, sua camada detalhada design-theory-models.md deve ser consultada apenas por âncora, não lida completamente; llm-behavior.md deve ser lido ao produzir documentos longos com mais de 2 telas.

Geral

• Não tem certeza de qual usar? Primeiro design-md. Sem DESIGN.md, não é possível produzir tokens rígidos confiáveis no draw-md, muito menos adaptação de framework.
• Cadeia de fluxo completo (cada output = input do próximo): design-md (→.maliang/DESIGN.md) → draw-md (→.maliang/ui-markdown/.md) → preview (→.maliang/preview/preview_.html) → critique (→ instantâneo de pontuação) → draw-harmony/draw-flutter/draw-element (→ código do framework); iteração retorna ao livro-razão de decisões via redesign/ui-graph.
• Especificações de dimensões (cor / fonte / imagem / espaçamento / canto / linha / layout / alinhamento / elevação) estão em references/dimensions/ (incluindo bibliotecas de paletas de cores color-palettes, sistemas de design de referência design-systems, receitas de vidro líquido glass-effect/glass-advanced, orçamento de textura texture (um grupo de textura por página / tokenização de transparência), elevação de superfície elevation, eixo de alinhamento/mesma linha mesma altura/relação de protrusão alignment, contrato de contêiner de página específica para H5 em h5-frame); princípios de design em references/meta/principles.md, compartilhados pelos treze subcomandos, não repetidos neste roteador. Seis falhas mecânicas de página de desktop para mobile em references/meta/mobile-floor.md.
• Parede de templates em references/templates/: 14 linguagens de design (vidro líquido/M3 Expressive/Fluent 2/Bento/editor suíço/escuro OLED/dashboard de dados etc.) + modos de página inteira (colunas de editor/corredor profundo/coleção de estilos de Dashboard/cinco tipos de mobile/faixa de rolagem/Workbench de IA) + orquestração de landing page + cartão de direção de personalidade; seleção segue roteiro de quatro passos do README + variation-engine combinação de sete eixos + memória de construção entre projetos (build-log + carimbo CSS, ≥5 eixos iguais significa re-seleção).
• Template de esqueleto de entrega em template/: esqueleto de DESIGN.md / esqueleto de página ui-markdown / contrato de prompt IP / registro de teste A11y, copie e preencha — a forma literal canônica única de cada esqueleto está em seu arquivo, regras de preenchimento e verificação nos documentos de subcomando correspondentes; divisão de trabalho com a parede de templates (referência de seleção vs ponto de partida para salvamento) veja template/README.md.
• Banco de termos em references/glossary/ (arquivo INDEX.md + termo por arquivo: design token / layout de página / operação de usuário / interação / dispositivo /...); ao ler documentos meta, quando um termo não é familiar ou o contexto é ambíguo, primeiro verifique o glossário. A saída do subcomando pode usar definições do glossário em vez de explicações longas (única fonte na primeira ocorrência do conceito); a opção --no-glossary impede a inserção de referências curtas.
• Saltos específicos de stack em references/stacks/: mapa de armadilhas e características do ecossistema de cada stack (Veact/Next/Vite/Gulp), cada entrada com seções de "O que funciona" / "O que não funciona" / "Padrões comuns"; carregue para o stack atual ao usar draw-*.
• Bibliotecas de cores de sistemas de design conhecidos em references/colors/: Material 3, Fluent 2, Apple HIG, shadcn/ui, Primer (GitHub), Polaris (Shopify), Spectrum (Adobe), Paste (Twilio) e distinct-company-colors (paleta de cores de empresas notáveis do mundo real sem sistema de design aberto, para referência de análise de concorrência); estruturas de token DTCG em references/colors/dtcg/.
• Restrições de geração de código: todos os draw-* (exceto draw-md) devem carregar references/meta/polish-craft.md antes de gerar código. Esta especificação documenta mais de 40 itens de micro-polimento de código front-end (efeito cascata de animação, feedback tátil, restauração de foco, dithering de sombra, etc.) — cada subcomando draw-* pode verificar itens específicos do framework após a geração principal.
• Estrutura de saída padrão: todos os artefatos gerados pelo skill (DESIGN.md, ui-markdown, preview HTML, código, instantâneo de pontuação, imagens IP, manual visual) são salvos dentro do diretório .maliang/ no projeto do usuário. Não toque em arquivos fora de .maliang/ sem instrução explícita do usuário.
• component gera uma especificação de componente independente, aceita style / shape / size três modificadores; modo de modificador multi-valor separado por espaço; "8 estados obrigatórios" para componente individual (normal/hover/pressionado/desabilitado/foco/selecionado/ativo/modo escuro).
• Orçamento estrito de tamanho de arquivo: o limite de draw-md não deve exceder 800 linhas por página. Use tabelas, estilos embutidos e importação de token razoavelmente. Quando uma página ultrapassar o limite, divida: layout principal em página pai, sub-elementos em subpáginas referenciadas por caminho relativo.
• Disciplina de referência visual: Cada especificação de página draw-md desktop deve vir com um layout mobile de referência (especificação de layout mobile em referência mobile.md ou mobile.spec.svg; se não existir, adicione uma especificação em anexo). draw-md mobile deve ser carregado explicitamente. Elementos não ajustados para mobile na especificação desktop serão considerados com problemas.

• Orçamento de Textura

Este skill segue uma disciplina de orçamento de textura de "um grupo de textura por página": use exatamente um grupo de textura visual coerente por página (vidro líquido / ruído / gradiente / borda /...). O grupo de textura escolhido deve permear todos os elementos da página (fundo, cartão, botão, entrada, etc.). Tabela de alocação de grupos de textura disponíveis, veja references/dimensions/texture/; a opacidade da camada de textura é tokenizada. Preencha texture_group no YAML do draw-md.

Ambiente de Execução

Pré-requisitos

Ferramentas

Variáveis de Ambiente

Dependências

Estrutura de Diretórios

Gerenciamento de Estado