Han Design Gives AI Agents a Chinese-Style Web Toolkit That Knows When to Stop

Han Design is a Chinese-style web design Skill for AI Agents, and also a set of CSS visual assets that can be directly copied into real projects.

The current version is v0.1.0-preview.0. Trials, feedback, and collaborative refinement are welcome.

The starting point wasn't CSS, it was a sentence

Here's how it happened.

I've always loved ancient Chinese culture.

Not the kind of love where you just change your avatar to red during Chinese New Year, but the kind where you can't help but look a little longer when you see ancient architecture, calligraphy, landscapes, artifacts, opera, or traditional patterns.

Some time ago, I thought again of something Jay Chou once said: "Chinese style is the coolest."

It sounds simple, but every time I think about it, it still feels energizing.

Because it's not just about music.

In recent years, whether in music, film, or visual art, I've seen more and more creators blending Chinese culture and Chinese aesthetics into their work. Some put classical instruments into pop arrangements, some turn traditional clothing, architecture, and colors into a new visual language, and some reimagine the stories we grew up hearing in animation, games, and on stage.

They aren't moving ancient elements over unchanged; they're letting these things continue to live in the present.

I started thinking: if a song, a movie, or a piece of art can have Chinese style, why can't a website?

Why is it that when a webpage mentions Chinese style, it's reduced to a beige background, a calligraphy-brush title, a red seal, and a ring of auspicious clouds?

My website should also have a bit of its own ancient charm, its own Chinese-style beauty.

Not to slap a Chinese-style label on the page, but so that when a user opens it, they can feel a hint of rice-paper warmth, the breath of ink, the quiet of negative space, and those cultural memories that belong to us.

That became the original intention behind Han Design.

I didn't want to make another Chinese-style page that just piles up symbols

At first, I really just wanted to make a page look a bit nicer.

The page already had seals, ink wash, rice paper, calligraphy, and scrolls. Individually, each element felt quite Chinese, but put together, something always felt off.

How to describe it.

It's like visiting an ancient town: you walk through the gate and see the memorial archway and think it's kind of interesting, but fifty meters further in, lanterns, auspicious clouds, dragon patterns, KaiTi font, and gold outlines all rush at you at once...

You can't say it's not Chinese.

You can only say it's trying a bit too hard to be Chinese.

So I started wondering: could this passion be turned into a true Eastern design language suited for the web? One that doesn't prove itself by piling up symbols, doesn't dare call itself national style just by switching to red and KaiTi, and isn't just asking AI to casually generate an ink-wash background image that leaves developers staring blankly at the picture.

Instead, it could actually land in things like HTML, CSS, React, and Vue.

AI Agents could understand it, frontend devs could continue modifying it, designers could keep adjusting it, and in the end, it could pass keyboard, contrast, and mobile checks.

After a round of tinkering, Han Design came into being.

The Chinese name is just one character.

汉 (Han).

The project is now open source, still at version v0.1.0-preview.0. It's not mature, and I wouldn't dare claim it defines any Eastern aesthetic standard. I'm still figuring things out myself.

But at least, it's no longer a design file lying in Figma, nor a pile of effect images that can only be looked at, not used.

It is now a design Skill that AI Agents can directly invoke, and a set of CSS visual assets that can be copied into real projects.

The image above is a real page from the project.

The seal buttons, landscape layers, fonts, colors, spacing, icons, and animations you see on the page are all genuinely rendered by the browser.

Why make this a Skill instead of yet another CSS framework?

I thought about this question at the start.

There are already enough frontend component libraries: Ant Design, Element Plus, TDesign, Arco Design — any of them is more complete than a personal project. Frankly, making another set of Buttons, Modals, Tables, and Date Pickers would be meaningless, aside from exhausting myself to death.

What Han Design really aims to solve

What Han Design really aims to solve isn't a shortage of components.

It's that AI, when designing Chinese-style pages, takes shortcuts far too easily.

