React Native

O @rivocode/ui-native leva o design system para o celular falando o mesmo vocabulário de classes do web (bg-bg, text-fg-muted, rounded-pill) via NativeWind, sobre os mesmos tokens. Nenhum componente conhece a cor da marca: ele pede um papel semântico e o tema responde. Entre os dois temas de casa a troca acontece em runtime; vestir a cor de um cliente é decisão de build, e há uma seção inteira abaixo sobre o que isso muda.

O catálogo nasce por tradução, não por porte: cada peça web foi julgada no idioma da plataforma antes de atravessar. Isso tem duas consequências, e a segunda é a que custa caro quando ninguém a escreve.

Mesmo nome não é mesma API

Onde o nome da peça é o mesmo, o nome da prop também é: Avatar recebe fallback, OTPField avisa por onValueComplete, ToggleGroup aceita vários com multiple. E, sem multiple, desaperta o anterior, como no web. Até a 0.1.0 estas três divergiam (initials, onComplete, single com o sentido invertido), e quem escrevia as duas telas do mesmo produto trocava de vocabulário no meio do caminho.

Nome igual, porém, não é assinatura igual: nenhuma das peças que atravessam aceita o mesmo JSX dos dois lados. Duas regras explicam quase toda a diferença.

No nativo tudo é controlado. Não existe defaultValue, defaultChecked nem defaultOpen de raiz. O estado mora no app, e as duas props do par são obrigatórias:

web     <Checkbox defaultChecked>ISS retido</Checkbox>
nativo  <Checkbox checked={retido} onCheckedChange={setRetido} />   os dois obrigatórios

A lista vem por items, e não por composição. O web monta o gatilho, o painel e cada opção; o nativo recebe o array e desenha a folha de baixo, que não tem gatilho ancorado para vestir:

web     <Select items={PERIODOS} defaultValue="30">
          <SelectTrigger><SelectValue /></SelectTrigger>
          <SelectContent>{/* um SelectItem por opção */}</SelectContent>
        </Select>

nativo  <Select items={PERIODOS} value={periodo} onValueChange={setPeriodo} label="Período" />

O mesmo vale para RadioGroup, CheckboxGroup, ToggleGroup, Combobox e Tabs: onde o web pede filhos, o nativo pede items. E o label que aparece ali não é enfeite: é por ele que o leitor de tela anuncia o controle, papel que no web era do SelectTrigger.

A conclusão prática: a tela não se copia de um lado para o outro. O que se reaproveita é o vocabulário de classes, o token e a decisão de qual peça usar. O JSX se reescreve.

O formulário entra por outro caminho

O Form, o FormField, os adaptadores e o useZodForm vivem em @rivocode/ui-native/form, e não no índice principal, com o mesmo arranjo do web e pela mesma razão: o react-hook-form é peer opcional, e o metro resolve import por arquivo. Dentro do índice da raiz, um app que só quer um Button teria de instalar o react-hook-form para o bundle fechar.

import { Button, Input } from '@rivocode/ui-native'
import { Form, FormField, forText, useZodForm } from '@rivocode/ui-native/form'

Duas diferenças mordem na primeira tela. Nada envia sozinho: não há <form>, type="submit" nem Enter que envie, então o Form entrega o envio por função: {({ submit, isSubmitting }) => …}. E o rótulo viaja no campo: no web o Field da Base UI liga rótulo e controle pelo for, e aqui não há for nem id; o FormField põe accessibilityLabel e invalid dentro do campo, e o adaptador os leva ao controle. Sem isso, um TextInput embaixo de um rótulo fica sem nome para o leitor de tela.

O gráfico entra por outro caminho, e traz um peer nativo

ChartContainer, ChartDonut e ChartRadial vivem em @rivocode/ui-native/chart, pela mesma regra do formulário, só que aqui o peer opcional custa mais do que bytes:

npx expo install react-native-svg

import { ChartContainer, ChartDonut, ChartRadial } from '@rivocode/ui-native/chart'

