Skip to content
Docs

Ontology

Ontology is the layer where you commit the semantic structure of the product. It takes Vision as input and pulls out the objects, the users, the workflows, and the rules that govern how the product behaves. Every downstream layer reads Ontology.

What Ontology captures

Five things, all in one file (design/ontology.json):

  • Intent — problem, outcome, jobs-to-be-done.
  • Entities — the objects. Attributes, states, relationships, cardinality, inline visual cues.
  • Personas — the users. Goals, frequency, tech comfort, mental models, owned entities + tasks.
  • Tasks — the workflows. Directed graphs of steps with triggers, mutations, entity touches.
  • Priority rules — conflict resolution when downstream rules clash.

Entities

The nouns. Each entity has:

  • Name + short description.
  • Attributes — data type (string, number, currency, date, reference, enum) + semantic role (identity, descriptor, status, metric, timestamp, reference).
  • States for entities with a lifecycle (draft → submitted → approved), each transition named.
  • Relationships (has-many / has-one / belongs-to / many-to-many) with a domain-meaningful label.
  • Cardinality (one / few / many / unbounded).
  • Visual cues inline — trigger (e.g. "has a status lifecycle") → treatment (e.g. "status badges with semantic colors") → scope (list / detail / form / all) → strength (strong / soft).

Personas

The users. Each persona has:

  • Goals — what they're trying to accomplish.
  • Frequency — how often they touch this product (daily / weekly / occasional).
  • Tech comfort — what they can handle (high / moderate / low).
  • Mental model — how they think about the domain; the conventions they bring.
  • Owned entities — the objects they primarily care about.
  • Owned tasks — the workflows they perform.

Tasks

The verbs. Each task is a directed graph:

  • Trigger — what starts the task.
  • Steps as nodes (create / read / update / delete / transition / decide).
  • Edges as transitions, branching at decision points.
  • Mutations — what the task creates, updates, or deletes.
  • Entity touches per step.

Priority rules

When two downstream rules clash, priority rules call the winner. Each rule has a scope (global / entity / conflict), a statement, and a resolution.

The canvas

[Screenshot TODO: Ontology panel showing entity cards (with inline cue chips), persona cards, the entity-relationship diagram with labeled arrows between entities, and a task flow graph with a branching decision diamond.]

  • Entities render as cards — attribute list, state diagram (if any), cue chips inline.
  • Personas render as cards.
  • Relationships show as labeled arrows between entity cards on the canvas — the product's domain model at a glance.
  • Tasks render as flow graphs on a canvas.
  • Priority rules sit below in their own section.

Edit any field inline. Renames propagate silently to references in the other files.

The file written

design/ontology.json — one file, five top-level keys: intent, entities, personas, tasks, priorityRules.

The skill

/ontology populates the layer.

  • Reads: design/vision.json + design/ontology.json if it exists (merges, preserves IDs) + any context you pass.
  • Writes: design/ontology.json.

Behavior:

  • Pulls entities, personas, tasks progressively as the conversation runs.
  • Fires visual cues automatically from entity attributes and names them inline.
  • Applies the four-question entity filter: identity? multiple attributes? created / read / updated / deleted? appears in multiple contexts? Failing candidates are probably attributes or views, not entities.
  • Flags ambiguity with null rather than fabricating fields.

The recipe example

A vision for a recipe-scaling tool, run through /ontology, produces:

Intent

  • Problem: home cooks scale recipes to off-original serving counts; existing apps bury scaling.
  • Outcome: scale any recipe in under 30 seconds on a phone.

Entities

  • Recipe — identity name; descriptors photo (file), baseServings (number); has-many Ingredient. Cues fired: has_image, has_identity.
  • Ingredient — identity name; descriptors quantity (number), unit (enum). Cue fired: currency_like_treatment on quantity.
  • ScalingRatio — small attached record. No strong cues.

Personas

  • Home Cook — cooks for varying family sizes; phone-first; moderate tech comfort.

Tasks

  • Scale a recipe — pick recipe → enter target servings → derive scaled ingredient list → optionally save ratio.
  • Browse saved scalings — return to a previously-scaled recipe.

Priority rules — none needed for this project.

What Ontology is not for

  • Pattern decisions. template + variant lives on each Screen in Architecture, not here.
  • Page inventory. That's Architecture.
  • Composition. That's Screens.
  • Aesthetic. Denote captures none of it — the implementer adapts to the target project's design system.

Where to next

  • Architecture — takes Ontology as input and derives the screen inventory, navigation, and per-screen template + variant.
  • Vision — the input Ontology reads from.
  • The four layers overview — where Ontology sits in the pipeline.