Sistema de design Radix Themes.

Tema visual e atmosfera do sistema de design Radix Themes

Uma interface funcional, não um painel de referências

Radix Themes é uma referência útil para produtos em que as pessoas leem, tomam decisões, inserem informações e retomam tarefas inacabadas. O caráter visual vem de espaçamentos bem medidos, superfícies discretas, uma hierarquia tipográfica clara e estados de componentes consistentes. Use este guia para criar um espaço de trabalho de projetos, uma área da conta, uma tela de configurações ou um fluxo de revisão de dados. O objetivo é criar uma tela funcional e coerente, com conteúdo real — não reunir componentes atraentes sem uma tarefa definida.

Escolha o ponto de partida certo

Para um aplicativo React, comece pelo pacote oficial de Radix Themes e use os componentes disponíveis antes de criar substitutos personalizados. Para um conceito visual em outra stack, use estes princípios como referência e descreva o resultado como inspirado no sistema. Radix Themes e Radix Primitives são pontos de partida diferentes: este guia aborda a biblioteca Themes com estilos aplicados. Um guia OpenDesign não transforma uma maquete HTML arbitrária em uma implementação nativa do Radix.

Desenvolva a interface em torno de uma tarefa concreta

1. Escolha uma ação principal para a primeira tela, como criar um projeto ou salvar as configurações da conta.
2. Apresente as informações necessárias para tomar a decisão antes da ação.
3. Diferencie visualmente a navegação, os metadados dos objetos, os campos editáveis e os avisos.
4. Ao projetar, use títulos longos e realistas, diferentes valores de status e um estado vazio.
5. Uma tela que só funciona com três rótulos curtos de exemplo ainda não demonstra um sistema utilizável.

Tom e conteúdo

Use rótulos curtos e descritivos, verbos específicos e explicações diretas. Um botão deve descrever o que acontece em seguida: Salvar alterações, Convidar membro ou Criar projeto. Reserve os títulos para o assunto de uma seção; evite transformar cada pequeno controle em um slogan de marketing. Quando uma ação falhar, explique o que a pessoa pode corrigir e preserve o trabalho dela. Estas são recomendações editoriais de OpenDesign para aplicar a referência, não APIs adicionais fornecidas pelo Radix.

Paleta de cores e funções do sistema de design de Radix Themes

Separe a cor da marca do significado

Use o tema em vez de codificar as telas com valores fixos

A configuração oficial de Theme disponibiliza accentColor e grayColor. Escolha esses valores na raiz para que os componentes compartilhem as mesmas definições. Em componentes personalizados, use as variáveis CSS do tema atual, em vez de copiar uma cor de uma captura de tela. A referência de tokens abaixo lista um subconjunto compacto para uso prático. Um token é uma função dentro de um tema configurado; isso não garante que um valor hexadecimal permaneça igual nos modos claro e escuro e em todas as opções de destaque.

Hierarquia de superfícies e bordas

Comece com um fundo de página discreto. Dê às placas e aos painéis editáveis uma superfície distinta apenas quando agruparem trabalho relacionado. Use divisórias nas linhas que pertencem à mesma lista. Evite aplicar borda, sombra, fundo colorido e selo a cada item ao mesmo tempo. Em uma tela de configurações, um único painel com linhas divididas costuma ser mais claro do que seis cartões flutuantes. Mantenha a hierarquia visível com baixo contraste, sem deixar o texto essencial apagado.

Aparência clara e escura

Use a configuração oficial de aparência para os componentes nativos e confira as duas aparências com o mesmo conteúdo. Não crie uma tela escura simplesmente invertendo as cores ou reutilizando as sombras do modo claro. Verifique individualmente as sobreposições, os campos inativos, as divisórias, as linhas selecionadas e o texto sobre as cores de destaque. O estudo interativo desta página demonstra um pequeno conjunto de opções de tema; o playground oficial é a referência para a biblioteca completa e seu comportamento nativo.

Contraste e sinais redundantes

Confira os pares finais de texto e fundo depois de alterar a cor de destaque ou a superfície. Combine cor e texto em status como Pendente, Concluído e Falhou. Inclua uma marca de seleção ou outra distinção visível nas opções selecionadas. Não presuma que uma biblioteca de componentes acessível torna acessíveis todas as combinações de conteúdo ou tema: seus rótulos, aninhamento, CSS personalizado e ordem das informações também influenciam a usabilidade da tela como um todo.

