5. Documentation structure

Local snapshot only. The workspace page is authoritative.

5.1 One governed Markdown source

Human and machine documentation are one governed documentation set. PDS does not maintain a separate machine-documentation.
The authoritative documentation source is Markdown. Coding agents consume the same governed meaning, rules, constraints, and component guidance available to people. Human-facing presentations may appear in Figma, Storybook, or a documentation site, but documentation content shown there must be pulled from or linked to the same Markdown rather than independently rewritten.
Authority by artifact remains explicit:

• Markdown is authoritative for governed component guidance and operating context.
• Figma is authoritative for approved design assets, anatomy, states, and variants.
• The code repository is authoritative for implementation, tests, public API, dependencies, and release history.
• Storybook renders implementation examples and supports configuration/testing; it is not a separate documentation source.
  Structured status, owner, version, artifact links, API facts, and evidence fields are stored once and used to generate repeated page fields and machine-readable output. Judgment-heavy usage, content, and accessibility guidance remains reviewed Markdown within the same documentation source.
  PROPOSED schema. The governing document establishes that structured fields exist, without specifying the fields or their format. A workable starting schema:

---
component: pds-alert
layer: core            # core | extended
maturity: beta          # alpha | beta | stable
support_level: pds-owned-implementation
owner: <name or team>
version: 1.2.0
status_updated: 2026-08-14
design_source: <figma link>
repo: <repository link>
storybook: <storybook link>
consumers: [team-a, team-b, team-c]
accessibility:
  wcag_target: "2.0 AA"
  automated: pass
  manual: partial        # missing scope disclosed in prose below
localization:
  fr_ca_applicable: true
  status: pass
known_gaps:
  - "manual screen-reader pass not yet performed"
review_date: 2026-11-14
---

5.2 Documentation authority

The Design Ops Lead owns the governed documentation service, final editorial governance, and overall experience-quality accountability.
The Design Ops Product Designer owns the design-quality gate for usage, behavior, content, Figma parity, anatomy, variants, and design evidence.
The PDP engineering lead owns the technical gate for installation instructions, API and dependency information, code examples, browser or platform support, version impact, release notes, and migration guidance.
Borrowed QA/SDET owns only the accessibility or regression evidence it performs. Product teams supply product-use evidence and corrections relating to their implementation.
Documentation does not publish or advance maturity until every required domain section has its go.

5.3 Alpha documentation

An Alpha page must include:

• purpose and owner;
• Alpha or assessment-incomplete warning;
• intended and excluded use;
• current Figma, code, or Storybook artifact;
• preliminary anatomy or API;
• known gaps and defects;
• accessibility and localization evidence completed to date;
• support level and feedback route.
  Links to working evidence are acceptable. Status, ownership, limitations, and evidence gaps are mandatory.

5.4 Beta documentation

Beta documentation includes all Alpha content plus:

• tested usage guidance;
• API, dependencies, and installation details;
• accessibility and keyboard behavior;
• applicable localization behavior;
• representative examples;
• known defects and migration risk;
• pilot or consumer evidence;
• support route;
• evidence still required for Stable.
  An FY27 Beta page may disclose missing manual QA. It must not imply Stable assurance.

5.5 Stable component template

Every Stable component page uses this order:

1. Status, version, ownership, and support
2. Overview and purpose
3. When to use and when not to use
4. Anatomy
5. Variants and options
6. States
7. Behavior and interaction
8. Content and applicable localization
9. Accessibility and keyboard behavior
10. Design source
11. Code, API, installation, and dependencies
12. Examples and consumer responsibilities
13. Test and readiness evidence
14. Release history
15. Migration, deprecation, or replacement guidance
16. Known limitations
17. Feedback and contribution route
    This template uses the already selected structures from Spectrum, Carbon, and Pajamas. (Spectrum, Carbon, Pajamas)

5.6 Extended documentation

Every registered Extended component records:

• purpose;
• owning team and contact;
• Figma, repository, Storybook, or production link;
• known consumers;
• Core dependencies;
• ownership and support warning;
• known gaps;
• available accessibility and localization evidence;
• last review date.
  Extended documentation provides visibility and possible upstream evidence. It does not imply PDS review, support, or maintenance.

5.7 Contributor and maintainer documentation

The governed repository must make the contribution path usable without private oral context. It must provide or link to:

• a README stating PDS’s purpose, status, supported scope, and authoritative sources;
• a contribution guide covering intake, Ready-for-contribution eligibility, assignment, local setup, branches, pull requests, required evidence, review, merge, and release boundaries;
• repository conduct and the company participation expectations;
• a security-reporting route that does not require public disclosure of sensitive defects;
• code-ownership and maintainer/delegate records;
• issue and pull-request templates linked to the PDS backlog and domain-gate checklist;
• architecture, package, API, dependency, token, and compatibility conventions;
• commands for build, lint, unit, accessibility, Storybook, documentation, and other available validation;
• the definition of done for Alpha, Beta, Stable, documentation-only, token, and defect work;
• maintainer contacts and the route for a blocked or stale contribution.
  These documents are governed Markdown and follow the authority boundaries in section 5.2. The PDS Lead Maintainer owns technical accuracy; the Design Ops Lead owns contribution-policy governance; each affected domain owner approves guidance within its domain.

5.8 Drift control and FY27 documentation scope

Every component has one component-health record containing status, owners, source links, version, consumers, and pass/gap states for design, code, documentation, accessibility, localization, installation, and adoption evidence. A change that alters those facts updates the health record and governed Markdown in the same pull request or linked Jira workflow.
FY27 documentation is complete when:

• every assessed component has a lifecycle state, owner, source links, implementation/install location, evidence gaps, accessibility/localization status, and next action;
• every Beta or Stable component has the applicable complete maturity page;
• the selected machine-readable documentation/coding-agent pilot is generated from the governed Markdown source and validated;
• remaining gaps are carried into the prioritized FY28 record.
  Open — pending Core team: English/French documentation boundary. Decide the exact boundary between English PDS guidance, French built-in component strings, localized examples, translation ownership, update triggers, fallback behavior, and parity validation. FY27’s ticket keeps general PDS documentation in English but requires localization-ready code and French translations for built-in strings; this document does not extend or narrow that scope without the Core-team decision.