@xetwa/design-system 1.0.2

package/src/GrelhaLayout.mdx

@@ -0,0 +1,375 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand Guidelines/Grelha & Layout" />
+
+# Grelha & Layout
+
+O layout do **Xetlingo** foi desenhado para garantir que a interface seja adaptável, organizada e acessível tanto em dispositivos móveis quanto em desktops e tablets. O nosso sistema baseia-se numa grelha fluida estruturada por colunas e limites máximos de conteúdo.
+
+---
+
+## 📐 Regras de Grelha
+
+* **Mobile (xs a md)**: Grelha de **4 colunas** com gutter adaptável. O conteúdo principal estende-se até às margens laterais seguras.
+* **Desktop (xl a xxxl)**: Grelha de **12 colunas**. Para evitar esticamento excessivo em ecrãs ultra-wide, o conteúdo principal é centrado e limitado a um `max-width` de **1200px** com padding horizontal de **48px**.
+
+---
+
+## 📱 Áreas de Layout (Mobile)
+
+A estrutura vertical em telemóveis divide-se em zonas específicas para garantir uma navegação ergonómica e sem sobreposição de elementos do sistema operacional:
+
+<div style={{
+  backgroundColor: 'var(--bg-surface)',
+  border: '1px solid var(--border-color)',
+  borderRadius: '16px',
+  padding: '1.5rem',
+  boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.05), 0 2px 4px -1px rgba(0, 0, 0, 0.03)',
+  marginBottom: '2.5rem',
+  marginTop: '1.5rem'
+}}>
+  <table style={{
+    width: '100%',
+    borderCollapse: 'collapse',
+    textAlign: 'left'
+  }}>
+    <thead>
+      <tr style={{
+        borderBottom: '2px solid var(--border-color)',
+      }}>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Zona</th>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Altura</th>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Notas de Implementação</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Status bar (sistema)</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>44–54px</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Espaço nativo do OS. Nunca colocar conteúdo interativo ou textos da app aqui.
+        </td>
+      </tr>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Navigation header</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>52px</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Contém o logótipo/título e botões de ação. Adicionar <strong>safe area top</strong> (ex: +16px ou mais no iPhone com notch).
+        </td>
+      </tr>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Conteúdo scrollável</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem' }}>flex: 1</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Área de conteúdo dinâmico. Ocupa todo o espaço vertical intermédio (com <code style={{ fontSize: '0.8rem' }}>overflow-y: auto</code> na web).
+        </td>
+      </tr>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Bottom tab bar</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>56px</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Barra inferior de abas. Contém de 4 a 5 ícones com respetiva label de 10px (<code style={{ fontSize: '0.8rem' }}>caption</code>) posicionada por baixo.
+        </td>
+      </tr>
+      <tr>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Safe area bottom (iPhone)</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>0–34px</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Nativo do OS. Usar <code style={{ fontSize: '0.8rem' }}>env(safe-area-inset-bottom)</code> para empurrar o conteúdo clicável e evitar conflito com o indicador de home do iOS.
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+---
+
+## 💻 Áreas de Layout (Desktop & Tablet)
+
+Em ecrãs maiores, o layout estende-se lateralmente para melhor aproveitamento do espaço horizontal:
+
+<div style={{
+  backgroundColor: 'var(--bg-surface)',
+  border: '1px solid var(--border-color)',
+  borderRadius: '16px',
+  padding: '1.5rem',
+  boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.05), 0 2px 4px -1px rgba(0, 0, 0, 0.03)',
+  marginBottom: '2.5rem'
+}}>
+  <table style={{
+    width: '100%',
+    borderCollapse: 'collapse',
+    textAlign: 'left'
+  }}>
+    <thead>
+      <tr style={{
+        borderBottom: '2px solid var(--border-color)',
+      }}>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Zona</th>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Largura / Altura</th>
+        <th style={{ padding: '10px 16px', fontSize: '0.75rem', fontWeight: '700', color: 'var(--text-secondary)', textTransform: 'uppercase', letterSpacing: '0.05em' }}>Notas de Implementação</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Sidebar nav (desktop)</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>220px largura</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Menu lateral fixo (<code style={{ fontSize: '0.8rem' }}>position: sticky; top: 0</code>). Contém o logótipo no topo e grupos de navegação com ícone + label horizontal.
+        </td>
+      </tr>
+      <tr style={{ borderBottom: '1px solid var(--border-color)' }}>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Top nav bar (tablet)</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>64px altura</code> / <code style={{ fontSize: '0.8rem' }}>100% largura</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Barra superior de navegação para tablets em modo retrato ou paisagem estreito. Logótipo à esquerda, abas centrais e ações à direita.
+        </td>
+      </tr>
+      <tr>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', fontWeight: '600', color: 'var(--text-primary)' }}>Conteúdo principal</td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          <code style={{ fontSize: '0.8rem', color: '#cf7a30', backgroundColor: '#fef6ee', padding: '2px 6px', borderRadius: '4px' }}>max-width: 1200px</code>
+        </td>
+        <td style={{ padding: '12px 16px', fontSize: '0.9rem', color: 'var(--text-primary)' }}>
+          Área de trabalho/estudo centralizada. Aplica <code style={{ fontSize: '0.8rem' }}>padding: 48px h</code> lateral. A grelha interna de 12 colunas fica restrita dentro deste limite.
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+---
+
+## 🎨 Esqueleto Visual dos Layouts
+
+Compara visualmente a anatomia de ecrãs estruturada em **Mobile** e **Desktop**:
+
+<div style={{
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: '2.5rem',
+  marginTop: '1.5rem',
+  marginBottom: '2.5rem'
+}}>
+
+  {/* Mobile Skeleton Mockup */}
+  <div style={{
+    flex: '1 1 300px',
+    maxWidth: '360px',
+    border: '4px solid #51332d',
+    borderRadius: '32px',
+    height: '600px',
+    backgroundColor: 'var(--bg-app)',
+    display: 'flex',
+    flexDirection: 'column',
+    overflow: 'hidden',
+    position: 'relative',
+    boxShadow: 'var(--shadow-lg)'
+  }}>
+    {/* Status Bar */}
+    <div style={{
+      height: '44px',
+      backgroundColor: 'rgba(81, 51, 45, 0.08)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      padding: '0 20px',
+      fontSize: '0.75rem',
+      fontWeight: 'bold',
+      color: 'var(--text-secondary)',
+      borderBottom: '1px dashed var(--border-color)',
+    }}>
+      <span>9:41</span>
+      <span style={{ fontSize: '0.65rem' }}>🔋 📶</span>
+    </div>
+    
+    {/* Navigation Header */}
+    <div style={{
+      height: '52px',
+      backgroundColor: 'var(--bg-surface)',
+      borderBottom: '2px solid var(--border-color)',
+      display: 'flex',
+      alignItems: 'center',
+      padding: '0 16px',
+      gap: '12px'
+    }}>
+      <div style={{ width: '28px', height: '28px', borderRadius: '50%', backgroundColor: '#f2974b', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#fff', fontSize: '0.7rem' }}>⬅</div>
+      <div style={{ fontFamily: 'var(--font-title)', fontWeight: 'bold', fontSize: '1rem', color: 'var(--text-primary)' }}>Xetlingo</div>
+      <div style={{ marginLeft: 'auto', fontSize: '1.1rem' }}>🔥 5</div>
+    </div>
+    
+    {/* Scrollable Content Mock */}
+    <div style={{
+      flex: 1,
+      padding: '16px',
+      overflowY: 'auto',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '12px'
+    }}>
+      <div style={{ backgroundColor: 'var(--bg-surface)', border: '1px solid var(--border-color)', borderRadius: '12px', padding: '12px', boxShadow: 'var(--shadow-xs)' }}>
+        <div style={{ width: '40%', height: '14px', backgroundColor: 'var(--border-color)', borderRadius: '4px', marginBottom: '8px' }} />
+        <div style={{ width: '90%', height: '10px', backgroundColor: 'var(--border-color)', opacity: 0.6, borderRadius: '4px', marginBottom: '6px' }} />
+        <div style={{ width: '75%', height: '10px', backgroundColor: 'var(--border-color)', opacity: 0.6, borderRadius: '4px' }} />
+      </div>
+      <div style={{ backgroundColor: 'var(--bg-surface)', border: '1px solid var(--border-color)', borderRadius: '12px', padding: '12px', boxShadow: 'var(--shadow-xs)' }}>
+        <div style={{ width: '50%', height: '14px', backgroundColor: 'var(--border-color)', borderRadius: '4px', marginBottom: '8px' }} />
+        <div style={{ width: '85%', height: '10px', backgroundColor: 'var(--border-color)', opacity: 0.6, borderRadius: '4px' }} />
+      </div>
+      
+      {/* Visual columns indicator overlay */}
+      <div style={{ marginTop: 'auto', display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: '10px', opacity: 0.25 }}>
+        <div style={{ height: '50px', backgroundColor: '#f2974b', borderRadius: '4px' }} />
+        <div style={{ height: '50px', backgroundColor: '#f2974b', borderRadius: '4px' }} />
+        <div style={{ height: '50px', backgroundColor: '#f2974b', borderRadius: '4px' }} />
+        <div style={{ height: '50px', backgroundColor: '#f2974b', borderRadius: '4px' }} />
+      </div>
+    </div>
+    
+    {/* Bottom Tab Bar */}
+    <div style={{
+      height: '56px',
+      backgroundColor: 'var(--bg-surface)',
+      borderTop: '2px solid var(--border-color)',
+      display: 'grid',
+      gridTemplateColumns: 'repeat(4, 1fr)',
+      alignItems: 'center',
+      justifyItems: 'center'
+    }}>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center' }}>
+        <span style={{ fontSize: '1.2rem', color: '#f2974b' }}>🏠</span>
+        <span style={{ fontSize: '8px', fontWeight: '800', textTransform: 'uppercase', color: '#f2974b', marginTop: '2px' }}>Home</span>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', opacity: 0.5 }}>
+        <span style={{ fontSize: '1.2rem' }}>📖</span>
+        <span style={{ fontSize: '8px', fontWeight: '800', textTransform: 'uppercase', marginTop: '2px' }}>Aulas</span>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', opacity: 0.5 }}>
+        <span style={{ fontSize: '1.2rem' }}>🏆</span>
+        <span style={{ fontSize: '8px', fontWeight: '800', textTransform: 'uppercase', marginTop: '2px' }}>Ligas</span>
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', opacity: 0.5 }}>
+        <span style={{ fontSize: '1.2rem' }}>👤</span>
+        <span style={{ fontSize: '8px', fontWeight: '800', textTransform: 'uppercase', marginTop: '2px' }}>Perfil</span>
+      </div>
+    </div>
+    
+    {/* Safe Area Bottom Slot */}
+    <div style={{
+      height: '24px',
+      backgroundColor: 'var(--bg-surface)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      borderTop: '1px dashed var(--border-color)'
+    }}>
+      <div style={{ width: '120px', height: '5px', borderRadius: '10px', backgroundColor: '#51332d', opacity: 0.3 }} />
+    </div>
+  </div>
+
+  {/* Desktop Skeleton Mockup */}
+  <div style={{
+    flex: '1 1 500px',
+    minWidth: '460px',
+    border: '4px solid #51332d',
+    borderRadius: '16px',
+    height: '600px',
+    backgroundColor: 'var(--bg-app)',
+    display: 'flex',
+    overflow: 'hidden',
+    boxShadow: 'var(--shadow-lg)'
+  }}>
+    {/* Sidebar Nav */}
+    <div style={{
+      width: '180px',
+      backgroundColor: 'var(--bg-surface)',
+      borderRight: '2px solid var(--border-color)',
+      padding: '20px 12px',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '24px'
+    }}>
+      {/* Brand logo slot */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px', padding: '0 8px' }}>
+        <div style={{ width: '28px', height: '28px', borderRadius: '8px', backgroundColor: '#f2974b' }} />
+        <span style={{ fontFamily: 'var(--font-title)', fontWeight: 'bold', fontSize: '1rem', color: 'var(--text-primary)' }}>Xetlingo</span>
+      </div>
+      
+      {/* Nav items */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '10px', padding: '8px', borderRadius: '8px', backgroundColor: '#fef6ee', color: '#f2974b', fontWeight: 'bold', fontSize: '0.85rem' }}>
+          <span>🏠</span> Painel
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '10px', padding: '8px', borderRadius: '8px', color: 'var(--text-primary)', opacity: 0.7, fontSize: '0.85rem' }}>
+          <span>📖</span> Lições
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '10px', padding: '8px', borderRadius: '8px', color: 'var(--text-primary)', opacity: 0.7, fontSize: '0.85rem' }}>
+          <span>🏆</span> Classificação
+        </div>
+        <div style={{ display: 'flex', alignItems: 'center', gap: '10px', padding: '8px', borderRadius: '8px', color: 'var(--text-primary)', opacity: 0.7, fontSize: '0.85rem' }}>
+          <span>👤</span> Perfil
+        </div>
+      </div>
+    </div>
+    
+    {/* Main area + header */}
+    <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
+      {/* Top Nav Bar for desktop/tablet context */}
+      <div style={{
+        height: '64px',
+        backgroundColor: 'var(--bg-surface)',
+        borderBottom: '2px solid var(--border-color)',
+        display: 'flex',
+        alignItems: 'center',
+        padding: '0 24px',
+        justifyContent: 'flex-end',
+        gap: '16px'
+      }}>
+        <div style={{ fontSize: '0.85rem', fontWeight: 'bold', color: 'var(--text-secondary)' }}>🔥 14 Dias</div>
+        <div style={{ width: '32px', height: '32px', borderRadius: '50%', backgroundColor: '#efe2d6', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>🦉</div>
+      </div>
+      
+      {/* Work area grid demonstration */}
+      <div style={{ flex: 1, padding: '24px', overflowY: 'auto' }}>
+        <div style={{ maxWidth: '1200px', margin: '0 auto', display: 'flex', flexDirection: 'column', gap: '16px' }}>
+          <div style={{ height: '36px', width: '200px', backgroundColor: 'var(--border-color)', borderRadius: '6px' }} />
+          
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(12, 1fr)', gap: '12px', marginTop: '12px' }}>
+            {Array.from({ length: 12 }).map((_, i) => (
+              <div key={i} style={{
+                height: '180px',
+                backgroundColor: 'rgba(242, 151, 75, 0.1)',
+                border: '1px dashed #f2974b',
+                borderRadius: '8px',
+                gridColumn: i < 8 ? 'span 4' : 'span 4',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                fontSize: '0.7rem',
+                color: '#cf7a30',
+                fontWeight: 'bold'
+              }}>
+                Col {i + 1}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+</div>

package/src/Icons.mdx

@@ -0,0 +1,42 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand Guidelines/Ícones (Lucide)" />
+
+# Biblioteca de Ícones Oficial
+
+A biblioteca oficial e exclusiva de ícones para o Design System do Xetlingo é a **\`lucide-react-native\`**.
+
+## Como Usar Ícones nos Componentes
+
+Para facilitar a vida aos developers e garantir consistência, **não passamos elementos JSX completos** nas propriedades dos botões ou componentes base. Em vez disso, passamos apenas o **nome exato** do ícone em formato de string.
+
+### A Regra de Ouro:
+Os componentes (como o \`IconButton\`, \`FabButton\`, etc.) expõem uma propriedade chamada \`iconName\`. Deve preenchê-la com o nome exato (em PascalCase) com que o ícone é exportado pela biblioteca Lucide.
+
+\`\`\`tsx
+// ❌ ERRADO: Não passe o componente importado instanciado
+import { Play } from 'lucide-react-native';
+<IconButton icon={<Play size={24} color="#000" />} />
+
+// ✅ CERTO: Passe apenas o nome do ícone (String)
+<IconButton iconName="Play" />
+<FabButton iconName="Volume2" />
+<JourneyButton iconName="ArrowRight" />
+\`\`\`
+
+## Onde encontrar os ícones disponíveis?
+Pode pesquisar todos os ícones disponíveis e os seus nomes na documentação oficial do projeto Lucide:
+👉 [**lucide.dev/icons**](https://lucide.dev/icons)
+
+*Nota: Lembre-se que o nome do ícone no site geralmente está em minúsculas com hífen (ex: \`arrow-right\`), mas ao passar na prop \`iconName\` deve usar a convenção do React Native / PascalCase (ex: \`ArrowRight\`).*
+
+## O que acontece por baixo do capô? / Como adicionar um novo ícone?
+Para evitar que o motor de compilação (Vite/Metro) tente importar **todos os mais de 1400 ícones** da biblioteca (o que causaria timeouts de memória e bundle enorme), criámos um ficheiro de mapeamento explícito.
+
+Se tentar usar um \`iconName\` e ele não aparecer, é porque ainda não foi mapeado!
+Siga este passo-a-passo:
+1. Abra o ficheiro **\`src/utils/iconMap.ts\`**
+2. Importe o novo ícone do \`lucide-react-native\` no topo do ficheiro.
+3. Adicione o ícone ao objeto \`IconMap\`.
+
+Pronto! A partir daí, qualquer developer pode referenciar esse ícone através de \`iconName="SeuNovoIcone"\`.