# Design Language for mujun.dev ## Aesthetics and Tone mujun.dev is built around a single, load-bearing pun: **矛盾 (mujun)** is the classical Chinese parable of the **unstoppable spear and the immovable shield** — the merchant who claimed both, and could answer no questions. The word now simply means *contradiction*. So this is a developer's site whose name confesses, up front, that the thing it documents does not fully cohere — and the design leans into that confession instead of hiding it. The aesthetic is **wabi-sabi**, specifically the **kintsugi-repaired ceramic** strain of it: the page presents itself as a single hand-thrown stoneware tile that has been **broken cleanly in two** — spear-half and shield-half — and rejoined down the middle with a wandering vein of gold lacquer. Every section of the site lives on one side of that crack or the other, and the crack itself is the spine of the layout. Nothing is glossy. Nothing is symmetrical. The "grid" is the kind a potter scratches into wet clay with a bamboo skewer — present, but wobbling. Edges are deckled. Corners are never 90°. The mood is **quiet, slightly melancholy, faintly amused at itself** — a craftsman who has accepted that the join is the most beautiful part precisely because it is where the failure was. Crucially this is *not* a zen-garden cliché site (raked sand, single rock, "less is more" in a serif). It is **rougher than that** — closer to a Bizen-ware kiln scar, an Oribe glaze pooling unevenly in a foot ring, the iron-speckled body of unrefined Shigaraki clay. Warm, earthy, imperfect, and unmistakably a *programmer's* notebook underneath the ceramic skin — there are still monospace logs and stack traces, they are just glazed over. Tone words: **grounded-earthy, zen-contemplative, quietly self-deprecating, mysterious-moody at the edges.** No exclamation marks anywhere. No "Get started in 60 seconds." The site assumes the reader has time and a cup of tea. ## Layout Motifs and Structure **The crack is the layout.** A single irregular gold seam runs roughly top-to-bottom through the entire document — not straight, not centered, but meandering between about 38% and 58% of viewport width as you scroll, the way a real fracture line wanders. This seam is an SVG path that is *the same path* the whole way down (the page is one continuous tile), and it is drawn with `stroke-dasharray` so it appears to be *traced in gold* as you scroll past each segment. - **Left of the crack — the SPEAR side (矛).** Content here is the active, forward, "what this tool *does*" material: the pitch, the API surface, the live example, the changelog. Visually it is the **thrown, still-spinning** half — text is set ranged-left, blocks lean very slightly clockwise (0.4–0.8°), elements enter from the left as if pushed. - **Right of the crack — the SHIELD side (盾).** Content here is the defensive, careful, "what this tool *refuses* to do" material: the limitations, the known bugs as a deliberate feature list, the threat model, the "why we said no" log. Visually it is the **fired, settled, cooled** half — text ranged-right, blocks dead still, a faint inner shadow as if recessed into the clay. - A reader scrolling down is **alternately addressed by the spear and the shield**, section by section, and the gold seam between them is where the two voices contradict each other — sometimes literally, with a one-line annotation sitting *on* the crack ("the spear says O(1); the shield says only for keys under 32 bytes"). **Spatial system.** No card grid. No bento box. Instead: **irregular fragments** — content sits inside polygonal "shards" of glaze with `clip-path` deckled edges (4–7 sided, each one unique, each one slightly rotated), arranged not on a grid but along a **gentle vertical drift** so the left column and right column never align horizontally — there is always a stagger of 60–140px between facing shards, the way two halves of a broken plate never quite line back up. **Generous ma (negative space)**: at least 40% of every screen is the bare clay body, unglazed, just texture. The page is long — `~600–700vh`, eight or nine "fragments" — and meant to be *walked through*, not skimmed. There is essentially no chrome: a tiny seam-following progress mark (a single gold dot riding the crack) is the only persistent UI. No sticky nav bar. No footer CTA. The last fragment is just the merchant's silence — a wide field of empty clay with the parable's final line set very small near the bottom. ## Typography and Palette **Three Google Fonts, used with kiln discipline.** - **Zilla Slab** (weights 300, 400, 600; also its italic) — the primary voice, all body copy and most headings. A slab serif with **soft, slightly clay-like terminals** — it has the weight of letterpress into damp paper without the stiffness of a true Egyptian slab. Body at 19px / 1.72 line-height, ranged-left on the spear side, ranged-right on the shield side. Headings in 600 weight, never larger than ~52px, always lowercase, always with a hairline gold underline that is *itself a tiny fragment of the crack path*. - **Shippori Mincho** (weights 400, 600) — the contemplative / CJK voice. Carries the actual kanji 矛 / 盾 / 矛盾 wherever they appear at display size (these are *huge* — 200–340px — set as pale ghost-glyphs behind the clay, like a maker's stamp pressed into the underside of the tile), plus all the parable-text interludes and Japanese glosses. A refined Mincho with delicate, brush-derived serifs that read as *old* without reading as *decorative*. - **JetBrains Mono** (weights 400, 500) — the buried programmer underneath. Every code block, every log line, every stack trace, every `npm i mujun` — set in this, but **rendered as if glazed**: dark iron-brown text on a slightly darker iron-brown shard, low contrast on purpose, with the *active line* lifting into legibility only on hover/scroll-focus, the way a wet finger brings out the pattern in unglazed clay. Letter-spacing -0.01em, 15px. **Palette — unrefined-clay earth tones, eight stops, all warm, none pure.** - `#EAE0D1` — **bisque** — the unglazed clay body, the page background. Not white; the color of fired-but-unglazed stoneware. - `#DDD0BC` — **kaolin shadow** — the recessed inner-shadow tone on shield-side shards. - `#3A3128` — **iron-body** — the deepest text color and the dark stoneware shards (Bizen-ware iron clay). Used instead of black, everywhere. - `#6B5A45` — **scorch** — mid-brown for secondary text, captions, the parable interludes. - `#9C7B4E` — **oribe-bronze** — warm dark gold, used for the *body* of the crack seam and for hairline rules. - `#C9962E` — **kintsugi-gold** — the bright lacquer highlight running *along the top edge* of the seam; the only saturated color on the page; also the single progress dot. - `#7C8B6A` — **oribe-green** — a muted, slightly grey sage (Oribe-glaze green pooling in a foot ring); the one cool accent, used sparingly for "shield" affirmations and successful-build states. - `#B5462E` — **shino-rust** — burnt iron-red flecks (the iron spots that bloom through a Shino glaze); used only for the "spear" side's emphasis and for the merchant's-defeat note. Contrast intentionally lives in the *texture and the crack*, not in slick color jumps. The whole thing should look like it was photographed in the warm raking light of late afternoon through a kiln-shed window. ## Imagery and Motifs **No photography. No stock 3D. No icon font.** Every visual element is either (a) an SVG path, (b) a CSS gradient/filter, or (c) a procedurally generated speckle layer — because *unrefined clay* is a texture you build, not an image you license, and 98% of the corpus leans on photography. **Motif family 1 — the crack and the join (the spine).** The single meandering gold seam described above, plus its tributaries: where a shard "wants" to break further, a hairline branch crack runs a few hundred pixels off the main seam and *fills with gold* as the reader's scroll reaches it. Every place two shards touch, there is a tiny **gold staple** (the metal-stitch style of *nakatsugi* repair) — a 14px hand-drawn double-stitch mark. **Motif family 2 — iron speckle / glaze pooling (the texture).** A fixed, very low-opacity layer of **iron spots**: 200–400 tiny dark-brown blotches of varying size and softness, scattered with blue-noise distribution across the bisque background, generated once in JS and frozen. Over the dark shards, the inverse: pale kaolin flecks. Where a glaze "pools," a soft radial darkening in the low corner of a shard (the foot-ring effect). This layer never moves with scroll — the clay body is *behind* everything, the reader scrolls *over* it. **Motif family 3 — the ghost stamps (the kanji).** Enormous, pale, nearly-invisible Shippori Mincho glyphs — 矛 on the spear side, 盾 on the shield side, and the full 矛盾 spanning the seam in the opening and closing fragments — pressed into the clay like a potter's chop mark: rendered at ~6–10% opacity in the iron-body color, positioned so they bleed off the edges, rotated 3–12°, and given a *very* subtle emboss (a 1px light highlight on the upper-left stroke edge) so they read as pressed *into* the surface, not printed on it. **Motif family 4 — the kiln log (the buried programmer).** Down the very margins, in 11px JetBrains Mono at scorch-brown on bisque (low contrast, ambient): a slow vertical ticker of fake firing-schedule lines that double as build logs — `0420 bisque hold 60m`, `0610 oribe reduction begin`, `npm run kiln --soak=8h`, `WARN: thermal-shock risk if cooled <4h`. Atmosphere, not content. ## Prompts for Implementation Build mujun.dev as **one HTML document, one CSS file, one small ES module — no framework, no router, no build step beyond a single esbuild/minify pass.** One continuous vertical scroll, ~600–700vh, eight or nine "fragments," no second page, no outbound links in the body. **The storytelling is the structure.** The nine fragments compose **a retelling of the 矛盾 parable braided with the actual README of an imagined tool** (a tiny library — call it whatever, the design doesn't need to know — that promises something it documents itself as unable to fully deliver). Fragment order: (1) the merchant arrives — full-bleed bisque, the 矛盾 ghost-stamp, the seam *un-drawn*, just a faint scratch; (2) "I sell a spear that pierces any shield" — spear-side pitch + API; (3) "I sell a shield no spear can pierce" — shield-side limitations, framed proudly; (4–7) alternating spear/shield fragments — example, then known-bug, then changelog, then threat-model — the seam now fully gold through the upper page, branch cracks active; (8) "what happens when the spear strikes the shield?" — a single fragment where a spear-side claim and a shield-side claim sit on *opposite sides of the same shard*, the seam running *between two halves of one sentence*, and a `shino-rust` annotation on the crack itself stating the contradiction plainly; (9) the merchant's silence — a near-empty field of clay, the parable's last line ("そこで彼は答えられなかった" / "and he had no answer") set tiny near the bottom, the 矛盾 stamp again, the seam now fully traced and *still*. **Animation = the gold being poured into the crack.** As the reader scrolls, the seam's `stroke-dasharray` offset retreats, so the gold *flows downward into the fracture* tracking scroll position — `path-draw-svg` driven by scroll, eased so it lags slightly behind and "catches up" (a spring settle) when scrolling stops. Branch cracks fill the same way, triggered when their parent fragment enters the viewport. Shards **enter on a fade + a tiny settle**: spear-side shards drift in from the left and rotate from ~1.2° to their resting ~0.6°; shield-side shards rise 30px and *sink* into a faint inner shadow — `fade-reveal` + a slow `scroll-triggered` `morph` of the clip-path corners (the deckled edge "settles" by 2–3px). The iron-speckle texture layer is generated once on load and never animates. The single gold progress dot rides the seam path with `offset-path: path(...)` keyed to scroll. Cursor: a faint warm glow under the pointer over dark shards only (the wet-finger-on-clay effect), nothing on the bisque. Respect `prefers-reduced-motion` — under it, the seam is simply drawn fully gold from the start and shards just fade. **Texture is non-negotiable.** Every shard gets: a deckled `clip-path` (unique per shard, 4–7 points, hand-tuned), a 1px inner border in `oribe-bronze` at low opacity, a faint corner glaze-pool radial gradient, and either (dark shard) a pale-fleck `box-shadow`-built speckle or (light shard) a recessed kaolin-shadow inner shadow. Background: layered — bisque base color, then a CSS `repeating-radial-gradient` at near-zero opacity for a faint clay tooth, then the JS iron-speckle `` fixed behind everything at ~8% opacity. Kanji ghost-stamps are real `` text in Shippori Mincho, `aria-hidden`, absolutely positioned, bleeding off edges, with a 1px upper-left text-shadow highlight for the pressed-in look. **AVOID:** any CTA-heavy layout; pricing tiers; stat-grids ("10k stars / 2M downloads / 99.9%"); a sticky nav bar; testimonial cards; a hero with a centered headline + two buttons; glassmorphism blur; neon; dark-mode-by-default; raked-sand / single-rock zen kitsch; any pure black or pure white; any straight-edged rectangular card. If a section feels like a typical SaaS landing block, it is wrong — re-cast it as either a spear claim or a shield refusal, on the correct side of the crack. ## Uniqueness Notes Differentiators this design commits to — none should be duplicated by any other CMassC site: 1. **The fracture-line *is* the layout grid.** A single meandering SVG seam splits the entire page into a "spear half" (left, active, leaning, ranged-left) and a "shield half" (right, settled, recessed, ranged-right), and content is *assigned to a side by its rhetorical stance* (what the tool does vs. what it refuses to do). No other site uses a literal crack as its spine, and the spear/shield rhetorical split is original to mujun.dev (矛 = spear, 盾 = shield — the literal characters of the domain name). 2. **Kintsugi-repaired *unrefined* ceramic, not zen-garden minimalism.** This deliberately rejects the raked-sand / single-rock / airy-serif reading of Japanese design. The reference points are Bizen iron-body stoneware, Shino iron-spot bloom, and Oribe-green glaze pooling in a foot ring — rough, speckled, brown, imperfect. wabi-sabi sits at ~8% in the corpus and ceramic-as-developer-site is, as far as the frequency analysis shows, unprecedented. 3. **The buried-programmer conceit.** Real code blocks, logs, and stack traces exist on the page but are *glazed over* — low-contrast iron-on-iron, legible only on scroll-focus/hover, the way a wet finger reveals pattern in raw clay — plus a "kiln firing schedule" margin ticker that doubles as a build log. Code is present but submerged, which is the opposite of the terminal/dev-tutorial aesthetics already in the corpus. 4. **No photography, no icons, no 3D files** — every visual is SVG path, CSS filter, or a once-generated procedural iron-speckle canvas — in a corpus where 98% of designs use photography. 5. **The contradiction is the climax, stated plainly.** Fragment 8 puts a spear claim and a shield claim on opposite halves of *one sentence split by the crack*, with the contradiction annotated in burnt rust *on the seam itself* — the design's whole argument resolved in one shard, then dissolved into the merchant's silent empty-clay closing fragment. Chosen seed/style: **wabi-sabi imperfect ceramic** (from `seeds.json`; aesthetic: wabi-sabi, layout: ma-negative-space + asymmetric/broken-grid, typography: slab-serif + serif-revival/mincho + mono, palette: warm-earthy + muted, patterns: path-draw-svg + fade-reveal + spring, imagery: noise-texture + generative-art + custom-illustration, motifs: crystalline→ceramic-shard + cultural, tone: grounded-earthy + zen-contemplative). Avoided overused patterns from the frequency analysis: **hand-drawn (96%)** — no childlike sketch lines, the only "hand" mark is a potter's tool scratch; **glassmorphism (77%)** — explicitly forbidden, replaced by opaque glazed clay; **photography (98%)** — none; **card-grid / full-bleed / centered (89/89/85%)** — replaced by drifting irregular shards split by the seam; **cursor-follow / spring / magnetic / stagger (89/85/80/73%)** — only a restrained scroll-driven seam-draw + a faint wet-clay glow on dark shards remain; **warm + gradient palette (98/96%)** — warm is kept (it is genuinely clay) but the "gradient" is only a near-invisible glaze-pool radial, never a candy mesh; **mono typography at 94%** — present, but demoted to the buried, low-contrast log layer rather than the headline voice.