Pular para o conteúdo

React Native

O mesmo vocabulário no celular, com tema que troca em runtime.

/react-native.mdmarkdown cru, para quem lê com agent em vez de olho

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.

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 o controle de valor é controlado. Campo, caixa, seleção e alternador não têm defaultValue nem defaultChecked: o estado mora no app, e as duas props do par são obrigatórias. Só as peças de abrir e fechar (Accordion, Collapsible, Spoiler, ToolCall) aceitam defaultOpen ou defaultValue, como no web:

web     <Checkbox defaultChecked>ISS retido</Checkbox>
nativo  <Checkbox checked={retido} onCheckedChange={setRetido}>ISS retido</Checkbox>   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 - como label nas peças, que se nomeiam por ele, e como accessibilityLabel no Input e no Textarea. Sem isso, um TextInput embaixo de um rótulo fica sem nome para o leitor de tela.

O gráfico entra por outro caminho, pelo peso

ChartContainer, ChartDonut, ChartRadial, ChartGauge, ChartHeatmap, ChartFunnel e ChartTreemap vivem em @rivocode/ui-native/chart, pela mesma regra do formulário:

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

Eles desenham com o react-native-svg, que desde a 6.0 é peer obrigatório da raiz - todo ícone do pacote é do lucide-react-native, que desenha com ele -, então a porta não cobra instalação nenhuma a mais. Ela continua separada pelo peso: quem monta formulário não carrega as escalas, as marcas e o QR. A Sparkline continua desenhada com View, no índice da raiz, porque é o slot chart do Stat.

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" (no iOS, onde ela não existe, o mesmo texto sai pelo anúncio do sistema) 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

149 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, native/src/file-upload/index.ts, native/src/ai/index.ts, native/src/dnd/index.ts, native/src/illustrations/index.ts, native/src/audio/index.ts, native/src/video/index.ts e native/src/mascot/index.ts em 2026-11-15: 119 traduzem com o mesmo nome, 4 traduzem com outro, 0 estão na fila e 26 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ê.

