# Documentation Directory

Canonical: https://socra.design/navigation/docs-directory

A compact product chooser with a search slot and contextual starting guides.

Use DocsDirectory for a documentation home. Supply canonical identities and real documentation destinations.

Status: ready. Shared source verified in the canonical catalog with three and six products, search-slot interaction, and native keyboard links; Workspace adoption verified at desktop and mobile widths in light and dark themes.

Library: @socra/ui-web-navigation

## Anatomy

- Page title
- Search slot
- Whole-entry product links
- Optional starting guides

## States

- **Rest:** Products remain readable and independently linked.
- **Hover:** A neutral surface identifies the target.
- **Focus:** A visible outline preserves native link keyboard behavior.
- **Pressed:** Native anchor activation opens the documentation destination.
- **Selected:** Product links do not retain a selected state on the directory.
- **Disabled:** Only available documentation destinations enter the catalog; product anchors are not disabled.
- **Loading:** The supplied search control owns its loading feedback; product links remain available.
- **Error:** The supplied search control owns search errors and empty results; product links remain available.

## Motion

No spatial motion is required.

## Usage

- Keep product descriptions concise. Readers choose a destination in the first viewport.

## Avoid

- Keep application launch links out of the product entries. Each product entry opens its documentation home.

## 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 { DocsDirectory } from '@socra/ui-web-navigation';
<DocsDirectory title="Documentation" search={<input aria-label="Search documentation" />} products={[{ title: 'Notes', description: 'Read the notes guides.', href: '/docs/notes' }]} />
```