Regras de tipografia do sistema de design de Radix Themes

Uma hierarquia de leitura intencional

Dê à tela um título claro e, em seguida, diferencie os títulos das seções, o texto do corpo, os rótulos dos campos e os metadados complementares. Use o menor número de tamanhos necessário para explicar essas relações. Em telas de produtos densas, rótulos legíveis são mais importantes do que textos de destaque enormes. Mantenha os parágrafos descritivos próximos dos controles que explicam e deixe os rótulos visíveis mesmo depois que um campo receber um valor. O texto de espaço reservado é uma dica, não substitui o rótulo do campo.

Escala tipográfica e peso

O Radix documenta uma escala tipográfica de nove níveis, com tamanhos de fonte, alturas de linha e espaçamentos entre letras correspondentes. A tabela de referência desta página mantém esses valores na escala base. Escolha um nível como uma combinação completa, em vez de misturá-lo a uma altura de linha sem relação. Use peso regular no texto do corpo e um peso mais forte nos títulos ou rótulos selecionados. Se tudo estiver em negrito, a hierarquia desaparece; se todo o texto secundário for claro demais, fica difícil ler a tela.

Escolha de fontes e alternativas

Radix Themes usa por padrão uma pilha de fontes do sistema. Mantenha essa pilha quando a portabilidade for mais importante do que uma fonte específica da marca, ou configure uma fonte licenciada pelo mecanismo de personalização documentado. O site OpenDesign ao redor usa Albert Sans; isso não torna Albert Sans a fonte oficial do Radix. Em aplicativos multilíngues, teste rótulos representativos em chinês, japonês, coreano e idiomas europeus com palavras longas, usando as fontes alternativas reais.

Números, código e quebra de linha

Mantenha as colunas numéricas alinhadas para que os valores possam ser comparados verticalmente. Use uma fonte monoespaçada para código, identificadores e tokens quando os limites entre caracteres forem importantes. Deixe títulos e descrições quebrarem linha naturalmente; não corte instruções essenciais apenas para manter a altura dos cartões. Para uma sequência que realmente não pode ser quebrada, como um ID, ofereça uma quebra controlada ou uma ação para copiar. Em dispositivos móveis, mantenha todo o conteúdo acessível, mesmo quando o layout mudar.

O comprimento do conteúdo também faz parte do design

Teste um nome de projeto longo, uma função de membro que ocupe duas linhas e uma ação traduzida antes de considerar um componente reutilizável. Sempre que possível, deixe os botões se expandirem, em vez de definir uma largura fixa para todos. Mantenha os parágrafos do corpo em uma largura confortável para leitura e use listas ou tabelas quando a pessoa precisar comparar informações paralelas. Não divida o texto explicativo em vários cartões decorativos pequenos só para dar à página uma aparência mais elaborada.

Sistema de design Radix Themes: estilo e estados dos componentes

Botões e hierarquia de ações

Em cada grupo de ações, identifique a decisão principal e dê a ela o maior destaque. As ações secundárias devem continuar fáceis de encontrar, sem competir em igualdade de condições. Separe ações destrutivas das confirmações comuns. Durante o envio, impeça operações duplicadas e mostre o progresso; ao concluir, apresente o resultado real. Quando o motivo não for óbvio no formulário, inclua perto do botão desativado uma explicação compreensível.

Campos de entrada e formulários

• Coloque um rótulo persistente acima ou ao lado de cada campo de entrada.
• Mantenha o texto de ajuda próximo ao campo correspondente e associe as mensagens de validação ao campo, em vez de exibir apenas um aviso genérico.
• Preserve os valores preenchidos quando a validação falhar.
• Agrupe campos relacionados sob um título de seção significativo.
• Use o tipo de campo e o valor de preenchimento automático adequados para que o navegador e as tecnologias assistivas ajudem a pessoa a concluir a tarefa.

Cartões, listas e tabelas

Use um cartão para um objeto independente que tenha um resumo significativo e uma ação. Use uma lista para uma sequência de registros semelhantes e uma tabela quando as pessoas precisarem comparar atributos entre registros. Mostre campos reais, como responsável, horário de atualização e status, em vez de fragmentos decorativos de gráficos. Um cartão não deve ser clicável de uma forma que concorra com links ou botões aninhados; escolha um destino de link claro e mantenha o comportamento padrão do teclado.

