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

Six 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, expertise, mental models, owned entities + tasks.
  • Tasks — the workflows. Directed graphs of steps with triggers, mutations, entity touches.
  • Mental models — the expectations users bring from other products, linked to personas.
  • 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 / monthly / occasional).
  • Expertise — what they can handle (novice / intermediate / expert).
  • Mental models — the expectations they bring, linked from the mental model list. Each model records the expectation, its source, its strength, and what it implies for the design.
  • 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 view showing the Intent section, entity rows, the relationship graph card, and a task flow overlay open with a branching decision.]

One scrolling view, top to bottom: Intent (problem, outcome, jobs to be done), Entities, Personas, Relationships, Tasks, Rules.

  • Entities, personas, and tasks render as rows. Click one and its detail panel opens on the right — attributes, states, and cues for an entity; goals and mental models for a persona; the step flow for a task.
  • Relationships render as a graph card — the product's domain model at a glance. Open it full-screen to explore the labeled connections between entities.
  • Tasks open into a flow graph overlay from their detail panel, decision branches included.
  • Rules hold the priority rules, each editable in place.

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

The file written

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

The skill

/ontology populates the layer.

  • Reads: everything in design/sources/, design/vision.json, and 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, Base Servings; has-many Ingredient. Cues fired: has-image, has-identity.
  • Ingredient — identity Name; descriptors Quantity (number), Unit (enum). Numeric-alignment cue fired on Quantity.
  • Scaling Ratio — small attached record. No strong cues.

Personas

  • Home Cook — cooks for varying family sizes; phone-first; intermediate expertise.

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.