Feature/maturity attribution

docs/design/specs/2026-06-04-maturity-label-design.md

@@ -0,0 +1,164 @@
+# Maturity Label Feature Design
+
+**Date:** 2026-06-04 (updated 2026-06-11)
+**Branch:** feature/maturity-attribution
+
+## Problem
+
+Scientists are reluctant to share early-stage ideas because they don't want to be held accountable if the idea turns out to be wrong. A maturity label gives authors a way to signal "this is as-is" — framing uncertainty positively rather than as a warning.
+
+## Decision Summary
+
+- 4 fixed levels with evidence-based labels: Speculative, Exploratory, Supported, Validated
+- Visual: ALLEN_BLUE opacity ramp pill badge with tooltip hint text (no emoji on rendered badge)
+- Two rendering contexts: pill badge in the idea list (after title), plain text with dotted underline in the idea detail metadata strip
+- Appears in both the idea list and the idea detail page (metadata strip)
+- Required in the CMS for new ideas; existing ideas default to Speculative via a schema resolver
+
+---
+
+## 1. Data Model
+
+### Frontmatter
+
+New optional string field on idea `.md` files. Existing files omit it; the resolver supplies the default.
+
+```yaml
+maturity: speculative  # speculative | exploratory | supported | validated
+```
+
+### GraphQL Schema (`gatsby/schema/base.gql`)
+
+Added to `IdeaPost` as a nullable `String`:
+
+```graphql
+type IdeaPost implements Node {
+  ...
+  maturity: String
+}
+```
+
+### Gatsby Resolver (`gatsby/resolvers/resolvers.js`)
+
+Returns `"speculative"` when the frontmatter field is absent:
+
+```js
+IdeaPost: {
+  maturity: {
+    resolve: (source) => source.maturity ?? "speculative"
+  }
+}
+```
+
+This ensures every idea always has a maturity value at query time without touching existing files.
+
+---
+
+## 2. CMS Configuration (`static/admin/config.yml`)
+
+New `select` widget in the `ideas` collection, placed after the `type` field:
+
+```yaml
+- label: "Maturity"
+  name: "maturity"
+  widget: "select"
+  required: true
+  default: "speculative"
+  options:
+    - { label: "🌱 Speculative — Untested, shared to invite discussion", value: "speculative" }
+    - { label: "🌿 Exploratory — Early investigation, findings are preliminary", value: "exploratory" }
+    - { label: "🌳 Supported — Backed by data or analysis, not yet exhaustive", value: "supported" }
+    - { label: "🍎 Validated — Well-evidenced and reproducible", value: "validated" }
+```
+
+The emoji in the CMS dropdown helps authors scan options visually. The rendered badge on the site uses the ALLEN_BLUE color scale only (no emoji).
+
+---
+
+## 3. `MaturityBadge` Component
+
+**Files:**
+- `src/components/MaturityBadge.tsx`
+- `src/style/maturity-badge.module.css`
+
+### Level config
+
+| Value         | Label       | Tooltip hint                                                                 |
+| ------------- | ----------- | ---------------------------------------------------------------------------- |
+| `speculative` | Speculative | Untested: shared to invite discussion and future investigation. Not a claim. |
+| `exploratory` | Exploratory | Early investigation — findings are preliminary                               |
+| `supported`   | Supported   | Backed by data or analysis, but not yet exhaustive. Needs further work.      |
+| `validated`   | Validated   | Well-evidenced and reproducible                                              |
+
+### Visual
+
+Four CSS classes (`.speculative`, `.exploratory`, `.supported`, `.validated`) on a shared pill shape. Colors use `--ALLEN_BLUE` with a `color-mix` opacity ramp — faint at Speculative, full blue at Validated:
+
+| Level       | Text opacity | Border opacity | Background opacity |
+|-------------|-------------|----------------|-------------------|
+| speculative | 45%         | 25%            | 8%                |
+| exploratory | 65%         | 40%            | 12%               |
+| supported   | 85%         | 60%            | 16%               |
+| validated   | 100%        | 80%            | 20%               |
+
+Tooltip uses Ant Design `<Popover>` component. Unknown values fall back to Speculative rendering.
+
+A `.inlineDotted` class provides the non-pill rendering: `text-decoration: underline dotted`, `cursor: help`, no border or background. Used with the `"inline"` variant (see Props).
+
+### Props
+
+```ts
+interface MaturityBadgeProps {
+  maturity: string;
+  className?: string;
+  variant?: "badge" | "inline";  // default: "badge"
+}
+```
+
+- **`"badge"`** (default): pill rendering using `.badge` + level class. Used in the idea list.
+- **`"inline"`**: plain text rendering using `.inlineDotted` + level class (color only, no pill). Used in the post detail metadata strip. The `Popover` wraps both variants.
+
+---
+
+## 4. Rendering Locations
+
+### List view (`src/components/IdeaRoll.tsx`)
+
+- `maturity` is already in the GraphQL query
+- Render `<MaturityBadge maturity={item.maturity} />` (default `"badge"` variant) inline after the title `<Link>`, as a sibling element
+- `FigureThumbnail` appears on the right side of each list row (88×56px pill shape). Rows without a figure have no reserved gap.
+- **Note:** `IdeaRoll.tsx` and `idea-roll.module.css` have unresolved merge conflicts (`UU` git status) from integrating the thumbnail branch. Resolution keeps both the thumbnail and the badge rendering.
+
+### Detail page (`src/templates/idea-post.tsx`)
+
+- `maturity` is already in the `IdeaPostByID` page query
+- `<MaturityBadge maturity={maturity} variant="inline" />` renders as colored text with a dotted underline in the `metaGroup` — no pill. The `Popover` hint remains active on hover.
+
+### Type update
+
+`IdeaPostNode` in `src/types/index.ts` is auto-derived from the GraphQL query via `Queries.IdeaPostByIDQuery`. No manual edit is needed — running `gatsby develop` after updating the query regenerates the Gatsby type and `maturity` flows through automatically. The inline `IdeaListItem` type in `IdeaRoll.tsx` similarly picks up the field once the query is updated.
+
+---
+
+## 5. Testing
+
+### `MaturityBadge` unit test
+
+- Each of the four level values renders the correct label and tooltip hint text
+- An unknown value falls back gracefully to Speculative rendering
+
+### Resolver unit test
+
+- Returns the field value when `maturity` is present in frontmatter
+- Returns `"speculative"` when `maturity` is absent
+
+No changes to existing tests are required — the new field is additive.
+
+---
+
+## Out of Scope
+
+- Allowing authors to update the maturity level of existing ideas in bulk (authors update individually via CMS)
+- Filtering or sorting ideas by maturity level on the index page
+- Any automated progression of maturity level
+- Thumbnail design changes (size, shape, shadow — kept as-is)

