Skip to main content
Parlance — home

Audits

An audit checks a source 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 source, 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 source honour the contract? Every clause in the contract becomes a check. Parlance evaluates each one against the source — 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 an issue.

Each audit produces:

  • A set of issues, one per failed or noted check.
  • A grouping by severity, so the most serious problems come first.
  • A record of drift — every place the source disagrees with the contract.
  • A timestamp and source 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 sources

Parlance audits the same contract across four kinds of source, 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, or automate the same checks with the SDK or REST API.
  • 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 source 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 source and run the check. In the platform, an audit is recorded manually: you work through the contract clause by clause and record each result yourself. Automated capture comes from the extensions — the Figma plugin, the browser extension, the VS Code extension and the native tooling measure the source for you and push the results back. You can also drive audits programmatically through the REST API and client SDK.

  • Choose the contract to audit against.
  • Choose the source — a design file, a code repository, a live URL or a native app.
  • Run the audit. Every clause is evaluated — captured automatically by an extension, or recorded by hand in the platform — and issues are 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 issues

An issue 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 source actually had.
  • The severity of the gap.
  • Where it was found, so you can go straight to the offending frame, line or screen.

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

Severities

Each issue 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 source 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 issues map to recognised standards — see accessibility for WCAG 2.2, WAI-ARIA 1.2, Section 508 and EN 301 549.

Scores, coverage & appearance

Alongside the issue list, an audit reports a conformance score — a single number for how closely the source honours the contract.

  • Severity-weighted. The score is a severity-weighted average over the clauses that were actually observed: a match weighs 1, a critical failure weighs 4. The worse the failure, the harder it pulls the score down.
  • Only observed clauses count. Clauses that weren't observed don't count towards the score. When an audit didn't cover the whole contract, it carries a Partial badge, so a high score is never mistaken for full coverage.
  • Skipped vs. absent. In a manual audit, leaving a clause blank skips it — skipped clauses are excluded from the score. Tick Value absent instead when the value is genuinely missing from the source: that counts as observed and scores as a failure.
  • Light and dark. An audit runs in a light or dark appearance; colour-role expectations resolve to that mode's shades, and a dark-mode run is badged dark mode. Both themes are first-class audit targets, never bolted on.

Conformance cells show each source's latest audit; the design system page rolls projects up worst-case. See conformance for how scores roll up.

Drift

Drift is where a source 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

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

  • Read the issue to see the clause, the expected value and the actual value.
  • Fix the source — pull the value from the glossary, correct the structure, meet the accessibility requirement.
  • Re-run the audit. Resolved issues 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 source 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 issues and severities across runs to see conformance improve as drift is resolved.
  • Hold the line by failing builds on critical issues, so regressions are caught the moment they appear.

Run audits everywhere your product lives and the contract stops being a document and becomes a continuous check — every surface, every change, held to the same line.

Next steps