Overview
These are the product requirements in plain language — what the site must do for its owner (the author) and its visitors.
How to read
Must = core value. Should = improves the experience. Can = nice to have.
For the Author (Publishing)
| ID | Requirement | Priority |
|---|---|---|
| FR-01 | Add a project by dropping a markdown file into projects/ — no code changes, no registry | Must |
| FR-02 | Frontmatter drives everything: slug, tags, links, image, visibility, sort order, featured flag | Must |
| FR-03 | Attach design docs to any project — local MDX or external Notion — via meta.yaml or frontmatter | Must |
| FR-04 | Invalid doc metadata fails the build with a precise error, never silently drops content | Must |
| FR-05 | Project images/screenshots live next to the markdown and are served automatically | Should |
| FR-06 | Add an external API documentation link via apiDocsUrl frontmatter (https:// only) — validated at build, no code change | Should |
| FR-07 | Git push triggers rebuild and deploy | Must |
For the Visitor (Reading)
| ID | Requirement | Priority |
|---|---|---|
| FR-08 | Scan projects fast: cards with banners, tags, demo/source links; featured section first | Must |
| FR-09 | Read deep dives: rendered MDX with diagrams, tables, callouts, and a table of contents | Must |
| FR-10 | Open external API docs when present — API Documentation button on project and design-docs index, opens in new tab with external-link indicator | Should |
| FR-11 | Navigate by keyboard and screen reader; visible focus everywhere | Must |
| FR-12 | Comfortable in light and dark mode, following system preference by default | Should |
| FR-13 | Find the site in search: per-page metadata, share images, structured data, sitemap | Can |
| FR-14 | Motion that delights without harm — everything respects reduced-motion settings | Should |
Behavior That Matters
- Content is code-reviewed — every change goes through git, so publishing has history, diffs, and rollback for free.
- Validation is loud — a broken
meta.yamlor duplicate doc id stops the build instead of shipping a broken page. - Docs are first-class — each project can carry as many documents as it deserves, mixed between local MDX and Notion.
- API docs are opt-in — a project declares
apiDocsUrland gets an externalAPI Documentationlink; projects without it show nothing — no empty state. - Diagrams render on demand — heavy libraries stay out of the critical path.
Out of Scope
To keep the site focused:
- No CMS UI, no database, no comments, no analytics beyond Vercel's built-ins.
- No blog/articles section yet (the header button is intentionally disabled).
- No client-side search — the project count doesn't warrant it.
Trade-off made visible
The filesystem-as-CMS trade is: lose editorial UI, gain version control, portability, and zero infrastructure.
Acceptance in One Glance
- Adding a new project takes one file and one push.
- A recruiter can go from home page → project → architecture deep dive in three clicks.
- Lighthouse-level basics hold: static HTML, responsive, keyboard-complete, dark-mode clean.
Why it matters
The portfolio's job is to prove engineering communication skills — the site itself should be the first piece of evidence.