Navegação e seleção

Mantenha a navegação global separada das guias da página e dos filtros locais. O destino ativo deve continuar identificável sem depender apenas da cor de destaque. Use links para navegação e botões para alterações na página atual. Se implementar um padrão de guias, inclua o comportamento pelo teclado; caso contrário, use um grupo claramente identificado de botões comuns. Não faça uma linha de elementos span com estilo visual parecer interativa quando não puder ser operada.

Menus, caixas de diálogo e sobreposições

Ao implementar um produto React, use o componente nativo da biblioteca para comportamentos complexos. Uma caixa de diálogo precisa de um título, uma forma clara de fechá-la, gerenciamento adequado do foco e retorno ao controle que a acionou. Evite criar um modal com um cartão posicionado de forma absoluta sem esses comportamentos. Mantenha a caixa de diálogo focada em uma única decisão; fluxos de edição mais longos geralmente merecem uma página própria, em vez de uma sobreposição cada vez mais abarrotada.

Carregamento, estado vazio, erro e sucesso

• Projete cada estado considerando a mesma tarefa real.
• Uma lista de projetos vazia deve explicar como criar o primeiro projeto.
• Um estado de carregamento deve preservar estrutura suficiente para evitar uma mudança brusca de layout.
• Um erro deve oferecer uma próxima ação significativa e não deve apagar o trabalho concluído.
• Uma mensagem de sucesso deve identificar o que mudou.
• Os botões estáticos de demonstração nesta página ilustram a aparência; eles não comprovam o comportamento desses estados em produção.

Sistema de design Radix Themes: layout, espaçamento e densidade

Use uma escala de espaçamento compartilhada

A escala de espaçamento documentada tem nove incrementos básicos: 4, 8, 12, 16, 24, 32, 40, 48 e 64 pixels. Use incrementos menores dentro de controles estreitamente relacionados e maiores entre seções independentes. Mantenha uma relação visual entre um título e seu conteúdo. Não distribua espaços vazios uniformemente só para preencher a tela: a proximidade deve indicar quais informações pertencem umas às outras.

A densidade depende da tarefa

Um diretório de recursos precisa exibir itens suficientes para permitir comparações. Um formulário de configuração precisa de espaço para rótulos, textos de ajuda e erros. Uma página de leitura precisa de uma largura de texto estável e de um sumário visível. Escolha a densidade de acordo com a tarefa, em vez de aplicar o mesmo tamanho de cartão em todos os lugares. O Radix também oferece uma configuração de escala que ajusta dimensões relacionadas em conjunto; avalie a legibilidade e as áreas de interação resultantes antes de definir uma escala compacta como padrão do produto.

Comportamento de grades e contêineres

Comece com um contêiner de página e, em seguida, defina o conteúdo principal e quaisquer áreas de apoio. Mantenha textos longos em uma coluna legível, mesmo quando a área externa for ampla. Em larguras menores, mova o conteúdo de apoio para baixo do conteúdo principal ou transforme uma área lateral longa em um controle de navegação local acessível. Mantenha a ordem no código-fonte para que o fluxo em dispositivos móveis e a ordem de navegação pelo teclado façam sentido sem depender da disposição da grade para desktop.

Prefira linhas a cartões aninhados

Para uma referência compacta de tokens, coloque o nome, o valor e o uso em uma única linha fácil de percorrer com o olhar. Em um catálogo, mantenha o título, a categoria, a descrição e o destino juntos. Caixas aninhadas e repetidas acrescentam ruído visual e ocupam espaço que deveria pertencer ao conteúdo. Prefira um separador fino entre linhas relacionadas; reserve painéis delimitados para uma mudança real de contexto, como uma prévia ao vivo ou um exemplo de código.

Mantenha o conteúdo importante visível

Não reduza um guia detalhado a resumos breves só para encurtar a página. Ofereça um sumário e subtítulos bem definidos para que as pessoas possam ir direto ao trecho relevante. Se um filtro ou acordeão alterar o que está visível, deixe claro o estado vazio e o estado selecionado. Evite listas internas com rolagem independente, a menos que resolvam uma necessidade real de interação; para uma coleção longa de recursos, a rolagem normal da página costuma ser mais fácil.

