Author a guideline page
Author a new or existing MDS guideline-page draft from approved policy. This is an internal method used by authoring-kit-writer, not a standalone user workflow.
Write one policy-focused MDS guideline page. Follow the assigned source state and iteration in the writer brief. The writer workflow owns paths, iteration mechanics, preservation, and handoff. This skill owns the guideline-page content method.
Read:
- Guideline page template: structure, frontmatter, and anchors;
- Content elements: shared MDX content contracts;
- Content voice and tone: documentation register and final editing pass.
Source states
| Source state | Required authority | Authoring rule |
|---|---|---|
new | An approved policy brief or equivalent first-party source | Establish only the supplied policy. Stop when policy authority is missing or contradictory. |
existing | The current guideline and approved additions | Preserve established policy and inbound anchors unless the brief explicitly approves a change. |
External design-system research may illustrate a pattern. It cannot establish MDS policy by itself.
Procedure
Audit
Run this section on iteration 1 only.
- Read the existing guideline or the approved policy brief.
- For an existing page, inspect its approved images and find every inbound link and heading anchor.
- Read any supplied guideline extractions from component-page work.
- Map established policy to the guideline template.
- Identify contradictions, missing policy decisions, reusable assets, anchors to preserve, and content that belongs on a component page instead.
Pause when an unresolved policy question would make the guidance unreliable. Do not ask for guideline extractions when none were supplied; proceed with the available approved policy.
Draft
- Follow the guideline template.
- Organise policy around reader decisions, not the source page’s historical order.
- Lead each section with the rule, then explain why and where it applies.
- Preserve inbound anchors where possible. Record every unavoidable anchor change and its inbound links for promotion.
- Apply the shared content-element rules to every meaningful example.
Self-check
- Check every policy statement against the approved source.
- Check that policy is not duplicated across sections.
- Check that examples prove the stated rule.
- Check preserved anchors and record unavoidable changes.
- Apply the final content check in Content elements.
Writer notes
Return these through the writer workflow’s handoff when they apply:
- preserved and changed anchors, with inbound links affected by each change;
- supplied extractions absorbed or left unresolved;
- policy that belongs on a component page;
- proposed assets and supporting implementation;
- contradictory or missing policy decisions.