AD‑14 [DS] — Design System & UX Safety Components

Aliases: None Cluster: Cross‑cutting Depends on: AD‑04 [TG], AD‑05 [MRP], AD‑08 [SO], AD‑11 [RA], AD‑12 [OP]

0. For humans

What question does this answer?

“If safety is real, where do I see it and how do I work with it without needing to read the paper?”

AD‑14’s job:

• Turn gates, pins, and states into stable, learnable UI components: Status beacons, Journey strip, Refusal Cards, Pin Chips, literacy primer, accessibility scaffolds.
• Make containment legible: “Which gate fired? Why? What can I do?” in one line + actions.
• Expose UX safety metrics in FHR so HCI / audit can verify real behaviour: refusal comprehension, find‑mode steps, error-recovery, a11y usage, pin review rates.

How do I know it’s live?

You can point to:

• Visible beacons: small stable labels for ethics gate, reflect‑only, sandbox, with hover‑explain.
• A Journey strip in the UI: “Hold → Options → Test → Decide”, clickable, aligned to MRP outcomes.
• Refusal Cards instead of raw “cannot comply”:
• 1‑line rationale (≤ 15 words, ≤ grade‑7)
• Which gate fired
• Buttons: Rephrase / See policy / Challenge / Ask human (where contestable).
• Pin Chips visible at top of the context, with forced Pin Review under drift; Pin history peek.
• A skippable 60–90 s primer that demos modes, beacons, Refusal Cards, Null state, with mini‑examples.
• FHR exporting UX metrics like: ux_refusal_ack_ms_p50/p95, ux_refusal_comprehension_rate, ux_toggle_adopt_rate, ux_toggle_revert_rate, ux_find_mode_steps_p95, ux_error_recovery_rate, ux_a11y_mode_active, pin_review_rate, pin_force_rate.

Where do I see it?

• FHR UX section: the metrics above, plus primer_seen, primer_completed.
• Events like: REFUSAL_CARD_SHOWN, REFUSAL_CHALLENGE_OPENED, REFUSAL_GUIDE_VIEWED, PIN_SET, PIN_EDIT, PIN_CONFLICT_DECISION, PIN_FORCE_REVIEW, PRIMER_SEEN, PRIMER_COMPLETED, PRIMER_REVISIT.

Quick checklist

• Implemented if: (1) Refusal Cards with ≤ 15‑word rationale, gate ID, action buttons; (2) Action Preview Cards with ≤ 25‑word action description, irreversible effects, confirm gate; (3) Status beacons and Journey strip present; (4) Pins visible at top with forced Pin Review under drift; (5) 60–90 s literacy primer shipped; (6) UX metrics in FHR (aggregate only)
• Key artefacts: design tokens, Refusal Card schema, Action Preview Card schema, Pin Chips, literacy primer
• Key FHR fields: ux_refusal_ack_ms_p50/p95, ux_refusal_comprehension_rate, ux_action_preview_ack_ms_p50/p95, ux_action_preview_rejection_rate, ux_find_mode_steps_p95, pin_review_rate, pin_force_rate, primer_completed
• Key failure codes: REFUSAL_CARD_SHOWN, ACTION_PREVIEW_SHOWN, PIN_FORCE_REVIEW, PRIMER_SEEN
• Escalation path: gate fire → Refusal Card → Rephrase / See policy / Challenge / Ask human; consequential action → Action Preview Card → Confirm / Reject

Preview/confirmation events use the AD‑08 §4.23 envelope and carry at least the Action Ticket ticket_id inside payload; the envelope supplies trace_id, schema identity/version, and timestamp. The normative join to MRP is defined at AD‑18.

1. Purpose & scope

AD‑14 defines the UI design system that makes SRF’s internals visible and usable:

• Components: tokens, gate chips, beacons, journey strip, Refusal Cards, constraint cards, colour‑safe palette, SR labels.
• Behaviour patterns: progress scaffolds, just‑in‑time explanations, long‑context hygiene, accessibility & localisation, onboarding primer.
• UX metrics + usability capsules: tied into AD‑11 [RA] and AD‑08 [SO].

2. Core design system primitives

2.1 Component families