Peça No React Native O que saber antes de contar com ela
AILabel ✔ traduz vive em @rivocode/ui-native/ai; a explicação abre numa Sheet, e não num painel ancorado, e é string
Accordion ✔ traduz value, defaultValue e onValueChange na raiz, pelo value de cada AccordionItem; um aberto por vez, como no web (multiple deixa vários), e item sem value abre sozinho. O title aceita nó, e description mostra o estado atual embaixo dele, visível fechado. Abre com a seta girando e o corpo em fade, e sem movimento quando o sistema pede para reduzir
ActionBar ✔ traduz o mesmo count, onClear e a mesma frase; gruda acima da área segura de baixo, que entra por bottomInset
Affix ✕ não porta a plataforma já dá: um irmão da ScrollView com position: absolute não rola com ela, e o que gruda ao rolar é o stickyHeaderIndices da lista
Alert ✔ traduz title é prop e o corpo é filho: texto sai embrulhado, e outro nó (o Button de ação) entra como está; sem AlertTitle/AlertDescription; icon, onDismiss e labels como no web, e o ícone também entra por função, na cor do tom. Sem ícone padrão, porque o pacote não traz biblioteca de ícone, e por isso o título continua na cor do tom: sem ele, a cor seria o único sinal
AlertDialog ✔ traduz onConfirm, onCancel e labels em vez de composição, com os nomes do Popconfirm; tone danger ou neutral, e onConfirm que devolve promessa segura o modal em espera até ela terminar; promessa que rejeita deixa a frase de labels.error (ou o error de fora) dentro do modal, como o Popconfirm do web, e o error também é o nome do AlertDialogContent de lá; não fecha no toque fora, como no web
AppShell ✕ não porta o esqueleto do app no celular é o router: tab bar, drawer e a barra de título da pilha
AspectRatio ✔ traduz ratio numérico, igual
AudioPlayer ✔ traduz vive em @rivocode/ui-native/audio, atrás do expo-audio; src aceita require e { uri, headers }, a busca é adjustable com ações de 5 segundos, e os picos vêm prontos
AudioRecorder ✔ traduz vive em @rivocode/ui-native/audio, atrás do expo-audio; entrega a uri em vez do Blob, o medidor lê o metering do gravador em dB, e a permissão negada de vez abre os ajustes
Autocomplete ✔ traduz value é o texto e aceita o que não está na lista; items em texto na raiz, rasa ou em grupos { label, items }, e o campo abre numa folha que sobe com o teclado
Avatar ✔ traduz src remoto pela Image do core; fallback é obrigatório, porque é ele que aparece enquanto a foto baixa e se ela falhar
Bacalhau ✔ traduz com o BacalhauPeek, as 36 poses, os chapéus e os movimentos do web, em @rivocode/ui-native/mascot, sobre o react-native-svg; a cor vem de tokens.mascot, fixa
Badge ✔ traduz os mesmos tons; o texto é filho e o símbolo entra por icon; não tem size, porque no nativo só há uma densidade
Banner ✔ traduz title e description em texto; o ícone é opcional, do lucide-react-native, e entra por função
Breadcrumb ✕ não porta o caminho de volta é o botão de voltar do router
Button ✔ traduz contrato controlado; hitSlop no sm, porque 32px de alvo não se toca sem ajuda. Afunda de leve no toque, e não afunda quando o sistema pede para reduzir movimento. O ícone entra por icon e iconPosition, e tone="danger" com variant="ghost" é o vermelho sem preenchimento, como no web
ButtonGroup ✕ não porta Tabs e ToggleGroup cobrem o caso; botão encostado em botão vira um alvo só no dedo
Calendar ✔ traduz mês desenhado à mão; value, onValueChange, min e max em ISO aaaa-mm-dd, que o web também aceita; exibição dd/mm/aaaa; o mês novo entra por fade; classNames com os nomes do DayPicker do web; disabled, modifiers e modifiersClassNames com os nomes e as formas do web ({ dayOfWeek }, { from, to }, { before }, { after }, lista, função), com o dia em Date ou aaaa-mm-dd, e o dia marcado ganha um ponto embaixo do número e o nome da marca na fala; month e onMonthChange controlam o mês, em aaaa-mm-dd
Card ✔ traduz com CardHeader, CardTitle, CardDescription, CardAction (à direita do título, alinhado ao topo), CardContent e CardFooter, todas com className; o CardTitle se anuncia como cabeçalho e aceita numberOfLines, e não há elevation
Carousel ✔ traduz sobre FlatList horizontal com pagingEnabled; a lista vem por items e renderItem, o index é controlado, e não há autoplay
ChartContainer ✔ traduz vive em @rivocode/ui-native/chart; os quatro finais atravessam com os mesmos nomes, e o desenho entra por função: não há Recharts, nem contentor que meça, nem var(--color-série)
ChartDonut ✔ traduz a legenda é o controle: sem dica para abrir no toque, tocar a linha acende a fatia, e o miolo escrito continua no meio; format aceita nome de formatador ou função, como no web, as pontas saem retas, e empty ocupa o lugar da rosca sem dado
ChartFunnel ✔ traduz mesmas props, com color como papel de token; cada etapa é uma parada com nome, número e taxa na mesma frase
ChartGauge ✔ traduz atravessa quase inteiro, como o ChartRadial; a régua das faixas entra no nome acessível, porque não há descrição separada no toque
ChartHeatmap ✔ traduz a grade vira uma parada adjustable só, como o Tracker, e o dedo escolhe a célula; sem dica, a leitura mora numa linha embaixo
ChartRadial ✔ traduz atravessa quase inteiro, porque nunca teve dica; color é papel de token e o nome sai do que está escrito no meio, não só da porcentagem
ChartTreemap ✔ traduz cada categoria é um botão com nome, valor e fatia; tocar acende o contorno e escreve a leitura embaixo, e a regra do rótulo que some é a mesma
Checkbox ✔ traduz checked e onCheckedChange obrigatórios; sem defaultChecked; indeterminate como no web; o tique aparece crescendo ao marcar
CheckboxCard ✔ traduz title, description, icon e classNames com os nomes do web, mais media, a área livre do desenho grande; controlado por checked e onCheckedChange, como o Checkbox nativo; title e description são string
CheckboxGroup ✔ traduz items na raiz e value: string[]; label nomeia o conjunto, no lugar do aria-label do web
Clipboard ✔ traduz vive em @rivocode/ui-native/clipboard; a confirmação é dupla: o botão troca de nome e um aviso fala, porque rótulo trocado debaixo do dedo não é reanunciado
Code ✔ traduz o trecho quebra linha junto com a frase que o cerca, e o toque longo copia (selectable); a rolagem própria é do CodeBlock, que continua fora
Collapsible ✔ traduz label no lugar de CollapsibleTrigger e CollapsiblePanel; open/onOpenChange ou defaultOpen, como no web; o mesmo movimento do Accordion
ColorPicker ✔ traduz sai na raiz; controlada, e sem seta: cada amostra é um alvo de 44px com o desenho de 32 por dentro, e são seis por linha, não dez
Combobox ✔ traduz a lista abre numa folha com busca sem acento, e a folha sobe com o teclado; items na raiz, rasa ou em grupos { label, items }, não ComboboxItem por filho; loading e loadingMessage na raiz, e a busca digitada sai por onQueryChange
Command ✕ não porta paleta de comandos é gesto de mesa: um campo, uma lista e o teclado
Container ✕ não porta o celular já é mais estreito que o menor passo; o respiro lateral é o padding da tela, dentro da área segura
ContextMenu ✔ vira Menu o toque longo é o botão direito do celular: a área alvo vai como children do Menu
Conversation ✔ traduz vive em @rivocode/ui-native/ai; a lista vem por items, renderItem e keyExtractor, sobre uma FlatList invertida
CookieConsent ✕ não porta app não tem cookie; o consentimento de rastreio no celular é o aviso da plataforma, o App Tracking Transparency no iOS
CurrencyInput ✔ traduz os mesmos centavos, a mesma digitação da direita e a mesma leitura do colado; o campo é controlado
DataTable ✔ vira DataList filter, selectable, a seleção por value/onValueChange e a revalidação (isFetching, isRefetchError) portam com o mesmo nome; ordenar, pageSize e o modo servidor ficam de fora por desenho, e a lista ganha o puxar para atualizar
DatePicker ✔ traduz abre a folha com o mês; guarda ISO aaaa-mm-dd, que o web também aceita, e exibe dd/mm/aaaa; disabledDays com o nome e as formas do web tira o fim de semana e a folga do calendário da folha
DateRangePicker ✔ traduz um mês numa folha, com as duas pontas na mesma grade e em ISO aaaa-mm-dd, que o web também aceita; a peça ordena os toques, e só o intervalo fechado sai, com null no Limpar, como no web
DateTimePicker ✔ traduz dois gatilhos de folha lado a lado, o do DatePicker e o do TimePicker, com o mesmo valor único aaaa-mm-ddThh:mm do web; label anunciado por cada gatilho com a parte, e dentro de um Field vale o rótulo dele
DescriptionList ✔ traduz as bordas entram por Children: a utility de divisória do Tailwind não existe no RN; variant="boxed" com o mesmo nome e a mesma caixa do web
Dialog ✔ traduz open, onOpenChange e title como props; sem DialogTrigger. Abre em fade, e sem transição quando o sistema pede para reduzir movimento; o cartão sobe para o espaço acima do teclado
Editable ✔ traduz quem abre é o toque longo, o retorno do teclado confirma e há um Cancelar visível: sair do campo não salva, ao contrário do web
EmptyState ✔ traduz description obrigatória, pelo mesmo motivo do web; icon e illustration nos dois lados
EventCalendar ✕ não porta grade de tempo é idioma de mesa; no telefone a resposta é a lista, e o mês é o Calendar
Field ✔ traduz label, description e error como props, e o label nomeia o campo de digitar que está dentro; validate, validationMode e validationDebounceTime com o nome, a assinatura e o momento do web, e o error explícito vence o validate; o validate recebe o texto dos campos de digitar (Input, Textarea, MaskedInput, InputGroup, PasswordInput) e o valor dos que abrem folha (Autocomplete, Select, Combobox, DatePicker, DateRangePicker), e o erro é anunciado, acende a borda deles e vira a dica; nos de folha, fechar a folha é a saída do campo, e o Concluir e a tecla de envio são o envio. O texto que chega depois entra por fade; necessity com o nome do web, e no required o asterisco também se fala ("obrigatório"), porque o controle do celular não tem required que o leitor anuncie
Fieldset ✔ traduz legend como prop
FileUpload ✔ traduz vive em @rivocode/ui-native/file-upload; a área de soltar vira um botão, porque no celular não há soltar; o accept fala MIME e o tamanho sai formatado sem Intl
FilterBar ✔ traduz rola na horizontal com o limpar ancorado FORA do que rola; a linha reservada é uma altura de alvo de toque; a borda com mais escondido vira régua de 1pt, e não esmaecido
FilterChip ✔ traduz a faixa de toque tem 44pt e a pílula pintada continua com 28; size muda o desenho, nunca o alvo
Form ✔ traduz vive em @rivocode/ui-native/form; o Form entrega o submit em vez de esperar um type="submit", e há dois adaptadores a mais, o forText e o forFiles; o FormErrorSummary anuncia em vez de tomar o foco
Gantt ✕ não porta cronograma é idioma de mesa; no telefone a tarefa por dia é lista, e o prazo é o Calendar
Grid ✔ traduz columns, minItemWidth em pontos e gap; a grade mede a própria largura para contar as colunas
Heading ✔ traduz level e size com os mesmos nomes e a mesma escala; sai como Text com accessibilityRole="header", e o leitor de tela do celular não anuncia o nível
Highlight ✔ traduz sobre o Text, com o mesmo query e a mesma regra sem acento; classNames.mark como no web
IconButton ✔ traduz label obrigatório, o mesmo nome do web; o sm ganha hitSlop até 44pt de alvo; sem tooltip, porque no toque não há pousar
Illustration ✔ traduz as nove, com os mesmos nomes, name e size em @rivocode/ui-native/illustrations, sobre o react-native-svg; a cor vem de useRivo().colors
ImageViewer ✔ traduz sobre Modal e FlatList com pagingEnabled; index controlado, pinça e arrastar para baixo que fecha pelo PanResponder do core, sem peer novo; o item de vídeo toca pelo renderVideo, com o renderViewerVideo de /video; o download é só a função, e o saveToGallery de /media-library salva na galeria
Indicator ✔ traduz label é obrigatório: a pastilha é uma parada só do leitor de tela, e o que ela diz é a frase, nunca o número
Input ✔ traduz a borda acende no foco: não há focus-visible em tela de toque; onValueChange recebe o texto, como no web, e o onChangeText do TextInput continua valendo
InputGroup ✔ traduz prefix, suffix e actions são props e a moldura desenha o próprio campo; sem size
Item ✔ traduz title, description, media, actions, value e chevron como props; o corte com reticências é numberOfLines, que lá é prop e não classe
ItemGroup ✔ traduz title e footer como texto; dentro dele o Item ganha 44pt e o respiro da linha, e o Switch com texto vira a linha inteira; o valor e a seta são value e chevron do Item
Kanban ✕ não porta o quadro é idioma de mesa: a 390px cabe uma coluna, e levar o cartão a outra é um menu "Mover para", e não um arrasto
Kbd ✕ não porta não há teclado para desenhar
Link ✔ traduz Text com accessibilityRole="link"; o toque abre o href pelo Linking, e onPress é o lugar do render do web, para o router
ListDetail ✔ traduz a lista vem por items e o detalhe por renderDetail; lado a lado a partir de 840 de largura da janela, um painel por vez abaixo disso, com o voltar do Android fechando o detalhe; sem resizable; os quatro finais e o puxar para atualizar com os nomes do DataList, bottomInset, e o detalhe com detailScrollEnabled, o teclado e o renderDetailFooter
MaskedInput ✔ traduz os mesmos moldes do web (cpf, cnpj, cpfCnpj, moeda, o 9 do molde escrito à mão) e a mesma ordem do onValueChange, o limpo primeiro e o texto com máscara depois; o value é só o limpo
Menu ✔ traduz folha de baixo com actions ou content, nunca popup ancorado; grupo, separador e item marcado com os nomes do web; children abre no toque longo; classNames com trigger, content e item
Menubar ✕ não porta idioma de mesa; navegação nativa é tab bar e drawer do router
Message ✔ traduz vive em @rivocode/ui-native/ai; onCopy no lugar do copyValue, porque copiar precisa do expo-clipboard, que mora em outro caminho
MessageMedia ✔ traduz vive em @rivocode/ui-native/ai, sem o expo-video: a miniatura é a imagem do poster com o play desenhado, e o vídeo abre onde o onOpen mandar; o primeiro quadro, a proporção e a duração saem do useVideoPreview de /video, e o quadro entra pelo renderPoster
Meter ✔ traduz format como no web, e o texto pronto em valueLabel quando a medida já vem escrita; a barra anda até o valor novo
MonthPicker ✔ traduz abre a folha com o ano e os doze meses; guarda aaaa-mm, o mesmo do web, e exibe mm/aaaa
NavigationMenu ✕ não porta idioma de mesa; navegação nativa é tab bar e drawer do router
NotificationCenter ✔ traduz a lista abre numa Sheet; open é controlado, o sino entra por icon, e a linha chama onItemPress no lugar do href
NumberField ✔ traduz vira stepper (menos, valor, mais), que é o idioma do toque; min nasce em 0, e não sem piso como no web
OTPField ✔ traduz caixas visíveis, um campo escondido: teclado, autofill de SMS e leitor veem um só; o dígito aparece crescendo; label nomeia o campo
PageHeader ✔ traduz title, description, badge e actions como props; classNames com as cinco partes do web
Pagination ✕ não porta lista de celular rola; escolher o número da página é gesto de mesa
PasswordInput ✔ traduz o botão troca de nome com o estado (labels.show/labels.hide), e sair do campo esconde de novo; classNames com wrapper, input e action
PixCode ✔ traduz vive em @rivocode/ui-native/chart, junto do QRCode; o copiar entra por renderCopy, porque o Clipboard mora em outro caminho
Popconfirm ✔ vira AlertDialog vira AlertDialog; no celular a confirmação é modal e não cancela ao tocar fora
Popover ✕ não porta painel ancorado que o próprio dedo cobre: use Sheet
PostalCodeField ✔ traduz a mesma lookup e os mesmos quatro finais; o valor são os dígitos, sem a pontuação
PreviewCard ✕ não porta aparece ao pousar o ponteiro, e não há pousar no toque
Progress ✔ traduz value de 0 a 100 e label; showValue e format como no web; a barra anda até o valor novo; classNames com as quatro partes do web
PromptInput ✔ traduz vive em @rivocode/ui-native/ai; controlado (value e onValueChange obrigatórios), o envio é só pelo botão, porque a tecla de retorno do teclado do celular quebra a linha, e o ditado não porta, porque o teclado do iOS e do Android já dita
QRCode ✔ traduz vive em @rivocode/ui-native/chart, porque desenha com o react-native-svg; o codificador é o mesmo, a tinta e o papel são fixos, e só o logo se veste por parte
QueryBoundary ✔ traduz mesmos nomes e mesma ordem, isFetching e isRefetchError inclusive; texto vira string, e classNames com as seis partes do web
Questionnaire ✔ traduz controlado, com as perguntas por items (single, multiple, text); os mesmos estados e os mesmos textos, sem atalho de teclado
RadioCard ✔ traduz title, description, icon e classNames com os nomes do web, mais media, a área livre do desenho grande; controlado por checked e onCheckedChange, porque não há RadioGroup com filhos; title e description são string
RadioGroup ✔ traduz items na raiz; não existe Radio solto; label nomeia o grupo, no lugar do aria-label do web; o ponto aparece crescendo
Rating ✔ traduz um controle ajustável só para o leitor de tela, com value controlado; cada estrela tem 44pt de alvo, e o ícone entra por função
RelativeTime ✔ traduz o relógio porta, com passo por unidade e refeitura ao voltar do fundo; sem Intl, o texto é sempre numérico
ResizablePanelGroup ✕ não porta painel que se arrasta para dividir a largura é idioma de mesa; no celular cada área é uma tela do router, ou uma folha por cima
Result ✔ traduz tone, layout, illustration, actions, animated e classNames com os nomes do web; title, description e meta viram string; o foco no título vira anúncio ao montar (announceOnMount); o símbolo é feito de View, e cresce em vez de se traçar
RichTextEditor ✕ não porta editar texto formatado no toque é outro motor (WebView ou biblioteca nativa, com peer de módulo nativo) e a barra é superfície de mesa; o celular escreve com Textarea e lê o que o web salvou com RichTextView
RichTextView ✔ traduz no índice principal, sem WebView e sem peer: o mesmo leitor do web monta cada bloco como View e cada marca como Text, e o link abre pelo Linking
RivoProvider ✔ traduz theme troca em runtime só entre os dois temas de casa, e tema de cliente é decisão de BUILD; density não existe: alvo de toque não encolhe, e comfortable é a única altura; o aninhado herda o tema do de fora e nunca mexe no esquema global, que é um só no celular; e ganha fonts, que o web não tem
SaveBar ✔ traduz os mesmos open, status, savedAt e labels; onSave é obrigatório, a área segura entra por bottomInset, e o useUnsavedChanges avisa pelo usePreventRemove do Expo Router, pelo beforeRemove da navegação ou pelo voltar do Android
ScrollArea ✔ traduz a barra continua a do sistema; o que a peça traz no celular é o teclado: rola até o campo em foco e prende um footer que sobe com ele
ScrollToTop ✕ não porta a plataforma já dá: o toque na barra de status no iOS e o toque de novo na aba do router sobem a lista
SearchInput ✔ traduz value e onValueChange obrigatórios
Select ✔ traduz poucas opções fixas; items e label na raiz, e a lista abre numa folha de baixo, em seções quando items vem em grupos
Separator ✔ traduz só a linha horizontal
Sheet ✔ traduz só o comportamento de baixo, que já era o modo estreito do web, e por isso sem o size da folha de lado; sobe deslizando, e sem transição quando o sistema pede para reduzir movimento; com campo dentro, a folha sobe junto com o teclado. title é opcional, com label no lugar quando o Result toma a folha, e scrollable faz o conteúdo rolar com o título parado; arrastar o topo para baixo fecha, como no web, e swipeToClose={false} desliga o gesto
ShimmerText ✔ traduz vive em @rivocode/ui-native/ai; o brilho é a cor do texto inteiro indo de fg-muted a fg e voltando, e não a faixa que corre, porque o React Native não recorta gradiente na letra
Sidebar ✕ não porta idioma de mesa; navegação nativa é tab bar e drawer do router
SignaturePad ✔ traduz vive em @rivocode/ui-native/chart, porque desenha com o react-native-svg; o traço é o mesmo arquivo do web, o gesto é o PanResponder, e o PNG fica de fora por não haver canvas
Skeleton ✔ traduz mesma marca de lugar, mesmo token, e o mesmo pulso de 2 s; parado com reduzir movimento
Slider ✔ traduz anda por gesto e responde às ações do leitor de tela; um valor só, label obrigatório, e showValue e format como no web; classNames com as seis partes do web
SortableList ✔ traduz vive em @rivocode/ui-native/dnd, sem peer: o gesto é o PanResponder do core, e só a alça arrasta; o leitor de tela move por ações, um passo por vez
Sparkline ✔ traduz line e bar valem nos dois lados; area fica de fora (pede polígono preenchido, e o desenho nativo é View)
Spinner ✔ traduz sm, md e lg com os 16, 20 e 32 do web, e o mesmo label; o giro é o LoaderCircle do lucide, igual no iOS e no Android, e fica parado com reduzir movimento
Splitter ✕ não porta duas áreas lado a lado não cabem em tela estreita; no celular a lista e o detalhe são duas telas do router
Spoiler ✔ traduz os mesmos maxHeight, open e labels; o degradê é pintado na cor de fadeOver, porque não há máscara
Stack ✔ traduz mesmas props, menos render; o vão é a escala confortável, porque no toque não há densidade compacta
Stat ✔ traduz value já formatado, delta numérico escrito pelo deltaFormat do web, e o slot chart que a Sparkline nativa preenche; o cartão que se toca é onPress ou href, com selected
Steps ✔ traduz só o modo estreito do web (texto e barra), e por isso sem onStepChange; o useWizard() atravessa inteiro; a barra anda e o passo novo entra por fade
Switch ✔ traduz checked e onCheckedChange obrigatórios; o trilho e o pino são desenhados pela casa, iguais no iOS e no Android, e o pino desliza no movimento da casa, parado com reduzir movimento; label é o nome falado, obrigatório sem children; classNames com track, thumb e label, as partes do web
Table ✕ não porta não há tabela no celular; a consulta vira DataList
TableOfContents ✕ não porta tela de app não tem índice lateral: texto longo no celular vira seções numa lista que abre cada uma, ou Tabs
Tabs ✔ traduz só a caixinha segmentada, por items, com count para o contador de cada aba; seção de página é trabalho do router nativo; o fundo da ativa desliza entre as abas
TagsInput ✔ traduz Enter e separador digitado fecham a ficha; o Backspace com o campo vazio não porta; a ficha nova entra crescendo e a que sai some por fade
Text ✔ traduz o mesmo Text que as outras peças vestem, com size, tone, weight, truncate e lineClamp; sem tone, o do topo sai em text-fg e o aninhado herda a cor do de fora. size="display" é o degrau de 32px, o piso do text-display do web
Textarea ✔ traduz rows é a altura inicial e o campo cresce sempre, com maxRows de teto; maxLength com o contador e o anúncio perto do limite do web; onValueChange recebe o texto, como no web e no Input
TimeField ✔ traduz digita com máscara e teclado numérico; as setas viram dois botões de passo, no molde do NumberField
TimePicker ✔ traduz gatilho mais folha de baixo com duas colunas; não embute o TimeField, ao contrário do web
Timeline ✔ traduz os eventos vêm por items, com tone e pending em cada um; at é texto pronto, e cada evento é uma parada só do leitor de tela, com a posição escrita no rótulo
ToastViewport ✔ vira useToast não se monta nada: o RivoProvider já traz a fiação, e o hook é o mesmo, com as quatro funções: add devolve o id, type escolhe o tom no vocabulário do Alert, timeout: 0 deixa o aviso até o close(id), e update e promise reescrevem o aviso que está na tela. Aqui o title e a description são string, porque o aviso é lido em voz alta, e não há xis: o aviso sem botão não recebe toque, então o que fica sai pelo close. Sem timeout, ele sai em 4 segundos, e não nos 5 do web. O actionProps do web, que põe o desfazer dentro do aviso, existe aqui com onPress no lugar do onClick ({ children: "Desfazer", onPress }), e só o aviso com botão recebe toque. O aviso sobe e desce com as durações do web, e aparece parado quando o sistema pede para reduzir movimento. O tom fica no fundo, sem borda saturada, como no Alert nativo, e o aviso de tom pousa sobre a surface-raised, para o que está embaixo não aparecer através dele. O pacote não traz ícone, então não há o símbolo do tom por padrão: icon aceita um nó ou a função ({ color, size }) => <CircleX color={color} size={size} />, que recebe a cor do tom, e só com ele o título passa a fg; sem ícone, o título continua na cor do tom, porque é o único sinal além do fundo. No web o ícone do tom vem por padrão, e o título é sempre fg. O aviso aparece por cima do Modal aberto da casa (Dialog, AlertDialog, Sheet, Tour e ImageViewer): o Modal do React Native é uma janela própria e cobriria a raiz, então o aviso passa a morar no Modal de cima enquanto ele está aberto, uma vez só, e volta para a raiz quando ele fecha. Modal escrito à mão no app não leva o aviso
Toggle ✔ traduz pressed e onPressedChange
ToggleGroup ✔ traduz items na raiz, cada um com icon (e iconOnly para o botão só de ícone); multiple para vários e required para nunca ficar vazio, os mesmos nomes e o mesmo sentido do web; label dá nome ao grupo e classNames.item veste cada botão
ToolCall ✔ traduz vive em @rivocode/ui-native/ai; os mesmos cinco estados com marca e texto, a entrada e a saída em fonte mono, e aprovar e recusar fora do painel
Toolbar ✕ não porta superfície de edição de mesa: uma parada de tabulação e navegação por seta, que o toque não tem
Tooltip ✕ não porta hover não existe no toque; o rótulo precisa estar na tela
Tour ✔ traduz sobre Modal e measureInWindow, com o alvo por ref; o balão é sempre folha, que sobe para o topo quando o alvo está embaixo, o passo é controlado e não há interactive
Tracker ✔ traduz a faixa inteira é um alvo só: o dedo arrasta e o período lido aparece na linha de baixo; label de cada ponto é string
TransferList ✔ traduz as duas listas empilham, cada uma com os próprios botões de mover; os mesmos items, value e labels
Tree ✔ traduz um nível por vez, empilhado: tocar num galho empurra o nível de dentro e o cabeçalho mostra o caminho e volta; sem recuo, sem busca; como árvore de arquivos, abrir é o toque (ou o toque longo com escolha única), e não o duplo toque
TreeSelect ✔ traduz o Tree dentro de uma folha, com a contagem do rascunho e o Aplicar no rodapé; sair pela lateral desiste
VideoPlayer ✔ traduz vive em @rivocode/ui-native/video, atrás do expo-video; src aceita require e { uri, headers }, a busca é adjustable com ações de 5 segundos, e a tela cheia é a do sistema
VirtualList ✕ não porta a plataforma já virtualiza: FlatList e FlashList fazem isto de fábrica

