SpeyDocs Component Spec Sheet v3.2

SpeyDocs Component Spec Sheet

Complete visual contract for the SpeyDocs documentation frontend, covering all four page kinds defined in TMADD-SD-2.0 §2.2: preamble, resource landing, object, and endpoint.

What’s Included

• Four page kind specifications — each with URL pattern, IR source annotations, middle/right column content mapping, mini wireframe preview, and column annotations. The resource landing page — entirely missing from the prior spec — is now fully specified.
• IR data access patterns — boxed code blocks showing exactly which IR path to read from per page kind. The object page explicitly documents ir.tags[].extensions['x-speydocs-object'], correcting the prior bug where schema data was read from endpoints.
• Light and dark theme previews — endpoint page shown in both themes, validating token contrast ratios visually. Code panel background switches with theme; code blocks inside are always dark.
• Preamble content authoring spec — frontmatter schema (title, slug, order, hasCodeExamples) for hand-written markdown files in src/content/preamble/.
• Mobile sidebar behaviour — collapsed by default behind a hamburger button, slide-in overlay, backdrop, close triggers, body scroll lock, and no-JS fallback.
• Top navbar contents — logo/wordmark, nav links, separator, and theme toggle with HTML elements and ARIA attributes.
• GET vs POST display rules — query parameters and request body fields use the same .sd-param component; the difference is the H3 section title and curl format.
• SchemaView breadcrumb format — separator (→), array indicator ([]), terminal type name, and construction algorithm.

Rendering Contract Amendments (TMADD-SD-2.0 §9.3, §9.4)

• ExampleNF block count invariant — endpoint pages must have exactly 2 code blocks (request + response), object pages exactly 1, resource landing pages exactly 1.
• RC-E1 (Example Totality) — every endpoint must have both curl and response examples. Checked in CI Pass A.
• RC-S1 (Schema Field Bijection) — rendered fields on object pages must exactly equal schema fields. Checked in CI Pass B.
• closure.json — two new flags: exampleTotality and schemaFieldBijection.

Bug Fixes

• Corrected heading hierarchy — H2 is reserved, H3 for all section titles per TMADD-SD-2.0 §9.
• Added missing --sd-sidebar-category token to the design token reference.
• Added max-width: 720px to resource landing content area, matching endpoint pages.
• Corrected code panel theming — --sd-code-bg switches with theme, only --sd-codeblock-bg is fixed dark.