# About Design System

## Essence

Orientation page for the Portfolio Design System.

`About Design System` explains what the Design System is, names the current human-facing snapshot version, and shows a compact changelog from the beginning of the Design System work.

## Hook

Use before editing tokens, components, blocks, media, or page templates.

## Internal Rules

- Keep this page at the top of the Design System navigation, above Tokens.
- Use existing Design System primitives for the page body.
- Keep changelog entries factual and grounded in `docs/portfolio-site-log.md`.
- Display changelog entries latest-first for scanning.
- Treat the version as a human-facing snapshot number, not as npm package metadata.
- Store changelog data outside the Astro page so the page only renders the documentation surface.
- Back each Design System version with an annotated git tag named `design-system/vX.Y.Z`.
- Include git evidence for each version: git tag, commit range, commit hash, commit date, and commit title.
- Version only material Design System stages: token contracts, component architecture, page/block structure, media systems, or rules that change how future UI work is done.
- Each version entry should name the stage, date/range, and 2-3 factual bullets covering what changed and why it matters structurally.
- When the owner asks to `push to git`, run the Design System version check automatically before pushing: if Design System scope changed, update the changelog and create the next `design-system/vX.Y.Z` tag; if not, push without a Design System version change.
- Do not require the owner to decide whether a change is `vX.Y.Z`; the agent should infer patch/minor/major from the changed Design System scope and explain the decision.
- Update the changelog when Design System structure changes materially.
- Do not replace component essence files with this page; this is an orientation layer.

## Current Snapshot

- Version: `0.11.0`.
- Package: `@portfolio/design-system`.
- Primary surface: `/design-system/`.

## Code Paths

- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/lib/designSystemChangelog.ts`
- `docs/portfolio-site-log.md`