Arquitetura

O site é uma aplicação Next.js 16 (App Router) construída como HTML estático no build, estilizada com a linguagem de design YuTheme, hospedada na Vercel. Não há runtime de servidor.

Stack

• Next.js 16 (App Router, geração estática)
• React 19
• TypeScript
• pnpm (gerenciador de pacotes, versão fixada via packageManager)
• Monorepo Turborepo (apps/, packages/)
• next-intl para os sete idiomas, localePrefix: as-needed
• Tokens e convenções editoriais YuTheme (veja design.md)
• Ícones Lucide via lucide-react
• Fontes: Geist Variable e Geist Mono Variable via next/font/local

O único JavaScript de cliente é uma pequena quantidade de hidratação: o menu móvel do header, o scrollspy, o scroll suave de âncoras e as revelações de scroll.

Estrutura

apps/web/src/
  app/
    [locale]/
      layout.tsx            shell do documento, fontes, metadata, JSON-LD
      page.tsx              home de página única
      docs/page.tsx         índice da documentação
      docs/[slug]/page.tsx  páginas individuais de documentação
      globals.css           tokens YuTheme, estilos base, motion
    sitemap.ts              sitemap para todos os idiomas
    robots.ts
  components/
    Analytics.tsx           hook Umami, ativado por env, inerte por padrão
    Footer.tsx
    Header.tsx              header fixo, scrollspy, gaveta móvel
    Icon.tsx                mapa de ícones Lucide, nomes tipados
    Reveal.tsx              revelação de scroll via IntersectionObserver
    sections/
      Hero.tsx              manchete + cartão terminal
      About.tsx
      WhatIDo.tsx           grade de cartões
      HowIWork.tsx
      WhereILive.tsx
      SelectedWork.tsx      lista de trabalhos públicos
  data/site.ts              constantes do site: URLs, navegação
  i18n/                     routing, config de request, navegação tipada
  lib/docs.ts               pipeline de markdown das páginas de docs
packages/
  content/                  fontes de docs/, lidas por idioma com fallback EN
  i18n/                     lista de idiomas + mensagens dos sete locales
  ui/styles/                CSS YuTheme canônico, referência de tokens

Localização

• Idiomas: en (padrão, sem prefixo), pt, es, fr, de, ja, zh-CN.
• O copy de interface vive em packages/i18n/messages/<locale>.json.
• A documentação vive em packages/content/docs/<locale>/; quando um idioma não tem um arquivo, a versão em inglês é servida como fallback.
• As rotas são estáticas: cada idioma e cada slug de doc é pré-renderizado no build via generateStaticParams.

Pipeline das docs

As páginas de documentação leem a pasta packages/content/docs/ através de packages/content/src/index.ts:

• cada doc é um arquivo Markdown com frontmatter: title, description, order, updated;
• o app a renderiza com remark/rehype (GFM, headings com slug, autolinks, HTML sanitizado) em /docs/<slug>, com índice em /docs;
• @ellamizuki/content é mantido externo ao bundle do app (serverExternalPackages) para que as leituras de filesystem funcionem em produção.

Como a coleção lê a mesma pasta versionada no repositório, as docs permanecem sincronizadas: uma fonte de verdade, duas visões (página do site e arquivos do repo).

Fluxo de dados

• No build: o Next.js pré-renderiza /, /docs, /docs/* para cada idioma.
• O conteúdo é pré-renderizado; não há servidor, API ou dados em runtime.
• Analytics (Umami) só é injetado quando NEXT_PUBLIC_UMAMI_SRC e NEXT_PUBLIC_UMAMI_WEBSITE_ID estão definidas no build.

Convenções

• HTML semântico com um único h1 por página.
• Headings de seção em ordem (h2 depois h3), sem pular níveis.
• Links externos abrem em nova aba com rel="noopener noreferrer".
• Links renderizados pelo next-intl nunca recebem href já prefixado; o prefixo do idioma é sempre adicionado pelos helpers de navegação.
• Reduced motion é respeitado em todo lugar: shimmer, revelações e transições são controlados por prefers-reduced-motion.