📋 Sobre o Projeto

Este é o repositório do Design System em React Native desenvolvido para o projeto Sebrae Na Palma da Mão. O objetivo é fornecer uma biblioteca de componentes reutilizáveis que seguem os padrões visuais e de interação do Sebrae, garantindo consistência e eficiência no desenvolvimento do aplicativo principal.

🧭 Princípios do Design System

• Composition Pattern: componentes devem priorizar composição sobre herança, com subcomponentes acessados via Parent.Child quando fizer sentido.
• Tokenização obrigatória: cores, tipografia, surfaces, bordas, elevações e demais aspectos visuais devem nascer em components/styles/tokens/.
• Sem hardcodes visuais estruturais: componentes não devem declarar diretamente color, backgroundColor, borderColor, fontFamily, fontSize, fontWeight, shadow* ou elevation fora do sistema de tokens.
• Tipografia centralizada: a família atual é Figtree, com adaptação entre iOS e Android encapsulada no domínio de tipografia do Design System.

Referências diretas:

• Tokens por aspecto: components/styles/tokens/
• Entry point compatível: components/styles/tokens.ts
• Tipografia centralizada: typography.ts
• Texto padronizado: Typography/RichText/index.js
• Base compatível de tipografia: Typography/SEText/index.js
• Regras do projeto: AGENTS.md

✅ Requisitos

• Node.js >= 18 (package.json)
• React 19 e React Native 0.79 (peer/dev deps)
• Yarn ou npm/pnpm instalado
• Xcode (iOS) e Android SDK/Java (Android)

🔧 Instalação

yarn
# ou
npm install

🎨 Componentes Disponíveis

• Exportados via src/index.ts
• Histórias em *.stories.(jsx|tsx) ao lado de cada componente
• Veja a lista completa em components/ ou rode o Storybook

Padrão de construção esperado:

• Componentes novos devem seguir composição e contexto quando houver partes acopladas semanticamente.
• Tipografia deve ser aplicada com RichText, SEText compatível ou via tokens.textStyles/tokens.typography.
• Estilos estáticos devem usar StyleSheet.create e tokens semânticos.

Exemplos de componentes:

• Accordion, Button, Checkbox, FilterTag, Input, Modal, Navbar, Pagination, Datepicker, Dropdown, Card, Toast, Typography, SEIcon, RichText, SEText, e muitos outros.

🚀 Como Usar

1. Instale as dependências (acima).

2. Execute o Storybook (nativo):

Para iOS:

yarn storybook:ios

Para Android:

yarn storybook:android

3. Execute o Storybook (web):

yarn storybook:web
# abre em http://localhost:6006

4. Gerar histórias automaticamente (opcional):

yarn storybook-generate

📚 Storybook

Cada componente possui sua própria história no Storybook, permitindo visualizar e testar diferentes estados e propriedades. As histórias estão localizadas junto aos componentes com o padrão de nomenclatura *.stories.(jsx|tsx).

• Nativo: storybook:ios e storybook:android
• Web: storybook:web (@storybook/react-native-web-vite)

As stories devem refletir o contrato real dos componentes e demonstrar:

• Uso básico
• Variações semânticas
• Estados visuais importantes
• Exemplos aderentes aos tokens do projeto

🎯 Tokens e Estilo

O projeto adota um sistema central de design tokens por aspecto. A estrutura atual fica em components/styles/tokens/ e está organizada em módulos como:

• palette
• colors
• surfaces
• elevations
• spacing e space
• typography
• radius
• borders
• opacity

Como consumir

Entrada principal compatível:

import tokens from 'vpt-sebraeds/components/styles/tokens'

Uso recomendado em componentes:

import { StyleSheet, View } from 'react-native'
import RichText from 'vpt-sebraeds/components/Typography/RichText'
import tokens from 'vpt-sebraeds/components/styles/tokens'

const styles = StyleSheet.create({
  card: {
    backgroundColor: tokens.colors.surface.default,
    borderColor: tokens.colors.border.default,
    borderRadius: tokens.radius.sm,
    borderWidth: tokens.borders.width.thin,
    padding: tokens.space.md,
    ...tokens.elevations[1],
  },
})

export function ExemploTokenizado() {
  return (
    <View style={styles.card}>
      <RichText type="ns-heading-5">Título</RichText>
      <RichText type="ns-sm-body" color={tokens.colors.text.secondary}>
        Conteúdo seguindo os tokens do projeto
      </RichText>
    </View>
  )
}

Regras importantes

• Componentes devem consumir tokens semânticos, não palette.
• Se um valor visual ainda não existir, ele deve ser adicionado primeiro em components/styles/tokens/.
• A diferença tipográfica entre iOS e Android já está encapsulada em tokens/typography.ts.
• colors.js, fonts.js e utilitários antigos existem apenas como camadas de compatibilidade durante a migração.

🧩 Composition Pattern

O padrão preferencial para novos componentes é composição. Quando um componente possui partes relacionadas entre si, ele deve expor subcomponentes e, se necessário, compartilhar configuração via Context.

Exemplo conceitual:

<Card>
  <Card.Header>
    <RichText type="ns-heading-5">Título</RichText>
  </Card.Header>
  <Card.Body>
    <RichText type="ns-sm-body">Conteúdo</RichText>
  </Card.Body>
</Card>

Boas práticas:

