The problem the two layers solve
A tea page needs to do two incompatible things. It needs to describe a tea well, which means prose — dried longan, wet stone, cassia bark, sassafras — because that is the writing a reader actually wants and the only kind that conveys anything specific. And it needs to be filterable, which means a fixed set of values a machine can match, because nothing can decide that wet stone and damp slate are the same thing without a human ruling on it. Prose cannot filter and a filter cannot describe. The note in this repository’s vocabulary file records the scale of the problem directly: at the time it was written, 137 teas carried free-text aroma notes and used 186 distinct descriptors between them, which is a rich body of writing and a useless index. The same tension appears wherever a catalogue tries to be both readable and searchable, and tea is an unusually hard case because its descriptive vocabulary is borrowed from other foods and varies by culture. A structured layer built on that prose would inherit every ambiguity in it. Building the two separately, and saying so on the pages that use them, is the arrangement that keeps each honest about what it can do.
What the controlled layer contains
Three short enumerations, kept separate because they answer different questions. Flavour families — floral, fruity, citrus, sweet, vegetal, grassy, roasted, nutty, smoky, woody, earthy, mineral, creamy, chocolate, spice, umami — answer what a tea tastes of. Mouthfeel and structure terms — light, medium, full-bodied, silky, smooth, drying, astringent, rich — answer how it feels, which is a different axis, because a tea can be a four for body and still be silky rather than rich. Two terms were removed from that list once the distinction was taken seriously: bitter is a taste rather than a texture and has its own numeric axis, and complex is a verdict on a tea rather than a sensation in the mouth, recorded separately as how much it rewards attention. Both had been sitting in the mouthfeel list doing another field's job. And a shorter list of aroma descriptors covers the signatures that recur often enough across the catalogue to be worth filtering on. Separately again, numeric axes carry intensity for astringency, bitterness, sweetness, umami, body, aroma intensity and aftertaste length. Two further fields sit alongside them and answer questions that none of the three enumerations can. One records how much a tea changes and layers across a session, as a judgement about whether it rewards attention rather than as a quality ranking — a breakfast blend is straightforward because it was built to be. The other records how easy a tea is to appreciate, which is a different question from how easy it is to brew, and the two disagree often enough to be worth separating.
Why coarse is a decision rather than a limitation
A user choosing roasted wants every roasted tea, not a choice between eleven kinds of roast. A vocabulary with two hundred terms filters nothing, because no two people place the same tea in the same leaf node, so the index fragments into buckets of one. The rule this repository applies is that a value may exist only when at least three real records need it, and a test asserts it rather than trusting the comment — which means a descriptor that stops earning its place is removed rather than kept for completeness. The discipline has caught real cases in both directions. Herbal was on the original list, was used by no tea in the catalogue, and failed the usage test; it returned only when the botanical catalogue arrived and dozens of records needed it. Perfumed, delicate, cool, powdery and faint were proposed and rejected as shades of terms already present. The discipline has a cost worth acknowledging: a genuinely distinctive tea whose character no existing facet captures will be filed under something approximate until two more like it arrive. That is the trade the rule makes, and it is the right way round — a facet added for one record indexes nothing and dilutes the ones that work. The prose layer carries what the facets cannot in the meantime, which is precisely why both exist.
Assigned by judgement, never derived from the prose
The controlled facets are assigned editorially. A tea tasting of dried longan is recorded as fruity and sweet because somebody decided the note reads that way, not because a string matched. This matters more than it sounds: a vocabulary derived automatically from prose inherits every ambiguity of the prose and adds the errors of the matcher, and it produces an index that looks principled and is not. Assigning by judgement means the facets are a deliberate editorial claim that can be argued with, which is the right property for a classification to have. It also means the two layers can disagree, and where they do the prose is generally the more accurate and the facet the more useful. There is a further reason to prefer judgement here that has nothing to do with accuracy. An editorially assigned facet has an author and can be revisited when it turns out to be wrong; a derived one is the output of a process nobody remembers configuring, and its errors are invisible because they look systematic. A classification that can be argued with is a classification that can be corrected, which over the life of a catalogue matters more than being right first time.
What the coarse layer cannot do
Several things, and they are worth naming rather than hiding. It cannot express change across infusions, which is most of what makes a good oolong good — a tea that opens floral and finishes mineral has to be assigned both or neither. It cannot capture the concepts other tea cultures have and English does not, such as the returning sweetness of huigan or the rock character of yan yun, which is why those live in prose and on their own pages. It cannot express intensity, which is why the numeric axes exist alongside. And it encodes the vocabulary of whoever built it, which is a cultural artefact rather than a description of the territory. A flavour wheel is a way in, not a map. It also cannot express uncertainty. A facet is present or absent, whereas a tea’s character may be marginal, contested between tasters, or dependent on how it was brewed — and the numeric axes carry intensity but not confidence. Where the underlying claim is genuinely uncertain the catalogue records it in prose with a hedge rather than forcing a facet, which is a small example of the general principle that a structured field should not be made to carry a judgement it cannot express.
Why keeping both is the honest arrangement
The temptation with any controlled vocabulary is to let it replace the prose, because the structured data is what powers the tools and the prose is what costs effort to write. Doing so would make every tea page worse in exchange for making the filters tidier. The opposite temptation is to skip the vocabulary and keep only the writing, which produces a catalogue nobody can navigate. TeaHQ carries both and says so on the pages that use them, because a reader who understands that the facets are coarse on purpose will use them correctly — as a way of narrowing a large catalogue to a shortlist, after which the prose and, ultimately, the cup decide. The same principle governs how the facets should be read by anyone using them. They are a shortlist mechanism, not a description, so a filter for floral and sweet returns a set of teas worth investigating rather than a set of teas that taste alike. Treating the output of a coarse filter as a verdict is the mirror image of the mistake this page is written against, and it is the one a well-built filter most invites.