• Tokens: semantic colours, typography scales, spacing.
• States for gates (ethics, policy, PEL), ring modes, sandbox.
• Palette is colour‑safe and tuned for WCAG 2.2 AA contrast.
• Gate chips: compact indicators of active gates / constraints; used in Refusal Cards, journey strip, and header.
• Status beacons: small persistent icons with SR labels:
• beacon_ethics_on – “Ethics gate active”
• beacon_reflect_only – “Reflect‑only mode”
• beacon_sandbox – “Sandbox mode”
• Constraint cards: visual wrappers for Pins (Goal, Constraints, Jurisdiction, Source Horizon).
• Journey strip: a horizontal progress scaffold mapping MRP states: Hold → Options → Test → Decide.

2.2 Accessibility defaults

• Aiming for WCAG 2.2 AA: keyboard navigation, SR landmarks, high‑contrast palette.
• Readability bands: Concise / Standard / Technical; tied into copy variants.
• RTL support and locale‑adapted question patterns; jurisdiction confirmation when the user code‑switches.

3. Status beacons & Journey strip

3.1 Status beacons

Small always‑visible indicators that expose safety state.

• Beacons:
• beacon_ethics_on – Ethics gate active.
• beacon_reflect_only – Model in Reflect‑only mode.
• beacon_sandbox – Experimental/sandbox environment.
• Behaviour:
• Always visible in header; hover‑to‑explain for short explanation.
• Screen‑reader labels and order defined in AD‑14’s a11y focus order; beacons and journey strip must be reachable before body content.

3.2 Journey strip

Provides MRP‑aligned wayfinding: Hold → Options → Test → Decide.

• Shows current step, near‑term next step, and completed steps.
• Steps are clickable; users can “jump back” to earlier phases (e.g. revisit Options).
• On hover, each step explains what the system is doing in that phase (e.g. “Testing alternative plans against gates”).

4. Refusal Cards

Core HCI object. When a gate fires, the user sees a Refusal Card, not a generic “cannot comply”.

4.1 Micro‑schema

Refusal Card schema:

{
"gate_id": "...",
"short_reason": "...", // ≤ 15 words, ≤ grade-7
"actions": ["rephrase", "see_policy", "challenge", "ask_human"],
"contestable": true|false
}

• Mandatory actions:
• Rephrase
• See policy
• Challenge (only if contestable = true)
• Ask human (if escalation path exists).
• Why‑This‑Decision drawer:
• Gate id, source (policy/PEL/statute), timestamp, and summary of evidence.
• Non‑contestable gates:
• No override UI; only Rephrase / Exit.

4.2 Copy budget & readability bands

• Budget:
• 1‑line rationale, ≤ 15 words, ≤ grade‑7 (Flesch‑Kincaid).
• Variants:
• Concise / Standard / Technical versions per rationale, keyed to the user’s readability band.
• Pipeline:
• Copy‑Lint checks length + readability; on failure, falls back to a simpler variant.
• Variant selection follows the user’s band; UI exposes a one‑tap toggle to downshift / upshift for this session.
• Ledger:
• REFUSAL_COPY_VARIANT{concise|standard|technical} event emitted on card display.

4.3 Events & metrics

Events: REFUSAL_CARD_SHOWN, REFUSAL_CHALLENGE_OPENED, REFUSAL_GUIDE_VIEWED.

FHR metrics:

• ux_refusal_ack_ms_p50/p95 – time to read/ack card.
• ux_refusal_comprehension_rate – % of sessions where Why‑This‑Decision was opened.

Limits:

• Never relax the 15‑word constraint or grade‑7 baseline for legally significant gates.

4b. Action Preview Card

The Action Preview Card is the complement of the Refusal Card: where the Refusal Card handles no, the Action Preview Card handles yes, but look first. It is required for external, persistent, or irreversible actions and states what will happen, where, with what data, and what cannot be undone.

4b.1 Micro‑schema

Action Preview Card schema:

{
"ticket_id": "T-...",
"action": "What will happen (plain language, ≤ 25 words)",
"target": "Where it will happen (system, service, resource)",
"data_used": "What inputs/state will be read",
"irreversible_effects": ["Explicit list of effects that cannot be undone"],
"reversibility": "REVERSIBLE | COMPENSABLE | IRREVERSIBLE",
"confirm_scope": true
}

• Mandatory fields: action, target, irreversible_effects, reversibility, confirm_scope.
• The card links to the underlying Action Ticket (AD‑18 [SE] §4.1) via ticket_id.
• Confirm gate: execution is blocked until the user explicitly confirms scope.
• Why‑This‑Action drawer: shows ticket_id, gate evaluation summary, risk_notes, and jurisdiction from the Action Ticket.