I didn't make this project to make all websites look the same.

I hope it acts more like an entry point, letting more websites borrow a bit of ancient charm, use a bit of China's own visual language, but ultimately still grow into their own thing.

If you tell it to make a Song-dynasty-style website, it often starts by setting the background to beige, then adds a calligraphy-brush title, stamps a red seal in the bottom right corner, and very confidently tells you that Song aesthetics are complete.

Come on, man...

If Song style were really that simple, designers would have clocked out long ago.

So the most important thing inside Han Design isn't actually the CSS; it's the judgment rules.

The Agent first determines whether you want historical restoration, historical inspiration, or contemporary Chinese style. It considers the period, region, medium, usage scenario, and visual intensity, then decides which theme to use, which reference materials to read, and which cultural symbols require caution.

When it comes to dragons, phoenixes, bats, lotuses, religious imagery, and official-rank patterns, it can't just casually stick them onto a page.

When it comes to calligraphy and seals, it must distinguish between calligraphic association, real script styles, seal faces, and plain red squares.

When it comes to region, ethnicity, religion, and living culture, it can't stuff everything into a drawer labeled "traditional Chinese style."

These rules might not be as flashy as CSS to read about, but I increasingly feel that this is exactly what a design Skill should have most.

Because if a style is written wrong, you can fix it.

If the cultural context is nonsense, it's genuinely embarrassing.

Of course, talking about culture can't just be about caution, or the resulting pages will end up feeling like museum disclaimers.

So Han Design still comes with plenty of things you can directly play with.

16 themes, not 16 color-swap skins

Currently, there are 16 themes in total.

Seven are dynasty-inspired themes: Qin-Han, Wei-Jin, Tang, Song, Yuan, Ming, and Qing.

The other nine lean toward specific visual scenarios: Ink Wash, Blue-Green Landscape, Blue-and-White Porcelain, Dunhuang, Court Gold, Martial-Art Dark Ink, Contemporary Tea Space, Vermilion Celebration, and Celadon.

The word "inspired" is used deliberately here.

They are visual starting points for modern web use, not historical restorations, and certainly don't imply that a dynasty had only this one color and temperament.

What you get	Specific contents
Theme system	7 dynasty-inspired themes, 9 cultural-scene themes
Visual assets	Color, typography, spacing, shadow, animation, and pattern tokens
Page components	Seal buttons, scroll cards, title slips, window lattice, screens, lanterns, etc.
Agent rules	Cultural context, theme selection, accessibility, and output boundaries
Integration methods	Standalone pages use han.css; existing projects use han-scoped.css

Switching themes doesn't require rewriting the entire page's CSS; just set a data-theme attribute.

<html lang="zh-CN" data-theme="song">

If you want a celadon direction, switch to celadon. For ink wash, use ink. For a more restrained tea brand, you can start from tea and then adjust further based on the brand itself.

I say "start from" because a theme is not the answer.

It's more like a starting point that won't let you go off track right from the beginning.

Han Design also includes seal buttons, scroll cards, window-lattice borders, title slips, album leaves, screens, lanterns, patterns, icons, typography, and some layout tools translated from the composition of Chinese painting.

But there's one rule here that I personally really like.

On a single page, it's best not to use more than two groups of eye-catching decorative components at the same time.

Exercise restraint.

Sometimes I feel that the so-called "premium feel" isn't that mysterious. Often, it's just knowing when to stop.

When actually integrating into a project, scoped is the key

Speaking of components, I need to be upfront here too.

Han Design is not a complete interactive component library.

Static structures like cards, dividers, seals, and title slips can be used right away.

For things like Modals, Tabs, custom Selects, Date Pickers, Trees, and Uploads, CSS can only handle the appearance. Keyboard behavior, focus management, state synchronization, and ARIA still need to be handled by the host project's existing components.

So it won't package a static dialog screenshot as a production-grade Dialog just to make it look like there are many components.

