Arena

Arena: a linguagem do sistema de design Arena, servida a um agente como recursos e ferramentas MCP, em React ou Angular, conforme o projeto instalado.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Arena by Dravensoft

Um design system, em React e em Angular, a partir de um único contrato.

npm react npm angular downloads license build

Licença MIT · Design system orientado a tokens para React, Angular e Tailwind.

One ArenaButton drawn under three style plugins, with the API and behaviour contracts pointing at it and an agent reading the whole thing

O que você obtém

Componentes com uma API contratada. Os mesmos componentes sob ambos os nomes de framework, renderizando os mesmos pixels, sobre uma camada Tailwind compartilhada. Como um membro é chamado, o que ele aceita, qual é seu padrão e o que significa estão escritos em contracts/api/, e os tipos e tabelas de cada camada são gerados a partir daí, para que as duas camadas não possam divergir silenciosamente. Todo valor que um componente desenha é resolvido por meio de um token de design, então nenhum hex e nenhum pixel puro fica em qualquer lugar dentro dele.

Acessibilidade vinculada por componente, em vez de auditada por versão. Cada componente declara qual padrão implementa, a maioria deles das Práticas de Autoria WAI-ARIA: os papéis que carrega, as teclas às quais responde, onde o foco pousa, o que o dispensa. Um requisito que ainda não atende é registrado ao lado dele com sua razão, e bun run check:behaviour falha no dia em que um componente deixa de responder ao padrão que nomeou.

Um núcleo de estilo, que é o que um projeto responde para parecer consigo mesmo. As perguntas sobre forma, espaço, peso e profundidade são da Arena; as respostas são um plugin de estilo que o projeto escreve, e a aparência que a Arena instala é um desses plugins, em vez de um piso sob eles. Paletas e fontes ficam em um arena.config.json, que o comando arena-to-prod que cada pacote envia transforma na única folha de estilo que um pacote não pode carregar: A Arena carrega a linguagem e nunca a pele, e nenhuma de suas próprias cores chega ao seu build.

Metadados para um produto que precisa ser encontrado, o que a maioria dos produtos não precisa. A camada Angular escreve o documento <head> a partir das rotas que recebe, em @dravensoft/arena-angular/metadata: composição de título, uma descrição, um canônico e o par og:*, sem que nenhuma rota seja indexada até que ela diga isso. Esse caminho de importação é um segundo ponto de entrada, então um projeto que nunca pede metadados nunca instala o roteador por trás dele. React não escreve <head> nenhum, e ambas as camadas publicam a trilha de navegação que desenham em termos de schema.org.

Oito produtos, desenhados duas vezes

Os bancos de teste são um conjunto de modelos que implementam Arena: Calendly, ClickUp, Duolingo, Etsy, Grafana, Instagram, Notion e Superhuman, cada um simulado duas vezes, uma em React e uma em Angular, a partir de um diretório arena.config.json e um design/ por par. Cada metade instala a Arena do npm e responde a um plugin de estilo próprio, então o que um par mostra é a aparência de um projeto, em vez da Arena, e as duas metades de um par são a mesma tela sob ambos os nomes de framework. Esse endereço é onde eles rodam, e dravensoft-dev/arena-web-benches é onde eles são escritos.

Por que um agente pode operá-lo

Uma API é um arquivo de contrato em vez de um parágrafo, e assim também é o padrão que um componente vincula e o papel que um plugin de estilo responde; um portão segura o código, a documentação e os pacotes publicados para eles. Um agente que recebe este repositório não adivinha a Arena: ele lê o contrato que governa o que está prestes a escrever, e o portão diz a ele quando errou.

