Cross-Site Linking Convention

This page documents the bi-directional linking convention between the Documentation site (Astro/Starlight) and the UX Prototype site (Storybook).

Site Relationship

Arda maintains two complementary documentation sites:

Site	Technology	Purpose	Deployment
Documentation	Astro + Starlight	Source of truth for product requirements, use case specifications, personas, and domain knowledge	arda-cards.github.io/documentation
UX Prototype	Storybook + React	Interactive prototypes demonstrating use cases with step-by-step stories	arda-cards.github.io/ux-prototype

The Documentation site is the canonical source for specification content. The UX Prototype site provides interactive demonstrations that reference back to the specifications.

Documentation to Storybook Links

The downstream-tracking Frontmatter Field

Documentation pages that have a corresponding Storybook prototype can declare a downstream-tracking field in their YAML frontmatter:

downstream-tracking:
  type: storybook
  path: "?path=/docs/use-cases-procurement-purchase-orders--docs"

When present, the site automatically renders a link to the prototype at the top of the page content. No manual component import is needed.

Field Structure

The field is an object with three properties:

• type (required): One of storybook, docs, or github-issue.
• path (required): The URL path appended to the base URL for that type.
• label (optional): Overrides the default link text.

Type Resolution

Type	Dev Base URL	Production Base URL	Default Label	Link Target
storybook	http://localhost:6006	https://arda-cards.github.io/ux-prototype	”View Interactive Prototype”	_blank
docs	relative (same site)	relative (same site)	“View Related Documentation”	_self
github-issue	https://github.com/	https://github.com/	”View GitHub Issue”	_blank

The Storybook base URL can be overridden with the PUBLIC_STORYBOOK_URL environment variable.

Deriving Storybook Paths

Storybook generates URL slugs from <Meta title="..." /> declarations. The convention is:

1. Take the Meta title (e.g., Use Cases/Procurement/Purchase Orders)
2. Lowercase everything
3. Replace / with -
4. Replace spaces with -
5. Append --docs

Result: ?path=/docs/use-cases-procurement-purchase-orders--docs

Storybook to Documentation Links

The docsUrl() Helper

The UX Prototype site uses a docsUrl() helper function to generate links back to the Documentation site:

import { docsUrl } from '../links';

// In MDX:
<a href={docsUrl('/product/use-cases/procurement/purchase-orders/')}
   target="_blank" rel="noopener">
  View full specification &#8594;
</a>

Environment-Aware Resolution

The helper resolves URLs based on the build environment:

Environment	Base URL
Development (import.meta.env.DEV)	http://localhost:4321
Production	https://arda-cards.github.io/documentation

Deriving Documentation Paths

Documentation paths follow the Starlight content collection structure. The convention maps from file paths:

1. Start from src/content/docs/
2. The file path becomes the URL path (e.g., product/use-cases/procurement/purchase-orders.md becomes /product/use-cases/procurement/purchase-orders/)
3. Always include the trailing slash

Local Development

To test cross-site links locally, run both dev servers:

# Terminal 1 — Documentation (port 4321)
cd documentation && npx astro dev

# Terminal 2 — UX Prototype (port 6006)
cd ux-prototype && npm run storybook

Documentation pages with downstream-tracking will link to localhost:6006. Storybook thin reference pages will link to localhost:4321.