álise da Pilha Tecnológica e Gerador de Regras do Cursor

=================== --- description: globs: alwaysApply: true --- # Guia de Stack e Dependências da UI da Página ## Visão Geral do Projeto **Page UI** é uma biblioteca de componentes de landing page construída sobre stack moderna de React/Next.js com: - **Website**: Site de documentação Next.js 14 com demos de componentes - **Ferramenta CLI**: `@ page-ui/wizard` para inicialização fácil de projetos - **Componentes**: Componentes React de copiar e colar construídos sobre Radix UI + Tailwind CSS ## Stack Principal do Framework ### **Next.js 14.2.24** (App Router) - **Framework**: Meta-framework React com arquitetura App Router - **Recursos Utilizados**: Rotas de API, SSG/SSR, geração de imagem OG, análise de bundle - **Melhor Prática**: Usar padrões do App Router, evitar diretório pages ### **React 18.2.0** - **Biblioteca UI**: Biblioteca React principal com recursos concorrentes - **Recursos**: Suspense, batching automático, componentes de servidor - **Melhor Prática**: Usar padrões do React 18 ### **TypeScript 5.1.3** - **Configuração**: Modo estrito habilitado para melhor segurança de tipos - **Melhor Prática**: Versão moderna do TS ## Sistema de Componentes UI ### **Primitivas Radix UI** (série v1.x) Ecossistema completo de componentes acessíveis em primeiro lugar: **Melhores Práticas**: - Usar padrões de componentes compostos - Sempre customizar com classes Tailwind, não estilos inline - Implementar atributos ARIA adequados (embutidos) - Envolver em componentes customizados para estilização consistente ### **Padrão de Design Shadcn/UI** - **Localização**: Diretório `/components/shared/ui/` - **Filosofia**: Componentes copy-paste, não dependências NPM - **Estilização**: Tailwind CSS + variáveis CSS para theming - **Variantes**: Usa `class-variance-authority` para variantes type-safe ## Sistema de Estilização e Design ### **Tailwind CSS 3.3.3** + Ecossistema ```json { "tailwindcss": "^3.3.3", "@tailwindcss/forms": "^0.5.4", "@tailwindcss/typography": "^0.5.9", "tailwindcss-animate": "^1.0.7", "tailwind-merge": "^1.14.0" } ``` **Melhores Práticas**: - Usar `tailwind-merge` para classes condicionais: `cn(baseClasses, conditionalClasses)` - Aproveitar variáveis CSS para theming: `hsl(var(--primary))` - Usar plugins para formulários e tipografia - Implementar sistemas consistentes de espaçamento e cor ### **Bibliotecas de Animação** - **Framer Motion 10.16.4**: Animações complexas, transições de página - **Tailwind Animate**: Animações CSS simples - **Melhor Prática**: Usar animações CSS para efeitos simples, Framer Motion para interações complexas ```typescript // Melhores práticas do Framer Motion: import { motion, AnimatePresence } from 'framer-motion' function AnimatedComponent() { return ( <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: -20 }} transition={{ duration: 0.3 }} > Content </motion.div> ) } ``` ## Gerenciamento de Estado e Formulários ### **Zustand 4.5.2** (Estado Global) - **Filosofia**: Gerenciamento de estado mínimo, sem opiniões - **Uso**: Preferências de tema, estado global de UI, estado do playground de componentes - **Melhor Prática**: Criar stores tipadas com seletores adequados ```typescript interface ThemeState { theme: 'light' | 'dark' setTheme: (theme: 'light' | 'dark') => void } export const useThemeStore = create<ThemeState>((set) => ({ theme: 'light', setTheme: (theme) => set({ theme }), })) ``` ### **React Hook Form 7.46.2** + Validação - **Biblioteca de Formulários**: Formulários não controlados e performáticos - **Validação**: `@hookform/resolvers` ^3.3.1 + `zod` ^3.22.2 - **Integração**: Funciona perfeitamente com componentes de formulário Radix UI ```typescript // Configuração de formulário de melhor prática: const formSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) function ContactForm() { const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), }) return <form onSubmit={form.handleSubmit(onSubmit)}>...</form> } ``` ### **Zod 3.22.2** (Validação de Schema) - **Uso**: Validação de formulários, validação de resposta de API, geração de tipos - **Melhor Prática**: Definir schemas próximos ao uso, aproveitar inferência de tipos ## Sistema de Gerenciamento de Conteúdo ### **Implementação Customizada de Contentlayer** ```json { "@shipixen/next-contentlayer-module": "1.0.2", "shipixen-contentlayer": "1.0.2", "@shipixen/pliny": "1.0.13" } ``` **Recursos**: - Processamento MDX type-safe - Parsing de frontmatter - Importações automatizadas de conteúdo - Geração de feed RSS ### **Pipeline de Processamento MDX** **Plugins Remark** (processamento Markdown): - `remark-gfm` ^3.0.1: GitHub Flavored Markdown - `remark-math` ^5.1.1: Expressões matemáticas **Plugins Rehype** (processamento HTML): - `rehype-slug` ^5.1.0: Gerar IDs de cabeçalho automaticamente - `rehype-autolink-headings` ^6.1.0: Vincular cabeçalhos automaticamente - `rehype-prism-plus` ^1.6.1: Realce de sintaxe - `rehype-katex` ^6.0.3: Renderização matemática **Melhores Práticas**: - Processar conteúdo em tempo de build, não em tempo de execução - Usar versões consistentes de plugins para builds estáveis - Consultas de conteúdo type-safe com tipos gerados ## Experiência de Desenvolvimento ### **Ferramentas de Qualidade de Código** ```json { "eslint": "^8.45.0", "@typescript-eslint/eslint-plugin": "^6.1.0", "@typescript-eslint/parser": "^6.1.0", "eslint-config-next": "^14.2.24", "eslint-config-prettier": "^8.8.0", "prettier": "^3.0.0", "prettier-plugin-tailwindcss": "^0.4.1" } ``` **Fluxo de Trabalho Git**: - **Husky 8.0.0**: Automação de hooks Git - **lint-staged 13.0.0**: Linting e formatação pré-commit ### **Ferramentas Interativas de Desenvolvimento** - **Monaco Editor 0.45.0**: Edição de código no navegador para playground de componentes - **Command Palette**: `cmdk` ^0.2.0 para busca e navegação global - **Bundle Analyzer**: `@next/bundle-analyzer` para monitoramento de performance ## Ferramenta CLI (@page-ui/wizard) ### **Configuração do Pacote** ```json { "name": "@page-ui/wizard", "type": "module", "bin": "./packages/cli/index.mjs", "engines": { "node": ">=14.17.0" } } ``` ### **Dependências da CLI** ```json { "chalk": "^5.3.0", // Cores e estilização de terminal "commander": "^12.0.0", // Framework de interface de linha de comando "enquirer": "^2.4.1", // Prompts interativos de CLI "ora": "^8.0.1" // Spinners de carregamento para CLI } ``` **Melhores Práticas**: - Usar módulos ESM (extensão `.mjs`) - Fornecer prompts interativos com enquirer - Mostrar progresso com spinners ora - Estilização consistente de terminal com chalk ## Analytics e Serviços Externos ### **Ecossistema Vercel** - **Analytics**: `@vercel/analytics` ^1.1.1 - **Imagens OG**: `@vercel/og` ^0.5.20 - **Melhor Prática**: Usar ferramentas nativas da Vercel para performance ideal ### **Analytics de Produto** - **PostHog 1.130.1**: Feature flags, rastreamento de usuários, testes A/B - **Melhor Prática**: Configuração em conformidade com privacidade com gerenciamento adequado de consentimento ### **Cliente HTTP** - **Axios 1.7.7**: Chamadas de API, assinaturas de newsletter - **Melhor Prática**: Criar instâncias axios com configuração base ## Bibliotecas Utilitárias ### **Data e Hora** - **date-fns 2.30.0**: Biblioteca utilitária de datas modular - **Melhor Prática**: Importar apenas as funções necessárias para tree-shaking ```typescript // Bom: Imports tree-shakeable import { format, parseISO } from 'date-fns' // Ruim: Import completo da biblioteca import * as dateFns from 'date-fns' ``` ### **Utilitários de Estilização e UI** - **clsx 2.0.0**: Utilitário de className condicional - **class-variance-authority 0.7.0**: Variantes de componentes type-safe - **chroma-js 2.4.2**: Manipulação de cores e geração de temas ### **Apresentação de Dados** - **@tanstack/react-table 8.10.7**: Componente de tabela poderoso - **lucide-react 0.400.0**: Biblioteca de ícones - **sonner 1.3.1**: Notificações toast