4b.2 Copy budget & readability

• Action description: ≤ 25 words, ≤ grade‑7 (Flesch‑Kincaid).
• Variants: Concise / Standard / Technical, keyed to the user's readability band (same pipeline as Refusal Cards, §4.2).
• Irreversible effects: listed as bullet points, each ≤ 15 words.

4b.3 Events & metrics

Events: ACTION_PREVIEW_SHOWN, ACTION_PREVIEW_CONFIRMED, ACTION_PREVIEW_REJECTED, ACTION_PREVIEW_DETAIL_VIEWED.

FHR metrics:

• ux_action_preview_ack_ms_p50/p95 – time to confirm/reject.
• ux_action_preview_rejection_rate – fraction of previews rejected (indicates system is proposing actions users don't want).
• ux_action_preview_detail_rate – fraction of previews where Why‑This‑Action was opened.

Limits:

• Never omit irreversible_effects for actions classified as IRREVERSIBLE.
• Confirm gate cannot be bypassed; no "don't ask again" option for irreversible actions.
• Aggregate counts/timings only; no content or PII.

5. Pin Chips & long‑context hygiene

5.1 Context Pins

Pins show Goal, Constraints, Jurisdiction, Source Horizon at the top of the context.

• User‑editable but arbitrated by PEL / jurisdiction.
• Edit → PIN_REVIEW flow; arbitration order: PEL ► Jurisdiction ► Constraints ► Goal ► Source Horizon.

5.2 Forced Pin Review

To enforce long‑context hygiene:

• If context window use > κ% or anchor‑slope < threshold, then:
• Force Pin Review before any tool call.
• Emit PIN_FORCE_REVIEW.

Limits: Jurisdiction pin cannot downgrade statutory constraints; Source Horizon cannot widen beyond allowed retrieval set.

5.3 Pin history peek

Small “Recent changes” popover showing last three edits + who/when + arbitration result.

• Events: PIN_SET, PIN_EDIT, PIN_CONFLICT_DECISION, PIN_FORCE_REVIEW.

6. Literacy primer & micro‑explanations

6.1 60–90 second primer

• Ships at first run; skippable, with progressive disclosure later.
• Shows:
• Modes [NARR]/[PROTO]/[DATA]
• Status beacons
• Refusal Cards
• Null state
• Two interactive mini‑examples (one refusal, one reflect‑only).
• Records PRIMER_SEEN, PRIMER_COMPLETED. If skipped, surfaces micro‑hints until completion.
• No telemetry beyond completion & step counts; no text content stored.

6.2 Just‑in‑time explanations

When a gate fires, users get one sentence + actions, not a treatise.

• Standardised containment vignette (≤ 15 words) on pause/hold.
• Example: “Output paused: verifying ethical consistency (EHG‑γ).”
• Buttons: Rephrase / See policy / Challenge (if contestable).

7. Accessibility, localisation, and mode memory

7.1 Accessibility & localisation

Accessibility is first‑class, localisation covers copy and interaction rhythm:

• WCAG 2.2 AA targets; keyboard navigation, SR landmarks, high‑contrast palette.
• Readability bands: Concise / Standard / Technical.
• RTL support, locale‑adapted indirect question forms.
• Jurisdiction confirm on code‑switch.

7.2 Mode memory

Remember choices but keep an obvious reset.

• Remember last chosen readability band and toggle set per session.
• UI provides one‑tap “Reset to defaults”.

7.3 A11y focus order

Publish the exact tab order in AD‑14; ensure status beacons and journey strip are reachable before body content.

8. UX metrics in FHR

AD‑14 defines the UX KPIs that AD‑08 [SO] and AD‑12 [OP] surface in FHR.

Metrics:

• primer_seen, primer_completed – literacy primer coverage.
• ux_refusal_ack_ms_p50/p95 – time to read/ack Refusal Card.
• ux_refusal_comprehension_rate – fraction of sessions opening Why‑This‑Decision.
• ux_toggle_adopt_rate, ux_toggle_revert_rate – how often users adopt/revert mode / readability toggles.
• ux_find_mode_steps_p95 – 95th percentile steps to find / switch to requested mode; target ≤ 3.
• ux_error_recovery_rate – success rate after rollback.
• ux_a11y_mode_active – screen‑reader / high‑contrast usage.
• pin_review_rate, pin_force_rate – frequency of voluntary vs forced Pin Review.

Constraints:

• Aggregate counts / timings only; no content or PII.
• No keystroke‑level tracking; all metrics can be disabled at deployment.

9. Usability capsules

Empirical UX metrics and small cross‑locale usability studies are part of the Replication/Audit story.

• Usability capsules (under AD‑11 [RA]):
• Optional eye‑tracking; primary KPIs: ux_find_mode_steps_p95 ≤ 3, ux_refusal_ack_ms_p50, comprehension rate, error‑recovery.
• Run with diverse language communities; feed findings into locale baselines and microcopy.

10. Invariants vs configurable degrees of freedom

Hard invariants (AD‑14 must‑haves)

• Sandbox deployments must use Refusal Cards; production keeps them on by default (can be compacted but not removed).
• Refusal Card:
• 1‑line rationale ≤ 15 words; ≤ grade‑7; has gate id + action buttons; Why‑This‑Decision drawer.
• Action Preview Card:
• Required for external, persistent, or irreversible actions.
• Action description ≤ 25 words; ≤ grade‑7; irreversible effects listed; confirm gate cannot be bypassed.
• Why‑This‑Action drawer links to Action Ticket (AD‑18 [SE] §4.1).
• Non‑contestable gates: no override UI.
• Pins visible at top; forced Pin Review under drift (context window use > κ% or anchor‑slope ↓).
• Beacons and journey strip present; journey strip aligned to MRP states.
• Accessibility baseline: WCAG 2.2 AA, readability bands, RTL, jurisdiction confirm on code‑switch.
• UX metrics are aggregate only; no content/PII; no keystroke‑level telemetry.

Degrees of freedom (configurable)

• Exact colours, icon shapes, typefaces, spacing tokens, as long as contrast and semantics are preserved.
• Journey strip labels (e.g. “Explore → Test → Commit”) so long as the mapping to MRP phases is documented.
• Primer duration within 60–90 s and how often it’s re‑offered.
• Threshold for ux_find_mode_steps_p95 (≤ 3 is the recommended spec; deployments may set stricter).
• Which UX metrics are enabled by default, provided the aggregate‑only constraint is preserved.

11. Acceptance: when can you say “AD‑14 is implemented”?

To implement AD‑14 in a product:

1. Instantiate design tokens for gate chips, beacons, journey strip, constraint cards; ensure colour palette is WCAG 2.2 AA.
2. Implement beacons & journey strip in the global shell; wire them to MRP states and gates.
3. Implement Refusal Cards with: - micro‑schema, copy budget, actions, Why‑This‑Decision drawer; - events and FHR metrics as per §4 and §8.
4. Implement Action Preview Cards with: - micro‑schema (§4b.1), copy budget (§4b.2), confirm gate, Why‑This‑Action drawer linked to Action Ticket (AD‑18 [SE] §4.1); - events and FHR metrics as per §4b.3.
5. Implement Pin Chips and Pin Review: - visible pins, edit → arbitration, forced review under drift, history peek, events.
6. Ship the literacy primer and micro‑hints: - 60–90 s guided, skippable; logs PRIMER_SEEN / COMPLETED; no content telemetry.
7. Wire UX metrics into FHR as aggregate fields with the limits described.
8. Validate HCI review points: - Refusal Cards: mandated (sandbox), compact default in prod. - Action Preview Cards: required for consequential actions; confirm gate enforced. - Pins: conservative arbitration + forced review. - Primer: 90‑second literacy primer shipped. - FHR UX metrics present. - A11y + localisation behaviours implemented.

Back‑references:

• AD‑18 [SE] (Action Preview Card triggered by Action Ticket's preview_required field; see AD‑18 §4.1, §4.4).
• AD‑29 [PLG] (boundary primitives originated in PLG bridge‑card work; Action Preview Card and Refusal Card are the two faces of the legibility surface for consequential decisions).
• AD‑30 [SC] (implements continuity mode indicator, memory review surface, model change notice, re‑attunement checkpoint UI).
• AD‑31 [HS] (implements readiness primer, integrity prompt UI, persistent rights controls, re‑entry confirmation).
• AD‑32 [PG] (implements pack provenance disclosure, pack challenge affordance in UI).