Audit Brand Compliance

Audit Brand Compliance

Rule-based brand-semantics audit. Detects (a) tokens used in forbidden contexts per their $extensions.harness.brand.forbidden_contexts metadata (BRAND-T001) and (b) UI copy containing phrases listed in DESIGN.md ## Brand Rules → voice.forbidden_phrases (BRAND-V001). The 4th composed verifier in harness check-design, alongside audit-component-anatomy, design-craft critique, and detect-design-drift.

When to Use

• After authoring or editing DESIGN.md ## Brand Rules — verify the new constraints are enforceable on the existing codebase
• After adding $extensions.harness.brand metadata to a token — discover existing call sites in forbidden contexts
• As part of harness validate (fast-mode hook, gated by design.audit.brandCompliance.enabled)
• As the 4th composed verifier in harness check-design (the unified design check)
• Before a PR with UI copy or token-usage changes lands
• NOT for tone-by-context rules (deferred to v1.x — requires component-state inference)
• NOT for reading-level or sentence-length rules (deferred to v1.x — ship with tone-context)
• NOT for asset-usage rules (deferred to v1.x — requires image-tag scanning)
• NOT for semantic-token-alias enforcement (overlaps with detect-design-drift T001 — design after both have shipped)
• NOT for brand-rule authoring (use harness-design skill to draft DESIGN.md sections)

Capability Roles

• Defines (Service Definition): the shared Verifier<F, Cat, Meta> interface (packages/cli/src/shared/verifier.ts); this was the 4th verifier whose addition triggered extraction of the interface.
• Provides (Provider): this skill — emits AuditBrandOutput = Verifier<BrandFinding> (packages/cli/src/brand/index.ts).
• Consumes (Consumer): harness-design-pipeline / harness check-design, which compose it generically via VerifierRegistry.

Process

Phase 1: LOAD — Parse the two input sources

1. Read project configuration. Check harness.config.json for:

   • design.strictness — strict / standard / permissive (default standard)
   • design.audit.brandCompliance.enabled — gate (default true)
   • design.audit.brandCompliance.rules.{tokenMisuse,voice} — per-rule toggles

2. Load design-system/DESIGN.md ## Brand Rules. The parser extracts:

   • voice.forbiddenPhrases: string[] — used by BRAND-V001 in v1
   • voice.constant, voice.readingLevel, voice.maxSentenceWords — parsed but unused in v1 (forward-compat)
   • toneByContext, assets, semanticTokenAliases — parsed but unused (v1.x)
   • Returns null when DESIGN.md absent or ## Brand Rules section missing → BRAND-V001 silently skips.

3. Load design-system/tokens.json $extensions.harness.brand. Walks the DTCG token tree capturing per-token role, approved_contexts, forbidden_contexts. Returns null when no token carries the extension → BRAND-T* silently skips.

Phase 2: SCAN — Apply the two rule families

1. BRAND-T001 — token misuse (regex-based). For each token whose forbidden_contexts is non-empty:

   • Find every reference to the token's dotted path in source (recognizes three forms):
     • tokens.X.Y.Z (JS accessor)
     • var(--X-Y-Z) (CSS var, kebab-cased)
     • 'X.Y.Z' / "X.Y.Z" (string literal)
   • Inspect surrounding context (same line + nearest non-blank previous and next line) for the v1 context-vocabulary keywords: cta, selection, focus, data-visualization, decorative, background, text, border, error, success, warning.
   • If a forbidden context matches: emit BRAND-T001.

2. BRAND-V001 — forbidden phrases (TS Compiler API). For each .tsx/.jsx file:

   • Walk the JSX tree.
   • For each JsxText node: case-insensitive substring scan for any forbiddenPhrase.
   • For each JsxAttribute whose initializer is a string literal: same scan.
   • Deduplicate per (file, line, phrase).

Phase 3: REPORT — Aggregate and surface

1. Severity from design.strictness (uses severityFor):

   • strict — all findings error
   • standard — BRAND-T001 error (declared violation), BRAND-V001 warn (copy nuance)
   • permissive — all findings info

2. Aggregate bySeverity and byCode into the standard Verifier shape: { findings, summary, catalog, meta }.

3. Persist findings to the graph (when composed by check-design). check-design routes brand findings through DesignConstraintAdapter.recordFindings() alongside anatomy / craft / drift. v1 uses the shared VIOLATES_design edge; v1.x may add a brand-specific edge.

Harness Integration

• harness validate — Fast-mode hook gated by design.audit.brandCompliance.enabled. Degrades gracefully on failure (single warning; other checks continue).
• harness check-design — Composes brand as the 4th verifier alongside audit-anatomy, design-craft critique, and detect-design-drift. This is the canonical invocation path.
• mcp__harness__audit_brand — MCP tool. Input: { path, mode, files?, designStrictness?, rules? }. Output: { findings, summary, catalog, meta }. Consumed by check-design and the (future) design-pipeline orchestrator.
• DesignConstraintAdapter.recordFindings() — Generic graph persistence entry point. Brand findings reuse the adapter (no graph schema changes in v1).
• harness-design skill — Authors DESIGN.md ## Brand Rules. audit-brand-compliance is the matching enforcer.
• Verifier<F> interface — Extracted in this PR at the 4th-verifier threshold. Lives at packages/cli/src/shared/verifier.ts. Adding a 5th verifier requires only a type-alias declaration of conformance.

