v1.0 to v1.0

+ description: Stack frontend para websites — Next.js App Router OU Astro (Content Collections, ilhas), Tailwind v4 (@theme), shadcn/ui e Motion. Use ao iniciar projeto de site em qualquer uma das duas stacks, criar componentes/seções, definir tokens de design ou implementar animações.

+ updated: "2026-09-20"

+ # Sites Frontend Stack — Next.js e Astro + Tailwind v4 + shadcn/ui

+ Stack padrão das duas trilhas suportadas pela squad `sites`, estrutura de projeto, tokens de design (definidos UMA vez, compartilhados), padrões de componente em cada stack e composição shadcn/ui.

+ ## 1. Escolha de stack

+ A decisão entre Next.js, Astro ou Híbrido é responsabilidade exclusiva do `sites-architect` (workflow "Escolher stack — Next.js / Astro / Híbrido", registrado como ADR em `docs/smart-memory/decisions/ADR-{N}-stack-choice.md`). Esta skill não repete os critérios de decisão — ela cobre a implementação de cada stack já decidida. Resumo de quando cada uma costuma entrar:

+

+ - **Next.js** — área autenticada complexa, painel com muito estado no cliente, infraestrutura de API pesada (webhooks, filas, jobs).

+ - **Astro** — site majoritariamente de conteúdo (institucional, landing page, blog, documentação, portfólio) com SEO/Core Web Vitals como prioridade dura.

+ - **Híbrido** (de ilha — um projeto Astro com ilhas React pontuais — ou separado — dois deploys, conteúdo em Astro e app autenticado em Next.js) — quando o projeto tem as duas necessidades ao mesmo tempo.

+

+ Ver o corpo do `sites-architect` para a tabela completa de critérios e o formato do ADR antes de escolher a stack de um projeto novo.

+

+ ## 2. Stack Next.js

+

+ ### Estrutura de projeto (Next.js)

+ ### Responsivo (mobile-first)

+ ```tsx

+ <div className="

+ grid grid-cols-1 /* mobile */

+ md:grid-cols-2 /* tablet */

+ lg:grid-cols-3 /* desktop */

+ gap-4 md:gap-6 lg:gap-8

+ ">

+ ```

+ Mesmas classes utilitárias do Tailwind v4 valem para a trilha Astro — só troca `className` por `class` (ver §3).

+

+ ### shadcn/ui

+

+ #### Instalação e setup

+

+ ```bash

+ npx shadcn@latest init

+

+ # UI base

+ npx shadcn@latest add button input label textarea select

+

+ # Layout e conteúdo

+ npx shadcn@latest add card separator badge avatar

+

+ # Navegação

+ npx shadcn@latest add navigation-menu dropdown-menu sheet

+

+ # Feedback

+ npx shadcn@latest add sonner dialog alert-dialog

+

+ # Formulários — o componente form usa react-hook-form + zod

+ npx shadcn@latest add form

+ npm install react-hook-form zod @hookform/resolvers

+ ```

+

+ #### Composição de componentes

+

+ ```tsx

+ import { Card, CardHeader, CardTitle, CardContent, CardFooter } from '@/components/ui/card'

+ import { Button } from '@/components/ui/button'

+ import { Badge } from '@/components/ui/badge'

+

+ export function ProductCard({ title, price, badge }: ProductCardProps) {

+ return (

+ <Card className="hover:shadow-lg transition-shadow">

+ <CardHeader>

+ <Badge variant="secondary">{badge}</Badge>

+ <CardTitle>{title}</CardTitle>

+ </CardHeader>

+ <CardContent>...</CardContent>

+ <CardFooter>

+ <Button className="w-full">{price} — Comprar</Button>

+ </CardFooter>

+ </Card>

+ )

+ }

+ ```

+

+ Em projeto Astro, os mesmos componentes shadcn/ui funcionam **via ilha React** — mesma instalação acima, componente importado dentro de um `.astro` e hidratado com a diretiva `client:*` adequada (ver §3.4). Não há um "shadcn para Astro" separado: é o mesmo pacote React, só que hidratado seletivamente em vez de rodar a árvore inteira no cliente.

+

+ #### Regra de customização

+ Preferir a prop `className` para overrides pontuais. Para variações sistemáticas, usar `cva()`. **Nunca modificar arquivos em `components/ui/` diretamente** — criar wrapper.

+

+ ### Animações — Motion (`motion/react`)

+

+ O sucessor do Framer Motion é o pacote **`motion`**; em React o import é `motion/react` (API compatível com `framer-motion`).

+

+ ```tsx

+ import { motion } from 'motion/react'

+

+ // Fade in up

+ <motion.div initial={{ opacity: 0, y: 24 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.4 }}>

+

+ // Scroll-triggered nativo (substitui useInView manual)

+ <motion.div initial={{ opacity: 0 }} whileInView={{ opacity: 1 }} viewport={{ once: true, amount: 0.1 }} />

+ ```