O react-native-svg é módulo nativo: quem não desenha gráfico não o instala, não o liga ao projeto de iOS e Android e não reconstrói por causa dele. É por isso que as três peças não saem do índice da raiz, e é por isso que a Sparkline continua desenhada com View, onde está: ela é o slot chart do Stat, o Stat sai da raiz, e trazê-la para cá cobraria o peer de quem só queria um número dentro de um cartão.

Duas decisões valem pelas três peças. Nada mede sozinho: no lugar do ResponsiveContainer e das var(--color-série), o ChartContainer mede com onLayout, resolve as cores do config e entrega { width, height, colors } a quem desenha, com a medida zerada no primeiro quadro, porque no telefone não existe largura antes do layout. E no toque não há dica: a rosca põe nome e valor de cada fatia na legenda, que é também o controle: tocar a linha acende a fatia e manda o valor para o meio do anel, no lugar exato onde o web abre a dica. O resto está na tabela abaixo.

Copiar e anexar entram por dois caminhos, e não por um

Clipboard e FileUpload fecham a mesma regra do formulário e do gráfico, e levam a divisão um passo adiante: um subcaminho por peer, e não um por assunto.

npx expo install expo-clipboard        # @rivocode/ui-native/clipboard
npx expo install expo-document-picker  # @rivocode/ui-native/file-upload

import { Clipboard } from '@rivocode/ui-native/clipboard'
import { FileUpload, FileUploadItem, FileUploadList } from '@rivocode/ui-native/file-upload'

Os dois poderiam dividir uma porta só (/expo, digamos), e a conta de quem instala diz que não. Quem põe um botão de copiar ao lado da chave de acesso de uma NF-e não anexa arquivo nenhum; um índice comum arrastaria o expo-document-picker para o projeto dele, que é exatamente o custo que este arranjo existe para não cobrar. Módulo do Expo no celular não é bytes: é build. A fronteira dos dois é guardada junto com a do gráfico e a do formulário, nos dois pacotes, por scripts/check-fronteira-do-chart.ts.

A confirmação de copiar passa a ser dupla, e no web bastava uma. A regra da peça não muda: copiar é a ação sem resultado visível, e sem confirmação a pessoa toca de novo por dúvida. O que muda é por onde ela chega: o botão troca o ícone e o nome acessível, como lá, e a peça dispara também um aviso, porque aqui trocar o accessibilityLabel de um Pressable que já está sob o foco não é reanunciado por leitor de tela nenhum. Quem não vê o ícone virar visto não ficaria sabendo de nada; o aviso que o RivoProvider já monta mora num accessibilityLiveRegion="polite" e é o único canal desta tela que fala sozinho. toast={false} desliga, para a tela que copia várias coisas seguidas. E quando a área de transferência recusa (o setStringAsync do Expo devolve false, o que no telefone não acontece e no passe web sim), nada é confirmado: mentir que copiou é pior do que não confirmar.

E a área de soltar não existe. No celular nada pode ser arrastado para lugar nenhum, e o retângulo tracejado do web é, letra por letra, o idioma de "solte aqui". Tirado o soltar, o que sobra daquela caixa é um botão com muito espaço vazio em volta: o espaço era o alvo de soltar, e não a affordance. Então o FileUpload nativo é um botão de altura de controle, com o hint dentro do nome falado (quem ouve a tela precisa saber "XML ou PDF, até 5 MB" antes de abrir o seletor, e não depois de ser recusado), e a altura que ele devolve é da lista. O accept fala MIME, que é o que o seletor do sistema sabe filtrar. Extensão com ponto continua valendo na validação de volta, mas não vai para o diálogo, onde não casaria nada. O que volta não é um File: é um PickedFile com o uri local que o app usa para subir, e cujo size pode faltar, porque nem todo provedor de arquivo do Android o informa. O maxSize só recusa o que conseguiu medir.

A paridade, peça por peça

