Turn a pile of projects into a catalog a visitor can filter and scan. One card per project, each opening a detail page, grouped by the kind of project. The framing that makes it work: track is the primary axis — a visitor does not care what stack you used, they care whether this is a real product to try, a competition build, or a lab experiment. Sort by that first, everything else second.
Keep two leading ideas in your reasoning the whole way through:
- One card, one project. Every project is a single card. The card is the hook; the detail page is the proof.
- Interview before you build. Never assume the stack, the categories, or what already exists. Ask, then build.
Step 1 — Interview (before you write any code)
STOP. Do not design a schema or write a component until you have answers. Ask, adapting to what they've already said:
- What site is this going into? Framework (Next.js / React, Astro, SvelteKit, plain HTML) and where projects would live — a data file, a CMS, or a database? This decides how everything below is built.
- Is there already a projects page or project data? If yes, read it first and extend it — do not replace it. Match its existing field names and visual style.
- What kinds of projects do you have? A sensible default track split is product / hackathon / rnd, but confirm it. Some people want "client work", "writing", or "open source" instead. The tracks are the primary filter, so get them right — they are the user's call, not yours.
- Per project, how much do you have? A one-liner, a longer "what it is", a live URL, a repo, a demo video, a diagram or screenshot, slides? This decides which optional fields and media each card and page use.
- What is the one action per card? Open the app, watch a demo, read the repo, view slides. That is the card's call-to-action.
Reflect their answers back in a sentence or two, then proceed. If they only want to add one project to an existing showcase, skip schema design entirely — read their existing data shape and write that one entry to match it.
Step 2 — The data model
Read references/schema.md for the field-by-field model and the trackOf() derivation trick (so existing entries don't all need editing when you add the filter). The essentials: a flat list of items, each with a slug, name, one-line description, a richer whatItIs, a track (the primary filter), a status, a stack[], links[], and a single cta. Media fields are optional, per item.
Step 3 — Build it
Read references/patterns.md for the card-vs-detail split, the filter bar, the media block, and the writing rules. The shape:
- A gallery: the filter bar (track first, then any secondary filters like kind/tier/status) + a responsive card grid.
- A card: concise — name, status, the one-line description, a couple of tags, one CTA. Concise, not a confession — a card says what a thing is; it is not a lengthy essay.
- A detail page, one per slug: the richer
whatItIs, optional embedded video (with a poster image so it doesn't open black), an optional hero image / diagram, and the links rendered as buttons.
Match the site's existing design tokens and components. Do not invent a new visual language.
Step 4 — Verify
Build or typecheck. Then confirm three things actually work, don't just assert them: the track filter narrows the grid, a card opens its detail page, and any embedded media renders (the video plays, the image loads). Show the user.
Guardrails (confirm, don't assume)
- The tracks are the user's — surface a default, but let them decide the categories.
- Extend an existing showcase, never silently replace it.
- Keep card copy concise; the long form lives on the detail page.