UCCA Mode System Standard¶

UMS-001 — Contextual Interface Modes¶

Version 1.0 — 3 April 2026¶

Universal Capability Certification Authority (UCCA Inc)¶

Status¶

Active Standard. This document is maintained by UCCA Inc and governs the design and implementation of contextual interface modes across all UCCA-engine products. Licensed implementations must reference this document by version number and may extend but not contradict it.

1. Purpose¶

The UCCA Mode System defines a three-mode interface pattern for administrative and operational surfaces built on the UCCA engine. The pattern exists to serve three distinct audiences from a single surface without building three separate interfaces.

The core principle: one surface, three lenses.

The data, controls, and functionality do not change between modes. What changes is the layer of contextual information overlaid on the surface — explanatory annotations for learners, governance anchors for auditors, nothing extra for experienced operators.

This standard defines the modes, their behaviour, the annotation content model, the translation pipeline, and the rules governing licensed forks.

2. The Three Modes¶

2.1 LIVE¶

The default mode. The surface is clean — no additional annotations, no overlay content. This is the workspace for an experienced operator who knows the system and needs no prompting.

LIVE is the baseline. All other modes are additive layers on top of LIVE. Nothing in GUIDED or COMPLIANCE mode removes or replaces functionality — it only adds contextual information.

2.2 GUIDED¶

The learner mode. Every annotated element on the surface receives a contextual badge explaining: - What the element is - Why it exists - What the user should do with it, or what it is telling them

GUIDED mode is designed for: - New users learning the system for the first time - Employees onboarding to a new role - Operators returning to an unfamiliar section of the product

L Plate metaphor: GUIDED mode is learner plates. The user puts them on when they need them and removes them when they don't. As users become confident with individual elements, they can dismiss annotations for those elements. Dismissals persist across sessions per user. When everything has been dismissed, the surface effectively returns to LIVE mode — but the annotations remain available to re-enable at any time.

GUIDED mode is not a help system or a tooltip library. It is a documentation layer that lives on the operational surface itself, visible to any user who needs it, invisible to those who don't.

2.3 COMPLIANCE¶

The audit mode. Every annotated element on the surface receives a governance badge showing: - A reference ID (e.g. INF-001, GF-§3.1) - The policy, clause, or standard the element satisfies - A one-sentence rationale for why the element exists in governance terms

COMPLIANCE mode is designed for: - Auditors conducting compliance reviews - Board members reviewing operational governance - Regulators assessing process controls - Internal governance officers mapping controls to frameworks

The auditor surface: In COMPLIANCE mode, the operator's daily workspace becomes a navigable compliance map. The auditor sees the same screen the board member uses every day — not a separate audit report — with the governance layer exposed. Every control is anchored to its policy reference in situ.

Export: COMPLIANCE mode includes an Export function that generates a structured JSON document containing every annotated element, its governance reference, and a coverage percentage indicating how complete the compliance mapping is. This export constitutes a machine-readable control register.

3. Annotation Content Model¶

3.1 Structure¶

Annotations are stored in structured text files — one file per surface section. Files are the source of truth. Runtime systems may cache annotation content in a database for serving performance, but the file is canonical.

Each annotation entry maps an element identifier to its mode-specific content:

{
  "element_id": {
    "guided": {
      "title": "Short label for the element",
      "body": "Plain English explanation of what this element is, why it exists, and what the user should do with it.",
      "_draft": true
    },
    "compliance": {
      "ref": "REFERENCE-ID",
      "title": "Short policy reference title",
      "clause": "Policy Document §Section",
      "summary": "One-sentence rationale for why this element exists in governance terms.",
      "framework": "Name of governing framework or document",
      "_draft": true
    }
  }
}

3.2 Element Identifiers¶

Every annotatable element in the UI carries a data-annotation-id attribute. The value is a dot-separated hierarchical identifier:

{product}.{surface}.{section}.{element}

Examples:

rtopacks.admin.radar.trigger_crawl
rtopacks.admin.organisations.abn_status
ucco.ops.infrastructure.zone_health
ucco.ops.pioneer.key_table

Identifiers are stable. Once assigned, an identifier does not change. If an element is removed from the UI, its annotation entry is archived, not deleted.

3.3 Draft Status¶

All annotation entries carry a _draft boolean. Draft entries are visible in GUIDED and COMPLIANCE modes but render with a visual indicator (e.g. dashed border) showing the annotation has not yet been reviewed by a human editor. Draft status is set to false only after human review and approval.

Machine-generated annotations (LLM-authored first drafts) are always _draft: true. Human-reviewed annotations are _draft: false.

3.4 Coverage¶

Coverage is calculated as the percentage of annotatable elements (data-annotation-id present) that have a corresponding annotation entry with _draft: false. Coverage is reported separately for GUIDED and COMPLIANCE modes.

A surface with 100% GUIDED coverage and 0% COMPLIANCE coverage is normal — GUIDED annotations are written first, COMPLIANCE annotations require policy mapping work.

4. Translation Pipeline¶

4.1 File Format for Translation¶

The annotation file format is designed for machine and human translation.

