Eve library

OSHUN Studio Component Primitives Journeys and Edge Cases

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Product Design + Web Engineering
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md
  • docs/releases/v1/specs/studio-component-primitives-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and edge-case behavior for Studio component-primitives governance.

This document is the execution artifact for OST-00043.

Personas#

  • Design System Lead
  • UX Architect
  • Accessibility Lead
  • Frontend Technical Director
  • Program Reviewer

Journey Principles#

  1. Primitive changes must be reviewable, reversible, and auditable.
  2. Composition behavior must remain deterministic across all governed surfaces.
  3. Accessibility semantics are release gates, not optional checks.
  4. Every governance action preserves Studio execution context and traceability.

1. Primary Journeys#

J1. Primitive Catalog Draft and Publish#

Goal: Publish a new component-primitives bundle to preview.

Entry: Studio -> Component Primitives -> Bundle Pipeline

Steps:

  1. Clone current primitive catalog as draft.
  2. Add/update primitive variants and state contracts.
  3. Run schema + token dependency checks.
  4. Publish bundle to preview channel.
  5. Record telemetry/audit and rollback reference.

Success State:

  • Immutable primitive bundle version is published and preview-ready.

J2. Composition Contract Validation#

Goal: Validate template composition behavior for command-heavy workflows.

Entry: Studio -> Component Primitives -> Composition Validation

Steps:

  1. Select bundle and composition template set.
  2. Execute composition integrity checks.
  3. Execute focus, keyboard, and state-transition checks.
  4. Review violations and remediation hints.
  5. Re-run until validation passes.

Success State:

  • Validation report status is pass with no critical violations.

J3. Domain Primitive Parity Sync#

Goal: Ensure Yemaya/Isis/Hathor/Aja/Bellona consume the canonical primitive bundle.

Entry: Studio -> Component Primitives -> Domain Parity

Steps:

  1. Generate parity drift report by domain and surface.
  2. Apply canonical primitive bundle references.
  3. Re-run parity checks.
  4. Confirm parity pass state.
  5. Attach parity report to release package.

Success State:

  • Domain parity status is pass across all target domains.

J4. Program Approval and Production Promotion#

Goal: Promote validated primitive bundle to production.

Entry: Review & Approvals

Steps:

  1. Review primitive diff and validation/parity evidence.
  2. Verify role-policy and approver matrix.
  3. Approve/reject with rationale.
  4. Promote to production if approved.
  5. Confirm deployment and audit-event completeness.

Success State:

  • Production promotion completes with signed approval and full evidence chain.

J5. Primitive Regression Incident Rollback#

Goal: Recover from primitive-level regression in production.

Entry: Observability alert or escalation.

Steps:

  1. Identify failing primitive bundle and impacted surfaces.
  2. Roll back to last certified bundle.
  3. Validate interaction and accessibility recovery.
  4. Freeze problematic bundle and open remediation task.
  5. Publish incident analysis and prevention actions.

Success State:

  • Stable primitive behavior restored with incident evidence captured.

2. Critical Edge Cases#

E1. Incomplete Studio Context#

  • Trigger: missing program/project/workspace identifiers.
  • Required behavior: block action, request context repair, emit audit error.

E2. Unauthorized Publish Attempt#

  • Trigger: role lacks permission to publish primitives bundle.
  • Required behavior: deny with explicit policy reason and escalation guidance.

E3. Primitive State Contract Violation#

  • Trigger: missing required state variant (loading, error, disabled).
  • Required behavior: fail validation with primitive-level diagnostics.

E4. Keyboard Contract Regression#

  • Trigger: composed flow breaks required keyboard traversal behavior.
  • Required behavior: block release and attach focus-path diagnostics.

E5. Aria Semantics Drift#

  • Trigger: primitives missing or conflicting aria roles/states.
  • Required behavior: fail accessibility validation and require remediation.

E6. Composition Template Mismatch#

  • Trigger: governed surface uses forbidden composition pattern.
  • Required behavior: block promotion and identify violating template.

E7. Persistent Domain Parity Drift#

  • Trigger: parity still fails after sync operation.
  • Required behavior: keep release blocked and surface domain-specific drift details.

E8. Telemetry Sink Degradation#

  • Trigger: telemetry/audit events cannot be emitted.
  • Required behavior: retry, mark degraded observability, reconcile buffered events.

E9. Approval Deadlock#

  • Trigger: approver conflict, absence, or stale decision window.
  • Required behavior: delegated approval path with SLA escalation.

E10. Missing Rollback Reference#

  • Trigger: release package does not include rollback bundle metadata.
  • Required behavior: block production promotion.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Primitive Catalog Draft and Publish Component Primitives Observability
J2 Composition Contract Validation Component Primitives Governance
J3 Domain Primitive Parity Sync Component Primitives Programs, Projects
J4 Program Approval and Production Promotion Review & Approvals Governance
J5 Primitive Regression Incident Rollback Observability Component Primitives, Governance

4. Instrumentation Requirements#

Required events:

  • primitives.journey.started
  • primitives.journey.step.completed
  • primitives.journey.blocked
  • primitives.journey.recovered
  • primitives.journey.completed

Required dimensions:

  • programId, projectId, workspaceId
  • journeyId, stepId, bundleVersion
  • actorRole, outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00043)#

OST-00043 is complete only when:

  1. At least five component-primitives journeys are documented.
  2. At least ten component-primitives edge cases are documented with deterministic behavior.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.