Plugin Claude Code

O makuco-ui é um plugin de Claude Code para o Makuco UI em repositórios consumidores do DB1 Group, com três comandos:

• /flow — mapeia um fluxo de usuário: traduz uma descrição em texto num diagrama PlantUML renderizado em SVG. Não resolve componentes nem gera código — é planejamento visual, standalone ou antes de um /design.
• /design — construção assistida: cria telas e formulários novos, a partir de um link do Figma, de uma descrição em texto, ou de um fluxo do /flow.
• /adopt — adoção assistida: escaneia o projeto, avalia cobertura e migra UI existente — componente a componente ou por arquivo/pasta — sempre UI-only, nunca reescrevendo regra de negócio ou estado.

/adopt e /design compartilham o mesmo MCP (makuco-ds), a mesma preparação de repositório e o mesmo conhecimento de wiring de campos de formulário — o que muda é a direção: /adopt traduz código que já existe, /design escreve código que não existia. /flow é independente dos dois, mas seu output pode alimentar o /design (ver Usando o fluxo como fonte do /design).

Conteúdo

• Instalação
• Instalação automática por repositório
• /flow — mapear um fluxo de usuário
• /design — construir telas e formulários novos
• /adopt — migrar UI existente
• Campos de formulário — compartilhado entre /adopt e /design
• Erro 401/403 ao instalar

Instalação

No Claude Code, adicione o marketplace do Makuco UI e instale o plugin:

/plugin marketplace add https://design.makuco.com.br/claude/marketplace
/plugin install makuco-ui@makuco-ui

O marketplace é servido como um JSON estático por este site — adicioná-lo não exige acesso ao repositório do design system. Quem só tem acesso de leitura ao feed npm da empresa (não ao repositório) consegue instalar normalmente.

O plugin registra automaticamente o MCP makuco-ds (veja MCP) — a fonte de verdade sobre a API dos componentes.

Instalação automática por repositório

Pra não depender de cada pessoa rodar /plugin marketplace add manualmente, é possível commitar a configuração no .claude/settings.json do repositório consumidor:

{
  "extraKnownMarketplaces": {
    "makuco-ui": {
      "source": {
        "source": "npm",
        "package": "@db1/makuco-ui-plugin",
        "registry": "https://db1global.pkgs.visualstudio.com/_packaging/makuco/npm/registry/"
      }
    }
  },
  "enabledPlugins": {
    "makuco-ui@makuco-ui": true
  }
}

Ao abrir o repositório no Claude Code, a pessoa é convidada a confiar na pasta do projeto — uma vez aceito, o plugin fica disponível sem mais nenhum passo manual.

/flow — mapear um fluxo de usuário

/flow <descrição do fluxo> [--nome=<slug>]

/flow quero que o usuário entre, digite e encontre o produto que bate com a descrição

O comando lê a descrição, extrai passos/decisões/telas distintas, monta um diagrama de atividade PlantUML e renderiza o SVG. Os artefatos ficam em .makuco-ui/flows/<slug>/flow.puml e flow.svg. Rodar de novo com o mesmo --nome é iteração — ajusta o fluxo existente em vez de recomeçar.

Escopo

• Vocabulário de passos/decisões/telas — nunca de componentes. Resolver pra mk-* é escopo do /design.
• Não inventa passos ou decisões alheios à descrição. Descrição insuficiente → pergunta objetiva.
• Se o fluxo tiver mais de uma tela/etapa, o comando pode sugerir que cada uma vire uma invocação de /design depois — nunca invoca automaticamente.

Usando o fluxo como fonte do /design

/design --from-flow=<slug-do-flow>[:<nome-da-partition>]

/design lê o flow.puml direto e traduz os passos da partition escolhida em componentes mk-*. Se o .puml tiver mais de uma partition (tela) e você não especificar qual, o comando pergunta antes de montar o plano — nunca compõe várias telas numa invocação só. if/else dentro da partition escolhida (sem partition própria em cada ramo) viram estados alternativos da mesma tela (ex.: lista vazia vs. lista com resultados); ramos com partition própria são telas diferentes, listadas no plano como próximas invocações possíveis.

/design — construir telas e formulários novos

