Skip to content
Docs

The governance schema

The governance schema is the set of rules that maps design signals to UI decisions. Signals are things Denote can see (the traits of an entity, the shape of a task, the role of a persona). Decisions are the visual and structural choices that follow (which pattern to use, which visual treatments to apply, what wins when rules 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 is independently improvised. The result is inconsistent, ungrounded in your thinking, and disconnected from the rest of the design.

The governance schema encodes your judgment as rules. "An entity with a status lifecycle gets status badges and filter tabs." "A browse-and-select task uses the list-detail pattern." "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 is not a suggestion. It is the constraint under which Claude Code builds.

Three kinds of rules

The schema has three kinds of rules. You see and edit them in the Map layer.

Visual cues

A visual cue is a rule of the shape trait → treatment. It reads one thing about an entity or attribute and applies one visual response.

Examples:

Trait Treatment
Entity has a status lifecycle Status badges with semantic colors plus filter tabs by status
Entity has an image attribute Card grid with image thumbnail, not a table row
Attribute type is currency Right-align, format with currency symbol, tabular numerals
High cardinality (more than 50 items) Paginated table with search and sort
Attribute role is identity Primary label position, larger type weight

Cues fire when their trigger matches. They can fire on their own or alongside other cues on the same entity. When multiple cues fire, priority rules resolve the conflict.

Pattern matching

A pattern matching rule is of the shape context → pattern. Context is any relevant combination of entity, persona, and task. Pattern is a UX pattern from the design system's library (list-detail, table, card grid, wizard, dashboard, kanban, inbox queue, and so on).

Context is flexible. Not all three pieces are required. Sometimes the entity alone is enough to determine the pattern. Sometimes it takes the full combination.

Examples:

Context Pattern Why
Users (entity alone) table High cardinality with dense attributes always wants a table
Manager + Expense Report + review inbox_queue The review task makes this a triage queue, not just a list
Employee + Expense Report + creation wizard Guided creation for a multi-field entity
Onboarding (task alone) wizard The task shape drives the pattern regardless of entity

Each assignment carries a rationale (why this pattern for this context) and alternatives (what else was considered and why they ranked lower). The rationale is the most important field. It is the thing you come back to when you revisit the decision six weeks later.

Priority assignment

A priority assignment is your explicit declaration of which rule wins when two rules fight. You set priority at three levels.

  • Global priority applies to all conflicts in the project. A common default is "mental models beat visual cues, visual cues beat pattern matching defaults."
  • Per-entity priority overrides the global for one entity. "For the Product entity, image-heavy beats high-cardinality." Card grid wins.
  • Per-conflict priority resolves one specific clash. "When high-cardinality conflicts with 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

Alongside the three rule kinds, the schema captures mental models. A mental model is a cultural expectation 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 are not derived from entity traits or task shapes. They come from you. They capture the cultural context structural analysis cannot see.

When a mental model contradicts a pattern matching rule, the mental model wins by default. Priority assignment can override this if you are deliberately breaking convention.

Two tiers

The schema lives at two tiers.

System-level rules ship with Denote. They are the universal vocabulary. The twenty patterns in the library. The standard visual cues ("entity has images → card grid"). The UI region names (header, main, sidebar, toolbar, footer, modal). Shared across every project.

Project-level rules are yours. The entities, personas, and tasks you extracted. The specific pattern assignments for your contexts. The priority rules for your project. The mental models for your audience. Written to your project's design/governance.json so Claude Code loads them automatically.

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

The recipe example

Consider the recipe portion calculator sample.

Visual cues fire on the Recipe entity: has_image (recipes have a photo) and has_identity (recipe name is the primary label). Both cues are strong. The treatments combine cleanly: a card grid with image thumbnail and recipe name as the primary label.

Pattern matching on contexts:

  • Home Cook + Recipe + browse is assigned card_grid. Rationale: image-heavy entity, browsing is scan-and-select.
  • Home Cook + Recipe + scale is assigned detail_page with an inline scaling control. Rationale: single-entity task, the scaling is the primary action.
  • Home Cook + ScalingRatio + save is assigned inline_edit. Rationale: low-complexity creation, already in context of the recipe.

No priority rules needed. The cues do not conflict. Image-heavy and identity-strong both point toward the same treatment.

One mental model: "Home cooks expect recipe apps to lead with the photo. Every recipe site and app they have used does this." This reinforces the card grid assignment.

Claude Code reads design/governance.json and builds accordingly. The list page is a card grid with recipe photos. The detail page leads with the photo, places the name below, and puts the scaling control inline above the ingredient table. These are not choices Claude Code made. They are choices you already made, written as rules, applied at build time.

What the schema does not cover

  • Content. Copy, labels, sample data. These come from the entity model and Claude Code.
  • Aesthetic direction. The feel, the register, the references. These live in Project Settings alongside the design system pointer, not in the governance schema.
  • Business logic. Validation rules, auth flows, API contracts. These belong in design/plan.md.
  • Framework choices. React versus Svelte, Next versus Remix, state libraries. Plan territory, not governance territory.

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

Where to next