---
id: portfolio.ds.related-projects
name: "Related Projects"
type: pattern
status: active
relations: [{"type":"composes","target":"portfolio.ds.related-projects-content"},{"type":"composes","target":"portfolio.ds.related-projects-footer"},{"type":"composes","target":"portfolio.ds.related-projects-header"},{"type":"related_to","target":"portfolio.ds.project-item"},{"type":"related_to","target":"portfolio.ds.project-landing-page"},{"type":"related_to","target":"portfolio.ds.related-reading"}]
sources: ["apps/portfolio-site/src/design-system/docs/related-projects.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts","packages/design-system/src/components/RelatedProjects.astro","packages/design-system/src/components/RelatedProjectsContent.astro","packages/design-system/src/components/RelatedProjectsFooter.astro","packages/design-system/src/components/RelatedProjectsHeader.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/related-projects.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/related-projects.astro"]
---
# Related Projects

## Purpose
Follow-up block for project detail pages.

`Related Projects` shows explicit neighboring projects as gallery cards after the main project body.

## Hook

Use when a visitor finishes a project and should continue to another concrete example.

## Contract
- Renders nothing when the item list is empty.
- Shows up to four related projects by default.
- Composes `Related Projects Header`, `Related Projects Content`, and `Related Projects Footer`.
- `Related Projects Header` owns the title area and Block spacing.
- `Related Projects Content` owns Block Compact spacing and `Project Item` small-state rendering.
- `Related Projects Footer` owns the follow-up action and Block-aligned horizontal spacing.
- Keeps the related-project layout outside `Project Landing Page`; the page composes this block instead of owning local related-card CSS.
- Accepts already-resolved project card data.
- Does not infer, rank, or generate related items.
- Temporarily renders without a gray background while the visual grouping is being reviewed.
- Is the final, optional discovery block after the canonical Project Brief; it must not interrupt the brief or duplicate project facts.

## Use
- A project detail page receives explicit related projects.
- A preview needs to exercise the related-project block independently.

## Do Not Use
- Rendering article or note recommendations; use `Related Reading` instead.
- There are no explicit related projects.
- The page needs a full project index.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `title` | string | Optional section heading. Defaults to `Related projects`. |
| `items` | array | Related project card data with at least `title` and `href`. |
| `limit` | number | Maximum number of items to render. Defaults to `4`; callers may pass the group size for index-page groups. |
| `showAction` | boolean | Whether the footer action is rendered. Defaults to `true`; index pages may set `false`. |
| `actionHref` | URL string | Optional target for the follow-up action. Defaults to `/projects/`. |
| `actionLabel` | string | Optional follow-up action label. Defaults to `View all projects`. |

## Accessibility
- The section has an accessible heading.
- Project cards should describe the target project.
- Empty state is intentionally quiet: no dead placeholder appears on project pages.

## Related Components And Patterns

- `Project Item`: renders each related project preview in small state.
- `Project Landing Page`: composes this block after Agent Ready Project Brief.
- `Related Reading`: same pattern for article recommendations.

## Code Paths

- `packages/design-system/src/components/RelatedProjects.astro`
- `packages/design-system/src/components/RelatedProjectsHeader.astro`
- `packages/design-system/src/components/RelatedProjectsContent.astro`
- `packages/design-system/src/components/RelatedProjectsFooter.astro`

## Verification

- Confirm every source path in frontmatter resolves to current implementation or documentation.
- Run `scripts/design-system-graph --check --no-write`.
- Verify actual usage and documented Preview against the enabled package profiles before completion.