---
id: promotion-demotion
class: b2
sourced: 2026-07-12
source: "b2b-ux-patterns ch.6"
license: open
---
# Pass: promotion & demotion

**Inputs:** per object × role — `frequency` (high | medium | low: how often this role touches it), `criticality`, `isParent`, `demotionContractMet`, `perRoleVariance`.
**Owns:** `requiredMechanics`, `clarifications`.
**Output artifact:** a per-persona sidebar — which objects earn top-level prominence and which are reachable only through other objects — plus a landing type per promoted item (chosen in the `page-archetype` pass). This pass covers exactly one IA decision: promotion/demotion; navigation mechanics are out of scope.

## The rule

**Prominence = frequency × criticality, computed per role. Parenthood is not the driver.** Parent/child position in the schema is a data-integrity fact; it says nothing about how often a human opens the object. The canonical counterexample: in a CRM, Account is the parent of Leads, Contacts, and Opportunities — and it is demoted; reps live in Leads, Opportunities, and Tasks. If you find yourself promoting an object because "it's the parent," ask instead who opens it, how often, and what breaks if they can't — that answer sets the sidebar. Without a frequency reading per role, prominence cannot be computed: clarify.

**Prominence is per persona × plan.** An object demoted for a rep is promoted for the ops admin who lives in it; the same schema yields different sidebars per role. Plan-gated items change what each tenant's sidebar contains (whether locked items render hidden or as upsell is `viewer-context`'s call). Agents and agent surfaces now compete for promoted slots like any object.

**The demotion contract** — demotion is only safe when two guarantees hold, or it punishes users:
1. **Creatable in context** — every demoted object is creatable from inside the flows of promoted objects that reference it (nested create-in-context: "+ New Account" inside the Lead form). If a rep must abandon a half-filled form to create the parent first, the demotion has failed.
2. **Reachable in context** — every demoted object is readable from the promoted objects it relates to, via related lists and parent links on their detail pages. The demoted object gives up its sidebar entry, not its existence.

Test every demotion: *can a user create it and reach it without ever visiting a dedicated page for it?* If yes, demote freely; if no, promote it or fix the contract first.

**Anti-patterns encoded below:** the schema-mirror sidebar (promoting every top-level object because it exists — the sidebar is a frequency map, not an ER diagram); parent-first promotion; one static sidebar for all roles; demotion without the contract.

```json decision-table
{"pass": "promotion-demotion", "rows": [
  {"when": {"frequency": "high"}, "then": {"requiredMechanics": {"mustInclude": ["sidebar-promotion"]}}, "reason": "frequency-times-criticality-wins-sidebar"},
  {"when": {"frequency": "low"}, "then": {"requiredMechanics": {"mustInclude": ["demote-reachable-in-context", "nested-create-in-context", "related-list-reachability"], "mustNotInclude": ["sidebar-promotion"]}}, "reason": "low-frequency-demotes-with-contract"},
  {"when": {"frequency": "low", "isParent": true}, "then": {"requiredMechanics": {"mustNotInclude": ["parent-first-promotion"]}}, "reason": "parenthood-is-not-navigational"},
  {"when": {"demotionContractMet": false, "frequency": "low"}, "then": {"requiredMechanics": {"mustInclude": ["nested-create-in-context", "related-list-reachability"]}}, "reason": "demotion-contract-before-demotion"},
  {"when": {"perRoleVariance": true}, "then": {"requiredMechanics": {"mustInclude": ["per-persona-sidebar"], "mustNotInclude": ["single-shared-sidebar"]}}, "reason": "prominence-per-persona-times-plan"},
  {"when": {"frequency": "__absent__"}, "then": {"clarifications": ["role-frequency-unspecified"]}, "reason": "prominence-needs-a-frequency-reading"}
]}
```