Instalação

O pacote é privado e mora no GitHub Packages, e não no npmjs.com. Antes do primeiro npm install, o app precisa de um .npmrc na raiz que mande o escopo @rivocode para lá:

@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, exportado no ambiente — na máquina, na CI e no EAS. O .npmrc pode ir para o git, porque só carrega o nome da variável; o token não.

Depois, num app Expo:

npx expo install nativewind@preview react-native-css@rc react-native-reanimated react-native-keyboard-controller react-native-safe-area-context react-native-svg lucide-react-native
npm install -D tailwindcss @tailwindcss/postcss postcss
npm install @rivocode/ui-native
npx rivocode-ui-native-init

A última linha é a que importa: o npx rivocode-ui-native-init escreve os arquivos de configuração que o pacote exige, confere os peers e a versão do motor de CSS, e imprime o que fez. Não escreva esses arquivos à mão — cada um tem um detalhe que só aparece quebrando, e o comando é a cópia que o repositório confere contra o app de exemplo que de fato roda. Num app recém-criado pelo create-expo-app, a saída é esta:

Receita do @rivocode/ui-native em meu-app/:

  = babel.config.js       nao existe, e e assim que tem que ser
  + postcss.config.mjs    criado
  + metro.config.js       criado
  + global.css            criado
  + nativewind-env.d.ts   criado
  ~ app.json              expo.userInterfaceStyle: "light" -> "automatic"
  + package.json          browserslist adicionado
  + package.json          overrides.lightningcss adicionado

  = peers obrigatorios    os 8 estao no package.json

