Han.css: A Sass, Stylus and JavaScript Typography Framework for Hanzi Web Pages

The typography problem Han.css exists to solve

Browsers treat Chinese and Japanese text as a stream of uniform ideographs with Latin punctuation rules bolted on. Full-width commas and periods sit in the middle of their em box, leaving a visible gap after every clause. Opening brackets and quotation marks hang awkwardly at the start of a line, closing ones dangle at the end. Latin words and numbers embedded in Chinese text get no extra space, so they collide with the characters around them. Han.css addresses exactly this layer: the project describes itself as a Sass/Stylus and JavaScript typesetting framework that standardises semantics, type design and advanced typesetting, and it states that it supports Traditional Chinese, Simplified Chinese and Japanese.

The audience is narrow and specific. It is for people publishing long-form Chinese or Japanese prose on the web: documentation sites, news archives, essay collections, government or academic pages. It is not for Latin-first sites that happen to have a few Chinese strings, because the stylesheet's defaults assume Han text is the main content and will re-space things accordingly.

How the stylesheet and the script divide the work

The repository ships two independent layers. The CSS side exists as Sass (index.scss), Stylus (index.styl) and precompiled output (han.min.css), and it carries the static rules: punctuation compression, spacing between Han characters and Latin text, and line-breaking behaviour. The JavaScript side (index.js, built into han.min.js) does the DOM work that CSS alone cannot express, and it is opt-in. The README states that the stylesheet and the script each do their own job with very low interdependence, and that multiple levels of style fallback exist, so the script can be skipped entirely.

That split is the design decision worth noting. A site that only needs punctuation and spacing rules can ship the CSS and nothing else. The script is only needed for the rendering passes the README points to in its JavaScript API manual. The README also states that han.min.css must be referenced before all other stylesheets on the page, which is an ordering constraint rather than a dependency, but it matters: load it after a reset or a framework and the rules lose their precedence.

Installing han-css and enabling rendering on a page

The README lists three package managers. Pick the one matching your build. For a Node or bundler-based project, the package is published as han-css:

npm install --save han-css

Bower and Rails users have their own routes, `bower install --save Han` and the `hanzi-rails` gem. If you would rather not compile anything, the README points at cdnjs for a prebuilt stylesheet, script and web font, compiled with default values. The stylesheet link looks like this:

<link rel="stylesheet" media="all" href="//cdnjs.cloudflare.com/ajax/libs/Han/3.3.0/han.min.css">

The README's three usage steps are: reference the compiled stylesheet before every other stylesheet, optionally load the script, and add the class `han-init` to the `<html>` element to enable DOM-ready rendering. The script tag and the class together look like this:

<script src="//cdnjs.cloudflare.com/ajax/libs/Han/3.3.0/han.min.js"></script>

With `han-init` on the html element, the script runs its rendering pass once the DOM is ready. If you need a different trigger, the README directs you to the rendering section of the JavaScript API manual rather than describing alternatives inline. The web font is available separately as WOFF and OTF files under the same cdnjs path.

Where Han.css stops being the right tool

The framework is a typographic normaliser, not a component system. It gives you no grid, no buttons, no form styling beyond what normalize.css, one of its two runtime dependencies, already provides. If you are looking for a UI kit that happens to handle Chinese, this is the wrong layer.

The more concrete limitation is release cadence. The recent releases listed for the repository end at v3.2.7 on 2015-10-26, while the README itself documents version v3.3.0 and the package.json declares `"version": "3.3.0"`. So the version in the repository has never appeared as a tagged release in the list you can see. Anyone pinning to a release tag is pinning to something older than what the README describes. The repository is not archived, and its last push was on 2026-09-06, but the gap between the last tagged release and the current version number is the thing to check before you depend on a specific behaviour.

The build toolchain is the second boundary. The devDependencies pin gulp 3.9, LiveScript 1.4 and gulp-sass 2.1, and the engines field asks only for Node `>= 0.12`. Gulp 3 does not run on current Node releases without workarounds. If you intend to compile the Sass yourself rather than use the CDN build, budget for that before you start.

Han.css against a general-purpose CSS reset

The obvious alternative is normalize.css alone, which Han.css already depends on. The difference in approach is the whole point: normalize.css makes default elements render consistently across browsers, and stops there. It has no opinion about where a full-width comma should sit, how much space belongs between a Han character and a Latin word, or which characters may start a line. Han.css takes over at that point and adds the Han-specific rules on top.

A second alternative is to write the punctuation and spacing rules yourself with a handful of `font-feature-settings`, `text-spacing` and `line-break` declarations. That is viable if you need three rules. It stops being viable when you need the full set across Traditional Chinese, Simplified Chinese and Japanese, because the punctuation sets differ between the three and the framework already encodes those differences. The trade-off is control: hand-written rules are transparent and easy to audit, while Han.css is a large compiled stylesheet whose internal structure you have to read the Sass source to understand.

Licence, upgrades and what maintenance actually costs

The project is MIT licensed, and the LICENSE.md file is at the repository root. MIT permits commercial and closed-source use with the copyright notice retained; that is the general shape of the licence, and anyone with specific obligations should read LICENSE.md rather than take this summary as advice.

Upgrade cost is dominated by the release situation, not by the licence. Because the newest version in the repository (3.3.0) is ahead of the newest tagged release (3.2.7), you have to decide whether to track the npm package, the CDN build, or the git repository, and those three may not be in step. The CDN URLs in the README are version-pinned at 3.3.0, so a CDN user gets 3.3.0 while a tag-pinning user gets 3.2.7. The CHANGELOG.md at the repository root is the place to check what changed between them.

Customisation runs through Sass variables and module imports, documented at hanzi.pro/manual/sass-api. That is the intended upgrade path: compile your own stylesheet from the source with your variables, rather than overriding the compiled output with later rules, which the README's ordering requirement makes fragile.

Reproducing the demos before you commit

The repository carries a demo directory with paired Jade and HTML files for each feature area: biaodian (punctuation), counter, deco-line, em, four, generics and hanging. Each demo has its own compiled CSS, for example demo/biaodian.html with demo/han.css and demo/han.min.css alongside it. The README links to a live test page at ethantw.github.io/Han/latest/.

Open those pages first. They show what the framework actually does to punctuation and spacing on real text, which is more useful than reading the Sass source, and they let you compare the rendering against your own content before you add a class to your html element. If the demos render acceptably in the browsers you support, the integration is one stylesheet link and one class. If they do not, no amount of configuration will fix it, and you are back to hand-written rules.

Editorial conclusion

Han.css fits sites whose primary content is Chinese or Japanese prose and whose authors can add a class to the html element and load one stylesheet before everything else. It does not fit Latin-only sites, and it does not fit projects that need a maintained release cadence: the last tagged release listed is v3.2.7 from 2015-10-26, while the repository's last push was on 2026-09-06. Before adopting, open the demo pages in the repository, confirm the compiled CSS matches the version you install, and check whether the older toolchain in package.json (gulp 3.9, LiveScript 1.4) still builds on your Node version.

Frequently asked questions

Official sources

1. ethantw/Han on GitHub
2. License: MIT
3. Project website
4. README
5. Releases