# Documentation Reading Tools

Canonical: https://socra.design/navigation/docs-reading-tools

Documentation navigation, Markdown actions, related pages, and reader feedback.

Use the shared documentation article to keep orientation, navigation, and portable content consistent on every documentation page.

Status: partial. The specimen consumes the published documentation package. Feedback uses a local demonstration action; submission security belongs to the host service.

Library: @socra/web-docs

## Anatomy

- Breadcrumb before the title
- Documentation navigation button
- Copy for LLM and View as Markdown actions after the introduction
- Desktop outline or compact On this page menu beside the breadcrumb
- Related documentation after the article
- Reader feedback with a host-owned submission action

## States

- **Rest:** The breadcrumb identifies the document location. Both Markdown actions remain visible.
- **Hover:** Available navigation and page actions show the shared hover treatment.
- **Focus:** The navigation drawer and outline preserve keyboard access and return focus when dismissed.
- **Pressed:** Navigation opens the selected document. Copy sends the complete portable Markdown to the clipboard.
- **Selected:** The navigation marks the current document, and the desktop outline marks the current section.
- **Disabled:** The copy action prevents a duplicate request while the clipboard operation is pending.
- **Loading:** Copy feedback keeps the action geometry stable until the request completes.
- **Error:** A clipboard failure leaves the Markdown link available as a recovery path.

## Motion

Navigation and outline overlays use the shared dismissal and reduced-motion behavior. Opening a control does not move the article.

## Usage

- Use one document source. The rendered article, copied text, and Markdown destination must describe the same document.

## Avoid

- Keep navigation out of the copied document. Portable Markdown contains the document content and useful source links.

## Tokens

- `designTokens.color[mode].color.brand.primary`: Primary action role.
- `designTokens.color[mode].color.surface.secondary`: Working surface role.
- `designTokens.color[mode].color.content.primary`: Primary content role.
- `designTokens.spacing.role.contentGap`: Spacing relationship.
- `designTokens.shape.role.control`: Shape relationship.

## Example

```tsx
import { DocsArticle, DocsProvider, DocsSearchProvider, type DocPage, type DocsConfig } from '@socra/web-docs';
import '@socra/web-docs/styles.css';

// Render inside the host router and compatible shared theme providers.
// config supplies areas, pages, and groups from the documentation source.
export function Document({ config, page }: { config: DocsConfig; page: DocPage }) {
  return (
    <DocsProvider config={config}>
      <DocsSearchProvider area={page.area}>
        <DocsArticle page={page} />
      </DocsSearchProvider>
    </DocsProvider>
  );
}
```