Para agents
Markdown cru, llms.txt, o servidor MCP e como pedir no prompt.
Boa parte do código que usa esta biblioteca hoje é escrita com um agent ao lado. Um site que só serve HTML obriga o agent a adivinhar a API a partir do nome, e ele adivinha com confiança, o que é pior do que errar em silêncio.
Por isso tudo aqui existe também em markdown cru.
Antes de tudo: instale a skill
Ler markdown cru resolve a conversa de hoje. A skill resolve todas: ela fica no disco do projeto, viaja no Git com a equipe e vem na versão da biblioteca que o projeto de fato tem.
npx rivocode-ui skill # Claude Code
npx rivocode-ui skill --para codex # ou copilot, gemini, cursor, todos
Se você é um agent lendo esta página para montar uma tela, este é o primeiro
comando a rodar, com o --para da ferramenta em que você roda. A skill é uma
só, no formato aberto do SKILL.md; o --para escolhe a pasta onde ela entra
(.claude/skills/ no Claude Code, .agents/skills/ nas outras) e o arquivo de
instruções que leva o método do agente (.claude/agents/, AGENTS.md,
.github/copilot-instructions.md, GEMINI.md ou a regra do Cursor). O guia
Skill tem a tabela inteira, as variantes por gerenciador de pacote
e a instalação por curl, para quando não há nenhum.
O servidor MCP
Para o agent que fala MCP, o
@rivocode/ui-mcp entrega o mesmo material por ferramentas: ele pede a peça
certa para uma intenção, lê a página dela e confere o token, sem sair da
conversa. Roda na sua máquina, pelo stdio, e não abre conexão de rede: a
documentação viaja dentro do pacote.
O pacote é privado e mora no GitHub Packages, e o npx que sobe o servidor
precisa achar o escopo num .npmrc. O do projeto basta quando a ferramenta
roda o servidor na pasta do projeto, como o Claude Code faz. Com --global, ou
numa ferramenta que rode o servidor de fora do projeto, as mesmas duas linhas
vão no ~/.npmrc:
@rivocode:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${RIVOCODE_NPM_TOKEN}
O RIVOCODE_NPM_TOKEN é um token pessoal do GitHub com read:packages, passado na
configuração do servidor. No Claude Code:
claude mcp add rivocode-ui -e RIVOCODE_NPM_TOKEN=ghp_seu_token -- npx -y @rivocode/ui-mcp
Em quem lê a configuração em JSON com mcpServers (Claude Desktop, Cursor,
Gemini CLI, Copilot CLI, Windsurf):
{
"mcpServers": {
"rivocode-ui": {
"command": "npx",
"args": ["-y", "@rivocode/ui-mcp"],
"env": { "RIVOCODE_NPM_TOKEN": "ghp_seu_token" }
}
}
}
| Ferramenta | O que devolve |
|---|---|
list_components |
o catálogo por família, uma linha por peça |
get_component |
a página inteira de uma peça: exemplos, props, quando não usar, React Native |
search_docs |
busca em toda a documentação, sem acento |
recommend_component |
as peças candidatas para uma intenção de tela, com o motivo e as vizinhas |
get_tokens |
papéis de cor, escalas, densidade e movimento, e o JSON DTCG cru |
get_native_parity |
como a peça fica no React Native, prop a prop |
get_guide |
as convenções e cada guia, inclusive as referências da skill |
audit_screen |
a auditoria de uma tela pronta, com nota de 0 a 100 (a mesma da skill de auditoria, abaixo) |
O pacote sai com a documentação da versão da biblioteca em que foi gerado, e toda resposta diz qual é. A skill e o servidor não competem: a skill fica no disco do projeto e ensina o método; o servidor responde a pergunta pontual no meio do trabalho.
Em cada ferramenta
O servidor é o mesmo em todas: npx -y @rivocode/ui-mcp, pelo stdio. O que
muda é o arquivo e o nome da chave.
| Ferramenta | Arquivo do projeto | Arquivo pessoal | Chave |
|---|---|---|---|
| Claude Code | .mcp.json |
claude mcp add --scope user |
mcpServers |
| Cursor | .cursor/mcp.json |
~/.cursor/mcp.json |
mcpServers |
| VS Code e Copilot | .vscode/mcp.json |
~/.copilot/mcp-config.json (Copilot CLI) |
servers no VS Code, mcpServers no Copilot CLI |
| Codex | .codex/config.toml (só em projeto confiável) |
~/.codex/config.toml |
[mcp_servers.<nome>] |
| Gemini CLI | .gemini/settings.json |
~/.gemini/settings.json |
mcpServers |
| Windsurf | — | ~/.codeium/windsurf/mcp_config.json |
mcpServers |
O npx rivocode-ui skill --para <ferramenta> --mcp escreve o arquivo do
projeto (ou o pessoal, com --global) das cinco primeiras, sem apagar os outros
servidores que estiverem lá, e sem token nenhum: o token fica no ambiente, e o
.npmrc só carrega o nome da variável. Arquivo com comentário, como o .vscode/mcp.json às vezes tem, ele
não reescreve, e diz para acrescentar à mão.
No VS Code, a chave é servers e cada servidor leva o type:
{
"servers": {
"rivocode-ui": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@rivocode/ui-mcp"],
"env": { "RIVOCODE_NPM_TOKEN": "ghp_seu_token" }
}
}
}
No Codex, é TOML:
[mcp_servers.rivocode-ui]
command = "npx"
args = ["-y", "@rivocode/ui-mcp"]
env = { RIVOCODE_NPM_TOKEN = "ghp_seu_token" }
Cursor, Copilot CLI, Gemini CLI e Windsurf usam o JSON com mcpServers acima.
Auditar uma tela pronta
A skill rivocode-ui ensina a montar. A rivocode-ui-audit confere o que já
foi montado: dada uma pasta ou os arquivos de tela de um app que usa o
@rivocode/ui ou o @rivocode/ui-native, ela devolve um relatório com os
achados, arquivo e linha, e uma nota de 0 a 100.
dir=$HOME/.claude/skills/rivocode-ui-audit && mkdir -p "$dir/scripts" && \
curl -fsSL https://ds.rivocode.com.br/skill-auditoria/SKILL.md -o "$dir/SKILL.md" && \
curl -fsSL https://ds.rivocode.com.br/skill-auditoria/scripts/audit.mts -o "$dir/scripts/audit.mts"
Trocando $HOME/.claude por .claude ela entra só no projeto. Depois, peça ao
agent "audite as telas de src/pages", ou rode o script você mesmo:
bun ~/.claude/skills/rivocode-ui-audit/scripts/audit.mts src/pages
O script não tem dependência, e o .mts roda também no Node 23.6 ou mais novo, mesmo em projeto commonjs, ou com
npx tsx em qualquer Node. --json troca o relatório por JSON e --minimo 85
sai com código 1 abaixo da nota, para barrar na CI.
A auditoria tem duas metades, e a nota sai das duas pela mesma conta. O
script acha o que se acha sem opinião: cor literal, z-index numérico, peça
reescrita à mão (<button> no lugar de Button, <input type="checkbox"> no
lugar de Checkbox, o modal caseiro no lugar de Dialog), IconButton sem
label, Field sem FieldLabel, texto de tela sem acento ou em inglês,
formulário sem useZodForm, dinheiro em parseFloat, CPF e CNPJ sem
isValidCpf e isValidCnpj, QR e Pix feitos à mão, importação pelo caminho
errado e o peer do subcaminho que falta no package.json. O agent lê as telas
e escreve o que só se decide entendendo o que elas fazem — a peça errada para a
situação, o texto que não diz o que acontece, a validação feita com useState
—, num JSON que o script lê de volta.
A nota é determinística: mesma entrada, mesma nota. Cada regra pesa pela severidade (crítico 10, sério 5, moderado 3, menor 1), e a mesma regra conta no máximo três vezes por arquivo. A nota do arquivo é 100 menos a soma; a nota final é a média dos arquivos menos o que vale para o app inteiro, como o peer faltando. O agent não dá nota: ele acrescenta ou descarta achados, e o descarte aparece no relatório com o motivo.
Quem usa o servidor MCP audita pela ferramenta audit_screen, sem instalar
nada: ela recebe os arquivos, os package.json do app e da raiz e o mesmo JSON de
julgamento, e devolve o mesmo relatório. A skill crua mora em
/skill-auditoria/SKILL.md, e o script em
/skill-auditoria/scripts/audit.mts.
Testar a tela de pé
A rivocode-ui monta e a rivocode-ui-audit julga o código. A
rivocode-ui-teste fecha o laço: ela testa a tela funcionando onde o projeto
roda — no navegador sempre, no Android e no iPhone quando o projeto tem o
@rivocode/ui-native, e o site comparado ao app quando há os dois. Ela mede em
vez de olhar (os bounds do Android, o frame do iPhone, o
getBoundingClientRect e o scrollHeight do navegador), percorre o erro e o
sucesso de cada fluxo e classifica cada achado com arquivo e linha.
O npx rivocode-ui skill já a instala, ao lado da rivocode-ui e da
auditoria. Sem o pacote:
dir=$HOME/.claude/skills/rivocode-ui-teste && mkdir -p "$dir/reference" "$dir/scripts" && \
curl -fsSL https://ds.rivocode.com.br/skill-teste/SKILL.md -o "$dir/SKILL.md" && \
for f in reference/android reference/armadilhas reference/iphone reference/metodo reference/regras reference/roteiro-modelo reference/web; do \
curl -fsSL "https://ds.rivocode.com.br/skill-teste/$f.md" -o "$dir/$f.md"; \
done && \
for f in scripts/droid.py scripts/ios.py scripts/medir.js; do \
curl -fsSL "https://ds.rivocode.com.br/skill-teste/$f" -o "$dir/$f"; \
done
Depois, peça ao agent "teste a tela de cadastro no navegador e no Android". Os
fluxos de cada app moram em .rivocode/roteiro-de-teste.md, na raiz do
projeto: a skill o lê antes de começar, e traz o modelo. O Android vai pelo
adb, o iPhone pelo simulador com o idb da Meta, e o navegador pelo Claude
in Chrome ou outra ferramenta que leia a página e rode JavaScript.
Os endereços
| Endereço | O que entrega |
|---|---|
/skill/SKILL.md |
a skill crua, para ler sem instalar |
/skill-auditoria/SKILL.md |
a skill de auditoria, com o script em /skill-auditoria/scripts/audit.mts |
/skill-teste/SKILL.md |
a skill de teste da tela de pé, com as referências em /skill-teste/reference/ e os scripts em /skill-teste/scripts/ |
/llms.txt |
o índice no formato de llmstxt.org, por família, com uma linha sobre cada documento |
/llms-full.txt |
tudo num arquivo só: convenções, guias, padrões e cada peça |
/componentes/<nome>.md |
o documento de uma peça: prosa, importação, exemplos, props e React Native |
/<guia>.md |
um guia, como /temas.md |
/padroes/<nome>.md |
um padrão de UX, como /padroes/salvar.md: o mesmo arquivo de reference/ da skill |
/convencoes.md |
o contrato da biblioteca: Provider, tokens, vocabulário |
O nome no endereço é o mesmo da página: ToggleGroup mora em
/componentes/toggle-group, e o markdown dele em
/componentes/toggle-group.md.
Na página de cada peça, o botão Copiar como Markdown põe esse mesmo documento na área de transferência, para colar na conversa com o agent.
São os mesmos arquivos que as páginas renderizam. Não há uma segunda cópia para manter, o que você lê como agent é o que a página mostra.
No prompt
O caminho mais curto é mandar o contrato junto com a peça que interessa:
Leia https://ds.rivocode.com.br/convencoes.md e
https://ds.rivocode.com.br/componentes/data-table.md e monte uma listagem de
notas com os estados de carregando, erro e vazio.
Para trabalho maior, o índice primeiro:
Comece por https://ds.rivocode.com.br/llms.txt e leia o que precisar.
Para agent com contexto de sobra e sem acesso à rede depois do primeiro fetch, o arquivo inteiro de uma vez:
Leia https://ds.rivocode.com.br/llms-full.txt antes de começar.
De onde isso vem
Os documentos não foram escritos para o site. Eles nasceram para o sync com o
claude.ai/design, onde um agent monta telas com estas peças, e por isso já
respondem o que um agent pergunta: para que serve, quando não usar, e qual
a diferença para a peça parecida do lado.
O padrão não é nosso: a própria Base UI envia a documentação inteira dentro do
pacote, em node_modules/@base-ui/react/docs/. Foi assim que o Sheet desta
biblioteca foi construído sem chutar API.