gatsby/resolvers/resolvers.js

@@ -90,6 +90,9 @@ const createIdeaPostResolver = (reporter) => ({
             };
         },
     },
+    maturity: {
+        resolve: (source) => source.maturity ?? "speculative",
+    },
 });
 
 module.exports = { createIdeaPostResolver };

gatsby/resolvers/test/resolvers.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { createIdeaPostResolver } from "../resolvers";
+
+const mockReporter = { error: () => {} };
+
+describe("createIdeaPostResolver - maturity", () => {
+    const resolver = createIdeaPostResolver(mockReporter);
+
+    it("returns the maturity value when present", () => {
+        expect(resolver.maturity.resolve({ maturity: "speculative" })).toBe(
+            "speculative",
+        );
+        expect(resolver.maturity.resolve({ maturity: "exploratory" })).toBe(
+            "exploratory",
+        );
+        expect(resolver.maturity.resolve({ maturity: "supported" })).toBe(
+            "supported",
+        );
+        expect(resolver.maturity.resolve({ maturity: "validated" })).toBe(
+            "validated",
+        );
+    });
+
+    it("returns 'speculative' when maturity is absent", () => {
+        expect(resolver.maturity.resolve({})).toBe("speculative");
+        expect(resolver.maturity.resolve({ maturity: null })).toBe(
+            "speculative",
+        );
+        expect(resolver.maturity.resolve({ maturity: undefined })).toBe(
+            "speculative",
+        );
+    });
+});

gatsby/schema/base.gql

@@ -57,6 +57,7 @@ type IdeaPost implements Node {
     description: String
     draft: Boolean
     introduction: String
+    maturity: String
     nextSteps: String
     preliminaryFindings: PreliminaryFindings
     primaryContact: Allenite

src/components/IdeaRoll.tsx

@@ -3,6 +3,7 @@ import React from "react";
 import { Link, graphql, useStaticQuery } from "gatsby";
 
 import FigureThumbnail from "./FigureThumbnail";
+import { MaturityBadge } from "./MaturityBadge";
 import { TagPopover } from "./TagPopover";
 
 const {
@@ -15,6 +16,7 @@ const {
     textBlock,
     thumbnail,
     title,
+    titleRow,
 } = require("../style/idea-roll.module.css");
 
 type IdeaNode = Queries.IdeaRollQuery["allIdeaPost"]["nodes"][number];
@@ -38,6 +40,7 @@ const IdeaRoll = ({ count }: IdeaRollProps) => {
                     slug
                     title
                     tags
+                    maturity
                     authors {
                         name
                     }
@@ -104,9 +107,16 @@ const IdeaRoll = ({ count }: IdeaRollProps) => {
                                         ))}
                                     </div>
                                 )}
