Structured Content Editor / CMS Authoring UX

When the preview looks right but the content contract is wrong

Two authors edit the same lesson. Author A changes heading structure and an assessment block. Author B, still based on an older revision, adds a media block without alternative text. B's autosave arrives after A's revision has already become the canonical head. A CMS that simply stores the last payload can silently overwrite A's work. A preview built from a different draft can show reviewers something other than the publish target. Accessibility defects discovered only at publish time arrive too late.

This lesson builds Structured Content Authoring State Machine & Accessible Editor Contract v1. Canonical content uses schema-versioned blocks and fields; each autosave binds an explicit base_revision_id; stale bases branch into conflicts instead of overwriting; semantics and accessibility metadata are validated before promotion; a review revision is selected explicitly; and preview/publish derive only from that declared revision.

The goal is not a prettier editor. The goal is an authoring UX that can prove what changed, from which base revision, which gates passed or failed, exactly which revision the reviewer saw, and what is allowed to publish.

For: CMS/LMS engineers, authoring-workflow designers, frontend/backend engineers, accessibility and QA reviewers. Not for: replacing a design system, authoring live production content, or claiming organizational/legal conformance from this lesson alone.

Route and lesson boundary

MKN-027 owns Structured Content Editor / CMS Authoring UX only. Its hard prerequisite is MKN-026; MKN-028 later owns private Mentor/Reviewer context sharing. This lesson does not absorb either adjacent outcome.

Foundation learners use a field map and baseline. Repair learners isolate the first broken evidence dimension, such as stale base, alt text, or preview revision. Experienced learners defend trade-offs among flexibility, conflict safety, accessibility assistance, deterministic preview, and migration compatibility without collapsing them into a synthetic score.

Three checkpoints: F1 restates the boundary and a non-goal; F2 rejects one shortcut using an exact field/state; F3 independently recomputes the schema-v2 transfer from changed evidence.

Mental model: the editor is a state machine over structured revisions

Reference flow:

structured edit → schema validation → accessibility assistance/check → revision + autosave → conflict detection → review revision → deterministic preview → publish gate

Critical branch:

stale base → conflict branch → preserve both drafts → explicit merge/review, not last write wins.

Keep three objects distinct:

1. Canonical content revision: schema-versioned blocks/fields with stable identities.
2. Authoring draft/autosave branch: work in progress bound to an explicit base; it is not yet the canonical review revision.
3. Review/preview/publish selection: one explicit revision that the reviewer sees and the renderer consumes.

A preview built from another revision breaks provenance even when it looks correct. Missing accessibility metadata must trigger assistance and validation rather than disappear behind a publish button.

Separate FACT / INFERENCE / DESIGN. ATAG and WCAG provide external facts. Aligning validation and preview with the canonical revision is an architecture inference. Exact schemas, states, and migration policy are local MAKNOW design.

Foundational contract: schema, revision, validation, and preview identity

Decision-critical fields are content_id, content_type, schema_version, block_id, block_type, field_semantics, required_state, validation_state, accessibility_metadata, alt_text_state, heading_structure_state, revision_id, base_revision_id, autosave_revision, conflict_state, author_ref, reviewer_ref, review_state, preview_revision, publish_state, migration_state, and audit_event_id.

Five invariants:

1. Schema explicit: every revision declares its schema version; unknown blocks are not guessed into existence.
2. Revision identity: an autosave without a base is weak evidence; a stale base must produce a conflict branch.
3. Accessibility before promotion: media without required alternative text or invalid heading structure cannot honestly retain validation_state=PASS.
4. Preview identity: preview_revision must equal the selected review revision, not merely the latest draft.
5. Publish bounded: publishing requires valid schema/accessibility state, appropriate review, contained/resolved conflicts, preview identity, and compatible migration state.

Preserve typed non-success states: UNKNOWN, UNVERIFIED, STALE, REVIEW_REQUIRED, CONFLICT, HOLD, and INSUFFICIENT_EVIDENCE.

