Design System Mobile - TellusCompany

Biblioteca de componentes oficial da TellusCompany para desenvolvimento de interfaces consistentes e escaláveis especificamente para aplicações mobile React Native baseada em NativeWind e Tailwind CSS.

🎯 Características

• 📱 Mobile First: Otimizado exclusivamente para React Native
• 🔧 TypeScript: Tipagem completa para melhor experiência de desenvolvimento
• 🎨 NativeWind: Powered by Tailwind CSS para styling consistente
• 🧩 RN Primitives: Componentes base acessíveis e customizáveis
• 🌙 Temas: Suporte nativo a light/dark mode com sistema de cores avançado
• 🎨 Customização: Temas totalmente personalizáveis via Tailwind
• ⚡ Performance: Build otimizado e tree-shaking automático
• 🧪 Testes: Cobertura completa com Jest e Testing Library
• 📦 Build: Distribuição otimizada para npm
• 🔍 Linting: ESLint + Prettier para qualidade de código

🚀 Instalação

npm install @telluscompany/design-system-mobile
# ou
yarn add @telluscompany/design-system-mobile
# ou
pnpm add @telluscompany/design-system-mobile

Configuração do NativeWind

Configure o NativeWind seguindo a documentação oficial:

🎯 Uso Básico

Usando Componentes

import React from "react";
import { Text } from "@telluscompany/design-system-mobile";
import { View } from "react-native";

export function MyScreen() {
  return (
    <View className="flex-1 bg-background p-4 justify-center items-center">
      <Text variant="h1" className="text-text-primary mb-4">
        Welcome to our app!
      </Text>
      <Text variant="default" className="text-text-secondary text-center">
        Built with TellusCompany Design System
      </Text>
    </View>
  );
}

� Sistema de Cores e Tokens

🌈 Paleta de Cores

🔵 Cores Base

| Token | Light Mode | Dark Mode | Descrição | | ------------ | ---------- | --------- | ------------------------------------- | | background | #ffffff | #0a0a0b | Fundo principal da aplicação | | foreground | #0a0a0b | #f6f7fa | Primeiro plano e elementos principais | | border | #e4e4e7 | #27272a | Bordas e divisores |

Cores Primárias

| Token | Light Mode | Dark Mode | Uso Recomendado | | -------------------- | ---------- | --------- | ----------------------------------- | | primary | #957341 | #c0ab8d | Botões principais, links ativos | | primary-foreground | #f6f7fa | #171717 | Texto sobre cor primária | | primary-lighter | #f5f1eb | #1d170d | Fundos sutis, highlights | | primary-light | #e0d5c5 | #5a4527 | Elementos secundários, hover states | | primary-dark | #5a4527 | #e0d5c5 | Elementos de contraste | | primary-darker | #1d170d | #f5f1eb | Textos de alta hierarquia |

Cores Secundárias

| Token | Light Mode | Dark Mode | Uso Recomendado | | ---------------------- | ---------- | --------- | -------------------------- | | secondary | #e0d5c5 | #5a4527 | Botões secundários, cards | | secondary-foreground | #171717 | #f6f7fa | Texto sobre cor secundária |

Cores de Estado

| Token | Cor | Uso | | --------------- | --------- | ------------------------------- | | success | #78bf71 | Confirmações, estados positivos | | success-light | #caf1c6 | Fundos de sucesso | | success-dark | #224d1e | Textos de sucesso | | warning | #ffa700 | Avisos, estados de atenção | | warning-light | #ffeabf | Fundos de aviso | | warning-dark | #a16000 | Textos de aviso | | error | #ec5444 | Erros, estados críticos | | error-light | #ffded8 | Fundos de erro | | error-dark | #781a12 | Textos de erro |

Cores de Texto

