jspsych · Mandyx22 · Jul 6, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 6, 2026
diff --git a/components/dashboard/MetadataControl.js b/components/dashboard/MetadataControl.js
@@ -3,6 +3,7 @@ import {
   HStack,
   Switch,
   Stack,
+  Badge,
 } from "@chakra-ui/react";
 
 import { useState } from "react";
@@ -19,7 +20,10 @@ export default function MetadataControl({ data }) {
     <Stack w="100%" gap={2}>
       <Field.Root>
         <HStack justify="space-between" alignItems="center" w="100%">
-          <Field.Label fontWeight={"normal"} mb={0}>Enable Psych-DS metadata production?</Field.Label>
+          <HStack gap={2} alignItems="center">
+            <Field.Label fontWeight={"normal"} mb={0}>Enable Psych-DS metadata production?</Field.Label>
+            <Badge colorPalette="green" variant="solid" px={2}>Recommended</Badge>
+          </HStack>
           <Switch.Root
             colorPalette="green"
             size="md"

diff --git a/pages/admin/[experiment_id].js b/pages/admin/[experiment_id].js
@@ -5,7 +5,8 @@ import { useDocumentData, useCollectionData } from "react-firebase-hooks/firesto
 import { db, auth } from "../../lib/firebase";
 import { doc, collection, query, where, orderBy } from "firebase/firestore";
 
-import { Spinner, Flex, VStack, HStack, Text, Badge, Separator } from "@chakra-ui/react";
+import { Spinner, Flex, VStack, HStack, Text, Badge, Separator, Popover, IconButton, Link } from "@chakra-ui/react";
+import { CircleHelp } from "lucide-react";
 
 import Title from "../../components/dashboard/Title";
 import ExperimentInfo from "../../components/dashboard/ExperimentInfo";
@@ -118,9 +119,37 @@ function ExperimentPageDashboard({ experiment_id }) {
               <ExperimentValidation data={data} />
 
               <Separator my={5} borderColor="whiteAlpha.200" />
-              <Text fontSize="xs" fontWeight="semibold" textTransform="uppercase" letterSpacing="wide" color="gray.500" mb={3}>
-                Metadata
-              </Text>
+              <HStack gap={1} mb={3} alignItems="center">
+                <Text fontSize="xs" fontWeight="semibold" textTransform="uppercase" letterSpacing="wide" color="gray.500">
+                  Metadata
+                </Text>
+                <Popover.Root>
+                  <Popover.Trigger asChild>
+                    <IconButton
+                      aria-label="What is metadata production?"
+                      variant="ghost"
+                      size="2xs"
+                      color="gray.500"
+                    >
+                      <CircleHelp size={14} />
+                    </IconButton>
+                  </Popover.Trigger>
+                  <Popover.Positioner>
+                    <Popover.Content maxW="xs">
+                      <Popover.Body>
+                        <Text fontSize="sm">
+                          Generates Psych-DS metadata describing your data&apos;s
+                          columns (descriptions, value ranges, and levels), making
+                          your dataset easier to share and reuse.{" "}
+                          <Link href="https://psychds-docs.readthedocs.io/en/latest/" target="_blank" rel="noopener noreferrer" color="blue.500">
+                            Learn more
+                          </Link>
+                        </Text>
+                      </Popover.Body>
+                    </Popover.Content>
+                  </Popover.Positioner>
+                </Popover.Root>
+              </HStack>
               <MetadataControl data={data} />
             </VStack>
 

diff --git a/pages/admin/index.js b/pages/admin/index.js
@@ -19,6 +19,7 @@ import {
   Card,
   CloseButton,
   Link as ChakraLink,
+  Tooltip,
 } from "@chakra-ui/react";
 import { Trash2, Pencil } from "lucide-react";
 
@@ -202,10 +203,10 @@ function ExperimentItem({ exp }) {
             </Text>
           </Link>
           <HStack gap={[2, 4]} flexWrap="wrap" rowGap={1}>
-            <StatusLabel label="Data" on={exp.active} />
-            <StatusLabel label="Base64" on={exp.activeBase64} />
-            <StatusLabel label="Conditions" on={exp.activeConditionAssignment} />
-            <StatusLabel label="Metadata" on={exp.metadataActive} />
+            <StatusLabel label="Data" on={exp.active} feature="Data collection" />
+            <StatusLabel label="Base64" on={exp.activeBase64} feature="Base64 data collection (for binary files like audio, video, and images)" />
+            <StatusLabel label="Conditions" on={exp.activeConditionAssignment} feature="Sequential condition assignment" />
+            <StatusLabel label="Metadata" on={exp.metadataActive} feature="Psych-DS metadata production" />
             {exp.sessions > 0 && (
               <Text fontSize="xs" color="gray.400">
                 {exp.sessions} {exp.sessions === 1 ? "session" : "sessions"}
@@ -219,19 +220,28 @@ function ExperimentItem({ exp }) {
   );
 }
 
-function StatusLabel({ label, on }) {
+function StatusLabel({ label, on, feature }) {
   return (
-    <HStack gap="5px">
-      <Box
-        w="6px"
-        h="6px"
-        borderRadius="full"
-        bg={on ? "green.400" : "gray.600"}
-      />
-      <Text fontSize="xs" color={on ? "gray.300" : "gray.600"}>
-        {label}
-      </Text>
-    </HStack>
+    <Tooltip.Root>
+      <Tooltip.Trigger asChild>
+        <HStack gap="5px">
+          <Box
+            w="6px"
+            h="6px"
+            borderRadius="full"
+            bg={on ? "green.400" : "gray.600"}
+          />
+          <Text fontSize="xs" color={on ? "gray.300" : "gray.600"}>
+            {label}
+          </Text>
+        </HStack>
+      </Tooltip.Trigger>
+      <Tooltip.Positioner>
+        <Tooltip.Content maxW="xs">
+          {feature} is {on ? "enabled" : "disabled"} for this experiment.
+        </Tooltip.Content>
+      </Tooltip.Positioner>
+    </Tooltip.Root>
   );
 }
 

diff --git a/pages/faq.js b/pages/faq.js
@@ -7,14 +7,32 @@ import {
   Box,
 } from "@chakra-ui/react";
 import NextLink from "next/link";
+import { useState, useEffect } from "react";
 
 export default function FAQ() {
+  const [openItems, setOpenItems] = useState(["item-0"]);
+
+  useEffect(() => {
+    const hash = window.location.hash.replace("#", "");
+    if (!hash) return;
+    setOpenItems((prev) => (prev.includes(hash) ? prev : [...prev, hash]));
+    // Wait for the accordion to expand, then bring the item's trigger into view.
+    // Chakra doesn't forward `id` to the DOM, so target the trigger via its
+    // data-controls attribute and offset for the fixed navbar.
+    setTimeout(() => {
+      const el = document.querySelector(`[data-controls$=":content:${hash}"]`);
+      if (!el) return;
+      const top = el.getBoundingClientRect().top + window.scrollY - 80;
+      window.scrollTo({ top, behavior: "smooth" });
+    }, 350);
+  }, []);
+
   return (
     <Stack maxW={800} w="100%" my={10}>
       <Heading as="h1" my={4}>
         FAQ
       </Heading>
-      <Accordion.Root defaultValue={["item-0"]} multiple collapsible>
+      <Accordion.Root value={openItems} onValueChange={(e) => setOpenItems(e.value)} multiple collapsible>
         <FAQItem value="item-0" question="How do I use DataPipe?">
           <Text>
             Follow our{" "}
@@ -238,15 +256,30 @@ export default function FAQ() {
           </Text>
         </FAQItem>
         <FAQItem value="item-11" question="How does metadata production work?">
+          <Text mb={2}>
+            When enabled, DataPipe generates a dataset_description.json file in
+            your OSF project that describes your dataset and its variables
+            according to the Psych-DS specification. The file is updated
+            automatically as new sessions are uploaded.
+          </Text>
+          <Text mb={2}>
+            For each variable, DataPipe records its data type and, when
+            available, a human-readable description from the relevant jsPsych
+            plugin documentation. It also combines information across sessions,
+            such as observed numeric ranges and categorical values.
+          </Text>
           <Text>
-            When enabled, DataPipe generates a metadata file describing your
-            data and its variables, following the{" "}
-            <Link href="https://github.com/psych-ds/psych-DS" target="_blank" rel="noopener noreferrer">
-              Psych-DS
+            Metadata production is recommended when you plan to share or publish
+            your data because it makes the dataset easier to understand and
+            reuse. You can enable it from your experiment dashboard. See the{" "}
+            <Link asChild textDecoration="underline">
+              <NextLink href="/getting-started">getting started guide</NextLink>
+            </Link>{" "}
+            for setup instructions, or visit the{" "}
+            <Link href="https://psychds-docs.readthedocs.io/en/latest/" target="_blank" rel="noopener noreferrer" textDecoration="underline">
+              Psych-DS documentation
             </Link>{" "}
-            specification. The file is stored in your OSF project as
-            dataset_description.json and is updated automatically after
-            each session.
+            to learn more.
           </Text>
         </FAQItem>
         <FAQItem value="item-12" question="What is one-click authentication?">

diff --git a/pages/getting-started.js b/pages/getting-started.js
@@ -211,10 +211,12 @@ export default function GettingStarted() {
           </FeatureItem>
           <FeatureItem name="Psych-DS metadata">
             — automatically produce metadata adhering to{" "}
-            <Link href="https://github.com/psych-ds/psych-DS" target="_blank" rel="noopener noreferrer" color="brandOrange.300">
+            <Link href="https://psychds-docs.readthedocs.io/en/latest/" target="_blank" rel="noopener noreferrer" color="brandOrange.300">
               Psych-DS
             </Link>
-            , updated after each session.
+            , updated after each session. See{" "}
+            <Link href="/faq#item-11" color="brandOrange.300">how it works</Link>
+            {" "}in the FAQ.
           </FeatureItem>
         </Stack>
         <Callout>