• Expor partes via Parent.Child, e não como exports avulsos.
• Compartilhar estilos/configuração por Context quando isso reduzir acoplamento.
• Compor estilos na ordem [baseStyle, contextStyle, propStyle].
• Evitar sobrecarga de props quando a composição resolve melhor a API.

🔗 Integração com o Projeto Principal

Este Design System é um artefato do projeto principal [Sebrae Na Palma da Mão], um aplicativo móvel que funciona como uma agência do Sebrae na palma da mão. O aplicativo principal inclui diversas funcionalidades como:

• Integração com redes sociais
• Recursos de geolocalização e mapas
• Funcionalidades de câmera e scanner QR Code
• Recursos de compartilhamento e calendário
• Suporte a chat e preview de links
• E muito mais

Instalação do React Design System (via Git + branch)

Instale diretamente a partir do repositório Git (escolha a branch conforme sua necessidade: main, develop, feature/...).

• Repositório: [email protected]:na/java/na-palma-da-mao/app-sebrae-react-ds.git

Compatibilidade mínima:

• Node.js 18+ (recomendado 20+)
• React 18 ou 19

Comandos (SSH):

# yarn
yarn add git+ssh://[email protected]/na/java/na-palma-da-mao/app-sebrae-react-ds.git#develop

Outras branches:

# main
yarn add git+ssh://[email protected]/na/java/na-palma-da-mao/app-sebrae-react-ds.git#main

# develop
yarn add git+ssh://[email protected]/na/java/na-palma-da-mao/app-sebrae-react-ds.git#develop

# feature (com barra, use aspas)
yarn add "git+ssh://[email protected]/na/java/na-palma-da-mao/app-sebrae-react-ds.git#feature/minha-feature"

Via package.json:

{
  "dependencies": {
    "vpt-sebraeds": "git+ssh://[email protected]/na/java/na-palma-da-mao/app-sebrae-react-ds.git#main"
  }
}

Observação: nesta biblioteca, o campo "name" é vpt-sebraeds.

Dependências e pós-instalação:

• Instale todos os peerDependencies declarados pelo Design System (ex.: react, react-dom, bibliotecas de estilo/animação se aplicável). Verifique o package.json do repositório.
• Configure a fonte Figtree no app consumidor. Veja FONTES_CONFIGURACAO.md.

Exemplo de uso:

import { Button } from 'vpt-sebraeds'

export function Exemplo() {
  return <Button variant="primary">Confirmar</Button>
}

Troubleshooting (GitLab/SSH):

• Permission denied (publickey):
  • Gere/adicione sua chave SSH ao GitLab (ssh-keygen -t rsa), inicie o agente (eval \"$(ssh-agent -s)\") e ssh-add ~/.ssh/id_rsa.
  • Teste: ssh -T [email protected].
• Host key verification failed:
  • Adicione o host: ssh-keyscan -H gitlab.sebrae.com.br >> ~/.ssh/known_hosts.
• Sem permissão ao repositório:
  • Verifique se seu usuário/grupo possui acesso ao projeto no GitLab ou solicite um Deploy Key.
• Ambiente CI/CD:
  • Configure a variável SSH_PRIVATE_KEY e injete-a no pipeline; adicione known_hosts do GitLab antes de yarn install.
• Alternativa HTTPS + Token Pessoal (quando SSH indisponível):
  • yarn add "https://oauth2:<PERSONAL_ACCESS_TOKEN>@gitlab.sebrae.com.br/na/java/na-palma-da-mao/app-sebrae-react-ds.git#main"
  • Mantenha o token fora do controle de versão e variáveis de ambiente seguras.

Consumo dos componentes

Após publicar/compilar, importe os componentes diretamente do pacote (ou via path local no monorepo):

import { Button, Modal, Typography } from 'vpt-sebraeds';

Os exports estão definidos em src/index.ts.

🧪 Testes e Qualidade

• Linter:

yarn lint

• Testes:

yarn test

🏗️ Build e Publicação

• Build TypeScript + cópia de assets:

yarn build
# tsc + [scripts/copy-assets.js](file:///Users/tegra/sebrae/storybook/dev/scripts/copy-assets.js)

• Build Android (release apk do app de Storybook):

yarn build-android
# [scripts/build-android.sh](file:///Users/tegra/sebrae/storybook/dev/scripts/build-android.sh)

• Publicação (pré-publish roda o build automaticamente):

yarn publish
# ou npm publish (verifique acesso/registro)

🗂️ Estrutura do Projeto

• components/ – componentes e histórias
• components/styles/tokens/ – design tokens por aspecto
• components/styles/tokens.ts – porta de entrada compatível para tokens
• src/ – ponto de entrada e exports da biblioteca
• assets/ – imagens, ícones e fontes
• .rnstorybook/ e .storybook/ – configs de Storybook nativo e web
• scripts/ – automações de build

🔤 Fontes

Guia completo de configuração de fontes: FONTES_CONFIGURACAO.md

🤝 Contribuição

Antes de adicionar novos componentes ou fazer modificações:

1. Verifique se o componente segue os padrões visuais do Sebrae
2. Adicione a documentação apropriada no Storybook
3. Teste o componente em diferentes dispositivos
4. Certifique-se de que as alterações não quebram a compatibilidade com o projeto principal
5. Use tokens semânticos em vez de hardcodes visuais
6. Adote composição quando a estrutura do componente pedir subpartes reutilizáveis
7. Mantenha o estilo de código (ESLint/Prettier) e exports em src/index.ts

📝 Licença

Este projeto está sob a licença MIT.