Bolio UI: componentes React que a IA realmente entende

A Bolio UI é uma biblioteca de componentes React que eu mantenho, o @bolio-ui/core. Ela tem botões, inputs, modais, grid, toasts, hooks e um tema com modo claro e escuro, tudo exportado de forma separada pra que o bundle só leve o que você de fato usa. A documentação fica em bolio-ui.com.

Nos últimos meses a maior parte do trabalho foi em duas frentes: deixar a biblioteca compatível com o React e o Next atuais, e fazer ela funcionar bem quando quem escreve o código é um assistente de IA.

Usando em um projeto

A instalação é a de sempre:

npm i @bolio-ui/core

Depois você importa o CSS uma vez e envolve o app com o provider:

import "@bolio-ui/core/styles.css";
import { BolioUIProvider, CssBaseline, Button } from "@bolio-ui/core";
 
export default function App() {
  return (
    <BolioUIProvider>
      <CssBaseline />
      <Button>Clique aqui</Button>
    </BolioUIProvider>
  );
}

A versão 3 saiu do styled-jsx e passou a usar CSS Modules no core, e a compatibilidade com React 18 e 19 e com Next 14, 15 e 16 é testada em uma matriz de builds a cada mudança. Também tem CLI pra iniciar um projeto: npx @bolio-ui/cli@latest init.

O problema: assistente chutando props

Quem usa Claude Code, Cursor ou Windsurf já viu isso. Você pede um formulário com a sua biblioteca, e o assistente escreve um código bonito, com props que parecem certas e não existem. Ele nunca leu a documentação, só lembra de algo parecido de outra biblioteca.

A correção não é um prompt melhor. É dar ao assistente um jeito de ler a documentação real. Foi isso que eu fiz, e hoje cada componente, hook e guia da Bolio UI é publicado também como Markdown, com quatro formas de conectar o assistente a ele.

1. LLMs.txt

O llms.txt é um arquivo na raiz do site que lista todas as páginas da documentação. Tem quatro versões:

• llms.txt: o índice de todas as páginas
• llms-full.txt: a documentação inteira em um arquivo só
• llms-components.txt e llms-guide.txt: versões menores, pra quando a janela de contexto é apertada

Você passa a URL de qualquer um deles pro assistente e ele lê direto. Cada página também tem um botão de copiar como Markdown, e dá pra abrir qualquer uma em bolio-ui.com/md/components/button, por exemplo.

2. Servidor MCP

O @bolio-ui/mcp é um servidor MCP que dá ao assistente cinco ferramentas: listar componentes, listar hooks, ler a documentação de um componente, ler os tokens do tema claro e escuro e ler qualquer página. Precisa de Node 18 e não pede chave de API.

No Claude Code, a instalação é uma linha:

claude mcp add bolio-ui -- npx -y @bolio-ui/mcp@latest

A diferença pra colar o llms.txt é que o assistente consulta só o que precisa, na hora que precisa, em vez de carregar tudo no contexto.

3. Agent Skill

A Skill ensina ao assistente o setup e as regras da biblioteca: abrir a página do componente antes de usar, importar sempre de @bolio-ui/core, nunca copiar código de componente e pegar cores do tema em vez de escrever hexadecimal no código. Instala assim:

npx skills add bolio-ui/bolio-ui

4. AGENTS.md

Esse é o mais simples. Um comando adiciona os links da documentação no AGENTS.md do seu projeto, que é o arquivo que vários assistentes leem sozinhos ao abrir o repositório. Rodar de novo só atualiza a seção:

npx @bolio-ui/cli@latest agents-md

Qual usar

Se você quer testar rápido, cole a URL do llms.txt na conversa. Se usa Claude Code todo dia, o MCP é o que mais compensa. A Skill e o AGENTS.md servem pra que o assistente já comece o projeto sabendo as regras, sem você repetir.

Dá pra usar os quatro juntos, não um atrapalha o outro.

Escala e espaçamento

Junto com isso saiu um guia novo, o de escala e espaçamento, que explica as props width, padding, margin e scale, aceitas por todos os componentes. É o tipo de página que o assistente precisa ler, porque é onde mais se erra tamanho e espaçamento.

Por onde começar

O guia principal do fluxo com IA está em bolio-ui.com/docs/guide/llms-txt. E se o seu assistente escrever algo errado com a Bolio UI, abre uma issue no GitHub. Esse erro quase sempre aponta uma página da documentação que precisa ficar mais clara, e é assim que ela melhora.