# Aqua — full component reference for LLMs

> Aqua recreates the classic Mac OS X (2000–2007) interface as a shadcn/ui registry: accessible React components on Radix primitives, styled with Tailwind CSS into gel gradients, pinstripes and brushed metal. Made by Igor Duca (https://duca.dev, @ducaswtf on X).

## Setup

1. The project must have shadcn/ui initialized (npx shadcn@latest init).
2. Register the namespace in components.json:

{
  "registries": {
    "@aqua": "https://aqua.duca.dev/r/{name}.json"
  }
}

3. Install the theme first: npx shadcn@latest add @aqua/theme
4. Add components as needed: npx shadcn@latest add @aqua/button @aqua/tabs

Components are copied into the project as source files and import as @/components/ui/<name>. Dependencies (Radix packages, lucide-react, shiki) install automatically.

## Theming

Every component derives its color from the --aqua-accent CSS variable and falls back to Aqua blue (#2f7de0) when the theme is absent. To retheme globally:

:root { --aqua-accent: #e02f6b; }

Scoped themes work too — set --aqua-accent on any element and its subtree recomputes (the derived --aqua-gel-* variables are declared on the universal selector).

## Avatar (@aqua/avatar)

The iChat buddy icon: photo, initials over a gel color, or the classic generic silhouette.

Install: npx shadcn@latest add @aqua/avatar
Docs: https://aqua.duca.dev/docs/avatar
Registry JSON: https://aqua.duca.dev/r/avatar.json

import { Avatar } from "@/components/ui/avatar"
<Avatar src="/me.png" /> | <Avatar initials="SJ" /> | <Avatar initials="ID" color="#e02f6b" /> | <Avatar initials="JI" randomColor /> | <Avatar /> (generic silhouette)
Props: size (sm|default|lg), shape (square|circle), color (any hex, rendered as gel), randomColor (stable hash of initials).

## Alert (@aqua/alert)

Soft gradient notice panel in note, caution and stop flavors.

Install: npx shadcn@latest add @aqua/alert
Docs: https://aqua.duca.dev/docs/alert
Registry JSON: https://aqua.duca.dev/r/alert.json

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
<Alert variant="warning"><AlertTitle>Low battery</AlertTitle><AlertDescription>…</AlertDescription></Alert>
Variants: default (note/blue), warning (caution/yellow), destructive (stop/red). Accepts an svg icon as first child.

## Dropdown Menu (@aqua/dropdown-menu)

Aqua context menu: white panel, gel highlight, checkable items and submenus.

Install: npx shadcn@latest add @aqua/dropdown-menu
Docs: https://aqua.duca.dev/docs/dropdown-menu
Registry JSON: https://aqua.duca.dev/r/dropdown-menu.json

import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@/components/ui/dropdown-menu"
Also exports CheckboxItem, RadioGroup/RadioItem, Label, Separator, Shortcut, Sub menus. Item variant="destructive" gets red gel highlight.

## Label (@aqua/label)

Etched form label in classic panel typography.

Install: npx shadcn@latest add @aqua/label
Docs: https://aqua.duca.dev/docs/label
Registry JSON: https://aqua.duca.dev/r/label.json

import { Label } from "@/components/ui/label"
<Label htmlFor="name">Account Name</Label> — pairs with Input/Textarea via htmlFor.

## Radio Group (@aqua/radio-group)

Glossy round radios that fill with gel and a white pip when selected.

Install: npx shadcn@latest add @aqua/radio-group
Docs: https://aqua.duca.dev/docs/radio-group
Registry JSON: https://aqua.duca.dev/r/radio-group.json

import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
<RadioGroup defaultValue="a"><label><RadioGroupItem value="a" /> Option A</label></RadioGroup>

## Textarea (@aqua/textarea)

Multi-line Aqua text well with an inset shadow and blue focus halo.

Install: npx shadcn@latest add @aqua/textarea
Docs: https://aqua.duca.dev/docs/textarea
Registry JSON: https://aqua.duca.dev/r/textarea.json

import { Textarea } from "@/components/ui/textarea"
<Textarea placeholder="Message" /> — multi-line version of the Input well.

## Toast (@aqua/toast)

Growl-style notifications: call toast() and an Alert slides in from the corner.

Install: npx shadcn@latest add @aqua/toast
Docs: https://aqua.duca.dev/docs/toast
Registry JSON: https://aqua.duca.dev/r/toast.json

import { Toaster, toast } from "@/components/ui/toast"
Mount <Toaster /> once near the root, then call toast({ title, description, variant, duration }) from anywhere. Growl-style: slides in top-right, auto-dismisses after 5s. Depends on @aqua/alert (installed automatically).

## Code Block (@aqua/code-block)

Shiki-highlighted code card with an Aqua copy button.

Install: npx shadcn@latest add @aqua/code-block
Docs: https://aqua.duca.dev/docs/code-block
Registry JSON: https://aqua.duca.dev/r/code-block.json

import { CodeBlock } from "@/components/ui/code-block"
<CodeBlock code={"const x = 1"} lang="ts" /> — async server component (shiki highlighting at render time) with an Aqua copy button. Next.js App Router only.

## Loader (@aqua/loader)

The twelve-spoke spinner, ticking around in steps like the original.

Install: npx shadcn@latest add @aqua/loader
Docs: https://aqua.duca.dev/docs/loader
Registry JSON: https://aqua.duca.dev/r/loader.json

import { Loader } from "@/components/ui/loader"
<Loader /> | <Loader className="size-4 text-white" /> — the twelve-spoke spinner ticking in steps(12); size and color via className (currentColor).

## Cursor (@aqua/cursor)

Wrap your app and get the classic Aqua arrow, pointing hand and I-beam cursors.

Install: npx shadcn@latest add @aqua/cursor
Docs: https://aqua.duca.dev/docs/cursor
Registry JSON: https://aqua.duca.dev/r/cursor.json

import { AquaCursor } from "@/components/ui/cursor"
Wrap the app once: <AquaCursor>{children}</AquaCursor>. Swaps cursors app-wide for the era set: black arrow with white outline, pointing hand on links, seriffed I-beam over text. Renders display:contents (no layout box).

## Badge (@aqua/badge)

Tinted capsule label in blue, glossy gray and red.

Install: npx shadcn@latest add @aqua/badge
Docs: https://aqua.duca.dev/docs/badge
Registry JSON: https://aqua.duca.dev/r/badge.json

import { Badge } from "@/components/ui/badge"
<Badge>new</Badge> — variants: default (blue), secondary (gray), destructive (red).

## Button (@aqua/button)

Glossy Aqua pill button with gel highlight, in blue, capsule and red.

Install: npx shadcn@latest add @aqua/button
Docs: https://aqua.duca.dev/docs/button
Registry JSON: https://aqua.duca.dev/r/button.json

import { Button } from "@/components/ui/button"
<Button>Save</Button>
<Button variant="secondary">Cancel</Button>
<Button variant="destructive">Delete</Button>
Variants: default (blue gel), secondary (glossy capsule), destructive (red gel). Sizes: sm, default, lg. Supports asChild.

## Tabs (@aqua/tabs)

Aqua tab bar with glossy active state over a pinstripe content pane.

Install: npx shadcn@latest add @aqua/tabs
Docs: https://aqua.duca.dev/docs/tabs
Registry JSON: https://aqua.duca.dev/r/tabs.json

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">General</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>
Renders as a gel segmented control seated on a pinstripe pane (NSTabView style).

## Input (@aqua/input)

The classic Aqua text field: white well with an inset shadow and blue focus halo.

Install: npx shadcn@latest add @aqua/input
Docs: https://aqua.duca.dev/docs/input
Registry JSON: https://aqua.duca.dev/r/input.json

import { Input } from "@/components/ui/input"
<Input placeholder="Search" /> — white well, inset shadow, blue focus halo.

## Checkbox (@aqua/checkbox)

Glossy square that fills with blue gel when checked.

Install: npx shadcn@latest add @aqua/checkbox
Docs: https://aqua.duca.dev/docs/checkbox
Registry JSON: https://aqua.duca.dev/r/checkbox.json

import { Checkbox } from "@/components/ui/checkbox"
<Checkbox defaultChecked /> — glossy square that fills with gel when checked.

## Switch (@aqua/switch)

Gel toggle with a polished metal thumb.

Install: npx shadcn@latest add @aqua/switch
Docs: https://aqua.duca.dev/docs/switch
Registry JSON: https://aqua.duca.dev/r/switch.json

import { Switch } from "@/components/ui/switch"
<Switch defaultChecked /> — gel toggle with polished metal thumb.

## Select (@aqua/select)

The Aqua popup button: glossy capsule with a gel arrow box, menu with gel highlight.

Install: npx shadcn@latest add @aqua/select
Docs: https://aqua.duca.dev/docs/select
Registry JSON: https://aqua.duca.dev/r/select.json

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
<Select defaultValue="blue"><SelectTrigger><SelectValue /></SelectTrigger><SelectContent><SelectItem value="blue">Blue</SelectItem></SelectContent></Select>
Also exports SelectGroup, SelectLabel, SelectSeparator. Styled as the classic NSPopUpButton.

## Slider (@aqua/slider)

iTunes volume slider: groove track, blue gel range, polished knob.

Install: npx shadcn@latest add @aqua/slider
Docs: https://aqua.duca.dev/docs/slider
Registry JSON: https://aqua.duca.dev/r/slider.json

import { Slider } from "@/components/ui/slider"
<Slider defaultValue={[60]} max={100} step={1} /> — iTunes-style groove with gel range.

## Dialog (@aqua/dialog)

The Aqua alert panel: soft gradient sheet with a deep drop shadow.

Install: npx shadcn@latest add @aqua/dialog
Docs: https://aqua.duca.dev/docs/dialog
Registry JSON: https://aqua.duca.dev/r/dialog.json

import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog"
Standard Radix dialog composition, styled as the Aqua alert sheet.

## Progress (@aqua/progress)

The iconic striped blue barber-pole progress bar.

Install: npx shadcn@latest add @aqua/progress
Docs: https://aqua.duca.dev/docs/progress
Registry JSON: https://aqua.duca.dev/r/progress.json

import { Progress } from "@/components/ui/progress"
<Progress value={62} /> — the striped barber-pole bar; stripes animate while in progress.

## iPod (@aqua/ipod)

The classic iPod: white shell, LCD screen and a working click wheel.

Install: npx shadcn@latest add @aqua/ipod
Docs: https://aqua.duca.dev/docs/ipod
Registry JSON: https://aqua.duca.dev/r/ipod.json

import { IPod, IPodScreen, IPodHeader, ClickWheel } from "@/components/ui/ipod"
The classic iPod shell with LCD screen and a working click wheel (onMenu, onPrev, onNext, onPlayPause, onSelect handlers).

## Window (@aqua/window)

Brushed metal window chrome with traffic lights and a titlebar.

Install: npx shadcn@latest add @aqua/window
Docs: https://aqua.duca.dev/docs/window
Registry JSON: https://aqua.duca.dev/r/window.json

import { Window, WindowTitlebar, WindowTitle, WindowContent, TrafficLights } from "@/components/ui/window"
Brushed metal window chrome with red/yellow/green traffic lights.

## Dock (@aqua/dock)

The translucent shelf: magnifying items, hover labels and running indicators.

Install: npx shadcn@latest add @aqua/dock
Docs: https://aqua.duca.dev/docs/dock
Registry JSON: https://aqua.duca.dev/r/dock.json

import { Dock, DockItem, DockIcon } from "@/components/ui/dock"
<Dock><DockItem label="Finder" active><img src="/icons/finder.png" /></DockItem></Dock>
Hover magnification, haloed labels, running-app dots.

## Chat Bubble (@aqua/chat-bubble)

iChat gradient bubbles with sculpted tails, in blue and orange.

Install: npx shadcn@latest add @aqua/chat-bubble
Docs: https://aqua.duca.dev/docs/chat-bubble
Registry JSON: https://aqua.duca.dev/r/chat-bubble.json

import { ChatBubble, ChatPanel } from "@/components/ui/chat-bubble"
<ChatPanel><ChatBubble from="me">hi</ChatBubble><ChatBubble from="them">hey</ChatBubble></ChatPanel>
iChat gradient bubbles with sculpted tails; "me" is blue/left, "them" orange/right.

## Tooltip (@aqua/tooltip)

Dock-style label tooltip: dark translucent capsule with white text.

Install: npx shadcn@latest add @aqua/tooltip
Docs: https://aqua.duca.dev/docs/tooltip
Registry JSON: https://aqua.duca.dev/r/tooltip.json

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
Styled as the classic yellow help tag (#ffffc7).