Isso também é o que torna as regras aplicáveis em vez de aspiracionais. Cada uma delas é decidida em contracts/design/AGENTS.md e entregue a um construtor por skills/design/SKILL.md, que declara cada uma por extenso e diz quais delas um portão lê em seus próprios fontes.

  • Tokens são a única camada de estilo.
  • Não coloque classe própria em um componente da Arena.
  • Perigo é contorno, nunca preenchido.
  • Um acento primário por visualização.
  • Sem gradientes, em nenhuma superfície.
  • Sem emoji, no produto ou no texto.
  • Ícones são strings de classe do Phosphor, nunca elementos e nunca SVG.
  • Nunca envolva um componente da Arena no link do seu próprio roteador.
  • Uma âncora que a Arena desenha divide suas ativações.
  • Uma pressão que começa em um controle permanece nesse controle.
  • Dois temas, escuro primeiro.
  • Um gráfico carrega identidade ou significado, nunca ambos.
  • O texto é formal e direto, no idioma do produto.
  • Um membro obrigatório ausente é um bug do chamador.
  • Nenhuma renderização decorre de você ter vinculado um ouvinte ou preenchido um slot.
  • Alguns componentes respondem com um método em vez de um membro.

Instalação

bun add @dravensoft/arena-react     # or @dravensoft/arena-angular

Essa é a instalação completa. Phosphor é um peer em vez de um segundo comando, porque a Arena renderiza nomes de classe de ícones e nunca SVG; a página da camada abaixo diz quais peers cada pacote declara.

Depois escreva arena.config.json, execute npx arena-to-prod (ou bunx, ou pnpm exec), e importe o que ele escreve. frameworks/react/PACKAGE.md e frameworks/angular/PACKAGE.md são tudo isso, e são as páginas que o npm mostra.

Via MCP

{
  "mcpServers": {
    "arena": { "command": "npx", "args": ["-y", "@dravensoft/arena-mcp"] }
  }
}

@dravensoft/arena-mcp é onde a linguagem viaja. Ele serve o roteador, as referências e cada documento de componente a um agente que fala o Model Context Protocol, como recursos e como ferramentas, e a camada que ele serve é a que seu projeto instalou. Os pacotes de componentes carregam o código, as folhas de estilo e os contratos aos quais seu próprio markup responde, e nenhuma da prosa.

Um corpus e os componentes que ele descreve são dois pacotes e dois números de versão, então eles podem discordar. arena_start lê a versão do pacote da Arena no seu projeto, compara com a do servidor e diz quando os dois diferem. Onde diferem, os componentes estão certos e o texto está antigo.

Como plugin do Claude Code

/plugin marketplace add dravensoft-dev/arena
/plugin install arena@dravensoft
/reload-plugins

Atualização

/plugin marketplace update dravensoft   # refresh the catalog: learns a new version exists
/plugin update arena@dravensoft         # update the plugin you actually have
/reload-plugins                         # apply it to the running session

Uma versão significa um commit. Cada versão é servida a partir de sua tag git, com a entrada do marketplace fixando source.ref em vX.Y.Z.

Como Skill de Agente autônoma

Entregue a qualquer agente skills/design/SKILL.md. É o roteador, e responde a cada pergunta com um arquivo. Ele roteia sobre esta árvore, então um agente que recebe o arquivo sozinho tem as perguntas e alcança as respostas por URL; um que recebe o clone ou o plugin as alcança por caminho.

Um pacote de componente é código, e a linguagem alcança um agente por uma das três rotas acima. Instale o servidor MCP, instale o plugin ou entregue a skill, e o agente obtém as diretrizes, os contratos e o documento de uso de cada componente, que é o que transforma "integrar Arena" em uma tarefa que ele conclui sozinho.

Veja

arena.dravensoft.org carrega as diretrizes de design, a pia de cozinha e uma página de playground para cada componente, sem clone e sem nada para instalar.

As mesmas páginas aparecem localmente com bun run demos, a partir da mesma lista, e scripts/build/AGENTS.md diz o que um clone novo precisa construir antes que elas signifiquem algo.

Um agente lê llms.txt primeiro, que roteia para as regras da linguagem e depois para um corpus por framework, React e Angular. Eles são separados de propósito: cada componente é enviado sob ambos os nomes e os dois documentos não são intercambiáveis.

