Relationships
#2499 Link each swamp-club panel to its manual page with a header DOCS link
Opened by skunk-ape · 9/24/2026
Problem
swamp-club's product surfaces never link to the manual. Nothing outside /manual links into /manual/, so someone looking at a collective's members, serve instances or notifications has no path from that panel to the page that explains it.
Proposed solution
Lab #1700 introduces components/HelpLink.tsx: a small, muted DOCS link in a panel's header row, on the right after any count and before any close control. It matches the header's text-hud-micro uppercase style, has a 24px target and a focus ring, and takes an ariaLabel naming the surface (for example "Collective tokens documentation"), since "Docs" alone does not say where it goes. The Access Tokens (/u/<username>) and Collective Tokens (collective settings) panels use it.
Roll the same component out with one placement rule everywhere, header right, so readers learn where help lives. Link to the most specific section (#anchor) that answers "how do I use this panel?".
Candidate surfaces and targets:
| Surface | Island / route | Manual target |
|---|---|---|
| Collective members, pending invites, invite form | CollectiveMembers, PendingInvites, InviteOperative (/o/<slug>/members) |
how-to/collaborate, reference/invite-commands |
| Serve instances | ServeInstanceList (/o/<slug>/serve) |
how-to/swamp-serve, reference/swamp-serve |
| Extension registry and extension detail (scorecard, trust) | ExtensionRegistry, extension pages |
reference/extensions, explanation/extension-scorecard, explanation/extension-trust |
| Lab issues | islands/lab/* |
how-to/file-issues-from-the-cli |
| Notifications | NotificationList |
reference/notifications |
| Collective SSO settings | collective settings | reference/okta-sso |
| Billing | BillingPanel (/o/<slug>/billing) |
none yet: there is no manual page for billing, so either write one or skip it |
Notes
- A panel whose collapsed header is itself a
<button>can only show the link once expanded, because a link cannot nest inside a button. The Access Tokens panel has this constraint. - When a header already shows a count, separate the two with an
aria-hidden·so "2 ACTIVE DOCS" does not read as one phrase. - Keep link text "Docs"; the accessible name carries the specifics.
- Out of scope: contextual inline help and tooltips. This is only the consistent doorway to the manual.
Open
No activity in this phase yet.
system commented 9/24/2026, 6:30:31 PM
Classified automatically when this issue was filed.
- Source: Swamp Club
If you feel this classification is incorrect, add a ripple to tell us so.
skunk-ape commented 9/24/2026, 6:59:51 PM
Correction and findings from a local trial. Nothing here ships yet.
#1700 no longer includes HelpLink. The body above says lab #1700 introduces components/HelpLink.tsx and puts DOCS links on the Access Tokens and Collective Tokens panels. That was taken out of #1700 before shipping: the idea needs refinement first. The component and placement rule described here are a proposal, not existing code.
What the trial showed. DOCS links were added temporarily to every panel on a non-personal collective's settings page (Dossier, Visibility, Operatives, Collective Tokens, Danger) and checked at 375px and 1280px.
- On desktop, the links form a quiet column at the right edge of the headers, the same weight as counts and badges. The repetition is noticeable when you scan but does not compete with titles or actions.
- The real "docs docs docs" problem was several panels linking to the same page. Dossier, Visibility and Danger have no page of their own, so all three pointed at the Collective API reference.
- Mobile crowding. At 375px, "COLLECTIVE TOKENS" plus "1 ACTIVE" plus DOCS wrapped the title and the count onto two lines each.
- A count next to DOCS ("1 DOCS", "2 ACTIVE DOCS") reads as one phrase without a separator.
Refinements to settle before building:
- One DOCS per distinct page. When several panels on a screen share a page, use one page-level link (for example, at the end of the collective tab row) instead of repeating it per panel.
- A narrow-width rule: keep the title and the link on one line, and drop secondary header items such as counts below
smrather than wrapping. - Only link where a specific page exists. Surfaces with no page (billing, dossier, visibility) either get one written or get no link.
- Collapsed panels whose header is itself a
<button>cannot contain a link. Decide whether DOCS appears only when expanded or moves out of the header.
Sign in to post a ripple.