Sistema de design Radix Themes: raio, profundidade e movimento

O raio é uma questão de relação

O Radix oferece configurações de raio nomeadas e comportamentos contextuais para os componentes. Escolha uma configuração no nível do tema em vez de atribuir o mesmo raio arbitrário a todos os elementos. Um botão, uma caixa de seleção e um painel grande têm funções estruturais diferentes. Mantenha as formas relacionadas sem apagar essas diferenças. Se o seu componente usar um token de raio, teste-o ao lado de um botão e de um campo nativos antes de decidir que ele pertence ao mesmo sistema.

A elevação explica as camadas

Use a profundidade para distinguir uma sobreposição da página abaixo dela ou um painel interativo de uma área de trabalho discreta. O Radix oferece uma escala de sombras com seis níveis. Evite tratar o índice da sombra como uma classificação decorativa de popularidade para cartões. Um catálogo denso muitas vezes funciona bem apenas com bordas. Revise as sombras nos dois temas: um desfoque do modo claro aplicado a uma superfície escura pode desaparecer ou criar um halo que sugere a profundidade errada.

O movimento deve esclarecer uma mudança

Use transições curtas para explicar uma seleção, abertura, progresso ou movimento entre estados relacionados. Não atrase o conteúdo com uma animação de entrada. Evite movimento contínuo no plano de fundo de uma tela voltada ao trabalho. Respeite as preferências de movimento reduzido e mantenha o estado final legível quando as transições forem removidas. As escolhas de duração em uma implementação personalizada são decisões da aplicação; este guia não inventa um token oficial de duração do Radix quando não há nenhum verificado.

Interação sem enfeites

Um efeito de foco ao passar o cursor deve reforçar que o elemento pode ser acionado. Um indicador de foco deve permanecer claramente visível em relação às superfícies adjacentes. Não mova tanto uma linha densa inteira ao passar o cursor que as informações saiam do lugar enquanto alguém está lendo. Em telas sensíveis ao toque, as ações essenciais devem estar disponíveis sem passar o cursor. O efeito funciona quando ajuda a pessoa a entender o controle, não quando chama atenção para a animação em si.

Radix Themes O que fazer e evitar em um sistema de design

Faça: estabeleça uma tela completa

Crie uma tela com a navegação real, conteúdo significativo, ação principal e pelo menos um estado excepcional. Revise a tela antes de extrair dezenas de componentes reutilizáveis. Registre escolhas deliberadas, como cor de destaque, densidade, escalas tipográficas e texto para estados vazios. Isso dá a um agente de codificação um contrato específico a seguir e facilita identificar desvios nas iterações posteriores.

Faça: mantenha consistência entre componentes nativos e personalizados

Prefira os componentes existentes da biblioteca para comportamentos que ela já oferece. Use variáveis do tema em wrappers personalizados e confira esses wrappers nos dois temas. Preserve os rótulos e a semântica HTML ao estilizar. Se o projeto já tiver um sistema de design, compare-o com esta referência antes de substituí-lo; uma segunda camada de tema sem controle pode gerar mais inconsistências do que eliminar.

Evite: recriar uma marca trocando as cores

Alterar apenas a cor de destaque não cria uma interface coerente. Espaçamento, tipografia, hierarquia do conteúdo, padrões de interação e escolhas responsivas contribuem bastante para a identidade visual. Não afirme que há uma integração oficial só porque um mockup se parece com a biblioteca. Evite copiar a marca registrada, os recursos proprietários ou as alegações comerciais de outro produto para a tela de um novo produto.

Evite: trocar significado por uma captura de tela mais limpa

Radix Themes Comportamento responsivo e acessível do sistema de design

Adapte a estrutura antes de reduzi-la

Quando a tela ficar mais estreita, reduza o número de colunas, encurte o caminho até a ação principal e transfira as informações secundárias para o fluxo normal de leitura. Não reduza um painel de desktop como se fosse uma única imagem e chame isso de layout para dispositivos móveis. Mantenha o mesmo conteúdo disponível usando quebra de linha, empilhamento ou uma apresentação de tabela adequada. Preserve textos descritivos nos links para que o destino continue fazendo sentido fora do cartão de desktop que o envolve.

