The governance schema

The governance schema is the rule set that maps design signals to UI decisions. Signals are things Denote can see (entity traits, task shapes, persona roles). Decisions are the structural choices that follow (which template + variant a screen uses, which visual treatments apply, which rule wins when they conflict). The schema is the bridge between your design thinking and the code Claude Code generates.

The problem it solves

Without governance, AI-generated UI is a fresh guess every time. Ask a coding agent to build an invoices page and it makes reasonable but arbitrary decisions. Table or card grid. Status badges or colored text. Sidebar filters or inline search. Each page improvised. Inconsistent, ungrounded, disconnected from your design thinking.

The governance schema encodes your judgment as rules. "An entity with a status lifecycle gets status badges and filter tabs." "A browse-and-pick task uses card_grid : with_filters." "When signals conflict, image-heavy wins over high-cardinality on this entity." These rules travel with the project and constrain every AI-generated component.

Governance isn't a suggestion. It's the constraint under which Claude Code builds.

Three kinds of rules

Visual cues (Ontology)

A rule of the shape trait → treatment. Reads one thing about an entity or attribute and applies one visual response.

Cues live inline on each entity in Ontology. They fire when their trigger matches. Multiple cues can fire on the same entity. When they conflict, priority rules resolve.

Template matching (Architecture)

A rule of the shape context → template + variant. Context is any relevant combination of entity, persona, and task. Template is one of 20 UX patterns; variant is the spatial expression.

Each Screen in Architecture carries its template + variant directly — there's no separate "pattern assignment" object. The /architecture skill picks the pair from task shape + entity traits and writes it onto the screen.

Priority rules (Ontology)

Your explicit declaration of which rule wins when two rules clash. Three scopes:

• Global — applies to all conflicts in the project. Default: mental models > visual cues > template-matching defaults.
• Entity-scoped — overrides the global for one entity. "For the Product entity, image-heavy beats high-cardinality."
• Conflict-scoped — resolves one specific clash. "When high-cardinality meets image-heavy, if the image is the identity attribute, card grid wins. Otherwise, table wins."

Priority rules are optional. Most conflicts resolve correctly from defaults. Priority rules are for the cases where defaults would be wrong.

Mental models

Cultural expectations about how a kind of product should work. "Users expect a kanban board for task management because the tools they have used before all use kanban."

Mental models live per-persona in Ontology. They're not derived from entity traits or task shapes — they come from you. They capture cultural context that structural analysis can't see.

When a mental model contradicts a template-matching rule, the mental model wins by default. Priority rules can override this if you're deliberately breaking convention.

Two tiers

• System-level rules ship with Denote — the 20 templates, the 48-variant catalog, the standard visual-cue triggers. Shared across every project.
• Project-level rules are yours — the entities, personas, tasks, and priority rules you write. Stored in design/ontology.json and design/architecture.json. Claude Code loads them automatically.

Most projects only edit project-level rules. The system-level vocabulary stays as shipped.

The recipe example

The recipe portion calculator sample:

• Visual cues fire on Recipe: has_image (photo attribute) and has_identity (name attribute). Both strong. Treatments combine cleanly: card grid with image thumbnail and recipe name as primary label.
• Template + variant on each screen:
  • recipes-list → card_grid : with_filters. Rationale: image-heavy entity, browsing is scan-and-pick.
  • recipe-detail → detail_page : with_aside. Rationale: single-entity task; scaling is the primary action with an aside for saved ratios.
• No priority rules needed. Cues don't conflict with templates.
• One mental model on Home Cook: "Home cooks expect recipe apps to lead with the photo." Reinforces the card-grid choice.

Claude Code reads design/ontology.json and design/architecture.json and builds accordingly. The list screen is a card grid with photos. The detail screen leads with the photo. These aren't Claude Code's choices — they're yours, written as rules, applied at build time.

[Screenshot TODO: Ontology + Architecture split — Ontology panel showing entity cards with cue chips inline; Architecture panel showing the sitemap with template + variant badges on each screen.]

What the schema does not cover

• Content — copy, labels, sample data. Implementer territory (informed by the entity model).
• Aesthetic direction — color, typography, density, references. Denote captures none of it; the implementer adapts the spec to the target project's existing design system.
• Business logic — validation, auth flows, API contracts. Implementer territory.
• Framework choices — React vs Svelte, Next vs Remix, state libraries. Implementer territory.

The governance schema is structural and visual. It says what kind of UI this should be — not what it should say, how it should be styled, or how it should be built.

Where to next

• Ontology — where visual cues, priority rules, and mental models live.
• Architecture — where template + variant lives.
• The four layers overview — where Ontology and Architecture sit in the pipeline.
• Spec — how the governance schema travels into the design specification.