Success Criteria

See docs/changes/design-pipeline/audit-brand-compliance/proposal.md for the full 34 success criteria. Highlights:

• DESIGN.md parser returns null when section absent (silent-skip pattern)
• Token-extensions walker returns null when no token carries $extensions.harness.brand
• BRAND-T001 fires on tokens.X, var(--x), and 'X' reference forms
• BRAND-T001 honors approved_contexts (no finding when context is allowed)
• BRAND-V001 fires on JSX text + string-typed JSX attributes (case-insensitive)
• BRAND-V001 deduplicates per (file, line, phrase)
• Verifier interface extraction: anatomy / drift / brand all declare structural conformance
• harness check-design test extended for 4-verifier composition (zero regressions)
• MCP tool count bumps 72 → 73

Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

Examples

Example: Token used in forbidden context

Input:

design-system/tokens.json:

{
  "color": {
    "brand": {
      "500": {
        "$type": "color",
        "$value": "#3b82f6",
        "$extensions": {
          "harness": {
            "brand": {
              "role": "primary",
              "approved_contexts": ["cta", "selection", "focus"],
              "forbidden_contexts": ["data-visualization", "decorative"]
            }
          }
        }
      }
    }
  }
}

src/Chart.tsx:

// data-visualization color palette
const palette = [tokens.color.brand.500, ...];

Output:

BRAND-T001 [error] src/Chart.tsx:2 — Token "color.brand.500" is used in forbidden context "data-visualization"
  Fix: Token "color.brand.500" is not approved for the "data-visualization" context.
       Use an approved token (allowed contexts: cta, selection, focus), or update
       tokens.json $extensions.harness.brand if the policy is wrong.

Example: Forbidden phrase in UI copy

Input:

DESIGN.md:

## Brand Rules

### Voice

forbidden_phrases:

- "click here"
- "best-in-class"

src/Cta.tsx:

export const Cta = () => <a href="/x">Click here</a>;

Output:

BRAND-V001 [warn] src/Cta.tsx:1 — UI copy contains forbidden phrase "click here" — declared at DESIGN.md ## Brand Rules → Voice → forbidden_phrases
  Fix: Rewrite to avoid "click here". If the phrase is unavoidable for this context,
       remove it from voice.forbidden_phrases (or scope the audit) — but the default
       policy is that brand voice trumps convenience.

Gates

• No findings without parsed inputs. DESIGN.md absent → BRAND-V001 skips silently. tokens.json $extensions.harness.brand absent on every token → BRAND-T001 skips silently. Either resolver returning null is NOT a verifier failure.
• No .ts/.js file scans for BRAND-V001. Only .jsx/.tsx (user-visible JSX). Doc copy in .md is a different audience.
• No tone-by-context inference. v1 only matches the explicit context-vocabulary keywords against surrounding source text. v1.x adds component-state inference.
• No autofix. audit-only. The matching align-brand-compliance fix-side skill is deferred until detect signals demand.
• No graph schema changes. v1 reuses VIOLATES_design via recordFindings(). v1.x may add VIOLATES_brand edge for queryability.
• Strictness from config, not assumed. Read design.strictness from harness.config.json; default standard if absent.

Escalation

• When BRAND-T001 false-positives on a far-context reference: the v1 context inference is intentionally narrow (same line + adjacent non-blank). For a token used in a "background" context where the keyword appears 10 lines away, v1 misses it. v1.x adds richer context inference; for now, either widen the surrounding comment or accept the miss.
• When BRAND-V001 false-positives on a substring (e.g., "as is" in "as issued"): v1 uses substring match. Add word-boundary regex in v1.x. For now, rephrase the copy or remove the phrase from voice.forbidden_phrases.
• When a project ships tokens with a different $extensions shape: v1 reads only harness.brand. Document the actual shape your project uses and add it to the schema sketch in ADR 0028 — DTCG $extensions namespaces are vendor-prefixed and additions are forward-compatible.
• When harness validate runtime exceeds 3 seconds: Set design.audit.brandCompliance.fastMode.maxFiles to cap the scope. The MCP tool ignores the cap (fast/full equivalent in v1).
• When the graph persistence fails: Skip graph integration for that run; findings still appear in the report. The graph is a consumer, not a gate.
• When you want tone-by-context rules today: Manual audit until v1.x ships. Component-state inference (empty/error/success/loading) requires JSX-context analysis that's a separate brainstorm.

Status

v1 — in implementation. See:

• Spec: docs/changes/design-pipeline/audit-brand-compliance/proposal.md
• ADR (input schema source): docs/knowledge/decisions/0028-brand-guidelines-source-of-truth.md
• Roadmap entry: part of the design-pipeline initiative in docs/roadmap.md
• Sibling rule-based audits: audit-component-anatomy, detect-design-drift
• Cross-cutting: extracts Verifier<F> interface at packages/cli/src/shared/verifier.ts (deferred until 4th data point — this is it)