-                                <Link to={item.slug} className={title}>
-                                    {item.title}
-                                </Link>
+                                <div className={titleRow}>
+                                    <Link to={item.slug} className={title}>
+                                        {item.title}
+                                    </Link>
+                                    {item.maturity && (
+                                        <MaturityBadge
+                                            maturity={item.maturity}
+                                        />
+                                    )}
+                                </div>
                                 <div className={byline}>
                                     by{" "}
                                     {item.authors

src/components/MaturityBadge.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+
+import { Popover } from "antd";
+
+import { getMaturityConfig } from "../constants/maturityLevels";
+import * as styles from "../style/maturity-badge.module.css";
+import * as popoverStyles from "../style/tag-popover.module.css";
+
+interface MaturityBadgeProps {
+    maturity: string;
+    className?: string;
+    variant?: "badge" | "inline";
+}
+
+export const MaturityBadge: React.FC<MaturityBadgeProps> = ({
+    className,
+    maturity,
+    variant = "badge",
+}) => {
+    const config = getMaturityConfig(maturity);
+    const levelClass = styles[maturity] ?? styles.speculative;
+    const baseClass = variant === "inline" ? styles.inlineDotted : styles.badge;
+    return (
+        <Popover title={config.hint} className={popoverStyles.popoverContent}>
+            <span
+                className={[baseClass, levelClass, className]
+                    .filter(Boolean)
+                    .join(" ")}
+            >
+                {config.label}
+            </span>
+        </Popover>
+    );
+};

src/constants/maturityLevels.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { getMaturityConfig } from "./maturityLevels";
+
+describe("getMaturityConfig", () => {
+    it("returns the correct label for each level", () => {
+        expect(getMaturityConfig("speculative").label).toBe("Speculative");
+        expect(getMaturityConfig("exploratory").label).toBe("Exploratory");
+        expect(getMaturityConfig("supported").label).toBe("Supported");
+        expect(getMaturityConfig("validated").label).toBe("Validated");
+    });
+
+    it("returns the correct hint for each level", () => {
+        expect(getMaturityConfig("speculative").hint).toBe(
+            "Untested: shared to invite discussion and future investigation. Not a claim.",
+        );
+        expect(getMaturityConfig("exploratory").hint).toBe(
+            "Early investigation — findings are preliminary",
+        );
+        expect(getMaturityConfig("supported").hint).toBe(
+            "Backed by data or analysis, but not yet exhaustive. Needs further work.",
+        );
+        expect(getMaturityConfig("validated").hint).toBe(
+            "Well-evidenced and reproducible",
+        );
+    });
+
+    it("falls back to Speculative for unknown values", () => {
+        expect(getMaturityConfig("unknown").label).toBe("Speculative");
+        expect(getMaturityConfig("").label).toBe("Speculative");
+    });
+});

src/constants/maturityLevels.ts

@@ -0,0 +1,27 @@
+interface MaturityConfig {
+    label: string;
+    hint: string;
+}
+
+export const MATURITY_CONFIG: Record<string, MaturityConfig> = {
+    speculative: {
+        label: "Speculative",
+        hint: "Untested: shared to invite discussion and future investigation. Not a claim.",
+    },
+    exploratory: {
+        label: "Exploratory",
+        hint: "Early investigation — findings are preliminary",
+    },
+    supported: {
+        label: "Supported",
+        hint: "Backed by data or analysis, but not yet exhaustive. Needs further work.",
+    },
+    validated: {
+        label: "Validated",
+        hint: "Well-evidenced and reproducible",
+    },
+};
+
+export function getMaturityConfig(maturity: string): MaturityConfig {
+    return MATURITY_CONFIG[maturity] ?? MATURITY_CONFIG.speculative;
+}

src/pages/ideas/2025-10-29-relate-cell-cell-junction-remodeling-to-migration-onset.md

@@ -1,14 +1,15 @@
 ---
 templateKey: idea-post
 title: Relate cell-cell junction remodeling to migration onset
-resources:
-  - released-emt-dataset
-program:
-  - EMT
-date: 2025-10-28T19:10:00.000Z
 type: analysis of existing data
+maturity: exploratory
+date: 2025-10-28T19:10:00.000Z
 authors:
   - Gokhan Dalgin
+program:
+  - EMT
+resources:
+  - released-emt-dataset
 tags:
   - EMT
   - migration

src/pages/ideas/2026-02-06-compare-actin-filament-compression-between-different-fiber-scale-simulators.md

@@ -2,6 +2,7 @@
 templateKey: idea-post
 title: Compare actin filament compression between different fiber-scale simulators
 type: micropublication
+maturity: validated
 date: 2026-02-06T11:42:00.000Z
 authors:
   - Jessica Yu

src/pages/ideas/2026-02-06-simulations-of-actin-compression-at-monomer-and-fiber-scale.md

@@ -2,6 +2,7 @@
 templateKey: idea-post
 title: Simulations of actin compression at monomer- and fiber-scale
 type: micropublication
+maturity: supported
 date: 2026-02-06T11:28:00.000Z
 authors:
   - Jessica Yu