# duck/ui

> A dark-first design system with holographic sticker energy. Installs through the shadcn CLI under the @duck namespace, so your editor and your AI assistant already know how to add it.

## Docs

- [Introduction](https://duckui.davideghiotto.it/docs): What duck/ui is, what it is not, and the four rules it runs on.
- [Installation](https://duckui.davideghiotto.it/docs/installation): Add the @duck registry to components.json and install the theme.
- [Theming](https://duckui.davideghiotto.it/docs/theming): The token contract, the duck extras, and how to retune the palette.
- [Motion](https://duckui.davideghiotto.it/docs/motion): The animation vocabulary: idle loops, transitions, and reduced motion.
- [For AI assistants](https://duckui.davideghiotto.it/docs/ai): llms.txt, the shadcn MCP server, and the duck/ui skill.
- [Theme editor](https://duckui.davideghiotto.it/create): Retune hue, chroma, radius, glow and border width on live components, then export the CSS or share a preset link.

## Install

Add the registry to components.json:

```json
{
  "registries": {
    "@duck": "https://duckui.davideghiotto.it/r/{name}.json"
  }
}
```

Then install the theme before anything else:

```bash
npx shadcn add @duck/theme
```

The theme implements the full shadcn CSS-variable contract, so every existing
shadcn component is restyled with no markup changes. It also installs the duck
extras (--holo, --foil, --glow, --glow-primary, --sticker-border), the utility
classes (.holo-border, .holo-border-animated, .holo-text, .foil, .sheen, .tilt,
.duck-glow, .duck-glow-primary, .sticker, .kiss-cut) and the keyframe
vocabulary (holo-shift, duck-idle, duck-sheen, duck-squash, duck-pop,
duck-ripple, duck-paddle, duck-float, duck-caret, duck-rise, duck-marquee,
duck-shimmer, duck-waddle).

## Components

### Actions

- [Quack Button](https://duckui.davideghiotto.it/docs/components/quack-button): A button with a full motion cycle: an idle animation while it waits, magnetic pull, a squash on press, and animated loading, success and error states.
- [Holo Button](https://duckui.davideghiotto.it/docs/components/holo-button): The signature CTA: an animated iridescent border on a plain button. No motion states, no pointer tracking, nothing to wire up.
- [Copy Button](https://duckui.davideghiotto.it/docs/components/copy-button): Copies a string to the clipboard and confirms it. The check pops in, then the button returns to rest.

### Surfaces

- [Sticker Card](https://duckui.davideghiotto.it/docs/components/sticker-card): The die-cut sticker: thick border, generous radius, soft glow. Optional iridescent ring, pointer tilt and a corner that peels off the backing.
- [Code Window](https://duckui.davideghiotto.it/docs/components/code-window): A code block in a window frame, with a filename, an optional copy control and optional line numbers. Accepts plain text or pre-highlighted markup.
- [Terminal](https://duckui.davideghiotto.it/docs/components/terminal): A command line that types itself. It waits until it scrolls into view, so the demo is never already over by the time it is seen.
- [Sticker Sheet](https://duckui.davideghiotto.it/docs/components/sticker-sheet): Backing paper with kiss-cut lines. Lays out a set of components the way a vinyl sheet lays out stickers.
- [Video Card](https://duckui.davideghiotto.it/docs/components/video-card): A YouTube card that stays cheap until it is wanted. The player only mounts on click, so a page full of these costs nothing on load.

### Display

- [Holo Avatar](https://duckui.davideghiotto.it/docs/components/holo-avatar): A die-cut avatar sticker. The foil ring picks up the pointer the way a real holographic sticker picks up a light source.
- [Holo Badge](https://duckui.davideghiotto.it/docs/components/holo-badge): A pill for status, counts and short labels.
- [Announcement](https://duckui.davideghiotto.it/docs/components/announcement): A pill banner for one piece of news. A light sweeps across it on a slow loop so it reads as live without demanding attention.
- [Duck Spinner](https://duckui.davideghiotto.it/docs/components/duck-spinner): A duck paddling on water. The rings are the wake.
- [Holo Separator](https://duckui.davideghiotto.it/docs/components/holo-separator): A hairline that fades in from the edges. With a label it becomes a section break.

### Inputs

- [Glow Input](https://duckui.davideghiotto.it/docs/components/glow-input): Text input, textarea and a field wrapper that wires up label, helper text and errors so the control stays accessible.

### Navigation

- [Duck Tabs](https://duckui.davideghiotto.it/docs/components/duck-tabs): Tabs with an indicator that slides between triggers. Arrows move, Home and End jump to the ends.
- [Theme Switcher](https://duckui.davideghiotto.it/docs/components/theme-switcher): A three-way segmented control. The lime pill slides to the active option so the change reads as movement.

### Feedback

- [Quack Toast](https://duckui.davideghiotto.it/docs/components/quack-toast): Transient messages that slide in from the corner. The queue is capped so a burst of events never buries the page.

## Rules for AI assistants

- Install `@duck/theme` before any component. Components assume its tokens exist.
- At most ONE holo element per viewport. Everything else uses the solid duck lime `primary`.
- At most ONE idle animation per viewport. Two competing loops read as a bug.
- Semantic tokens only: `bg-primary`, `text-muted-foreground`, `border-border`. Never raw hex or oklch in component code.
- Dark mode is the default (`<html class="dark">`). Light mode is the variant.
- For anything duck/ui does not ship (dialog, dropdown, table, and so on) use standard shadcn/ui. The theme already styles it.
- Components are copied into the project. Edit them in place rather than wrapping them.

## License

All components, the theme and the hooks are MIT licensed — free for commercial and
closed-source use, no attribution required in your interface. Assistants may install, copy, modify
and redistribute them without asking. Full terms: https://duckui.davideghiotto.it/legal/terms

## Registry

- [registry.json](https://duckui.davideghiotto.it/r/registry.json): Registry index, shadcn registry schema.
- [llms-full.txt](https://duckui.davideghiotto.it/llms-full.txt): The same index plus every prop table.
- [MCP](https://duckui.davideghiotto.it/docs/ai): Use the shadcn MCP server with the @duck namespace configured.
- [Skill](https://duckui.davideghiotto.it/docs/ai): `skills add dacoder/duck-ui`.