introduction

What is @gentleduck/ui?

Look, we're not going to waste your time with flowery marketing speak. @gentleduck/ui is a UI component library that actually works. It's part of the @gentleduck ecosystem a collection of open-source tools built by developers who are tired of fighting their frameworks instead of building great products.

We're here to solve real problems: components that don't break when you look at them wrong, documentation that doesn't assume you have a PhD in computer science, and a maintainer who actually responds to issues. Wild concept, right?

The Human Behind the Duck

@wildduck2 is the architect behind @gentleduck. He's not interested in building another abandoned open-source graveyard. He's obsessed with creating tools that developers actually want to use performant, maintainable, and battle-tested in production environments.

He's also criminally responsive to community feedback. Got a bug? It gets fixed. Got a feature request that makes sense? It gets seriously considered. No corporate bureaucracy, no waiting three quarters for a minor patch. Just direct, honest development.

The entire @gentleduck organization exists because modern web development shouldn't feel like assembling IKEA furniture in the dark. Every library, every tool, every decision is made with one question: "Does this actually help developers ship better products faster?"

Why @gentleduck/ui Doesn't Suck

Most UI libraries fall into two camps: gorgeous but impossible to customize, or flexible but uglier than a frontend developer's first CSS file. @gentleduck/ui refuses to pick a side.

What you actually get:

• Themes that bend to your will: Light mode, dark mode, chaos mode customize everything without fighting specificity wars or using !important like a caveman.

• Responsive by default: Your components work on a 4K monitor and a potato phone. No media query gymnastics required.

• Accessibility baked in: ARIA labels, keyboard navigation, screen reader support all there from day one because shipping inaccessible products in 2025 is embarrassing.

• Performance that matters: These components are optimized to load fast and stay fast. We've done the bundle size optimization so you don't have to explain to your manager why your app loads like it's 2010.

• Actually extensible: Want to modify a component? Go ahead. We won't lock you into our way of doing things. Build your own components using our primitives. Fork what you need. We trust you're not an idiot.

• APIs that make sense: We've designed our component APIs to match patterns from popular libraries you already know. Migrating from other UI frameworks? You'll feel right at home. No need to relearn everything or fight muscle memory.

Contributing (Yes, Actually)

We want your contributions. Bug reports, feature requests, code, documentation improvements, hot takes on component naming bring it all to our GitHub repository.

Unlike projects run by committees, we move fast. Good ideas get implemented. Bad ideas get respectfully declined with actual reasoning. Contributions get reviewed by humans who remember what it's like to be on the other side of a pull request.

The @gentleduck community is built on mutual respect and the shared understanding that we're all just trying to build cool stuff without losing our minds.

Getting Started (The Fast Version)

Install

npx @gentleduck/cli init

npx @gentleduck/cli init

Add Components

npx @gentleduck/cli add button

npx @gentleduck/cli add button

Use Them

import { DuckButton } from '@/components/ui'
 
<DuckButton>Actually works on first try</DuckButton>

import { DuckButton } from '@/components/ui'
 
<DuckButton>Actually works on first try</DuckButton>

That's it. No webpack configuration hell, no mysterious peer dependency conflicts, no sacrificing a rubber duck to the JavaScript gods.

The Origin Story

This started as @wildduck2's side project one of those "I'm tired of this nonsense, I'll build it myself" moments that every developer has at 2 AM. But instead of collecting digital dust, it evolved into something people actually wanted to use.

Was it inspired by Shadcn, Radix UI, Float UI, and others? Absolutely. Great artists steal, and great developers learn from what works. But @gentleduck/ui isn't just another clone it's built from the ground up with its own primitives, utilities, and ecosystem.

We're standing on the shoulders of giants while building something genuinely different. If you're looking for another Shadcn, this isn't it. If you're looking for the fastest, most complete component library maintained by someone who gives a damn, welcome home.

The Ecosystem (Or: How Deep This Rabbit Hole Goes)

Here's where things get interesting. @gentleduck/ui isn't just a component library it's the centerpiece of an entire ecosystem built from the ground up for one purpose: being the absolute best UI library you'll ever use.

We're talking custom primitives, performance utilities, development tools, and yes rewrites of popular libraries that weren't fast enough or flexible enough for what we needed. When existing solutions didn't meet our standards, we didn't compromise. We rebuilt them. Better. Faster. More aligned with modern web development.

This isn't duct tape and wishful thinking. This is a cohesive, intentionally designed system where every piece works together seamlessly. The CLI, the primitives, the utilities, the components they're all part of a larger vision to give you the most powerful, performant UI development experience possible.

Other libraries give you components. We give you an unfair advantage.

Built with spite, caffeine, and an unreasonable commitment to developer experience.