Looking clickable and being truly usable are separated by quite a lot.

This was also one of the most concrete pitfalls I hit while making this project.

Initially, I prepared a han-scoped.css for existing applications. The idea was simple: if I don't import a global reset, it won't pollute the host project, right?

But when I actually tested it in the browser, problems appeared.

Tokens were still being attached to :root, theme selectors could still potentially collide with the host project, and even .han-container secretly depended on the global box-sizing. It looked fine on desktop, but when switched to a 375-pixel width, the page had an extra 7 pixels of horizontal scrolling.

7 pixels.

These little things are the most annoying because they're easy to miss when eyeballing a screenshot, but once they're in your project, they'll keep nagging at you.

Later, I separated the global base styles, utility classes, and accessibility rules, added an explicit data-han-scope boundary to the scoped entry point, and made tokens and theme variables only take effect within this area.

The host application continues using its own fonts, border radii, colors, and buttons. Han only lays down a little ink where needed.

Now, a scoped integration looks roughly like this.

<link rel="stylesheet" href="/han/han-scoped.css">

<section data-han-scope data-theme="song">
  <button type="button" class="han-btn-seal">Confirm</button>
</section>

This might not be as flashy as a full-screen animation, but for people actually maintaining projects, I think this capability is more useful.

You don't need to overturn your existing design system, don't need to rewrite an entire component suite for Chinese style, and don't need a marketing page's styles crawling through the entire backend system via body and button.

Only lay down a little ink where it's needed.

How to get started

If you want to try it, installation isn't complicated.

First, clone the repository.

git clone https://github.com/you-want/han-design.git han

Then copy the Skill directory into the Agent Skills directory.

mkdir -p "$HOME/.agents/skills"
cp -R skills/han-design "$HOME/.agents/skills/han-design"

For Codex, you can also place it in ~/.codex/skills/han-design.

Once installed, you don't need to memorize a bunch of commands; just talk to the Agent in plain language.

Using han-design, help me make a restrained Song-style product landing page.

Using han-design, turn the current React Dashboard into a low-intensity ink-wash style, keeping existing components and interactions, without polluting global styles.

Using han-design, make a mobile-first, contemporary celadon-style official site for a young tea brand.

If you don't want to install the Skill for now and just want the CSS, you can also directly copy skills/han-design/assets.

For standalone pages, use han.css. For scoped integration into existing products, use han-scoped.css.

It's that simple.

What I hope it eventually becomes

Of course, what's simple is the start, not the final result.

The hardest part of Chinese style has never been finding a red color or a rice-paper texture. The truly hard part is knowing what you're expressing, why you're using this element, and why you stop here.

This is also something I've become more and more certain of after finishing Han Design.

Design assets in the AI era can't just give AI a pile of copyable code.

You also have to give it judgment.

When to use it, when not to, what can be said, what can't be casually thrown around, what is just a modern design association, and what needs to be checked against real sources.

Code determines whether a page can run.

Judgment determines whether it ultimately looks like something made with care.

Final words

The project is now open source under the MIT License. You're welcome to take it and play with it directly, and also welcome to submit Issues, PRs, add themes, fix accessibility, or tell me where it still looks too much like a tourist-trap souvenir shop...

Honestly, I don't know what it will eventually grow into.

Maybe a set of increasingly mature Agent design Skills, maybe a very light layer of Eastern visual language in many projects, or maybe just a starting point for people who like Chinese culture and web design to keep tinkering.

But I always feel this is worth doing.

Because the Chinese internet doesn't lack Chinese-style images.

What it lacks are Chinese-style design tools that can land in real products, can be continuously maintained, and are willing to respect cultural boundaries.

Only lay down a little ink where it's needed.

This sentence fits well on a page.

It seems to fit just as well when applied to making tools.

Project address: Han Design on GitHub

If you find this project somewhat interesting, a Star is welcome. You're also welcome to throw the pages you make my way.

I genuinely really want to see what people will create with it.