The English master file is the source of truth. Translated files are copies of the master with localised content, stored alongside the master with a locale suffix:

annotations/
  radar.en.json        ← English master
  radar.zh-Hans.json   ← Simplified Chinese
  radar.ja.json        ← Japanese
  radar.fr.json        ← French

4.2 Machine Translation Pass¶

The entire English master file is submitted to an LLM translation pass in one operation. The LLM receives the full file and returns a translated version. All translated entries receive _draft: true regardless of the English source entry's draft status.

The machine translation pass is the starting point, not the end point.

4.3 Human Review Pass¶

A human translator reviews the machine-translated file. They edit entries in place, correcting terminology, adjusting register, and ensuring accuracy. When an entry is reviewed and approved, _draft is set to false.

The human reviewer does not need to understand code. The JSON file is their only working document. They receive: - The translated file (to edit) - The English master (for reference) - A screenshot of the surface in GUIDED or COMPLIANCE mode (for context)

4.4 Diff on Master Update¶

When the English master is updated (new annotations added, existing annotations revised), the diff between the previous and current version is used to identify which translated entries require re-review. Only changed entries are reset to _draft: true in translated files — unchanged entries retain their review status.

4.5 Locale Selection¶

The runtime system selects the annotation file based on the user's locale preference, falling back to English if a locale file does not exist or if a specific entry has not yet been translated.

5. Renderer Specification¶

5.1 GUIDED Mode Renderer¶

Scans the DOM for elements with data-annotation-id attributes
For each element, looks up the annotation entry from the loaded annotation file
If an entry exists and has not been dismissed by the current user: renders a blue information badge adjacent to the element
Badge displays: title (bold), body text
Draft entries render with a dashed border on the badge
Badge is dismissible — clicking the dismiss control hides the badge for that element for that user, persisted in the user's session store
A global "Reset all dismissed annotations" control is available in user settings
Elements with no annotation entry: no badge rendered (silent)
Elements with an annotation entry that the user has dismissed: no badge rendered

5.2 COMPLIANCE Mode Renderer¶

Same DOM scan as GUIDED renderer
Renders an amber governance badge adjacent to each annotated element
Badge displays: ref ID (bold), title, clause, summary
Draft entries render with a dashed border
Badges are not dismissible in COMPLIANCE mode — the governance mapping is always visible when the mode is active
Elements with no annotation entry: renders a grey placeholder badge — "No compliance mapping" — to signal a gap in coverage
Export button: generates JSON control register and downloads it

5.3 Mode State¶

Mode state is stored in the user's session (localStorage or equivalent)
Mode persists across navigation within the product
Default mode on first visit: LIVE
Mode tabs are always visible in the header — LIVE, GUIDED, COMPLIANCE
Active mode tab is visually highlighted
Mode change takes effect immediately — no page reload required

5.4 Layer Access Rules¶

Implementations may restrict mode access by user role:

Standard users: LIVE and GUIDED only. No COMPLIANCE tab.
Administrators: All three modes.
Auditor role (if implemented): All three modes, COMPLIANCE default.

Access rules are defined by the licensed implementation, not by this standard. The standard defines the modes; the implementation defines who can use them.

6. Implementation Requirements¶

Any licensed implementation of the UCCA Mode System must:

Implement all three modes. Partial implementations (e.g. LIVE and GUIDED only, no COMPLIANCE) are not compliant with this standard.
Use the defined annotation file format. The JSON schema defined in Section 3.1 is canonical. Extensions are permitted; the core fields are required.
Use dot-separated hierarchical element identifiers as defined in Section 3.2, prefixed with the product identifier assigned by UCCA.
Maintain English as the master language. All annotation files have an English master. Translations are derived from the English master.
Implement the draft status system. All machine-generated annotations begin as drafts. Human review is required before draft status is cleared.
Reference this document by version number in the implementation's own Mode System documentation.

7. Licensing¶

The UCCA Mode System Standard is intellectual property of UCCA Inc (EIN 84-4522608), a Delaware C-Corporation.

Licensed implementations are granted the right to implement, fork, and extend this standard for their own products under the terms of their UCCA licensing agreement. Fork documents must:

Reference the UCCA master standard by document identifier and version number (UMS-001 v1.0)
Identify where their implementation extends the standard
Identify where their implementation restricts or narrows the standard
Not claim authorship of the standard itself

UCCA Inc retains all rights to the standard. Improvements made by licensees that are of universal applicability may be submitted to UCCA Inc for consideration for inclusion in a future revision of the master standard. Inclusion is at the sole discretion of UCCA Inc.

8. Version History¶

Version	Date	Author	Notes
1.0	3 April 2026	UCCA Inc	Initial standard. Derived from implementation experience across UCCA ops console and RTOpacks admin panel.

9. Document Information¶

Field	Value
Document ID	UMS-001
Title	UCCA Mode System Standard
Version	1.0
Status	Active
Owner	UCCA Inc
Repository	ucca-docs/docs/standards/mode-system.md
Licence	Proprietary — UCCA Inc. Licensed use only.

This document is maintained by UCCA Inc. Licensed implementations must reference this document by identifier and version. For licensing enquiries: tim@ucca.online