React Native
O mesmo vocabulário no celular, com tema que troca em runtime.
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-lightousystem, que segue o aparelho. Entre os dois temas de casa, trocar a prop troca a tela inteira em runtime: essas cores foram compiladas comolight-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, ecomfortableé a única altura.- O
useToastjá 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]) outranslate-*: o compilador do react-native-css atual não tolera var viva nem a shorthandtranslate. Altura de controle é fixa por tamanho. - Remover o
browserslistmoderno dopackage.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 (
✓,›,★,−),Viewgirada ou SVG próprio: o ícone vem dolucide-react-native, o mesmo nome do web. - Esquecer
accessibilityRole/accessibilityStateem 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.