+ é arquivo novo, ~ é uma chave de JSON trocada com o valor antigo à vista, = é o que já estava certo, e ! é o que ele não tocou: arquivo que já existe com outro conteúdo nunca é reescrito calado, o comando termina com código 1, e só --force faz a receita vencer. --dry-run mostra o plano sem escrever nada.

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 react-native-safe-area-context é peer obrigatório desde a 6.0: o Sheet, o Dialog, o AlertDialog, o ImageViewer, o Tour e o toast cobrem a tela inteira, por cima da barra de status e da de navegação, e medem a área segura com ele em vez de adivinhar um número por sistema. Ele também vem no Expo Go, e o expo-router já monta o SafeAreaProvider; fora dele, embrulhe o app no SafeAreaProvider. Sem provider nenhum a área segura mede zero, e em desenvolvimento o console avisa.

A medida que vale é a do aparelho, e quem a guarda é o RivoProvider. Dentro de uma tela com cabeçalho, a navegação monta outro provider de área segura, e nele a faixa que o cabeçalho já cobre mede zero: um useSafeAreaInsets() ali devolve top: 0, e no Android costuma devolver bottom: 0 também. As peças desta lista cobrem a janela inteira - num Modal, ou na raiz do app, como o toast -, e por isso não usam essa medida: o RivoProvider da raiz lê a área segura antes da navegação e a entrega a elas. Monte-o no app/_layout.tsx, por fora do Stack. Se ele ficar acima de todo SafeAreaProvider, vale a medida que o aparelho deu ao abrir o app (initialWindowMetrics), e em cada borda a peça fica com a maior entre essa e a do provider mais perto.

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 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.