91 peças no catálogo do web, medidas contra native/src/index.ts, native/src/form/index.ts, native/src/chart/index.ts, native/src/clipboard/index.ts e native/src/file-upload/index.ts em 2026-09-23: 70 traduzem com o mesmo nome, 5 traduzem com outro, 0 estão na fila e 16 não portam por decisão. A coluna do meio separa as duas ausências, que é a distinção que a tabela existe para fazer: ○ muda com o tempo, ✕ não muda. E ✔ não quer dizer copiar e colar: a seção acima explica por quê.

Instalação

Num app Expo:

npx expo install nativewind@preview react-native-css react-native-reanimated react-native-keyboard-controller tailwindcss @tailwindcss/postcss postcss
npm install @rivocode/ui-native

O react-native-keyboard-controller é o que impede o teclado de cobrir o campo, e ele vem incluído no Expo Go do SDK 57. O KeyboardProvider que ele pede já está dentro do RivoProvider: não monte outro. Se o seu app já tinha um por fora, o provider reaproveita o seu. A tela de formulário é o ScrollArea, que rola até o campo em foco e prende a ação num footer que sobe com o teclado; o Sheet e o Dialog sobem sozinhos.

O @preview não é enfeite: no npm a tag latest do NativeWind ainda é a 4.2.6, e este pacote pede a 5 (nativewind: ">=5.0.0-preview.1" no peer). Sem a tag você instala a v4, e aí o metro.config.js logo abaixo nem carrega: a v5 exporta withNativewind, a v4 exporta withNativeWind, com W maiúsculo, e o erro que sai é um undefined is not a function que não conta de onde veio. Saiba antes de começar: a NativeWind 5 ainda é pré-lançamento e é o único caminho que o @rivocode/ui-native conhece hoje, então ir para produção com ele é ir para produção sobre um preview.

Cinco arquivos do app participam, cada um por um motivo que morde:

1. metro.config.js. O NativeWind entra no build:

const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

module.exports = withNativewind(getDefaultConfig(__dirname));

2. package.json. Navegadores modernos, cravados:

"browserslist": ["chrome 130", "safari 18", "firefox 130"]

Não é sobre navegador nenhum: o Expo roda um passe web no CSS antes do compilador nativo, e sem esse campo ele reescreve o light-dark() dos tokens num polyfill de vars órfãs que mata a compilação. É esta linha que sustenta a troca entre os dois temas de casa em runtime.

3. app.json. "userInterfaceStyle": "automatic", senão o iOS prende a aparência no claro e o tema escuro nunca chega.

4. global.css. A fonte do CSS:

@import "tailwindcss/theme.css" layer(theme);
@import "@rivocode/ui-native/theme.css";
@import "tailwindcss/utilities.css";

@source "./App.tsx";
@source "./node_modules/@rivocode/ui-native/src";

O app não importa o global.css: importa o pré-compilado.

npx rivocode-ui-native-css   # lê global.css, escreve generated.css

O pipeline do metro tropeça em @import e @property dentro do compilador nativo; o comando entrega um arquivo já resolvido, e falha com o nome da var quando algo não traduziria. Usou uma classe nova, rode de novo.

5. nativewind-env.d.ts. O TypeScript aprende o className:

/// <reference types="nativewind/types" />

O sintoma é o projeto novo abrir com uma parede de erro: Property className does not exist on type ... em toda View, Text e Pressable que você escreveu, e nas do @rivocode/ui-native junto (foram 167 num app recém-criado). A causa é que className não existe no React Native: quem o acrescenta às props é uma declaração de módulo que mora na NativeWind, e ela só entra no programa se este arquivo a referenciar. Nada disso aparece em runtime (o app roda e as cores estão certas), então é fácil ler os erros como culpa da biblioteca.

O withNativewind do passo 1 gera o arquivo na primeira vez que o metro sobe, com este nome exato (a opção typescriptEnvPath muda o caminho). Escreva-o à mão quando o tsc roda antes do app (CI, ou o editor num clone recém-baixado), e não o coloque no .gitignore: sem ele versionado, o erro volta a cada clone.