Designing the editor: block semantics, accessible assistance, and conflict-safe autosave

Structured blocks. Meaning should not be hidden in font size or CSS classes. Heading, assessment, callout, and media blocks need explicit types and field semantics. Presentation renderers can evolve without changing canonical meaning.

Schema validation. Validate required fields and data types at the block/field boundary. Messages should point to the exact field and remain keyboard-operable; a generic “content invalid” modal is not enough.

Accessibility assistance. ATAG distinguishes accessibility of the authoring tool itself from the tool's support for producing accessible content. For CMS/LMS authoring this includes keyboard-operable authoring and useful guidance/checks for content such as media alternatives and structure. WCAG 2.2 supplies testable requirements for the resulting web content, but does not define MAKNOW's editor architecture.

Revision-aware autosave. Every autosave declares its base. If the canonical head advanced from R11 to R12 while an autosave still says base_revision_id=R11, do not overwrite R12; create a conflict/branch record and preserve both versions.

Review selection. The reviewer sees an explicit revision identity such as REVIEWING:R12, not “preview latest.”

Deterministic preview. Renderer inputs are the exact review revision, declared schema version, and deterministic asset bindings. A revision mismatch fails the gate even if the HTML looks acceptable.

Publish gate. Publishing is a chain of evidence: valid schema, valid required accessibility metadata, contained/resolved conflicts, approved review state, matched preview identity, and compatible migration state.

Worked baseline: two editors, one stale autosave, one media block without alt text

The baseline uses content LESSON-77 on schema v1. Author A starts from R11, fixes heading structure and an assessment block, and produces R12. Author B also started from R11, adds media block BLK-M9 without alternative text, and B's autosave arrives after R12 exists.

Correct behavior:

• base_revision_id=R11 while canonical head=R12 → conflict_state=CONFLICT_PRESERVED; B's work is not lost or overwritten into A's revision.
• The media branch lacks alt text → accessibility validation on that branch is FAIL; it cannot honestly claim validation_state=PASS.
• The reviewer selects R12; preview is rendered only from R12.
• Because an unresolved conflict branch remains, publish_state=HOLD and the bounded decision is REVIEW_REQUIRED.

MKN-027-T1 aligns schema, revision/base, conflict, validation/accessibility, review/preview, publish, and migration evidence. lab://MKN-027/MKN-027-LAB1 makes those checks replayable.

Failure modes that must fail closed

1. Overwrite a newer revision with a stale autosave → HOLD / STALE_BASE_OVERWRITE.
2. Remove required alt text while leaving validation_state=PASS → HOLD / ACCESSIBILITY_VALIDATION_CONTRADICTION.
3. Keep an invalid heading hierarchy while accessibility state says PASS → HOLD.
4. Build preview from a draft other than the selected review revision → HOLD / PREVIEW_REVISION_MISMATCH.
5. Omit schema version → INSUFFICIENT_EVIDENCE or HOLD; the parser must not guess.
6. Accept a new block type under schema v1 without a migration/compatibility declaration → HOLD.
7. Publish before review approval or with unresolved conflict → HOLD.
8. Silently rewrite a historical v1 revision during v2 migration → HOLD / HISTORICAL_REVISION_MUTATION.
9. Omit the audit event → the decision is not fully replayable.

Repair the smallest broken evidence dimension; never invent evidence.

Experienced bridge: canonical AST + evented revisions + a version-aware renderer

At scale, model structured content like a canonical AST/document graph: blocks own identity and semantics while presentation is a projection. A revision layer tracks base and conflict; a validation layer checks schema and accessibility; a renderer accepts an explicit revision plus schema version.

This separation lets the authoring UX improve without binding canonical meaning to a toolbar or HTML blob. Conflict handling can also become block-aware rather than string-only.

For collaborative editing you may evaluate optimistic concurrency, branch/merge, CRDT, or OT. The pattern name is not the proof. For each option, state how it proves identity, stale-base detection, conflict visibility, accessibility validation, and exact preview revision.