O react-native-css@rc anda junto: o nativewind@preview pede a versão exata da linha rc do react-native-css, e sem a tag o npm instala a latest, que fica atrás. O expo install não reclama, e o npm install seguinte morre em ERESOLVE. O comando confere a versão instalada contra a que o NativeWind pede e imprime o npx expo install certo quando elas divergem.

O que o comando escreve, e por quê

Os blocos abaixo saem do próprio comando, e não de uma cópia: é isto que ele escreve no seu app.

babel.config.js: o certo é não existir. Sem arquivo de Babel, o Expo cai no babel-preset-expo sozinho e liga o plugin de worklets junto. Escrever um à mão com presets: ["babel-preset-expo"] derruba o app no SDK 57, com MODULE_NOT_FOUND antes do primeiro módulo. Se o seu já tem um, o comando o mantém e acusa pelo nome as duas linhas da receita v4 do NativeWind que não valem mais: jsxImportSource: "nativewind" e o preset nativewind/babel.

postcss.config.mjs. É ele que faz o Tailwind rodar no passe de CSS do metro; sem ele a tela renderiza sem estilo, sem erro e sem pista:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

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

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

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

app.json. Sem esta chave o iOS prende a aparência no claro e o tema escuro nunca chega. O template do Expo nasce em "light", então é a chave que o comando quase sempre troca:

