Biblioteca Oficial de Componentes Smart NX
A NX UI é a biblioteca oficial e exclusiva de componentes React + TypeScript da Smart NX, desenvolvida pela equipe de Product Design / UI UX e Frontend Engineering.
Ela serve como núcleo visual e funcional de todos os produtos do ecossistema Smart NX, refletindo o design system unificado da empresa.
💡 A NX UI substitui completamente bibliotecas externas de UI como Ant Design, garantindo padronização, performance, acessibilidade e manutenção centralizada.
1. Objetivo e Propósito
A NX UI tem como missão padronizar e acelerar o desenvolvimento de interfaces em todo o ecossistema da Smart NX.
Principais objetivos
- Unificação visual e comportamental entre todas as aplicações NX Suite.
- Eliminação de dependências externas de UI, reduzindo riscos e inconsistências.
- Melhoria de performance com tree-shaking, renderização otimizada e componentes agnósticos.
- Automação de formulários e validações via integração nativa com TanStack Query e Zod.
- Governança e segurança com controle de acesso via Verdaccio NPM privado.
2. Estrutura e Stack Técnica
| Item | Detalhes |
|---|---|
| Repositório | NX Suite Design System — Bitbucket |
| Linguagem | React + TypeScript |
| Validação | Zod |
| Gerenciamento de estado e queries | TanStack Query |
| Testes | Vitest + Testing Library |
| Documentação | Storybook |
| Publicação | Verdaccio (NPM privado Smart NX) |
| Bundle | Tree-shaking, minificação e tipagem completa (.d.ts) |
3. Distribuição Privada via Verdaccio
A NX UI é distribuída internamente através do Verdaccio, um servidor NPM privado da Smart NX.
Somente membros autorizados podem instalar ou publicar novas versões da biblioteca.
Instalação
npm set registry https://verdaccio.smartnx.internal
npm login --registry=https://verdaccio.smartnx.internal
pnpm add @smartnx/nx-ui
# ou
yarn add @smartnx/nx-ui
⚠️ A instalação é restrita a repositórios oficiais Smart NX. O uso em projetos pessoais, externos ou não corporativos é estritamente proibido.
4. Filosofia de Componentes
Cada componente da NX UI é projetado com base nos princípios de escalabilidade, acessibilidade e desacoplamento.
| Princípio | Descrição |
|---|---|
| Agnóstico | Não depende de contexto global ou estado externo — funciona isoladamente em qualquer app NX. |
| Performático | Usa renderização controlada, memoização inteligente e tree-shaking nativo. |
| Tipado | Todos os componentes são fortemente tipados com TypeScript. |
| Validado | Props e inputs validados com Zod. |
| Testado | Cobertura garantida com Vitest + Testing Library. |
| Acessível | Segue recomendações WCAG 2.1 e uso de atributos ARIA. |
| Depurável | Inclui modo de depuração interno, ativável via prop debug, para inspecionar comportamento e estado durante o desenvolvimento. |
5. Modo de Depuração
Durante o desenvolvimento, é possível habilitar o modo de depuração (debug) para inspecionar o comportamento interno dos componentes.
<Button debug variant="primary">
Enviar
</Button>
Esse modo exibe logs internos, estados temporários e warnings não críticos no console, facilitando a análise de comportamento durante a fase de QA.
⚙️ O modo de depuração é ignorado automaticamente em builds de produção.
6. Integração com TanStack Query
Os componentes de formulário (ex: Form, Input, Select, DatePicker, Uploader) integram-se nativamente com o TanStack Query, permitindo:
- Sincronização de dados em tempo real.
- Cache automático e invalidação.
- Submissão e revalidação otimizadas.
<Form queryKey="userForm" onSubmit={handleSubmit}>
<Input name="email" label="E-mail" required />
<Button type="submit">Salvar</Button>
</Form>
Essa integração reduz a complexidade de formulários e elimina a necessidade de libs como react-hook-form ou formik.
7. Storybook — Playground Oficial
O Storybook é o ambiente de desenvolvimento e documentação visual da NX UI. Cada componente é documentado com exemplos, args controláveis e casos de uso reais.
Rodando localmente
pnpm storybook
Acesse o playground em http://localhost:6006 para visualizar componentes interativamente.
8. Política de Uso e Governança
A NX UI é considerada um ativo estratégico da Smart NX. Seu uso, manutenção e evolução seguem regras claras de governança técnica:
| Política | Diretriz |
|---|---|
| Acesso restrito | Apenas membros da equipe interna com autenticação no Verdaccio podem instalar ou publicar. |
| Proibição de uso externo | É terminantemente proibido utilizar a NX UI em projetos pessoais, clientes externos ou forks não autorizados. |
| Aprovação de dependências | Nenhuma biblioteca externa pode ser adicionada ao projeto NX UI sem aprovação técnica e de design. |
| Manutenção centralizada | A NX UI é mantida pela equipe oficial da Smart NX — alterações diretas não são permitidas fora do fluxo de PRs oficiais. |
| Auditoria de segurança e licenças | Todas as dependências passam por verificação de segurança antes da publicação. |
| Versionamento semântico | O versionamento segue o padrão SemVer (MAJOR.MINOR.PATCH), controlado pelo pipeline interno. |
9. Escalabilidade e Arquitetura
A NX UI segue uma arquitetura modular e extensível, com foco em performance e manutenção a longo prazo.
- Cada componente é isolado em diretório próprio (
index.tsx,style.ts,stories.tsx,test.tsx). - A estrutura de build garante compatibilidade com ESM, CJS e Type Declarations.
- As dependências internas são minimalistas (React, Styled-components, Zod, TanStack Query).
- Todas as importações são tree-shakable e compatíveis com Vite, Next.js e Webpack.
10. Restrições de Uso
- 🚫 Não é permitido instalar bibliotecas externas dentro da NX UI sem aprovação prévia do time técnico.
- 🚫 Não é permitido publicar forks, variantes ou versões modificadas fora do pipeline oficial.
- 🚫 Não é permitido usar a NX UI em projetos pessoais, testes externos ou protótipos não corporativos.
🔒 Qualquer violação de uso pode resultar no bloqueio de acesso ao repositório e às credenciais Verdaccio.
11. Ciclo de Vida e Atualizações
- Versões novas são publicadas via pipeline após aprovação de PR.
- Changelog automático é gerado no merge para
main. - Publicação privada via Verdaccio com autenticação de conta Smart NX.
- Documentação Storybook é atualizada automaticamente na build de release.
🕓 Histórico de Versões
| Data | Versão | Autor / Revisor | Alterações |
|---|---|---|---|
| 29/10/2025 | v1.0.0 | @Matheus Telles | Criação inicial e estrutura base do documento |