Citing the canon is the load-bearing UX choice

FengShui Blueprint is a Toronto building assessment tool. You input an address, floor, facing direction, and unit size; in about two seconds it returns a CAD-styled report with a composite score, five dimensional scores, a “master’s annotation” in Chinese, and a static map of the eight nearest surrounding features (lakes, subway, hospitals, highways, cemeteries, tall buildings, and so on). The category it lives in — feng-shui apps — has a near-universal trust problem: nobody believes the number on the screen.

When I scoped the project, I assumed the trust problem was a visual problem. The category is full of gilt scrolls, magenta ink, and dragon motifs that read like a fortune-teller’s pamphlet. So the obvious move was to dress the output as engineering drafting — bone paper, monospace numerics, drafting frames with DRAWING NO. / SHEET / CONFIDENCE. That move helped. But it didn’t solve the trust problem; it just sidestepped one bad visual cliché.

The thing that actually moved trust was much smaller and almost unrelated to design: every advisory line in the report points to a classical source.

【补靠山】玄武空虚 — 后方 200m 内无高楼或山丘 出处：《阳宅十书》“宅以山为靠”

That single citation line — 《阳宅十书》"宅以山为靠" — is doing more work than the engineering-blueprint visual identity. This post is about why.

What “feng-shui as a product” usually looks like

If you scroll any of the existing online feng-shui sites, the experience is some variation of:

1. Pick your birth year + a direction
2. The site emits a generic paragraph about which of the five elements you “are”
3. There is no map, no traceability, no anchor to a specific place
4. The interpretation feels indistinguishable from astrology

The category’s user expectation is vibes plus authority cosplay. The site looks expensive; the text is florid; there’s no path back to a source. If you don’t already believe, there’s no surface to grab.

This is a familiar failure mode in any product that wraps a soft body of knowledge. It also shows up in:

• Astrology apps that emit confident readings with no schema behind them
• “AI” personality-test sites that report “your archetype” with no construct validity
• Nutrition apps that hand-wave to “research shows…” without naming a paper

The pattern is: take a body of knowledge that has real internal structure, throw it through a stylistic blender, and emit confident output without anchors. It feels authoritative on first read and immediately cheap on second read.

The bet: be the opposite

I picked the opposite bet for FengShui Blueprint:

• The rules engine is a dependency-free TypeScript package (packages/rules-toronto). It takes a normalized site reading and emits dimensional scores + detected defects. Pure functions, 55 tests, identical inputs always produce identical outputs.
• Every module of the engine maps to a classical text. Twenty-four mountains → 《青囊奥语》(Yang Yunsong) + 《天玉经》. Five-elements generation/destruction → 《尚书·洪范》 + 《黄帝内经》. Floor → five-elements → 《河图》. Sha taxonomy → 《阳宅十书》 + 《阳宅撮要》 + 《鲁班经》. Four-emblem terrain → 《葬书》(Guo Pu) + 《雪心赋》.
• The narrator can only describe what the engine computed. It cannot invent a finding; it can only render the existing score into Chinese prose, and when it does so it carries the citation through.

The output of that pipeline reads like this (paraphrased):

本宅坐西北向东南（坐山315°「乾」，向首135°「巽」）。坐属金，向属木，金克木 — 主气场流通不畅。 出处：《八宅明镜》“乾巽相对，金木相战” … 【镇阴气】2km 内 ≥2 处医院/墓地，阴气积聚 化解：每日开窗纳阳、玄关红色摆件、盐灯 出处：《阳宅十书·避煞篇》

A user reading that doesn’t have to believe in feng-shui to understand what’s happening: a rule fired, it pointed to a passage, the passage is a real book that exists. The whole interaction shifts from “trust the algorithm” to “trust the draftsman who read the references correctly.”

The footnote is doing the trust work that visual design alone could not.

Why this is more than dressing

You could argue: this is just the same generic feng-shui app with citations bolted on. That argument is wrong, and the reason is structural.

The classical citations only stay honest if the rule that fired was the one the citation describes. If the engine emits “玄武空虚” but the citation says “白虎抬头,” the whole framing collapses on first inspection. So the citations force a discipline on the engine: each rule has to correspond cleanly to a passage, or it cannot ship.

In practice this changed how I wrote the engine. A few examples:

• I had a “general bad vibes” defect early on that aggregated several signals. There was no single classical passage that matched it, so it broke the citation invariant. I had to either split it into per-source rules or drop it. I split it.
• The four-emblem analysis originally collapsed dragon and tiger into “left-right balance” because the math was easier. But 《葬书》 names them separately and gives different prescriptions; collapsing them broke the citation. I separated them.
• A floor multiplier I wanted to add (“higher is always better, capped at 30”) had no canonical basis. I removed it. The honest 《河图》 floor-to-element mapping replaced it.

The citation requirement became a schema check on the rules, the way a type system is a schema check on code. The product has a smaller, more defensible engine because of it.

How this generalizes

I think there’s a broader pattern under this:

When you wrap a soft body of knowledge in a product, the user trusts you in proportion to how cheaply they can audit you. Citations are an audit primitive. Footnotes are an audit primitive. “Here’s the row in the dataset” is an audit primitive. Confident prose with no audit primitive is the opposite of trust.

This generalizes to:

• A research summary tool should link the exact paragraph in the source paper, not just the paper.
• An LLM chat-with-your-docs product should pin the specific span of the source document, not just the doc title.
• A nutrition app should name the study, the cohort size, and the year — not say “research shows.”
• A legal-information tool should cite the statute section, not “the law says.”

The shape of all of those is the same shape: make the user’s audit cost approach zero, and trust climbs even when the underlying knowledge is contested. Trust is not a function of confidence; it’s a function of how cheaply a skeptic can disprove you.

What it cost

This wasn’t free. Three concrete costs:

1. The engine is smaller than I wanted it to be. I had to drop rules I couldn’t trace to a canonical source. Some of those rules would have made the report “more accurate” by some vibes-based standard. They didn’t ship.
2. The narrator is constrained. It can’t say “I sense that…” or “this feels…” because the engine doesn’t compute feelings. The prose is colder than the category’s house style. That cost real warmth.
3. The classical sourcing has to be done by hand, at least at this stage. I read the relevant passages and decided which of the engine’s rules they corresponded to. An LLM could probably do this, but the calibration would still need a human pass to avoid hallucinated citations — which would be the exact opposite of the product’s promise.

I’d take that trade again. The product’s most distinctive feature ended up being a UX choice, not a model choice.

What I’d watch for next time

If I were building another product in a soft-knowledge category, the question I’d ask up front is:

What is the unit of audit, and how cheaply can I show it to the user?

For feng-shui, the unit of audit is a passage in a classical text. For a research tool, it’s a sentence in a paper. For a marketplace, it’s the on-chain transaction. For an AI-triage system, it’s the score that decided the routing.

The mistake I keep seeing — and made once myself — is to design the output before identifying the unit of audit. Output is easy. Audit is the hard part. Build the audit primitive first; the output writes itself around it.

— S.