Alternatives and trade-offs

Rich-text HTML blob: easy initially, weaker semantics/migration and noisier diff/conflict. Structured block editor: stronger semantics and validation, but requires schema governance and migration discipline. Last-write-wins autosave: smooth-looking UX with hidden data-loss risk. Optimistic concurrency + explicit conflict: more friction, better provenance and recoverability. Preview latest draft: simple, but the reviewer can see something different from the publish target. Preview exact review revision: reproducible and auditable, requiring revision identity and deterministic rendering. Hard-block accessibility errors: stronger assurance, but error quality, false positives, and governed overrides matter. Warning-only: lower friction, greater risk that critical defects ship.

Do not hide the trade-off behind one aggregate score. Separate decisive evidence, advisory evidence, and escalation triggers.

Guided and independent practice

Guided: open baseline.json. Record schema/version, revision/base, validation/accessibility, conflict state, and review/preview identity for each relevant branch. Without looking at a supplied answer label, explain why the stale autosave cannot overwrite and why the branch with missing alt text cannot open publishing.

Repair: missing_alt_but_pass.json contains one contradiction. Identify the first invalid field/state and the minimal repair. Then run preview_wrong_revision.json and explain the difference between “a valid render” and “a render of the correct revision.”

Independent: schema v2 introduces interactive_code while old lessons remain on v1. Design a compatibility/migration path that preserves v1 history, keeps v1 rendering replayable, accepts the new block only under declared v2, and derives preview/publish using each revision's declared schema version.

Verification: what is actually proven?

Each run records a fixture identity, deterministic issues, bounded decision, and visible evidence references. The lab is synthetic: it proves the contract for these fixtures, not production-editor behavior or organizational conformance.

The baseline should be REVIEW_REQUIRED: the conflict is preserved, the media branch has an accessibility failure, preview is tied to the review revision, and publishing stays on HOLD. Stale overwrite, false accessibility PASS, preview mismatch, missing schema, an unknown v1 block, premature publish, and missing audit must all fail closed.

The visible rules and fixtures are the oracle. Hidden model reasoning is not.

Assessment and transfer: schema v2 without rewriting history

Transfer requirement: a new block type appears in schema v2 while historical lessons remain on schema v1.

A bounded design does the following:

• Historical v1 revisions remain immutable; their schema version does not change.
• The renderer chooses a v1 or v2 compatibility path from the revision's declared version.
• The new block is valid only under v2; inserting it into v1 without explicit migration is HOLD.
• Migration creates a new revision instead of rewriting the old one.
• Preview and publish render each revision under that revision's schema version.
• Audit evidence links the old revision, new revision, and migration event.

The healthy transfer fixture yields COMPATIBILITY_REVIEW_REQUIRED: compatibility and history preservation are correct, but v2 promotion still requires explicit review. A silent-rewrite fixture must yield HOLD.

References, claim boundaries, and freshness

1. W3C ATAG Overview includes CMS and LMS tools within authoring-tool scope and separates accessibility of the authoring tool from helping authors produce accessible content. The overview was updated 14 November 2025 and says ATAG 2.0 remains relevant even though the Recommendation was published in 2015.
2. WCAG 2.2 is a W3C Recommendation for web-content accessibility with testable criteria including text alternatives, information/relationships, and keyboard accessibility. The current Recommendation is dated 12 December 2024.
3. Schema taxonomy, revision state machine, conflict policy, validation severity, exact-preview rule, and migration policy in this lesson are MAKNOW DESIGN; ATAG/WCAG do not prescribe those local architecture choices.

Official sources were rechecked on 2026-09-13. Practice-evolving claims must be requalified by 2027-01-15 or earlier after a material guidance change. Accepted package bytes are never silently rewritten; canonical changes require a new version.

Closing question: which shortcut creates the most false confidence in your current editor—HTML blobs, last-write-wins, warning-only accessibility, or preview-latest—and which exact evidence field exposes it?