Language & Tone Guidelines

Purpose

This document defines how Evalium speaks — to users, clients, auditors, and internal stakeholders.

Its goal is to ensure that Evalium remains:

• Easy to understand in normal use
• Calm and reassuring under pressure
• Serious and precise only when it needs to be

This document enforces a strict separation between:

• Internal implementation language (how the system works)
• User-facing language (how the system is experienced)

Evalium’s complexity is intentional — but it is the system’s responsibility to carry that complexity, not the user’s.

---

Capability Baseline (Validated 2026-02-25)

Copy must reflect current capability truth:

• Use present-tense language only for backend-live surfaces.
• For target-state surfaces (skills profiles, compliance case timeline, dedicated grading queue/proctor commands), use explicit future/feature-flag wording.
• Never imply first-class backend states that do not yet exist (for example, persisted assignment draft status).

---

Core Voice Principles (Non‑Negotiable)

1. Calm by Default

Evalium should feel like a quiet, confident professional.

• Use plain, steady language
• Avoid urgency unless there is real risk
• Prefer reassurance over instruction

Good

• “Saved.”
• “Changes will apply to future work.”
• “You can review the impact before continuing.”

Avoid

• “Warning!”
• “Critical error!” (unless truly critical)
• Overuse of modal confirmations

---

2. Simple First, Precise Second

Always lead with the simplest accurate explanation.

• Start with what the user needs to know now
• Reveal detail only when requested or required

Example

• Default: “Results updated.”
• Expanded (Explain): “These results were recalculated using the rules in place on 12 Mar 2025.”

---

3. The System Takes Responsibility

Language should make it clear that Evalium is protecting the user, not policing them.

• The system explains consequences before action
• The system pauses when an action is irreversible
• The system records history quietly and consistently

Good

• “Here’s what will change if you continue.”
• “This action is recorded so you can refer back to it later.”

Avoid

• “This action is irreversible. Proceed at your own risk.”

---

4. Seriousness Is Situational

Evalium is not serious all the time — it becomes serious when the moment requires it.

Moments of seriousness include:

• Publishing changes with downstream impact
• Finalising grades or judgements
• Correcting results
• Applying overrides
• Compliance or governance actions

In these moments:

• Slow the user down slightly
• Be explicit about consequences
• Require reasons where appropriate

Outside these moments, the UI should remain lightweight and fast.

---

Vocabulary Rules

1. User‑Facing Language Always Wins

If a concept can be described without internal terminology, it should be.

Internal terms must never appear by default in the UI. They may appear only in:

• Explain views
• Advanced drawers
• Audit or governance contexts

---

2. Approved User‑Facing Aliases

Internal Concept	User‑Facing Language
Execution Ledger	Activity / History
Version Snapshot	What was used at the time
Projection	Calculated result
Evidence Fact	Supporting evidence
Remediation Batch	Result correction
Link Principal / Glass Box	Client Link
Verification Level (L1–L4)	Verification strength
Context Binding	Verified context
Proof Readiness	Defensibility status
Defensibility Exception	Needs attention item
Auth Session	Sign-in activity
Delivery Session	Delivery run

These aliases should be used consistently across the product.

---

3. Identity vs Delivery Naming (MUST)

The word "session" is overloaded in Evalium and can confuse users.

Use these defaults:

• Identity/security surfaces:
  • Use Account Security, Sign-In Security, or Sign-in activity
  • For row-level objects, prefer Device / Sign-in
• Runtime/delivery surfaces:
  • Use Delivery run (or Evaluation run where domain context requires)

Do not use bare Session as a primary nav label or page title for user-facing UI.

If a technical term is unavoidable, qualify it explicitly (sign-in session or delivery run) instead of relying on a clarifier note.

---

4. Words to Avoid by Default

The following terms are implementation‑level and should not appear in normal UI copy:

• ledger
• immutable
• append‑only
• projection worker
• recalculation job
• RLS
• WORM

If they appear at all, they must be:

• Behind an Explain or Advanced affordance
• Accompanied by a plain‑language explanation

---

Writing Style Guidelines

Contract-Aligned Status Vocabulary (MUST)

Where status contracts exist, copy must use canonical labels to avoid ambiguity:

• Readiness states: Ready, Needs review, Blocked
• Exception triage states: Open, Acknowledged, Resolved
• Assignment monitor states:
  • backend invited -> UI Not started
  • backend started -> UI In progress
  • backend completed -> UI Completed
  • backend expired -> UI Expired

Do not invent alternate labels for these in the same workflow (for example mixing “Action needed” and “Needs review” for the same contract state).

Localisation Runtime Contract (MUST)

• UI copy must be served through Inlang Paraglide-JS message keys (no hardcoded literals in UI components).
• Runtime translation override precedence is:
  1. org override
  2. tenant override
  3. product default
• Missing override values must silently fallback down the chain.
• Placeholder tokens (variables) must be preserved exactly in override values.

Visual and Interaction Shift During Serious Moments

When the system enters a moment of seriousness (e.g. publishing with impact, correcting results, finalising grades), language and visuals should subtly change together:

• Slightly slower pacing
• Clearer spacing and emphasis
• Reduced visual noise
• Focused summaries and previews

This reinforces seriousness without alarm, and signals to the user that attention is warranted.

Short, Declarative Sentences

Prefer short sentences that state facts.

Good

• “Saved.”
• “No changes were made.”
• “3 results will be updated.”

Avoid

• Long explanatory paragraphs in primary UI
• Legalistic phrasing

---

Neutral, Professional Tone

Evalium should never sound:

• sarcastic
• jokey
• alarmist
• overly formal

It should sound like a competent colleague who knows what they’re doing.

---

No Blame Language

The system never implies user error unless explicitly necessary.

Good

• “This result was updated due to a correction.”

Avoid

• “This result was incorrect.”
• “You made an error.”

---

Explaining Depth (When Requested)

When users click Explain, the tone becomes more precise, but remains outcome-focused and human.

Explain views must:

• Describe what this means for the user, not how the system is built
• Focus on outcomes, scope, and protection, not internal mechanics
• Avoid raw implementation terminology unless strictly necessary

Good deep-dive language

• “This record cannot be changed. Any future corrections will be added as new entries so the full history is preserved.”
• “These results reflect the rules that were in place at the time the work was completed.”

Avoid

• “This record is stored in an append-only ledger.”
• “This was recalculated by a projection worker.”

The goal of Explain is confidence, not technical education.

---

Internal vs External Communication

Internal (Docs, Code, Architecture)

• Precision over accessibility
• Correct technical terminology
• Full invariants and guarantees

External (UI, Emails, Demos, Sales)

• Accessibility over precision
• Human language
• Focus on outcomes, not mechanisms

If there is tension between the two, external clarity wins.

---

Enforcement

All new features and copy should be reviewed against this document.

Checklist:

• Would a non‑technical SMB understand this?
• Is seriousness only introduced where appropriate?
• Are we describing outcomes instead of mechanisms?
• Are internal terms hidden unless explicitly requested?

If the answer to any is “no”, the language should be revised.

---

Relationship to Other Docs

• Normal Use & Depth Discovery defines how Evalium feels in practice
• FOUNDATION defines why Evalium exists
• architecture defines how Evalium is built

This document ensures all three speak with one voice.