"expo": { "userInterfaceStyle": "automatic" }

package.json. Duas chaves:

"browserslist": ["chrome 130", "safari 18", "firefox 130"],
"overrides": { "lightningcss": "1.30.1" }

O browserslist 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.

O override fixa o lightningcss, e é o que fecha o bundle de iOS e Android: da 1.31 em diante o compilador do react-native-css quebra com "expected an object-like struct named Specifier, found ()" já numa borda tracejada. A chave depende do gerenciador, e o comando escolhe pelo lockfile que achar:

  • npm e bun: overrides.lightningcss
  • yarn: resolutions.lightningcss
  • pnpm: pnpm.overrides.lightningcss

Ele só vale depois de instalar de novo, e o comando lembra disso no fim.

global.css. A fonte do CSS:

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

@source "./src";
@source "./node_modules/@rivocode/ui-native/src";
@source not "./**/*.md";

@source not inline("shadow");
@source not inline("invert");
@source not inline("filter");
@source not inline("transform");

O @source da primeira linha segue onde o app guarda o código, e o init escolhe pelo que acha na pasta: ./src no template atual do create-expo, com as rotas em src/app/; ./app e ./components no template anterior, com as rotas na raiz; e ./App.tsx só quando não há pasta nenhuma, como no template em branco.

