-
Notifications
You must be signed in to change notification settings - Fork 0
Vocabulary Gardening Workflows
This page turns the Garden philosophy into practical vocabulary work. It is written from implementation experience, but the examples are deliberately fictional: copy the workflow, not the names.
Use this page when a lexicon change is more than adding one obvious leaf. The goal is to keep API, UI, analytics, support, and operations language connected without forcing every team into the same taxonomy.
- Gather the words people already use in code, designs, analytics plans, support notes, runbooks, and product conversations.
- Mark the owner of each term before changing the shape. Ownership is usually more important than visual neatness.
- Search the existing graph for related language.
- Decide whether the change needs a new node, type, synonym, import, or root.
- Add the smallest vocabulary shape that lets the owner keep their language while linking to adjacent domains.
- Validate, inspect, and review the composed graph.
- Generate or publish the vocabulary where people will actually use it: code, editor completion, analytics routing, support tools, or operational workflows.
- Revisit the shape after real use. A gardened vocabulary is allowed to improve.
Less good:
product:
checkout_confirm_button_tap_analytics_event:
This packs UI structure, user intent, and analytics ownership into one name. It may be easy to emit once, but it is hard for UI, product, and data owners to review independently.
Better:
product:
ui:
checkout:
confirm:
button:
+ product.ui.type.button.primary
tap:
+ product.ux.type.action
analytics:
event:
checkout:
confirm:
+ product.analytics.type.action
+ product.ui.checkout.confirm.button.tap
Now the UI team owns the screen/control language, the analytics team owns the event language, and the relationship is reviewable.
Less good:
product:
ui:
card:
primary_cta:
main_action:
If these are the same concept, two separate leaves make downstream tools choose a spelling.
Better:
product:
ui:
card:
primary_cta:
+ product.ui.type.button.primary
main_action:
= primary_cta
The synonym preserves a local term without pretending there are two concepts.
Less good:
product:
ui:
banner:
blue:
large:
bold:
Raw implementation details make the vocabulary brittle. A platform or brand change can invalidate terms that were meant to describe intent.
Better:
product:
design:
type:
tone:
emphasis:
success:
danger:
scale:
compact:
comfortable:
ui:
banner:
status:
+ product.design.type.tone.success
layout:
+ product.design.type.scale.comfortable
This lets a semantic UI layer bind visual implementation to stable product meaning.
A semantic UI layer should name what a view is for, not only how it is rendered. Good UI vocabulary gives generated code and runtime events a stable contract that design systems, analytics, accessibility, and support can all understand.
Useful UI roots often include:
-
ui.typefor reusable controls, surfaces, labels, navigation, and feedback. -
design.typefor semantic tone, density, hierarchy, typography, and motion. -
ux.typefor actions, tasks, journeys, state transitions, and errors. - product-owned screen or component branches that reference those shared types.
Example:
product:
ui:
type:
control:
button:
+ product.ui.type.control
primary:
+ product.ui.type.button
message:
banner:
+ product.ui.type.message
settings:
save:
+ product.ui.type.button.primary
+ product.ux.type.action
failure:
+ product.ui.type.banner
+ product.design.type.tone.warning
+ product.ux.type.error
design:
type:
tone:
warning:
ux:
type:
action:
error:
The important part is not the exact root names. The important part is that the UI term can be understood as a control, a design-system role, and a user-facing action without duplicating the concept in three places.
Analytics vocabulary should describe observable product meaning. Avoid event names that only repeat implementation callbacks.
Useful analytics branches often separate:
- event family: action, state, impression, error
- source surface: screen, component, control, workflow
- context fields: stable dimensions that analysts can trust
- lifecycle: when the event is emitted and which owner reviews it
Example:
product:
analytics:
type:
event:
action:
+ product.analytics.type.event
state:
+ product.analytics.type.event
context:
field:
event:
settings:
save:
+ product.analytics.type.action
+ product.ui.settings.save
context:
screen:
+ product.analytics.type.context.field
control:
+ product.analytics.type.context.field
Review analytics terms with data owners and the product/domain owner. The UI owner should confirm the source surface, but the event contract should not be owned only by the component implementation.
Support vocabulary should preserve the language used by agents and customers. It can reference product, API, or operations terms without becoming any of those domains.
Example:
product:
support:
type:
case:
intent:
escalation:
case:
account_access:
+ product.support.type.case
intent:
recover_access:
+ product.support.type.intent
+ product.ui.sign_in.recover
escalate:
+ product.support.type.escalation
+ product.ops.runbook.identity.recovery
Support terms are often the best place to discover missing product language. If agents need a phrase that the product graph cannot express, treat that as design feedback.
Operations vocabulary should name states and procedures that people use during incidents, deployments, and reliability reviews. It should connect to product surfaces, but it should not be hidden under UI or API roots.
Example:
product:
ops:
type:
runbook:
incident:
service_state:
runbook:
identity:
recovery:
+ product.ops.type.runbook
incident:
sign_in_degraded:
+ product.ops.type.incident
+ product.ui.sign_in
service:
identity:
state:
+ product.ops.type.service_state
Ops terms are useful when runtime events, dashboards, or alerts need to route back to the same vocabulary used by support and product teams.
Use a new node under an existing root when the owner, lifecycle, and domain are already clear.
Use a type when many terms should share semantics or inherited children. Types are good for UI controls, analytics event families, support case kinds, operational states, primitive data shapes, and broad runtime subscriptions.
Use a synonym when two names mean the same thing and both names should remain valid. Synonyms are for local dialects, not for avoiding a needed product decision.
Use an import when a different file should own a subtree or when a shared vocabulary should be reused by several roots. Imports are a boundary of authorship, not just a way to shorten a file.
Use a new root when the vocabulary has a distinct public contract, owner group, release cadence, or audience. A support root, partner root, or operations root can still reference product terms without living under product ownership.
Use notes for domain-facing explanation. Use comments for maintainers and tooling context.
For every non-trivial vocabulary change, ask:
- Who owns each new term?
- Which existing terms were searched before adding this one?
- Is this a new concept, a subtype, a synonym, or a reference to an existing term?
- Does the proposed spelling match the owner's language?
- Does any generated code or runtime event depend on this ID remaining stable?
- Does the change preserve local dialects while connecting adjacent domains?
- Are notes written for domain readers and comments written for maintainers?
- Does composition still validate without conflicts?
For UI/design-system changes, also ask:
- Is the term semantic, or does it encode one platform's rendering detail?
- Can accessibility, analytics, and support understand the term without reading implementation code?
- Should this be a shared
ui.typeordesign.typeinstead of a product-specific leaf?
For analytics changes, also ask:
- What product meaning does the event represent?
- Which UI, UX, or operations term is the event connected to?
- Which context fields are stable enough to become vocabulary?
- Who owns breaking changes to the event ID?
For support and operations changes, also ask:
- Is this the language people use during real customer or incident work?
- Which product/API/UI term does this support or operational term help explain?
- Is the term stable enough for routing, dashboards, or runbooks?
Use this as a lightweight issue or PR template when proposing a vocabulary change.
## Problem
What workflow, product surface, event, support case, or operational procedure needs vocabulary?
## Owner
Who owns the language and who should review it?
## Existing Terms Checked
List the searches or related branches inspected before adding new terms.
## Proposed Shape
```taskpaper
product:
...
```
## Why This Shape
Explain why this is a new node, type, synonym, import, or root.
## Connected Domains
List the API, UI, analytics, support, operations, or design-system terms this should reference.
## Generated or Runtime Use
Where will this be used: generated code, editor completion, analytics routing, support tooling, alerts, documentation, or tests?
## Migration Notes
Does any existing ID need to remain stable, become a synonym, or be deprecated gradually?When a real project uncovers a repeatable pattern, add it here. When an example becomes misleading, prune it. The wiki should grow from working vocabulary practice rather than abstract doctrine.