+

+ Componentes com Motion precisam de `"use client"` no App Router. Respeitar `prefers-reduced-motion` (ver skill `sites-ux-interaction`).

+

+ ## 3. Stack Astro

+

+ ```

+ Astro (SSG por padrão, SSR seletivo por rota) + TypeScript

+ Tailwind CSS v4 (@theme CSS-first — mesmo bloco da trilha Next, ver §4)

+ Content Collections (Content Layer API) para conteúdo versionado em repo

+ astro:assets para imagens e fontes

+ Ilhas React/Vue/Svelte via diretivas `client:*` — só onde há interatividade real

+ View Transitions nativa (astro:transitions) para navegação entre páginas

+ ```

+

+ ### Estrutura de projeto (Astro)

+

+ ```

+ src/

+ ├── pages/ # roteamento por arquivo — cada .astro/.md vira uma rota

+ │ ├── index.astro

+ │ ├── sobre.astro

+ │ └── blog/

+ │ ├── index.astro # listagem

+ │ └── [slug].astro # rota dinâmica — getStaticPaths() para SSG

+ ├── content/ # Content Collections (Content Layer API, Astro 5+)

+ │ └── blog/

+ │ └── *.md | *.mdx

+ ├── content.config.ts # defineCollection + schema Zod (fora de src/content/config.ts nas versões novas)

+ ├── components/

+ │ ├── ui/ # componentes .astro (ou ilhas React em components/react/)

+ │ └── sections/

+ ├── layouts/

+ │ └── Layout.astro # <head> + <slot />

+ └── styles/

+ └── global.css # Tailwind v4 (@theme) — mesma seção da trilha Next

+ ```

+

+ ### Componente `.astro` (sem framework, HTML por padrão)

+

+ ```astro

+ ---

+ // frontmatter = roda no servidor/build, nunca no navegador

+ interface Props {

+ title: string

+ variant?: 'default' | 'secondary'

+ }

+ const { title, variant = 'default' } = Astro.props

+ ---

+ <div class:list={['card', variant]}>

+ <h3>{title}</h3>

+ <slot />

+ </div>

+

+ <style>

+ .card { padding: 1rem; }

+ </style>

+ ```

+

+ Sem `"use client"`, sem hook, sem re-render — o frontmatter roda uma vez, no build/servidor. Interatividade só entra via `<script>` (client-side, escopado automaticamente ao componente — ver `sites-ux-interaction`) ou via ilha de framework.

+

+ ### Content Collections (Content Layer API, Astro 5+)

+

+ ```ts

+ // src/content.config.ts

+ import { defineCollection, z } from 'astro:content'

+ import { glob } from 'astro/loaders'

+

+ const blog = defineCollection({

+ loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),

+ schema: z.object({

+ title: z.string(),

+ description: z.string().max(160),

+ pubDate: z.coerce.date(),

+ image: z.string().optional(),

+ }),

+ })

+

+ export const collections = { blog }

+ ```

+

+ ```astro

+ ---

+ // src/pages/blog/[slug].astro

+ import { getCollection, render } from 'astro:content'

+ export async function getStaticPaths() {

+ const posts = await getCollection('blog')

+ return posts.map(post => ({ params: { slug: post.id }, props: { post } }))

+ }

+ const { post } = Astro.props

+ const { Content } = await render(post)

+ ---

+ <Content />

+ ```

+

+ Substitui CMS leve para blog/docs/portfólio quando o conteúdo vive em arquivos do repositório. Para CMS externo (Contentful/Sanity/Strapi), a Content Layer API também aceita loaders customizados que buscam de API — mesmo papel que o `sites-dev-beta` já cobre na trilha Next.

+

+ ### Ilhas — hidratação seletiva (Islands Architecture)

+

+ 5 diretivas oficiais, cada componente de framework (React/Vue/Svelte/Preact) precisa de uma:

+

+ | Diretiva | Quando hidrata | Uso típico |

+ |---|---|---|

+ | `client:load` | Imediatamente após o HTML carregar | Componente crítico acima da dobra (ex.: um seletor de idioma no header) |

+ | `client:idle` | Quando o navegador fica ocioso (`requestIdleCallback`) | Componente importante mas não urgente |

+ | `client:visible` | Quando entra na viewport (IntersectionObserver) | **Padrão recomendado** para qualquer coisa abaixo da dobra — carrossel, FAQ, formulário no meio da página |

+ | `client:media={query}` | Quando uma media query bate | Componente só relevante em certo breakpoint (ex.: menu mobile) |

+ | `client:only={framework}` | Sem SSR — só client, precisa dizer o framework (`client:only="react"`) | Componente que depende de API só de navegador (mapa, player) |

+

+ **Regra de ouro de performance:** cada `client:load` que não precisa ser `client:load` é JS que o usuário baixa à toa — o oposto do que SEO/CWV pede. Padrão é `client:visible`/`client:idle`; `client:load` só com justificativa (o `sites-qa` cobra isso no checklist).

