Começando

Instalação

Os arquivos prontos para copiar estão no topo. Abaixo, o que cada passo faz no Next.js, no Vite ou em qualquer React com Tailwind CSS v4.

Copie e cole

Os arquivos na ordem em que entram no projeto. Cada bloco tem o botão de copiar. Os passos abaixo explicam o que cada um faz e trocam pnpm por npm, yarn ou bun.

bash

pnpm add aura-ui-components aura-ui-tailwind tailwindcss

bash

pnpm add -D @tailwindcss/postcss

postcss.config.mjs

export default { plugins: { "@tailwindcss/postcss": {} } };

app/globals.css

@import "aura-ui-tailwind";
@import "aura-ui-components/tailwind.css";

app/providers.tsx

"use client";

import { ThemeProvider } from "aura-ui-core/client";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system" defaultColorScheme="aura">
      {children}
    </ThemeProvider>
  );
}

app/layout.tsx

import { Providers } from "./providers";
import "./globals.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

app/page.tsx

import { Button } from "aura-ui-components/button";
import { Card, CardContent, CardHeader, CardTitle } from "aura-ui-components/card";

export default function Page() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Bem-vindo ao Aura UI</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="gradient">Começar</Button>
      </CardContent>
    </Card>
  );
}

1Instale os pacotes

bash

pnpm add aura-ui-components aura-ui-tailwind tailwindcss

Opcionais: aura-ui-effects (efeitos de profundidade) e aura-ui-three three @react-three/fiber (cenas WebGL).

2Configure o Tailwind CSS v4

bash

pnpm add -D @tailwindcss/postcss

postcss.config.mjs

export default { plugins: { "@tailwindcss/postcss": {} } };

3Importe o CSS do Aura

No CSS global (app/globals.css ou src/index.css), use o preset no lugar de @import "tailwindcss":

globals.css

@import "aura-ui-tailwind";                /* Tailwind + tokens + primitivas + 33 temas */
@import "aura-ui-components/tailwind.css"; /* registra as classes dos componentes */
@import "aura-ui-effects/tailwind.css";    /* só se usar aura-ui-effects */
@import "aura-ui-three/tailwind.css";      /* só se usar aura-ui-three */

Por que o tailwind.css de cada pacote?

O Tailwind v4 não escaneia node_modules. Cada pacote publica um tailwind.css com @source apontando para o próprio código — sem ele, os componentes aparecem sem estilo.

4Envolva o app com o ThemeProvider

app/providers.tsx

"use client";

import { ThemeProvider } from "aura-ui-core/client";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system" defaultColorScheme="aura">
      {children}
    </ThemeProvider>
  );
}

app/layout.tsx

import { Providers } from "./providers";
import "./globals.css";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

O provider salva a escolha no localStorage e aplica data-theme e .dark no <html>. Não quer provider? Defina os atributos à mão — veja Temas.

5Use os componentes

app/page.tsx

import { Button } from "aura-ui-components/button";
import { Card, CardContent, CardHeader, CardTitle } from "aura-ui-components/card";

export default function Page() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Bem-vindo ao Aura UI</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="gradient">Começar</Button>
      </CardContent>
    </Card>
  );
}

Importe da raiz (aura-ui-components) ou por componente (aura-ui-components/button) para o menor bundle. Cada página em Componentes mostra o import exato.