O Provider, uma vez, na raiz

import "./generated.css";
import { RivoProvider, Button, useToast } from "@rivocode/ui-native";

export default function App() {
  return (
    <RivoProvider theme="rivocode-dark">
      <MinhaTela />
    </RivoProvider>
  );
}

• theme: rivocode-dark (padrão), rivocode-light ou system, que segue o aparelho. Entre os dois temas de casa, trocar a prop troca a tela inteira em runtime: essas cores foram compiladas como light-dark(), e o provider só gira o esquema de cor do Appearance. A prop aceita também o mapa de um tema de cliente, e aí a história é outra: leia a seção abaixo antes.
• density: não existe no pacote nativo. Alvo de toque não encolhe em tela de dedo, e comfortable é a única altura.
• O useToast já vem ligado, como no web: nenhum provedor extra para montar.

Tema de cliente: é decisão de build, não prop de runtime

Esta é a diferença mais cara entre os dois pacotes, e a que mais se supõe errado. No web a camada 3 é lida em runtime, e <RivoProvider theme="acme"> troca a página inteira com ela aberta. Aqui não.

A cor de classe só muda em build. O compilador do react-native-css resolve o token e crava o valor dentro da regra: .bg-accent vira {"backgroundColor":"#d4f34a"}, literal, e nos 56 KB de CSS compilado não sobra uma ocorrência de --. Não há variável viva no aparelho para redefinir, e por isso nenhum objeto de tema passado em runtime jamais trocou cor de classe.

O mapa de tema SAIU do provider. Ele alcançava quem lê a cor por JS, do contexto - ChartDonut, ChartRadial, o giro do Button e do Spinner, o trilho do Switch, a Sparkline, o texto de dica dos campos -, e não alcançava fundo, cartão, botão, selo e borda, que são classe: dava donut de um tema e botão de outro na mesma tela, sem nada vermelho no console além do aviso em __DEV__.

Uma metade que discorda da outra é pior do que nenhuma. O provider passou a resolver os 45 papéis lendo o CSS compilado, uma classe bg- por papel, e publica no mesmo contexto que as peças já liam: contexto e classe dizem sempre a mesma cor. Com isso o mapa deixou de ter o que fazer e foi removido: a prop theme aceita só rivocode-dark, rivocode-light e system, e a prop scheme saiu junto, porque era ela que escolhia o esquema do mapa.

O caminho que funciona

Sobrescreva os papéis num @theme seu no global.css, depois do theme.css do pacote, e pré-compile de novo. É a mesma camada 3, no vocabulário --color-* que o compilador nativo lê:

@import "tailwindcss/theme.css" layer(theme);
@import "@rivocode/ui-native/theme.css";
@import "tailwindcss/utilities.css";