| Token | Light Mode | Dark Mode | Hierarquia | | ---------------- | ---------- | --------- | ------------------------------ | | text-primary | #37393f | #f6f7fa | Títulos, textos principais | | text-secondary | #1a1c21 | #692d21 | Subtítulos, textos secundários | | text-disabled | #e0e1e3 | #808389 | Textos desabilitados |

Como Usar os Tokens

Com NativeWind/Tailwind CSS

import { View, Text } from 'react-native';

// Fundos
<View className="bg-background" />        // Fundo principal
<View className="bg-primary" />           // Fundo primário
<View className="bg-secondary" />         // Fundo secundário
<View className="bg-primary-light" />     // Fundo primário claro

// Textos
<Text className="text-text-primary" />   // Texto principal
<Text className="text-text-secondary" /> // Texto secundário
<Text className="text-primary" />        // Texto na cor primária

// Bordas
<View className="border border-border" />     // Borda padrão
<View className="border border-primary" />    // Borda primária

// Estados
<View className="bg-success" />          // Fundo de sucesso
<View className="bg-warning" />          // Fundo de aviso
<View className="bg-error" />            // Fundo de erro

Exemplo Prático

import React from "react";
import { Pressable, Text, View } from "react-native";

export function NotificationCard({ type, title, message }) {
  const getBackgroundColor = () => {
    switch (type) {
      case "success":
        return "bg-success-light";
      case "warning":
        return "bg-warning-light";
      case "error":
        return "bg-error-light";
      default:
        return "bg-primary-lighter";
    }
  };

  const getTextColor = () => {
    switch (type) {
      case "success":
        return "text-success-dark";
      case "warning":
        return "text-warning-dark";
      case "error":
        return "text-error-dark";
      default:
        return "text-primary-dark";
    }
  };

  return (
    <View className={`p-4 rounded-lg ${getBackgroundColor()}`}>
      <Text className={`font-bold mb-2 ${getTextColor()}`}>{title}</Text>
      <Text className="text-text-secondary">{message}</Text>
    </View>
  );
}

Modo Escuro Automático

O sistema de cores adapta-se automaticamente ao tema do dispositivo:

import { useColorScheme } from "nativewind";

export function ThemeToggle() {
  const { colorScheme, setColorScheme } = useColorScheme();

  return (
    <Pressable
      onPress={() => setColorScheme(colorScheme === "dark" ? "light" : "dark")}
      className="bg-primary p-4 rounded-lg"
    >
      <Text className="text-primary-foreground text-center">
        Alternar para tema {colorScheme === "light" ? "escuro" : "claro"}
      </Text>
    </Pressable>
  );
}

🛠️ Desenvolvimento

Comandos Disponíveis

# Instalar dependências
pnpm install

# Desenvolvimento (Expo)
pnpm start          # Inicia o servidor Expo
pnpm android        # Roda no Android
pnpm ios           # Roda no iOS
pnpm web           # Roda na web

# Build da biblioteca
pnpm build

# Testes
pnpm test
pnpm test:ci

# Linting
pnpm lint
pnpm lint:fix

# Type checking
pnpm type-check

⚠️ Notas Importantes

• tw utility: O utilitário tw é apenas para uso interno do design system. Em sua aplicação, use className.
• NativeWind: Certifique-se de configurar o NativeWind corretamente em seu projeto para que os estilos funcionem.

📱 Compatibilidade

• React Native: ≥0.72
• React: ≥18.0.0
• TypeScript: ≥4.5.0
• NativeWind: ≥4.0.0
• Tailwind CSS: ≥3.4.0
• iOS: 11+
• Android: API 21+ (Android 5.0)

🚀 Dependências Principais

• NativeWind: Sistema de styling baseado em Tailwind CSS
• @rn-primitives: Componentes primitivos acessíveis
• @react-navigation/native: Navegação e theming
• class-variance-authority: Variants de componentes
• tailwind-variants: Utilitários avançados do Tailwind

Licença

Este projeto é privado e de uso exclusivo da TellusCompany.