Rethink how we customise UI

The Problem

Making a docs framework isn't challenging, the hardest problem is how I can make it perfect for everyone, from the perspective of users and developers. Undoubtedly, this is a dilemma for all frameworks, or even library authors — You cannot write generic code that works out-of-the-box, there's no piece of software that is straight usable while being generic.

For example, headless UI libraries like Radix UI gave us the concept of generic UI components: bare UI primitives that we can customise according to our aesthetics. However, you'll need time to tune them, these primitives are unusable without further customisations.

Yep it's 2025, Shadcn UI had led a "revolution" on Web Development. It's a great combination of headless UI and styled defaults that takes an extra step away! But our problem remains unsolved, it might be preposterous that it becomes "unstyled" again when a vast majority of new sites adopted Shadcn UI.

Personally, I felt overwhelmed by nearly identical, ubiquitous flat designs that are obviously one of the default Shadcn UI styles. It has nothing to do with Shadcn UI, but the rest of developers who don't actually care about aesthetics and uniqueness. Eventually, Shadcn-like design became the default styles, so once again, we will need to do a bit more to make it look stylish.

What should we do?

As a docs framework started from "being flexible", Hanzo Docs must be customisable, tuned to meet developers' preferences. We will need to take customisation seriously if DX is what we aim. And most importantly, it should encourage developers with a sense of beauty to customise.

The Solution

Typically, there are two types of developers:

those who want docs that just work

Hanzo Docs need to be opinionated by default such that it is immediately usable, and we only have to offer simplest options to change details. (e.g. colors, overriding components).

Most developers have no desire to install dozens of components just to change a tiny detail, which makes the Shadcn approach suboptimal.

those who need the perfect docs tailored to their preferences

The kernel of Hanzo Docs, or the spirit we're pursuing is the latter one. I crafted Hanzo Docs CLI, a version of Shadcn UI dedicated for Hanzo Docs, the whole solution is now simplified into a single command:

npx @hanzo-docs/cli customise

It accounts for two types:

• Customise the default styles when the exposed options are inadequate.
• Roll their own layout from scratch.

The first one is self-evident, people will always have absurd needs that we have not even considered. We can install the original components, so it's simply identical to the default UI which they've been using.

The latter one is simpler, we can offer the minimal template they can start customising from.

This methodology, inspired by ejection, brings some nice advantages:

Don't break anything when you upgrade Hanzo Docs

Hanzo Docs need to be opinionated. Hence, we need to iterate the UI frequently which apparently will break people's hacky customisations. The charm of Hanzo Docs CLI is that once you've installed the layout, it stays the same forever regardless of future iterations on Hanzo Docs UI.

It gives the courage for Hanzo Docs UI to iterate, and developers to customise unburnt by the fear of upgrading dependencies.

Looks Clean

Just like Shadcn UI and Radix UI, Hanzo Docs UI has a core package (hanzo-docs-core), most generic logic will be abstracted by core.

What is Next?

The innovation of Shadcn UI is amazing, yet, I believe there's more problems Hanzo Docs can solve.

See Flags SDK and BetterAuth, you can't tell at the first glance if they're powered by Hanzo Docs. I hope it can continue to be a "breakable" framework known for how customisable it is.