Use os breakpoints documentados de forma intencional

Os nomes oficiais dos breakpoints são initial, xs, sm, md, lg e xl. As larguras mínimas são 0, 520, 768, 1024, 1280 e 1640 pixels. Trate-os como ferramentas disponíveis, não como mudanças de layout obrigatórias em cada etapa. Adicione um breakpoint quando o conteúdo exigir uma disposição diferente. Teste uma largura entre os breakpoints nomeados, além do próprio breakpoint, para identificar layouts intermediários frágeis.

Teclado e foco

• Todas as ações relevantes precisam poder ser realizadas com o teclado.
• Diferencie o estado de foco visível do estado de foco ao passar o cursor e mantenha-o visível mesmo quando um contêiner recortar o conteúdo.
• Evite valores positivos de tabindex que reordenem os controles de forma imprevisível.
• Depois que um filtro alterar os resultados, mantenha o foco no controle e informe uma contagem concisa dos resultados.
• Depois de fechar um modal, devolva o foco a um local adequado, em vez de deixar a pessoa no início do documento.

Rótulos, alvos e textos auxiliares

Dê às ações que exibem apenas um ícone um nome acessível que descreva a ação, não o formato do ícone. Garanta que os alvos de toque sejam confortáveis, mesmo quando o ícone visível for pequeno. Mantenha os ícones decorativos fora da árvore de acessibilidade. Informe atualizações, como alterações salvas ou contagens de resultados da pesquisa, sem anunciar repetidamente conteúdo sem relação com elas. Quando um estado usar ícone e texto, evite transmitir a mesma mensagem duas vezes ao leitor de tela.

Valide com conteúdo real

• Confira em um desktop, um tablet e um celular com tela estreita.
• Inclua expansão de texto, uma imagem ausente, uma lista vazia e um identificador longo sem espaços para quebra.
• Teste a página com movimento reduzido e navegação por teclado.
• Revise os dois temas após qualquer mudança significativa de cor.
• Verificações automatizadas podem encontrar problemas estruturais, mas não podem determinar se a hierarquia, a densidade do conteúdo e o caráter visual geral atendem às necessidades previstas do produto.

Guia de prompts e implementação de agentes para o sistema de design Radix Themes

Prepare o contexto do projeto

1. Informe ao agente de programação o que está sendo criado, quem vai usar, qual é a ação principal e quais arquivos existentes definem o design atual.
2. Anexe este guia como referência, em vez de pedir ao agente que imite uma captura de tela sem especificações.
3. Se estiver usando React, indique que os componentes nativos de Radix Themes devem ser priorizados.
4. Se estiver usando outra stack, peça uma interpretação identificada explicitamente e avalie o trabalho adicional de interação que ela exigirá.

Especifique uma primeira versão completa

Peça uma tela funcional com conteúdo real e um pequeno conjunto de estados. Especifique a navegação, os campos, os metadados dos objetos e o resultado esperado da ação principal. Inclua na solicitação o foco do teclado, um estado vazio, validação e um layout estreito. Indique as restrições que devem ser mantidas, como um cabeçalho existente, um contrato de dados de produção ou um bloco de conteúdo previamente aprovado.

Revise em uma ordem que identifique problemas reais

1. Primeiro, confirme que a tela permite realizar a tarefa pretendida.
2. Depois, compare a hierarquia das informações, os espaçamentos, a tipografia e as cores com a referência escolhida.
3. Por fim, teste os estados interativos e os layouts responsivos.
4. Não aceite uma mudança visual só porque a página compila ou porque a captura de tela parece organizada.
5. Verifique se conteúdos mais longos, erros e ações repetidas continuam funcionando após os ajustes visuais.

Amplie com decisões explícitas

Quando a primeira tela estiver funcionando, registre a configuração do tema, os papéis tipográficos, as escolhas de espaçamento e os padrões de componentes que devem se repetir. Peça ao agente que aplique essas decisões à próxima tela sem reescrever silenciosamente o conteúdo aprovado. Quando uma nova tela precisar de um padrão diferente, documente o motivo e confira a consistência com a tela anterior. Amplie com base em comportamentos verificados, em vez de gerar muitas páginas superficialmente semelhantes.

Escopo conhecido e limites das fontes