A linha @source not "./**/*.md" tira o Markdown da varredura automática do Tailwind, que lê a pasta inteira do app e não só o que o @source lista. Sem ela, a skill que o rivocode-ui skill instala em .claude/, o AGENTS.md do template e qualquer README com exemplo do pacote web viram classe de verdade, como h-[var(--rc-control-md)], e o rivocode-ui-native-css morre com "vars usadas sem declaracao" por uma var que só existe no web.

As quatro últimas linhas não são higiene: o scanner do Tailwind lê o código como texto, e shadow, invert, filter e transform aparecem no TypeScript das peças como chave e nome de prop, nunca como className. .shadow redeclara --tw-shadow, e var declarada duas vezes derruba o compilador nativo.

O app não importa o global.css: importa o pré-compilado, que não sai do init porque depende do seu código.

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.

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

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

declare module "*.css";

O sintoma, sem ele, é 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. A segunda linha é do generated.css, que o arquivo de entrada importa no topo.

Não o coloque no .gitignore: sem ele versionado, o erro volta a cada clone, no tsc da CI ou no editor de quem acabou de baixar o projeto.

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>
  );
}

Com o expo-router não existe App.tsx: o import e o RivoProvider vão no app/_layout.tsx, em volta do que ele devolve, e o caminho sobe até a raiz do app (import "../../generated.css" no src/app/_layout.tsx do template novo). O provider não mora dentro da pasta de rotas: todo arquivo ali vira tela. O rivocode-ui create --base expo já escreve assim: um providers.tsx ao lado da pasta de rotas, com o RivoProvider em system e, com a camada de dados, o QueryClientProvider dentro, e o _layout.tsx do template embrulhado inteiro, com o splash e as abas que ele trazia.

  • 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.

