@unooria/design-system

v0.2.14

Published

an hour ago

Design System oficial da Plataforma Unooria para React e Next.js com suporte completo a temas Light/Dark

0High
0Medium
0Low

lucas.salomao.unooria

Unooria Design System (`@unooria/design-system`)

Biblioteca oficial de componentes de interface, tokens de design e documentação interativa da Plataforma Unooria.

📌 Sumário

📖 Visão Geral

O Unooria Design System foi concebido sob os mais rigorosos padrões de engenharia de software e fidelidade de design (Figma). Ele fornece uma base consistente, acessível e performática para criação de aplicações web modernas.

Principais Características:

Suporte Nativo a Temas (Light & Dark): Todos os componentes e tokens respondem fluidamente ao tema selecionado (theme="light" | "dark" ou classes .unooria-theme-light / .unooria-theme-dark).
Arquitetura Dual ESM + CommonJS: Compatibilidade total com empacotadores modernos (Vite, Webpack, Turbopack, Rollup) e Node.js.
Tipagem Estrita em TypeScript: Autocomplete inteligente e definições completas (.d.ts).
Zero Dependências Pesadas em Runtime: Focado em CSS modularizado e React puro.

🛠️ Stack Tecnológica

Core: React 18+ / React 19+
Linguagem: TypeScript 5+
Bundler de Produção: tsup (esbuild + rollup-dts)
Documentação & Playground: Storybook 10
Estilização: CSS Vanilla com CSS Variables e Design Tokens padronizados

📦 Instalação

Instale o pacote no seu projeto utilizando o gerenciador de pacotes de sua preferência:

# npm
npm install @unooria/design-system

# yarn
yarn add @unooria/design-system

# pnpm
pnpm add @unooria/design-system

# bun
bun add @unooria/design-system

Nota: Certifique-se de que react e react-dom (versão 18 ou 19) estejam instalados no seu projeto.

🎨 Configuração de Estilos

Para garantir que todos os tokens de cor, tipografia, elevação, espaçamento e componentes sejam renderizados corretamente, importe a folha de estilos compilada no ponto de entrada global da sua aplicação.

No Next.js (`app/layout.tsx` ou `pages/_app.tsx`):

import '@unooria/design-system/styles.css';

No React com Vite (`src/main.tsx` ou `src/index.tsx`):

import React from 'react';
import ReactDOM from 'react-dom/client';
import '@unooria/design-system/styles.css';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

🚀 Guia de Uso e Exemplos

Exemplo com React (Vite / SPA)

import React, { useState } from 'react';
import { Button, AlertBox, Badge, Breadcrumb } from '@unooria/design-system';

export function Dashboard() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  const breadcrumbItems = [
    { label: 'Início', href: '/' },
    { label: 'Configurações', href: '/settings' },
    { label: 'Perfil' },
  ];

  return (
    <div
      className={theme === 'dark' ? 'unooria-theme-dark' : 'unooria-theme-light'}
      style={{
        minHeight: '100vh',
        padding: '32px',
        background: theme === 'dark' ? '#0f172a' : '#f8fafc',
        color: theme === 'dark' ? '#f8fafc' : '#0f172a',
      }}
    >
      <header style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '24px' }}>
        <Breadcrumb items={breadcrumbItems} theme={theme} />
        
        <Button
          variant="secondary"
          size="sm"
          theme={theme}
          onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
        >
          Alternar Tema ({theme === 'light' ? '🌙 Dark' : '☀️ Light'})
        </Button>
      </header>

      <main style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
        <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
          <h1>Painel Unooria</h1>
          <Badge variant="brand" theme={theme}>v0.1.0</Badge>
          <Badge variant="success" theme={theme}>Ativo</Badge>
        </div>

        <AlertBox
          severity="info"
          theme={theme}
          title="Novidade no Design System"
          description="Todos os componentes agora possuem empacotamento otimizado para produção."
          isDismissible
        />

        <div style={{ display: 'flex', gap: '12px', marginTop: '16px' }}>
          <Button variant="primary" theme={theme} onClick={() => alert('Salvo com sucesso!')}>
            Salvar Alterações
          </Button>
          <Button variant="outline" theme={theme}>
            Cancelar
          </Button>
        </div>
      </main>
    </div>
  );
}

Exemplo com Next.js (App Router)

