🎛️

DOCS_SYSTEM (Visual + Export Standard)

🎛️

Documentation Visual System (canonical). This page defines the visual + structural standards for the entire spec pack (headings, callouts, diagrams, tables, placeholders) and the rules for mirroring/exporting to /docs and clean HTML.

đź”’

Source of Truth. This page is the authoritative “documentation design system”. When a page’s formatting conflicts with this system, update the page to match (unless a higher-authority spec forbids it).

Executive summary

This doc standardizes how every spec page is written so the pack is:

  • visually rich (Notion-native)
  • deterministic to export (Markdown → /docs and clean HTML)
  • easy for Cursor + Claude Code to consume
  • consistent across authors and roles

What this page controls

  • The required Spec Page Chrome (standard sections every page must have).
  • The callout palette and when to use each color.
  • Diagram centralization rules (Option 1): link to the canonical diagrams page.
  • Export conventions: anchors, filenames, placeholders, and lint checks.

Who should read this

  • Everyone who edits specs, especially Docs lead, Product architect, Developer-tooling lead.

Source of Truth status

  • Authority: Reference
  • Status: Approved
  • Primary sync targets: docs/DOCS_SYSTEM.md

Dependencies / related pages

1) Spec Page Chrome (required sections)

Every major spec page must contain these sections in this order (even if brief):

  1. Executive summary
  1. What this page controls
  1. Who should read this
  1. Source of Truth status
  1. Dependencies / related specs
  1. System diagrams (Mermaid) — link to canonical diagrams unless the diagram is truly page-local
  1. Contracts / interfaces (tables + code blocks)
  1. Implementation notes
  1. Validation checklist
  1. Risks / gotchas
  1. Done means
  1. Cursor / Claude Code instructions

2) Callout palette

  • Blue: summary / what this is
  • Red: locked / forbidden / supersedes
  • Purple: architecture / cross-cutting / canonical systems
  • Orange: implementation guidance / runbooks
  • Green: acceptance criteria / “ready” checks
  • Gray: reference / notes / glossary / backlog

3) Diagrams (Option 1: centralized)

  • Other pages should:
    • link to specific diagram headings (e.g. “See D-03 RAG indexing pipeline”)
    • avoid duplicating Mermaid blocks unless the diagram is specific to that page only
  • If a local diagram exists, it must be tagged at the top with: Local diagram (do not copy; consider moving to canonical set).

4) Image / screenshot placeholders (export-safe)

Use machine-detectable placeholders:

<!-- IMAGE:START id=IMG-<short> -->
**Screenshot:** <title>
**Purpose:** <why it exists>
**Source:** <where to capture it>
**Status:** placeholder
<!-- IMAGE:END -->

5) Clean HTML export conventions

  • Headings must be stable (no emoji prefixes in headings; emoji belongs in page icon).
  • Each heading must be unique within a page (exporters rely on anchor stability).
  • Code blocks must specify language when known.
  • Mermaid blocks must be lint-clean (exporter should fail or warn on invalid Mermaid).
  • Use tables for structured contracts.

6) Cursor / Claude Code instructions (required section)

Every page must end with:

  • Mirror path(s) under docs/
  • Owned files/globs (sync targets)
  • “When editing this spec” rules
  • “When implementing this spec” checks/commands

Validation checklist

  • Every major page contains the Spec Page Chrome sections.
  • Pages link to the canonical diagrams page instead of duplicating.
  • Placeholders use the standard IMAGE marker format.
  • Export rules are not violated (unique headings, language-tagged code).

Done means

  • The spec pack is consistent enough that a repo mirror + HTML export can be fully automated without manual cleanup per page.