/design <link-do-figma | descrição da tela>
/design form <link-do-figma | descrição do formulário>
/design --from-flow=<slug-do-flow>[:<nome-da-partition>]

/design https://figma.com/design/abc123/App?node-id=42-7
/design uma tela de listagem de pedidos com filtro por status e paginação
/design form cadastro de cliente com nome, e-mail, telefone e endereço

O comando prepara o repositório (sem bloquear por versão — construir tela/formulário novo não retrofita nada existente), planeja a composição contra a API real do Makuco (resolvendo Figma, texto, e/ou um fluxo do /flow pra uma árvore de componentes mk-*, com gaps listados) e, depois da sua confirmação, gera o código no framework detectado (React, Angular ou Web Components puro). O plano e o log de geração ficam em .makuco-ui/design/<slug>/.

Escopo

• Telas e formulários novos. Não migra UI existente — pra isso, use /adopt.
• Nunca inventa prop, evento ou tag. Toda API vem confirmada do MCP makuco-ds.
• Lógica de negócio fica de fora. Handlers de submit, chamadas de API, validação de regra de negócio saem como esqueleto/TODO.
• Um escopo por invocação. Uma tela ou um formulário por vez. Sem build/commit automático.

/adopt — migrar UI existente

/adopt

O comando lê o estado em .makuco-ui/ e conduz a próxima fase automaticamente:

Para migrar um componente específico: /adopt Button.

Projetos abaixo do mínimo (React < 18, Angular < 19) são bloqueados por padrão. Pra seguir por conta própria, use --force-eligible (ex.: /adopt --force-eligible Button) — o veredito real de elegibilidade continua registrado, só o bloqueio é sobreposto.

Modo setor — uma página por vez

Sem passar pelo pipeline completo, migra todos os componentes elegíveis dentro de um arquivo ou pasta:

/adopt src/pages/OrderPage.tsx
/adopt src/features/checkout/

A preparação do repositório ainda vale, mas não exige scan/ledger prontos. Ideal para modernizar uma página de forma isolada e revisável (1 PR = 1 arquivo/pasta) sem se comprometer com a jornada completa.

Escopo

• UI-only. Substitui import/tag, remapeia props/eventos, troca valores por tokens --db1-*.
• Nunca toca em handlers, fluxo de dados, stores ou conversão de estado.
• Um escopo por vez (componente em todo o projeto, ou arquivo/pasta com todos os componentes dentro). Sem build/commit automático — a verificação é do usuário.

Campos de formulário — compartilhado entre /adopt e /design

Os 9 componentes de campo (mk-input, mk-select, mk-checkbox, mk-radio, mk-switch, mk-textarea, mk-date-picker, mk-time-picker, mk-color-picker) têm o wiring de estado coberto pela mesma referência interna, usada dos dois lados:

• Ao migrar (/adopt): reconhece um binding existente e aplica o mapeamento mecânico — React controlled/uncontrolled nativo, TanStack Form, Angular Reactive/Template-driven Forms. React Hook Form via register() fica de fora da migração automática (ref-forwarding não verificado) — vai para decisão humana, com a receita de correção (Controller) apontada no TODO.
• Ao criar (/design): escreve o padrão do zero, detectando a convenção já usada no projeto ou perguntando se não houver uma. Aqui Controller do React Hook Form é o padrão de escolha — sem register() legado envolvido, não há o mesmo risco.

Erro 401/403 ao instalar

@db1 é um escopo privado (feed do Azure Artifacts) — não é o npm público. Um 401/403, seja ao instalar o próprio plugin ou ao rodar a preparação do repositório (/adopt ou /design), quase sempre significa que o ambiente não tem o registry do escopo configurado, e não uma falha do pacote:

• Confira se existe .npmrc (npm/pnpm) com @db1:registry=https://db1global.pkgs.visualstudio.com/_packaging/makuco/npm/registry/, ou .yarnrc.yml (Yarn Berry) com um bloco npmScopes.db1 apontando pro mesmo feed.
• Se o arquivo existe mas o erro persiste, confirme que o token de autenticação referenciado nele está de fato definido no ambiente.
• Se ainda assim não resolver, fale com o time Makuco para provisionar o acesso.