app/layout.tsx:

import type { Metadata } from 'next';
import '@unooria/design-system/styles.css';

export const metadata: Metadata = {
  title: 'Minha Aplicação Unooria',
  description: 'Criada com @unooria/design-system',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="pt-BR">
      <body className="unooria-theme-light">{children}</body>
    </html>
  );
}

app/page.tsx:

'use client';

import { Button, AlertBox, Badge, Breadcrumb } from '@unooria/design-system';

export default function HomePage() {
  return (
    <main style={{ padding: '40px', maxWidth: '800px', margin: '0 auto' }}>
      <Breadcrumb
        items={[
          { label: 'Home', href: '/' },
          { label: 'Documentação' },
        ]}
      />

      <h1 style={{ marginTop: '24px', fontSize: '32px' }}>Plataforma Unooria</h1>
      
      <div style={{ margin: '16px 0' }}>
        <Badge variant="success">Em Produção</Badge>
      </div>

      <AlertBox
        severity="success"
        title="Pacote Pronto!"
        description="O Design System Unooria foi integrado com sucesso na sua aplicação Next.js."
      />

      <div style={{ marginTop: '24px' }}>
        <Button variant="primary" onClick={() => console.log('Clicado')}>
          Começar Agora
        </Button>
      </div>
    </main>
  );
}

Uso de Tokens e Variáveis CSS

Você pode importar os tokens diretamente em TypeScript ou utilizar as variáveis CSS no seu próprio CSS / Styled Components / Tailwind:

import { tokens } from '@unooria/design-system';

// Acesso a tokens em TypeScript
console.log(tokens.unooriaColorsLight.brandPrimary[500]);
console.log(tokens.unooriaSpacing.scale[16]);

No seu arquivo CSS:

.meu-card-customizado {
  background-color: var(--unooria-color-surface-card);
  border-radius: var(--unooria-radius-md, 8px);
  padding: var(--unooria-space-16, 16px);
  box-shadow: var(--unooria-elevation-2);
  color: var(--unooria-color-text-primary);
}

🧩 Componentes Disponíveis

💻 Scripts de Desenvolvimento

No repositório do Design System:

📂 Estrutura do Pacote

@unooria/design-system/
├── dist/
│   ├── index.mjs          # Saída ESM (para bundlers modernos)
│   ├── index.cjs          # Saída CommonJS (para Node.js / legados)
│   ├── index.d.ts         # Definições TypeScript consolidadas
│   └── styles.css         # CSS consolidado com todos os tokens e componentes
├── src/                   # Código-fonte TypeScript e CSS
├── package.json
└── README.md

🚢 Guia de Versionamento e Publicação no NPM

1. Configuração do Secret no GitHub

Para que as publicações automatizadas funcionem:

Acesse o NPMjs.com e gere um Access Token do tipo Automation.
No repositório GitHub, navegue até Settings > Secrets and variables > Actions.
Crie um novo Secret com o nome: NPM_TOKEN e cole o token gerado.

2. Publicação Automatizada via GitHub Actions

O repositório possui o workflow .github/workflows/publish-npm.yml pronto para publicação.

Fluxo recomendado:

Atualize a versão semântica:

# Para correções de bugs (0.1.0 -> 0.1.1)
npm version patch

# Para novas funcionalidades compatíveis (0.1.0 -> 0.2.0)
npm version minor

# Para mudanças com quebra de compatibilidade (0.1.0 -> 1.0.0)
npm version major

Envie a tag e os commits para o GitHub:
```
git push origin main --tags
```
O GitHub Actions detectará a tag v* e executará o build, validação de tipos e o npm publish --access public automaticamente!
(Opcional) Você também pode criar uma Release no GitHub a partir da tag ou disparar manualmente pela aba Actions > Publicar Pacote no NPM > Run workflow.

3. Publicação Manual via Terminal

Caso precise publicar diretamente do terminal:

# 1. Realizar login no NPM (caso ainda não esteja logado)
npm login

# 2. Executar verificação de tipos e compilação do pacote
npx tsc --noEmit
npm run build:package

# 3. Atualizar versão (opcional caso já tenha alterado no package.json)
npm version patch

# 4. Publicar pacote com acesso público
npm publish --access public

📄 Licença

Distribuído sob a licença MIT. Consulte o arquivo de licença para obter mais informações.