+

+ ### Imagens e fontes — `astro:assets`

+

+ ```astro

+ ---

+ import { Image, Picture } from 'astro:assets'

+ import heroImg from '../assets/hero.jpg'

+ ---

+ <Image src={heroImg} alt="…" width={1200} height={630} loading="eager" fetchpriority="high" />

+ <!-- responsivo com formatos modernos -->

+ <Picture src={heroImg} alt="…" formats={['avif', 'webp']} widths={[400, 800, 1200]} sizes="100vw" />

+ ```

+

+ Otimiza formato/tamanho no build, injeta `width`/`height` automaticamente (zero CLS por design — mesmo objetivo do `next/image`, execução diferente). Fonte: usar `@fontsource/*` (self-hosted, sem request externo) ou o font helper de `astro:assets` — ambos evitam o layout shift de fonte carregada via `<link>` do Google Fonts.

+

+ ### View Transitions e Server Islands (Astro 5+)

+

+ - **View Transitions API nativa** (`<ClientRouter />` em `astro:transitions`): navegação com transição suave entre páginas sem virar SPA — mantém o modelo multi-page (bom para SEO: cada página continua sendo uma URL real, indexável).

+ - **Server Islands**: parte da página fica em cache estático (CDN) e um componente específico renderiza sob demanda no servidor a cada request — útil para personalização (ex.: "olá, {nome}") sem perder o cache da página inteira. Diferente de uma ilha de cliente: essa hidrata no servidor, não no navegador.

+

+ ### API server-side — Astro Actions e endpoints

+

+ ```ts

+ // src/actions/index.ts — Astro Actions: função tipada, chamável do client sem fetch manual

+ import { defineAction } from 'astro:actions'

+ import { z } from 'astro:schema'

+

+ export const server = {

+ subscribeNewsletter: defineAction({

+ input: z.object({ email: z.string().email() }),

+ handler: async (input) => {

+ // validação já garantida pelo schema Zod — mesma disciplina da trilha Next (dev-beta)

+ return { success: true }

+ },

+ }),

+ }

+ ```

+

+ ```ts

+ // src/pages/api/contact.ts — endpoint tradicional, equivalente ao Route Handler do Next

+ export async function POST({ request }: APIContext) {

+ const data = await request.json()

+ return new Response(JSON.stringify({ ok: true }), { status: 200 })

+ }

+ ```

+

+ Astro Actions = paralelo direto do Server Action do Next (função tipada chamada do client, sem escrever fetch). Endpoint em `pages/api/*.ts` = paralelo do Route Handler. Exigem `output: 'server'` ou `output: 'static'` com `export const prerender = false` na rota específica (SSR seletivo).

+

+ ### Renderização — output modes

+

+ ```js

+ // astro.config.mjs

+ export default defineConfig({

+ output: 'static', // default — tudo pré-renderizado (SSG). Rota específica pode virar SSR com:

+ // export const prerender = false (dentro da própria página/endpoint)

+ // ou output: 'server' — tudo sob demanda, precisa de adapter

+ })

+ ```

+

+ `static` é o ponto de partida certo para o cenário de "SEO em primeiro lugar" (páginas viram HTML no build, servidas por CDN, sem cold start). `server` só quando a maior parte do site depende de dado por request.

+

+ ## 4. Compartilhado entre as duas — Design tokens Tailwind v4 (@theme, CSS-first)

+

+ Os tokens vivem **uma vez só** — em `app/globals.css` (Next.js) ou `src/styles/global.css` (Astro), mesmo bloco `@theme`. No Tailwind v4 não há `tailwind.config.ts` por padrão — o tema é declarado em CSS e cada token vira utility automaticamente (`bg-primary`, `text-foreground`, `rounded-lg`...).

+

+ /* globals.css (Next.js) ou global.css (Astro) */

+ > **Nota (legado v3):** em projetos ainda no Tailwind v3, os mesmos tokens vão em `:root` como custom properties e são mapeados em `theme.extend` no `tailwind.config.ts` (`primary: 'hsl(var(--primary))'`). Ao migrar para v4, mover tudo para o bloco `@theme` e remover o config. Vale para as duas stacks.

+ ## 5. Padrão de componente

+ ### React function component (Next.js)

+

+ ### Componente `.astro` (Astro)

+ ```astro

+ ---

+ interface Props {

+ variant?: 'default' | 'secondary'

+ class?: string

+ const { variant = 'default', class: className } = Astro.props

+ ---

+ <div class:list={['component', variant, className]}>

+ <slot />

+ </div>

+ Mesma disciplina de props tipadas e variantes das duas stacks — a diferença é que o componente `.astro` não recebe `children` como prop: usa `<slot />` nativo, e a composição de classes usa `class:list` em vez de `cn()`.