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.mddocs/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#
- Primitive changes must be reviewable, reversible, and auditable.
- Composition behavior must remain deterministic across all governed surfaces.
- Accessibility semantics are release gates, not optional checks.
- 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:
- Clone current primitive catalog as draft.
- Add/update primitive variants and state contracts.
- Run schema + token dependency checks.
- Publish bundle to preview channel.
- 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:
- Select bundle and composition template set.
- Execute composition integrity checks.
- Execute focus, keyboard, and state-transition checks.
- Review violations and remediation hints.
- Re-run until validation passes.
Success State:
- Validation report status is
passwith 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:
- Generate parity drift report by domain and surface.
- Apply canonical primitive bundle references.
- Re-run parity checks.
- Confirm parity pass state.
- Attach parity report to release package.
Success State:
- Domain parity status is
passacross all target domains.
J4. Program Approval and Production Promotion#
Goal: Promote validated primitive bundle to production.
Entry: Review & Approvals
Steps:
- Review primitive diff and validation/parity evidence.
- Verify role-policy and approver matrix.
- Approve/reject with rationale.
- Promote to production if approved.
- 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:
- Identify failing primitive bundle and impacted surfaces.
- Roll back to last certified bundle.
- Validate interaction and accessibility recovery.
- Freeze problematic bundle and open remediation task.
- 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.startedprimitives.journey.step.completedprimitives.journey.blockedprimitives.journey.recoveredprimitives.journey.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,bundleVersionactorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00043)#
OST-00043 is complete only when:
- At least five component-primitives journeys are documented.
- At least ten component-primitives edge cases are documented with deterministic behavior.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.