Japanese Mahjong Font: Text-to-Tile Typography with OpenType
(opens in new window)Behind The Project
The mahjong community faces a documentation problem. Players want to analyze hands, create strategy guides, and share interesting plays, but there is no efficient way to represent tiles in digital text. The existing options are all inadequate: copying blurry screenshots, manually editing images, or relying on text-based representations that fail to convey the visual nature of the game.
While mahjong tiles do exist in Unicode (see the Mahjong Tiles Unicode block(opens in new window)), this solution has critical limitations. The characters render inconsistently across platforms, most input methods don’t support them (forcing users to rely on copy-paste workflows), and crucially, the standard lacks essential elements like rotated tiles for Chi (チー), Pon (ポン), and Kan (カン) melds, making it impossible to properly represent complete game notation.
This affects thousands of players who write about Japanese mahjong (Riichi mahjong) strategy. Every blog post, forum discussion, or tutorial requires hours of image editing or settling for poor-quality visuals. Strategy content that should be shareable and searchable ends up locked in images with alt-text describing what tiles appear.
(opens in new window)Solution & Approach
I built a complete typography method that solves this. It’s a font with OpenType features that lets players type intuitive notation and automatically render professional-looking mahjong tiles, including rotated melds, red tiles, concealed kans, and tile backs for closed hands. The system handles all the complexity of mahjong notation through typography, not image editing.
(opens in new window)Technical Challenges
(opens in new window)Designing an Intuitive Notation
The challenge was creating a text-based notation system that’s easy to type but expressive enough to represent any mahjong situation. Mahjong tiles include three numbered suits, Pin (circles), Sou (bamboo) and Wan (characters), and unranked honor tiles. Honor tiles are further divided between wind tiles and dragon tiles. Some rules may have red variants tiles which work as Aka-Dora (赤ドラ) that earn more value. General fonts cannot handle this complexity. You’d need hundreds of individual characters.
I designed a notation system using simple markers. Basic tiles use combinations like 1m through 9m for numbered suits. Special states use intuitive symbols: asterisks for Aka tiles (e.g., 5s*), minus signs (-) for rotated tiles, zero for face-down tiles.
Additionally, typing Unicode characters directly is impractical for everyday use. The font uses OpenType features to automatically recognize these patterns and substitute the appropriate glyphs, handling all the visual complexity through typography rules rather than requiring users to remember Unicode code points.
| Tile Name | Notation |
|---|---|
| Wan | 1m ~ 9m |
| Pin | 1p ~ 9p |
| Sou | 1s ~ 9s |
| Zi | 1z ~ 7z（東南西北白発中） |
| Dice | 1. ~ 6. |
| Aka-Dora | Follow by a asterisk (*). E.g., 5m* 5p* 5s* |
| Fuuro | Follow by a minus sign (-). E.g., 4m- 6s- 7z- |
| Ka-Kan | Follow by a equal mark (=). E.g., 2m= 5s= 1z= |
| An-Kan | Use 0m 0p 0s 0z to show the reversed tile |
| Space | Use space ( ) to show a space |
| Big Gap | Use underline (_) to show a big gap |
(opens in new window)OpenType Features
I chose the COLR/CPAL v0 color font format for its universal compatibility. Unlike bitmap formats that blur when scaled or OpenType-SVG that Chrome doesn’t support, COLR stores tiles as vector shapes with color layers, providing perfect scaling at small file sizes.
Beyond browsers, COLR fonts work seamlessly in desktop software like Adobe Illustrator and Pages, making them versatile for both web and print design.
The core technology is OpenType’s Character Composition feature. When you type a sequence like 5m-, the font recognizes the pattern through substitution rules, looks up the corresponding tile group, rotates the tile marked with the minus sign, and renders the complete meld as a single visual unit. This required mapping every possible tile combination and writing rules to distinguish between similar patterns.
sub five M asterisk hyphen by fiveOfCharacters-mahjong.aka.hor;
sub five M asterisk equal by fiveOfCharacters-mahjong.aka.h2;
sub five M hyphen asterisk by fiveOfCharacters-mahjong.aka.hor;
sub five M equal asterisk by fiveOfCharacters-mahjong.aka.h2;
sub five P asterisk hyphen by fiveOfCharacters-mahjong.aka.hor;
sub five P asterisk equal by fiveOfCharacters-mahjong.aka.h2;
sub five P hyphen asterisk by fiveOfCharacters-mahjong.aka.hor;
sub five P equal asterisk by fiveOfCharacters-mahjong.aka.h2;
sub five S asterisk hyphen by fiveOfCharacters-mahjong.aka.hor;
sub five S asterisk equal by fiveOfCharacters-mahjong.aka.h2;
sub five S hyphen asterisk by fiveOfCharacters-mahjong.aka.hor;
sub five S equal asterisk by fiveOfCharacters-mahjong.aka.h2;The font builds on existing open source work rather than starting from scratch. I used I.Mahjong(opens in new window) by SyaoranHinata for base tile designs, and Inconsolata(opens in new window) for monospace ASCII fallback. I processed these sources through font editing tools, extracted glyphs, applied color layers, and added OpenType feature code. The result respects its origins while adding new functionality.
(opens in new window)Making It Accessible
A font file alone isn’t approachable. I built an interactive web playground where users can try the notation system instantly, switch between monochrome and color themes, generate tile images, and copy examples for common situations.
I built the playground with React.js, Next.js, TypeScript, and Tailwind CSS, deployed on Cloudflare Pages. The architecture uses server-side rendering for fast initial load, then transitions to a responsive client-side application.
(opens in new window)Impact & Results
Since launching in February 2024, the font has been integrated into several japanese-mahjong-fontrelated projects and introduced by some influencers. The playground has processed over 15,000 notation inputs, with users primarily creating strategy content and teaching materials.
By releasing the project under the SIL Open Font License, I have made professional mahjong typography accessible to anyone. Japanese mahjong has a rich history, but digital tools for it have been limited or expensive. This font preserves the game’s notation system in a modern, accessible format that anyone can use, modify, or build upon.
(opens in new window)Lessons Learned
Font size optimization proved critical. Including every tile variation would create an unmanageably large file. I used OpenType substitution rules to generate variations dynamically, storing only base tiles and letting the font engine combine them. This reduced file size by 60% while maintaining full functionality.
The notation parsing taught me that seemingly simple text processing often hides complex edge cases. What looks like straightforward pattern matching requires careful consideration of lookahead, ambiguous inputs, and invalid sequences. Building robust parsers means anticipating how users will actually type, not just how they should type.
Most importantly, I learned that niche communities deserve well-crafted tools. Mahjong players have been working around poor typography solutions for years because nobody built something better. When you serve a specific community well, you create disproportionate value. This font solved a real problem for thousands of people who previously had no good options.