@theme {
  --color-accent: #2563eb;
  --color-accent-hover: #3b82f6;
  --color-accent-fg: #ffffff;
  --color-bg: light-dark(#f7f8fa, #0d1220);
  --color-surface: light-dark(#ffffff, #141b2d);
  /* …e os outros papéis que a marca troca. */
}

@source "./App.tsx";
@source "./node_modules/@rivocode/ui-native/src";

npx rivocode-ui-native-css

Isto sozinho veste a marca inteira, gráfico incluído: a classe pinta a cor nova, e a peça que pinta por fora da classe lê a mesma cor do mesmo CSS. Não passe mapa nenhum na prop theme.

E há um teto: dois temas por build. light-dark() tem duas vagas, uma clara e uma escura. Um app de um cliente cabe folgado, e é o caso normal; uma vitrine de cinco temas, como a deste site no web, não cabe sem cinco bundles. É teto de arquitetura, e não pendência. O guia de temas tem o passo a passo e a lista completa de papéis.

Escreva só a paleta, e o comando escreve o tema

O @theme acima tem 45 papéis para preencher, e é aí que o tema de cliente começa a envelhecer. Os nomes de papel, os pares de contraste, os mínimos, a composição de alfa e o formato que o compilador nativo aceita são conhecimento da biblioteca. Antes deste comando eles moravam no app de quem vestia o cliente: um consumidor real escreveu 220 linhas para isso, e portou a conta de contraste com um defeito calado justo nos 12 papéis que carregam alfa.

O segundo binário do pacote traz essa conta de volta para dentro:

npx rivocode-ui-native-theme acme.ts    # lê a paleta, escreve acme.theme.css
npx rivocode-ui-native-theme acme.ts saida.css
npx rivocode-ui-native-theme --papeis   # o que você escreve, o que ele deriva

Você escreve oito papéis por esquema, num .ts, .js, .mjs ou .json:

export const acme = {
  light: {
    bg: "#ffffff",
    surface: "#ffffff",
    fg: "#111111",
    accent: "#1d4ed8",
    success: "#0f6b52",
    warning: "#7a4a00",
    danger: "#b3261e",
    info: "#1d4ed8",
  },
  dark: {
    bg: "#101314",
    surface: "#191d1f",
    fg: "#f2f3f0",
    accent: "#8ab4f8",
    success: "#3ddc97",
    warning: "#f2b21c",
    danger: "#ff8a8a",
    info: "#8ab4f8",
  },
};

A saída entra no global.css depois do tema do pacote, e o pré-compilado sai como sempre:

@import "tailwindcss/theme.css" layer(theme);
@import "@rivocode/ui-native/theme.css";
@import "./acme.theme.css";
@import "tailwindcss/utilities.css";

@source "./App.tsx";
@source "./node_modules/@rivocode/ui-native/src";

npx rivocode-ui-native-css

Qualquer um dos 45 papéis se escreve à mão na paleta, e o comando para de derivar aquele.

Ele recusa escrever tema que não passa no contraste

A medida é a do @rivocode/ui-native/contrast, o mesmo motor que o bun run check do repositório usa: os pares que carregam texto, a fronteira de controle de 3:1, o alfa sobre alfa do Calendar, a camada achatada por opacity do botão destrutivo e o trilho do Switch ligado.

Guarda de contraste:
  claro: 1 falha(s)
    accent-fg sobre accent  2.45:1 (min 4.5)
  escuro: passa

Nada foi escrito: conserte o contraste antes de gerar o CSS.

Nada é escrito enquanto um par estiver abaixo do mínimo. Tema que ninguém mediu é exatamente o que este comando existe para não deixar acontecer.

O que ele deriva, e o que ele se recusa a adivinhar

Derivar aqui é reusar cor que você escreveu, ou compor alfa dela. O comando nunca inventa matiz nova:

Duas escolhas dessa tabela merecem o motivo escrito.

accent-text e os quatro *-text são reusados, e só quando passam. Eles são a cor que se lê: escurecer o vermelho da marca um passo sem avisar é decisão de quem desenha, e não de um script. Então o comando tenta o próprio preenchimento, e onde ele não alcança 4,5:1 sobre os três fundos ele recusa e diz o valor que passaria:

    light.accent-text foi DERIVADO: o proprio `accent`, e so quando ele passa em 4,5:1
      `accent-text: "#667524"` passaria - confira se e a cor da marca.

chart-1 a chart-8 caem na série da RivoCode. É a única exceção declarada, e ela não é derivação: série de gráfico é escala categórica, e não identidade de marca. Mesmo sendo padrão, ela é medida sobre o seu fundo, e reprova se não couber. Escreva as oito na paleta se a marca tiver a dela.

Papel novo em versão nova acusa, em vez de o tema quebrar calado

A lista de papéis sai do tokens.json do pacote instalado, e não de uma cópia dentro do comando. Quando uma versão nova trouxer um papel, o comando o cobra pelo nome na primeira vez que você rodar:

1 papel(eis) sem valor:
    light.accent-quiet  - papel novo no @rivocode/ui-native 0.4.0, e este comando ainda nao sabe derivar

Sem isso o papel novo simplesmente não sairia no seu @theme, a classe cairia no valor do theme.css do pacote, e a tela sairia misturada: metade do cliente, metade da RivoCode. Nome errado na paleta é acusado do mesmo jeito, com sugestão do papel que você quis dizer.

oklch() entra direto, e a paleta do Tailwind 4 com ele

A conta da WCAG desta casa lê hexadecimal de 3, 4, 6 e 8 dígitos, rgb(), rgba(), hsl(), hsla(), hwb(), lab(), lch(), oklab(), oklch() e color() nos espaços predefinidos do CSS, e converte tudo para sRGB antes de medir. A paleta do Tailwind 4 é escrita em oklch(): copie a cor de lá e o comando mede, sem conversor no meio. O CSS que ele escreve continua sendo sRGB literal, porque é o que o compilador nativo crava — a conversão acontece na entrada, e não na sua mão.

Duas coisas ainda são recusadas, e as duas por não terem medida possível: color-mix(), que não é uma cor e sim uma conta cujo resultado depende do espaço de interpolação e do método de matiz, e semente que carrega alfa — semente é cor cheia, porque é dela que sai a escada de alfa dos papéis derivados.

Cor que descreve tom fora do gamut do sRGB — 82 das 286 cores nomeadas do Tailwind 4 estão nessa faixa — é medida no valor que o aparelho mostra: o excedente é cortado canal por canal, e o comando avisa quais papéis caíram ali e para qual valor.

O teto de dois temas está na mensagem de erro, e não só aqui

Um terceiro esquema no arquivo é recusado com o motivo, porque quem passa três precisa ouvir por que não cabem:

3 esquemas em acme.ts: light, dark, contraste.

    Cabem dois, e o teto nao e escolha nossa. Cada papel sai como
    `light-dark(claro, escuro)`, e `light-dark()` tem DUAS vagas: uma clara
    e uma escura. [...]
    Um terceiro esquema e um terceiro BUNDLE: rode o comando uma vez por par
    e escolha o CSS no build.

Ajuste fino com className

Como no web, toda peça aceita className na raiz e a classe de quem usa vence a da peça: h-14 derruba o h-12 do Button, rounded-pill derruba o rounded-md. É o que permite um wrapper de cliente num arquivo do app, sem fork. Nas peças com folha (Select, Combobox, DatePicker, Sheet, Dialog, Menu), a documentação da prop diz o que ela veste, o gatilho ou o painel. Lembre da regra do pré-compilador: classe nova usada no app pede npx rivocode-ui-native-css de novo.

Ícones

O mesmo Lucide do web, pelo pacote irmão:

npx expo install lucide-react-native react-native-svg

Os nomes são os mesmos (Receipt lá é Receipt aqui), então o vocabulário canônico do guia de ícones vale nos dois mundos, e a galeria com busca serve aos dois. Dentro das peças da biblioteca os ícones de estado continuam desenhados com borda (o visto do Checkbox, os chevrons do Calendar): peça não carrega dependência de ícone, app carrega se quiser.

O que nunca fazer

• Classe com var arbitrária (h-[--rc-control-md]) ou translate-*: o compilador do react-native-css atual não tolera var viva nem a shorthand translate. Altura de controle é fixa por tamanho.
• Remover o browserslist moderno do package.json. O erro que aparece (expected an object-like struct named Specifier) não diz o porquê; esta linha diz.
• Glyph de texto como ícone de estado: o visto do Checkbox é borda rotacionada, porque fonte muda de corpo entre iOS e Android.
• Esquecer accessibilityRole/accessibilityState em controle custom. Toda peça do catálogo já os traz.

O exemplo completo

O repositório traz um app Expo em examples/native com todas as peças em uso numa tela de produto: painel, listagem com detalhe em Sheet, formulário, confirmação destrutiva e o interruptor de tema. bunx expo start --ios dentro dele, e o simulador conta o resto.