Skip to main content
parlance — home

UI contracts

A contract is the heart of parlance. It describes what a single component must be — its properties, the values they take and the states they hold — in a form that can be checked against design, code, live products and native apps alike. Once a contract is active, it becomes the source of truth every surface is audited against, so design and code can never quietly drift apart.

What a contract describes

A contract belongs to a project and describes exactly one component — for example Button / primary, Card / elevated or Input / default. It captures the component's intended appearance and behaviour as a set of clauses, each one a precise, checkable statement.

A contract is not a snapshot of how a component happens to look today. It is the agreed definition of how the component should look and behave, expressed in shared vocabulary so that every team and every surface reads it the same way.

Clauses

A contract is made of clauses. Each clause ties a property to a value, and the value is sourced from a glossary rather than written by hand.

A clause has three parts:

  • Property — what is being constrained, for example background, padding-x, font or contrast.
  • Value — what the property must equal, drawn from a glossary entry rather than a literal. A background clause points at a colour role; a padding-x clause points at a spacing step; a font clause points at a type entry.
  • Scope — the state or context the clause applies to, so a component can hold different values across its states (for example default, hover, focus and disabled).

Because every value is a reference into a glossary, a single change to a glossary entry flows through every clause that points at it. There are no stray literals to chase down, and no opportunity for a hard-coded value to disagree with the design tokens.

Properties

Clauses constrain the properties that define a component. Common families include:

  • Colour — background, foreground, border, and the contrast between them.
  • Spacing — padding-x, padding-y, gap, margin and related steps.
  • Type — font, size, weight and line height.
  • Shape and motion — radius, border width, and transition or motion properties.

Accessibility clauses such as contrast are first-class here, not an afterthought. A contrast clause is checked against WCAG 2.2 in both light and dark, so the contract enforces an accessible result rather than only a colour value. See accessibility for how this is evaluated.

Sourcing values from glossaries

Clauses never hold raw values like a hex colour or a pixel measurement. Instead, each clause references an entry in a glossary — the shared vocabulary for colour, spacing, type and motion.

This is what makes a contract a true source of truth:

  • A colour clause points at a semantic role (for example surface or accent), which resolves to the right value in light and in dark.
  • A spacing clause points at a step on your dimensional scale, so spacing stays consistent across components.
  • A type clause points at a type entry, keeping fonts, sizes and weights aligned.

When a glossary entry changes, every contract that references it stays correct automatically. When a surface uses a value that does not match the referenced entry, the audit flags it as drift.

The component hierarchy

Contracts are organised around an atomic hierarchy, so a complex interface is described as a composition of smaller, well-defined parts rather than one sprawling definition. The levels are:

  • Atom — the smallest building block, such as a button, input or icon.
  • Molecule — a small group of atoms working together, such as a labelled field.
  • Organism — a larger, self-contained section, such as a navigation bar or a form.
  • Template — a page-level arrangement of organisms without specific content.
  • Page — a concrete instance of a template.

parlance ships with roughly 129 component types spanning these levels, plus a custom escape hatch for anything that does not fit a predefined type. Choosing the right type and level keeps contracts consistent and makes audits across surfaces directly comparable.

Statuses

A contract moves through statuses as it matures:

  • Draft — a work in progress. You can shape clauses freely; the contract is not yet treated as binding during audits.
  • Active — the agreed source of truth. Surfaces are audited against it, and disagreements are reported as findings.

Promoting a contract from draft to active is the moment its definition becomes binding across every surface you audit.

How a contract becomes the source of truth

Once a contract is active, parlance holds every surface of your product to it:

  • Design files are checked so the design matches the contract it claims to implement.
  • Code is checked so components render the values the contract requires.
  • Live products are checked in the browser against the same clauses.
  • Native apps are checked through the native auditor.

Each surface is compared clause by clause. Where a surface agrees, it passes; where it disagrees, parlance records a finding and flags the drift, grouped by severity so you can act on what matters first. See audits for how findings and severities work.

Next steps