Dependências

  • Fontes são auto-hospedadas, e nenhuma solicitação de CDN é feita. A Arena envia os binários Archivo / Familjen Grotesk / Spline Sans Mono .woff2 em assets/fonts/, e contracts/design-generated/fonts.generated.css os declara com @font-face, então eles carregam da mesma origem que a página que os lê. Um consumidor de pacote nomeia suas próprias três famílias em arena.config.json, onde src é uma URL de folha de estilo ou um binário que ele hospeda.
  • Ícones são Phosphor Icons (MIT), e não são empacotados. Instale o pacote oficial por padrão, seja @phosphor-icons/web (webfont) ou @phosphor-icons/react, para peso total e flexibilidade de tree-shaking. O CDN é uma conveniência apenas para protótipos, não o padrão. Veja Iconografia.

Qual versão estou obtendo

Os dois pacotes e o plugin nem sempre carregam o mesmo número, porque um pacote publica apenas quando algo que ele envia mudou. .github/workflows/AGENTS.md explica o que isso significa para uma atualização.

Artefatos de projeto mais recentes

Para onde ir a seguir

Qual é este trabalho? Os dois públicos leem conjuntos quase disjuntos desses arquivos, e começar no ramo errado é como uma pergunta curta vira uma leitura longa.

Construindo algo com a Arena. skills/design/SKILL.md é o roteador. A partir dele: frameworks/INDEX.md é cada componente em uma leitura e frameworks/<layer>/INDEX.md é a mesma lista sob os nomes do seu próprio framework, o .prompt.md de cada componente é como usar aquele, e frameworks/react/PACKAGE.md ou frameworks/angular/PACKAGE.md é como instalá-lo.

Trabalhando na própria Arena. AGENTS.md é a raiz desse ramo, e tudo abaixo é alcançado através dele.

  • scripts/build/AGENTS.md: compile a Arena pela primeira vez, ou seja, o que uma máquina já precisa carregar, o que um clone novo deve construir antes que bun run demos ou bun run check signifiquem algo, e por que alguns arquivos gerados são rastreados e outros não. Linux e macOS são as duas plataformas suportadas; no Windows, o caminho suportado é WSL2, com o clone no sistema de arquivos Linux.
  • frameworks/PACKAGING.md: o canal npm, ou seja, como os dois pacotes são montados a partir da árvore no lugar, por que uma Arena publicada não carrega pele, e o que o consumidor declara em vez disso.
  • contracts/AGENTS.md: os três níveis de contrato da Arena, e um mapa de tudo neste repositório.
  • contracts/design/AGENTS.md: a especificação de design normativa, cobrindo voz, tipografia, cor, espaçamento, movimento, a convenção de perigo, iconografia e temas. contracts/design/TokenTypes.md ao lado carrega o mapa de tipos de token DTCG, para quem autorar um token.
  • frameworks/react/AGENTS.md: a camada React.
  • frameworks/angular/AGENTS.md: a camada Angular, cuja própria última seção entrega a adoção à página do pacote acima.
  • frameworks/tailwind/AGENTS.md: a camada Tailwind compartilhada.
  • frameworks/demos/AGENTS.md: o fixture por trás da página de playground de cada componente, que é a única parte dessa página que alguém escreve.
  • DOUBTS.md: o que conta como dívida na Arena, e onde os registros vivem.

Contribuindo e segurança

A Arena aceita pull requests de qualquer pessoa. CONTRIBUTING.md diz quais mudanças vão direto para uma e quais começam como uma proposta, e o que uma mudança não pode quebrar. SECURITY.md é para onde uma vulnerabilidade vai, e CODE_OF_CONDUCT.md é o Contributor Covenant ao qual este projeto se mantém.

Sobre

A Arena é a linguagem de interface única sob a qual cada produto de software da Dravensoft é construído, publicada sob a Licença MIT para que qualquer outra pessoa também possa construir sob ela.