Conferir o app inteiro: rivocode-ui-native-doctor

npx rivocode-ui doctor

O pacote nativo também instala o comando rivocode-ui, com o mesmo nome do web: no celular ele entende doctor, init, css, theme e skill, e é o mesmo que npx rivocode-ui-native-doctor e os outros. O create continua no pacote web. O doctor confere a receita arquivo por arquivo, com o mesmo plan do init e sem escrever nada, os peers obrigatórios, a versão do motor de CSS, o .npmrc, se o generated.css existe e não ficou mais velho que o global.css, e, no arquivo de entrada (src/app/_layout.tsx, app/_layout.tsx ou App.tsx), se o generated.css é o primeiro import e se o RivoProvider é montado ali ou num arquivo local que ele importa. Com o @tanstack/react-query nas dependências, cobra o QueryClientProvider também. Sai com código 1 quando acha falha.

Ele confere também a cópia da skill: a que estiver em .claude/skills e em .agents/skills (ou, onde o projeto não tem a dele, na sua pasta pessoal) precisa ser a do @rivocode/ui-native instalado. O rivocode-ui skill grava de onde a cópia veio num .rivocode-version ao lado do SKILL.md, e cópia de outra versão, de outro pacote ou sem a marca é aviso, com o comando exato que a troca. É aviso, e não falha: o app roda igual, quem erra é o agente.

A skill e o agente viajam dentro do pacote nativo, na versão dele, e o comando tem as mesmas opções do web:

npx rivocode-ui skill                  # Claude Code: .claude/skills e .claude/agents
npx rivocode-ui skill --para codex     # ou copilot, gemini, cursor, todos
npx rivocode-ui skill --global --mcp   # na pasta pessoal, e o servidor @rivocode/ui-mcp

Rode de novo a cada atualização do pacote: o comando apaga a cópia antiga antes de escrever a nova.

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 "./src";
@source "./node_modules/@rivocode/ui-native/src";
@source not "./**/*.md";
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
npx rivocode-ui-native-theme acme.ts --ajustar   # move o mínimo a cor que reprova, e diz quanto

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 "./src";
@source "./node_modules/@rivocode/ui-native/src";
@source not "./**/*.md";
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.

Quando quem reprova é uma cor que você escreveu, a recusa traz a cor sugerida para ela e termina com "Rode de novo com --ajustar para mover o minimo". Com --ajustar, a semente anda o mínimo na luminosidade OKLCH, com a mesma matiz e o mesmo croma, o papel derivado que reprova anda também, e o tema é escrito; o bloco "Sementes ajustadas por --ajustar:" diz cada antes -> depois e o contraste de cada par que reprovava. É o mesmo --ajustar do rivocode-ui theme do web, pelo mesmo módulo. Se nem movendo a semente o par passa, o comando diz qual par e quais sementes tentou, e não escreve nada.

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. A única matiz nova é a da série de gráfico, e ela sai da sua marca:

Papéis De onde saem
surface-raised igual a surface
fg-muted, fg-subtle, fg-disabled fg puxado 30%, 38% e 55% para o bg
border, border-strong, border-disabled, border-hover, skeleton, overlay alfa de fg na escada da casa
accent-hover, accent-active accent um passo para o claro e um para o escuro
accent-subtle, selected, os quatro *-subtle alfa da cor correspondente
accent-fg e os quatro *-fg o tom de fg/bg que pesa mais sobre o preenchimento, e o branco ou o preto puro quando nenhum dos dois alcança 4,5:1
ring igual a accent-text
chart-1 a chart-8 chart-1 igual a accent-text; as outras giram a matiz dele na OKLCH, a 3:1 sobre o seu fundo

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 saem da sua marca. A primeira é o próprio accent-text, e as outras sete giram a matiz dele na OKLCH, 135 graus de uma para a seguinte, com croma bastante para se distinguirem e a luminosidade empurrada para longe do fundo até 3:1 contra bg e surface. É a única matiz que o comando inventa, e a razão é que um tema de cliente com a série da RivoCode desenha o gráfico com o lima de outra marca. Escreva as oito na paleta se a marca tiver uma série própria.

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, que é peer obrigatório desde a 6.0 e já entra na primeira linha da instalaçã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. As peças da biblioteca também desenham com ele - o visto do Checkbox, os chevrons do Calendar, a estrela do Rating, o xis do Alert -, o mesmo ícone que a peça irmã do web usa. Nenhum ícone é desenhado à mão, com View, caractere ou SVG próprio; outro conjunto só entra quando o lucide não tem o desenho.

A cor não desce da View para o SVG: passe color com o papel do tema, lido de useRivo().colors, ou use a forma de função das peças que recebem ícone, que já entregam a cor e o tamanho.

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.
  • Ícone desenhado à mão - caractere (✓, ›, ★, −), View girada ou SVG próprio: o ícone vem do lucide-react-native, o mesmo nome do web.
  • 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.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.