|
1 | | -# Featured content: design and requirements |
| 1 | +# Featured content |
2 | 2 |
|
3 | | -This document thinks through how to present Flexion's featured projects — Forms, Messaging (Notify), Document Extractor, and Forms Lab — within the existing site structure. |
| 3 | +The home page showcases three Flexion Solutions offerings as "featured labs". Each lab is one markdown file in `content/featured/`, with curated content independent of the repo catalog. |
4 | 4 |
|
5 | | -## Goals |
| 5 | +## Content type |
6 | 6 |
|
7 | | -1. **Signal intentionality.** Visitors should immediately understand that these four repos represent Flexion's deliberate, invested product work — not just code that happens to be public. |
8 | | -2. **Stay part of the collection.** Featured projects are *members* of the broader catalog, not a separate silo. They should feel like the "front shelf" of the same library. |
9 | | -3. **Invite exploration.** A visitor drawn in by a featured project should naturally discover the rest of the work index, and vice versa. |
10 | | -4. **Scale gracefully.** The design should work today with 4 featured projects and still work with 6–8 later, without requiring a layout overhaul. |
11 | | - |
12 | | -## Current state |
13 | | - |
14 | | -- The home page has a "Featured labs" section with a 3-column grid, but no repos are marked `featured: true` in `overrides.yml` yet — so it renders empty. |
15 | | -- The work index already sorts featured repos first. |
16 | | -- `document-extractor` exists in `repos.json`. The others are in various stages of going public: |
17 | | - - `forms-lab` — now public (will appear in next refresh) |
18 | | - - `forms` — public access requested, pending |
19 | | - - `flexion-notify` — will be made public soon |
20 | | -- Rich content overlays exist for `forms`, `messaging`, and `document-extractor` in `content/work/`. |
21 | | -- **Naming mismatch:** The Notify repo is `flexion-notify` on GitHub, but the overlay is `content/work/messaging.md`. It needs to be renamed to `content/work/flexion-notify.md` for the merge logic to attach it. |
22 | | - |
23 | | -## Data model gap |
24 | | - |
25 | | -The merge logic (`src/catalog/merge.ts`) only produces entries for repos present in `repos.json`. Overlay content for repos not yet in the snapshot is orphaned until they appear. |
26 | | - |
27 | | -### Resolution: Approach A (wait for public repos) |
28 | | - |
29 | | -All four repos are going public: |
30 | | - |
31 | | -| Repo | Status | Action needed | |
32 | | -|------|--------|---------------| |
33 | | -| `document-extractor` | Already in snapshot | None | |
34 | | -| `forms-lab` | Now public | Next daily refresh (or manual dispatch) picks it up | |
35 | | -| `forms` | Public access requested | Wait for approval, then refresh picks it up | |
36 | | -| `flexion-notify` | Will be made public soon | Wait, then refresh picks it up | |
37 | | - |
38 | | -No code changes needed for the data pipeline. Once a repo is public, the 09:00 UTC refresh workflow adds it to `repos.json` automatically. |
39 | | - |
40 | | -### Content file rename needed |
41 | | - |
42 | | -The overlay at `content/work/messaging.md` must be renamed to `content/work/flexion-notify.md` to match the actual GitHub repo name. The merge logic joins on filename slug → repo name. |
43 | | - |
44 | | ---- |
45 | | - |
46 | | -## Layout and presentation |
47 | | - |
48 | | -### Home page: featured section |
49 | | - |
50 | | -The current `home-featured__grid` (3-column at 48rem+) is appropriate for 3–4 cards. But the standard `RepoCard` — name, one-line summary, tier/category badges — is designed for browsing, not for *selling* a product. Featured projects deserve more presence. |
51 | | - |
52 | | -#### Option 1: Enhanced card (recommended) |
53 | | - |
54 | | -Keep the grid layout but introduce a `FeaturedCard` variant that provides: |
55 | | - |
56 | | -- **Title** (from overlay, e.g. "Forms" not "forms") |
57 | | -- **Tagline/summary** (the overlay's `summary` field, already written to be compelling) |
58 | | -- **2–3 bullet "value props"** — a new optional field in the overlay front-matter, e.g. `highlights: [...]` |
59 | | -- **CTA link** to the detail page |
60 | | - |
61 | | -Why: The featured section lives on the home page, which is a marketing surface. The current RepoCard is neutral/informational; a featured card should persuade. |
62 | | - |
63 | | -#### Option 2: Hero spotlight + carousel |
64 | | - |
65 | | -One project dominates above the fold; others are secondary. More dramatic, but: |
66 | | -- Introduces ordering politics (which one is "first"?) |
67 | | -- Doesn't scale to 6+ without pagination |
68 | | -- Adds JS complexity for carousel behavior |
69 | | - |
70 | | -#### Option 3: Keep current RepoCard, just mark them featured |
71 | | - |
72 | | -Simplest change (just set `featured: true`), but doesn't visually distinguish featured work from the catalog list below. Misses the goal of signaling intentionality. |
73 | | - |
74 | | -**Recommendation:** Option 1 — an enhanced card in the existing grid. It's the minimum change that achieves the "front shelf" feeling without adding interaction complexity. |
75 | | - |
76 | | -### Work index: integration between featured and full catalog |
77 | | - |
78 | | -The work index currently sorts featured repos to the top, which is good. But there's no visual break between them and the rest. Options: |
79 | | - |
80 | | -#### A. Visual separator with section heading (recommended) |
81 | | - |
82 | | -Add a lightweight heading ("Featured" or "Highlighted work") above the featured cluster, with a subtle divider before the rest. Featured repos still live *in* the list (same filter/sort controls apply), but they're visually grouped. |
83 | | - |
84 | | -- Preserves "part of the same collection" feeling |
85 | | -- Featured repos still respond to tier/category filters (if a user filters to "Tool" and a featured repo is a Tool, it stays; if not, it correctly disappears) |
86 | | -- Low implementation cost |
87 | | - |
88 | | -#### B. Separate "pinned" section outside the filter |
89 | | - |
90 | | -Featured repos get a fixed section above the filterable list, unaffected by filters. |
91 | | - |
92 | | -- Guarantees visibility regardless of filter state |
93 | | -- But breaks the "same collection" mental model — they become a separate thing |
94 | | - |
95 | | -#### C. Visual emphasis only (border/background) |
96 | | - |
97 | | -Featured repos get a subtle highlight (accent border, background tint) but stay in normal sort flow with no heading. |
98 | | - |
99 | | -- Lightest touch |
100 | | -- May be too subtle; visitors won't understand *why* some cards look different |
101 | | - |
102 | | -**Recommendation:** Option A — section heading within the list. Featured repos are still part of the filterable collection, but the heading signals "start here." If filtered out by tier/category, the heading hides too, which is correct behavior. |
103 | | - |
104 | | -### Detail pages: connecting back |
105 | | - |
106 | | -Each featured repo already gets a full detail page from the existing `WorkDetail` template. No structural change needed there. But consider: |
107 | | - |
108 | | -- **Cross-linking between related projects.** Forms and Forms Lab should cross-link on their detail pages via a "Related projects" section. Driven by a `related: [forms-lab]` field in overlay front-matter. This is low-cost and makes the relationship explicit without conflating the two. |
109 | | -- **"Back to featured" breadcrumb vs. "Back to all work."** Since featured repos are *part of* the catalog, the breadcrumb should go to `/work/` (the full index), not to a separate featured page. This reinforces the "same collection" principle. |
| 7 | +Files in `content/featured/*.md` use front-matter only. The body is ignored. |
110 | 8 |
|
| 9 | +````markdown |
| 10 | +```yaml |
111 | 11 | --- |
112 | | - |
113 | | -## Content requirements per featured project |
114 | | - |
115 | | -Each featured overlay should communicate: |
116 | | - |
117 | | -| Field | Purpose | Example | |
118 | | -|-------|---------|---------| |
119 | | -| `title` | Human-friendly name | "Forms" | |
120 | | -| `summary` | One-sentence value prop (used on cards) | "Accessible, USWDS-aligned form experiences..." | |
121 | | -| `highlights` (new) | 2–3 bullet differentiators for the featured card | ["WCAG 2.1 AA conformant", "Multi-step with save-and-resume", "Agency-agnostic"] | |
122 | | -| Body `## What it solves` | Problem framing | (already written for 3 of 4) | |
123 | | -| Body `## Who it's for` | Audience | (already written for 3 of 4) | |
124 | | -| Body `## Status` | Maturity signal | (already written for 3 of 4) | |
125 | | -| Body `## Get started` | Entry point for developers | (already written for 3 of 4) | |
126 | | - |
127 | | -**Forms Lab** still needs its overlay (`content/work/forms-lab.md`). |
128 | | - |
| 12 | +title: Forms Lab |
| 13 | +tagline: Digitize forms to create modern, accessible experiences for public outreach. |
| 14 | +order: 1 |
| 15 | +links: |
| 16 | + - label: Demo (Forms Platform) |
| 17 | + url: https://pp4cc7kwbf.us-east-1.awsapprunner.com/ |
| 18 | + - label: GitHub repository — Forms Platform |
| 19 | + url: https://github.com/flexion/forms |
129 | 20 | --- |
| 21 | +``` |
| 22 | +```` |
130 | 23 |
|
131 | | -## Forms and Forms Lab: linked but separate |
132 | | - |
133 | | -Forms and Forms Lab are **separate featured items** — each gets its own card, detail page, and overlay. But they should be visibly linked so visitors understand the relationship. |
134 | | - |
135 | | -### How to surface the link |
136 | | - |
137 | | -| Mechanism | Where it appears | Effort | |
138 | | -|-----------|-----------------|--------| |
139 | | -| **`related` field in overlay front-matter** | Detail page — "Related projects" section at bottom | New field + render logic | |
140 | | -| **Explicit mention in body copy** | Detail page body (e.g. "See also [Forms Lab](/work/forms-lab/)") | Zero code, just content | |
141 | | -| **Shared "family" tag or badge** | Cards and detail pages | New taxonomy concept — probably overkill | |
142 | | -| **Adjacent placement in featured grid** | Home page | Just ordering, no code | |
143 | | - |
144 | | -**Recommendation:** Use the `related` front-matter field (planned for stretch anyway) to cross-link them on detail pages, and place them adjacent in the featured grid on the home page. The body copy can also reference the sibling naturally. This gives multiple touchpoints without introducing new taxonomy. |
| 24 | +### Fields |
145 | 25 |
|
146 | | ---- |
| 26 | +- `title` — card heading (string, required) |
| 27 | +- `tagline` — one-sentence summary (string, required) |
| 28 | +- `order` — display order ascending (integer, required) |
| 29 | +- `links` — list of `{ label, url }` pairs rendered as external links (array, required) |
147 | 30 |
|
148 | | -## Navigation and discovery flow |
| 31 | +## Loader |
149 | 32 |
|
150 | | -``` |
151 | | -Home page |
152 | | -├── Featured labs (4 enhanced cards) ──→ /work/{name}/ (detail) |
153 | | -├── "Explore our work" CTA ──────────→ /work/ (full index) |
154 | | -└── Stats section (public projects count, etc.) |
155 | | -
|
156 | | -Work index (/work/) |
157 | | -├── [Featured heading] |
158 | | -│ ├── Featured repo card ──────────→ /work/{name}/ |
159 | | -│ ├── Featured repo card ──────────→ /work/{name}/ |
160 | | -│ └── ... |
161 | | -├── [All work heading] |
162 | | -│ ├── Repo card ───────────────────→ /work/{name}/ |
163 | | -│ └── ... |
164 | | -└── Filter controls (tier, category) |
165 | | -
|
166 | | -Detail page (/work/{name}/) |
167 | | -├── Full content (overlay body) |
168 | | -├── Stewardship sidebar |
169 | | -├── "View on GitHub" link |
170 | | -└── Related projects (optional, future) |
171 | | -``` |
| 33 | +`src/build/featured.ts` exports `loadFeatured(rootDir)` which reads every `.md` file in `content/featured/`, parses front-matter, validates the schema, and returns labs sorted by `order`. |
172 | 34 |
|
173 | | -This means: |
174 | | -- Home → featured detail: 1 click |
175 | | -- Home → full catalog: 1 click |
176 | | -- Featured detail → full catalog: 1 click (breadcrumb / header nav) |
177 | | -- Full catalog → featured detail: 0 extra clicks (they're in the list) |
| 35 | +## Rendering |
178 | 36 |
|
179 | | -No dead ends. Featured content is always reachable from the catalog, and the catalog is always reachable from featured content. |
| 37 | +The home page renders one `<LabCard />` per lab. The card shows the title (not linked), the tagline, and a vertical list of external links. Cards stack on narrow viewports and flow into a grid on wider viewports via the existing `.home-featured__list` composition. |
180 | 38 |
|
181 | | ---- |
| 39 | +## Adding a featured lab |
182 | 40 |
|
183 | | -## Implementation sequence |
| 41 | +1. Add a new file at `content/featured/<slug>.md` with the required fields. |
| 42 | +2. Pick an `order` value that places the lab where you want it. |
| 43 | +3. `bun run build` and spot-check the home page. |
184 | 44 |
|
185 | | -1. **Rename:** `content/work/messaging.md` → `content/work/flexion-notify.md` (update title/summary to reflect repo name if needed). |
186 | | -2. **Content:** Write `content/work/forms-lab.md`. Add `highlights` field to all four overlays. Add `related` field to Forms and Forms Lab overlays. |
187 | | -3. **Overrides:** Mark all four repos as `featured: true`, `tier: active`, `category: product` in `overrides.yml`. |
188 | | -4. **Refresh:** Trigger manual catalog refresh (or wait for daily run) once repos are public, to populate `repos.json`. |
189 | | -5. **Component:** Build `FeaturedCard` component (or extend `RepoCard` with a `variant` prop). |
190 | | -6. **Home page:** Wire `FeaturedCard` into the existing `home-featured__grid`. Place Forms and Forms Lab adjacent. |
191 | | -7. **Work index:** Add section heading logic for featured cluster. |
192 | | -8. **Related projects:** Add `related` field support to overlay front-matter and render cross-links on detail pages (needed for Forms ↔ Forms Lab link). |
| 45 | +## Removing or reordering |
193 | 46 |
|
194 | | ---- |
| 47 | +Delete the file or adjust `order`. No other changes needed. |
195 | 48 |
|
196 | | -## Open questions |
| 49 | +## Related: the catalog directory |
197 | 50 |
|
198 | | -1. ~~Are the repos going to be public?~~ **Resolved** — yes, all going public. Approach A confirmed. |
199 | | -2. ~~Forms Lab's relationship to Forms?~~ **Resolved** — separate featured items, but linked visibly (cross-links on detail pages, adjacent in grid). |
200 | | -3. Should the featured section on the home page have its own heading/intro copy, or just the grid? |
201 | | -4. Do we want a cap on featured projects (e.g., max 6) to protect the home page layout? |
202 | | -5. For the `highlights` field — should these be auto-derived from the overlay body, or always hand-authored? |
| 51 | +The catalog directory (`/work/` index, per-repo detail pages, `/work/health/` stewardship page) is **temporarily disabled** on the public site. The code, tests, and daily catalog refresh workflow remain intact; only the routes are commented out in `src/build/routes.ts`. See the spec at `notes/specs/2026-05-01-homepage-pare-down-design.md` for the rationale and the plan for restoring the directory. |
0 commit comments