Skip to main content
parlance — home

Audits

An audit checks a surface against a contract and reports what it finds. The contract is the source of truth — it describes what a component must be. The audit takes a real surface, compares it clause by clause, and tells you where the two agree and where they have drifted apart.

If contracts are the rules, audits are how you enforce them.

What an audit is

An audit answers one question: does this surface honour the contract? Every clause in the contract becomes a check. parlance evaluates each one against the surface — a property in a design file, a value in code, a computed style on a live page, a measurement in a native screen — and records the result as a finding.

Each audit produces:

  • A set of findings, one per failed or noted check.
  • A grouping by severity, so the most serious problems surface first.
  • A record of drift — every place the surface disagrees with the contract.
  • A timestamp and surface reference, so you can compare runs and watch conformance change.

See UI contracts for how contracts and clauses are defined, and glossaries & tokens for the vocabulary clauses draw on.

The four surfaces

parlance audits the same contract across four kinds of surface, so one definition holds the whole product to account.

  • Design. Your Figma files. parlance reads frames and components and checks them against the contract — colour, spacing, type, structure and accessibility — without leaving the canvas. Run these through the Figma plugin.
  • Code. Your repositories. parlance checks the components in your codebase against the contract, so drift is caught before it ships. Catch it as you write with the VS Code extension, which runs in CI too.
  • Live. Your production URLs, in a real browser. parlance audits what users actually receive — computed styles, contrast, ARIA and token usage in the wild. Run these through the browser extension.
  • Native. Your iOS apps. parlance audits SwiftUI and UIKit screens against the same contract through a shared ParlanceKit core. Use the Xcode extension during development and the native auditor on shipped apps.

Because every surface is measured against one contract, design, code, live and native can never quietly diverge — the audit makes any gap explicit.

Running an audit

Point parlance at a surface and run the check. You can do this from the platform, from an extension, or programmatically through the REST API and client SDK.

  • Choose the contract to audit against.
  • Choose the surface — a design file, a code repository, a live URL or a native app.
  • Run the audit. parlance evaluates every clause and returns findings grouped by severity.

Audits are repeatable. Run them on demand while you work, or wire them into continuous integration so every change is checked automatically before it merges.

Reading findings

A finding is a single result from a single check. It tells you:

  • Which clause was checked, and the property it governs (for example background, padding-x or contrast).
  • What the contract expected — the value sourced from your glossary.
  • What the surface actually had.
  • The severity of the gap.
  • Where it was found, so you can go straight to the offending frame, line or screen.

Findings are grouped by severity so you read the most serious problems first and triage the rest in order.

Severities

Each finding carries a severity that reflects how much the gap matters. Severities let you draw a clear line between what blocks a release and what can wait.

  • Critical — a breach that should block the surface from shipping, such as an accessibility failure or a structural violation of the contract.
  • Serious — a clear contract violation that needs fixing, but is not release-blocking on its own.
  • Moderate — a meaningful deviation worth correcting in the normal course of work.
  • Minor — a small, low-impact discrepancy or a note for awareness.

Use severity to decide what to fix now and what to schedule. Accessibility findings map to recognised standards — see accessibility for WCAG 2.2, WAI-ARIA 1.2, Section 508 and EN 301 549.

Drift

Drift is where a surface disagrees with the contract. It is the heart of what an audit detects: the design file uses a colour that is not in the glossary, the code hardcodes a spacing value the contract does not allow, the live page renders type the contract never specified, the native screen falls short of a contrast role.

Drift creeps in quietly — a one-off override here, a copied value there — until design and code tell different stories. An audit makes every instance visible and attributes it to the exact clause it breaches, so nothing accumulates unseen.

Fixing and re-auditing

Findings are a worklist, not a verdict. The loop is simple:

  • Read the finding to see the clause, the expected value and the actual value.
  • Fix the surface — pull the value from the glossary, correct the structure, meet the accessibility requirement.
  • Re-run the audit. Resolved findings drop away; anything still drifting remains.

Because clauses draw their expected values from your glossary and tokens, the fix is usually to adopt the shared value rather than invent a new one. That is what keeps every surface speaking the same language.

Conformance over time

A single audit is a snapshot. The value compounds when you run audits continuously and watch the trend.

  • Re-audit on every change — in the editor, in CI, on each design revision and each release.
  • Track findings and severities across runs to see conformance improve as drift is resolved.
  • Hold the line by failing builds on critical findings, so regressions are caught the moment they appear.

Run audits everywhere your product lives and the contract stops being a document and becomes a guarantee.

Next steps