diff --git a/docs/develop/priority-fairness-walkthrough.mdx b/docs/develop/priority-fairness-walkthrough.mdx
new file mode 100644
index 0000000000..f51c37dcaf
--- /dev/null
+++ b/docs/develop/priority-fairness-walkthrough.mdx
@@ -0,0 +1,20 @@
+---
+id: priority-fairness-walkthrough
+title: Task Queue Priority and Fairness - Interactive Walkthrough
+sidebar_label: Priority and Fairness
+description: Interactively explore how Task Queue Priority and Fairness control dispatch order. Step through scenarios, see which task gets picked next and why, then grab the SDK code.
+toc_max_heading_level: 2
+keywords:
+  - task queue priority
+  - task queue fairness
+  - priority key
+  - fairness key
+  - interactive demo
+tags:
+  - Task Queues
+  - Priority and Fairness
+---
+
+import { PriorityFairnessWalkthrough } from '@site/src/components';
+
+<PriorityFairnessWalkthrough />
diff --git a/sidebars.js b/sidebars.js
index d5944d13fb..4ef019afaa 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -890,6 +890,15 @@ module.exports = {
       ],
     },
     'glossary',
+    {
+      type: 'category',
+      label: 'Interactive Demos',
+      collapsed: false,
+      items: [
+        'develop/activity-retry-simulator',
+        'develop/priority-fairness-walkthrough',
+      ],
+    },
     'with-ai',
     // {
     //   type: "autogenerated",
diff --git a/src/components/elements/PriorityFairnessSimulator.js b/src/components/elements/PriorityFairnessSimulator.js
new file mode 100644
index 0000000000..1f9019d955
--- /dev/null
+++ b/src/components/elements/PriorityFairnessSimulator.js
@@ -0,0 +1,702 @@
+import Chart from "chart.js/auto";
+import React, { useState, useEffect, useRef } from "react";
+import { useColorMode } from "@docusaurus/theme-common";
+import styles from "./priority-fairness-simulator.module.css";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const PRIORITY_META = {
+  1: { color: "#ef4444", textColor: "#fff", label: "Critical" },
+  2: { color: "#f97316", textColor: "#fff", label: "High" },
+  3: { color: "#3b82f6", textColor: "#fff", label: "Normal" },
+  4: { color: "#22c55e", textColor: "#000", label: "Low" },
+  5: { color: "#94a3b8", textColor: "#fff", label: "Batch" },
+};
+
+const FAIRNESS_PALETTE = [
+  "#6366f1", "#ec4899", "#14b8a6", "#f59e0b", "#8b5cf6", "#06b6d4",
+];
+
+const PRESETS = [
+  {
+    label: "Choose a scenario…",
+    queue: [],
+    fairnessKeys: [],
+  },
+  {
+    label: "Priority only — Payments vs Inventory",
+    queue: [
+      { priorityKey: 5, fairnessKey: "" },
+      { priorityKey: 5, fairnessKey: "" },
+      { priorityKey: 5, fairnessKey: "" },
+      { priorityKey: 3, fairnessKey: "" },
+      { priorityKey: 3, fairnessKey: "" },
+      { priorityKey: 1, fairnessKey: "" },
+      { priorityKey: 5, fairnessKey: "" },
+      { priorityKey: 1, fairnessKey: "" },
+      { priorityKey: 2, fairnessKey: "" },
+      { priorityKey: 3, fairnessKey: "" },
+    ],
+    fairnessKeys: [],
+  },
+  {
+    label: "Fairness only — Multi-tenant (equal weights)",
+    queue: [
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-big" },
+      { priorityKey: 3, fairnessKey: "tenant-mid" },
+      { priorityKey: 3, fairnessKey: "tenant-mid" },
+      { priorityKey: 3, fairnessKey: "tenant-small" },
+      { priorityKey: 3, fairnessKey: "tenant-small" },
+    ],
+    fairnessKeys: [
+      { key: "tenant-big", weight: 1 },
+      { key: "tenant-mid", weight: 1 },
+      { key: "tenant-small", weight: 1 },
+    ],
+  },
+  {
+    label: "Fairness only — Tiered weights (Premium 5×, Basic 3×, Free 1×)",
+    queue: [
+      { priorityKey: 3, fairnessKey: "premium" },
+      { priorityKey: 3, fairnessKey: "premium" },
+      { priorityKey: 3, fairnessKey: "premium" },
+      { priorityKey: 3, fairnessKey: "premium" },
+      { priorityKey: 3, fairnessKey: "basic" },
+      { priorityKey: 3, fairnessKey: "basic" },
+      { priorityKey: 3, fairnessKey: "basic" },
+      { priorityKey: 3, fairnessKey: "free" },
+      { priorityKey: 3, fairnessKey: "free" },
+      { priorityKey: 3, fairnessKey: "free" },
+    ],
+    fairnessKeys: [
+      { key: "premium", weight: 5 },
+      { key: "basic", weight: 3 },
+      { key: "free", weight: 1 },
+    ],
+  },
+  {
+    label: "Priority + Fairness — E-commerce platform",
+    queue: [
+      { priorityKey: 1, fairnessKey: "vendor-a" },
+      { priorityKey: 1, fairnessKey: "vendor-a" },
+      { priorityKey: 1, fairnessKey: "vendor-b" },
+      { priorityKey: 2, fairnessKey: "vendor-a" },
+      { priorityKey: 2, fairnessKey: "vendor-b" },
+      { priorityKey: 2, fairnessKey: "vendor-c" },
+      { priorityKey: 3, fairnessKey: "vendor-a" },
+      { priorityKey: 3, fairnessKey: "vendor-a" },
+      { priorityKey: 3, fairnessKey: "vendor-b" },
+      { priorityKey: 3, fairnessKey: "vendor-c" },
+      { priorityKey: 5, fairnessKey: "vendor-a" },
+      { priorityKey: 5, fairnessKey: "vendor-c" },
+    ],
+    fairnessKeys: [
+      { key: "vendor-a", weight: 3 },
+      { key: "vendor-b", weight: 2 },
+      { key: "vendor-c", weight: 1 },
+    ],
+  },
+];
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+let _seed = 0;
+function makeTask(priorityKey, fairnessKey) {
+  return { id: ++_seed, priorityKey: +priorityKey, fairnessKey: (fairnessKey || "").trim() };
+}
+
+/**
+ * Weighted Fair Queue dispatch simulation.
+ * Returns tasks in dispatch order respecting priority (lower = first),
+ * then within each priority tier uses WFQ (lowest dispatched/weight wins).
+ */
+function simulateDispatches(initialQueue, fairnessKeys) {
+  const order = [];
+  let queue = [...initialQueue];
+  const counters = {};
+
+  const weightOf = (key) => {
+    const fk = fairnessKeys.find((f) => f.key === key);
+    return fk ? fk.weight : 1;
+  };
+
+  while (queue.length > 0) {
+    const minPriority = Math.min(...queue.map((t) => t.priorityKey));
+    const tier = queue.filter((t) => t.priorityKey === minPriority);
+    const rest = queue.filter((t) => t.priorityKey !== minPriority);
+
+    // Group tier by fairness key
+    const groups = {};
+    tier.forEach((t) => {
+      const k = t.fairnessKey || "__none__";
+      if (!groups[k]) groups[k] = [];
+      groups[k].push(t);
+    });
+
+    const keys = Object.keys(groups);
+    let chosenKey = keys[0];
+
+    // If multiple fairness keys exist within this priority tier, use WFQ
+    const hasRealFairness = keys.some((k) => k !== "__none__");
+    if (keys.length > 1 && hasRealFairness) {
+      let lowestRatio = Infinity;
+      for (const k of keys) {
+        const ratio = (counters[k] || 0) / weightOf(k === "__none__" ? "" : k);
+        if (ratio < lowestRatio) {
+          lowestRatio = ratio;
+          chosenKey = k;
+        }
+      }
+    }
+
+    const task = groups[chosenKey][0];
+    counters[chosenKey] = (counters[chosenKey] || 0) + 1;
+    order.push(task);
+    queue = [...tier.filter((t) => t !== task), ...rest];
+  }
+
+  return order;
+}
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+export default function PriorityFairnessSimulator() {
+  const { colorMode } = useColorMode();
+  const isDark = colorMode === "dark";
+  const chartRef = useRef(null);
+
+  // Config state
+  const [queue, setQueue] = useState([]);
+  const [fairnessKeys, setFairnessKeys] = useState([]);
+  const [newTaskPriority, setNewTaskPriority] = useState(3);
+  const [newTaskFairnessKey, setNewTaskFairnessKey] = useState("");
+  const [newFkName, setNewFkName] = useState("");
+  const [newFkWeight, setNewFkWeight] = useState(1);
+
+  // Simulation state
+  const [dispatchOrder, setDispatchOrder] = useState([]);
+  const [stepIndex, setStepIndex] = useState(0);
+  const [simStarted, setSimStarted] = useState(false);
+
+  const dispatched = dispatchOrder.slice(0, stepIndex);
+  const remainingIds = new Set(dispatchOrder.slice(stepIndex).map((t) => t.id));
+
+  // ── Derived fairness key color map
+  const fkColorMap = {};
+  fairnessKeys.forEach((fk, i) => {
+    fkColorMap[fk.key] = FAIRNESS_PALETTE[i % FAIRNESS_PALETTE.length];
+  });
+
+  // ── Preset loader
+  function loadPreset(idx) {
+    if (!+idx) return;
+    const p = PRESETS[+idx];
+    const newQueue = p.queue.map((t) => makeTask(t.priorityKey, t.fairnessKey));
+    setQueue(newQueue);
+    setFairnessKeys(p.fairnessKeys.map((fk) => ({ ...fk })));
+    resetSim(newQueue, p.fairnessKeys);
+  }
+
+  // ── Task management
+  function addTask() {
+    const task = makeTask(newTaskPriority, newTaskFairnessKey);
+    const newQ = [...queue, task];
+    setQueue(newQ);
+    resetSim(newQ, fairnessKeys);
+  }
+
+  function removeTask(id) {
+    const newQ = queue.filter((t) => t.id !== id);
+    setQueue(newQ);
+    resetSim(newQ, fairnessKeys);
+  }
+
+  // ── Fairness key management
+  function addFairnessKey() {
+    if (!newFkName.trim() || fairnessKeys.find((f) => f.key === newFkName.trim())) return;
+    const updated = [...fairnessKeys, { key: newFkName.trim(), weight: +newFkWeight || 1 }];
+    setFairnessKeys(updated);
+    setNewFkName("");
+    setNewFkWeight(1);
+    resetSim(queue, updated);
+  }
+
+  function removeFairnessKey(key) {
+    const updated = fairnessKeys.filter((f) => f.key !== key);
+    setFairnessKeys(updated);
+    resetSim(queue, updated);
+  }
+
+  function updateWeight(key, weight) {
+    const updated = fairnessKeys.map((f) => (f.key === key ? { ...f, weight: +weight || 1 } : f));
+    setFairnessKeys(updated);
+    resetSim(queue, updated);
+  }
+
+  // ── Simulation controls
+  function resetSim(q = queue, fk = fairnessKeys) {
+    setDispatchOrder([]);
+    setStepIndex(0);
+    setSimStarted(false);
+  }
+
+  function runSim() {
+    if (!queue.length) return;
+    const order = simulateDispatches(queue, fairnessKeys);
+    setDispatchOrder(order);
+    setStepIndex(0);
+    setSimStarted(true);
+  }
+
+  function stepForward() {
+    setStepIndex((i) => Math.min(i + 1, dispatchOrder.length));
+  }
+
+  function dispatchAll() {
+    setStepIndex(dispatchOrder.length);
+  }
+
+  function restart() {
+    setStepIndex(0);
+  }
+
+  // ── Chart
+  useEffect(() => {
+    if (!chartRef.current) return;
+    const hasFairness = fairnessKeys.length > 0;
+    if (!hasFairness || dispatched.length === 0) {
+      if (chartRef.current._chart) {
+        chartRef.current._chart.destroy();
+        chartRef.current._chart = null;
+      }
+      return;
+    }
+
+    const totalWeight = fairnessKeys.reduce((s, f) => s + f.weight, 0);
+    const labels = fairnessKeys.map((f) => f.key);
+    const actualCounts = {};
+    dispatched.forEach((t) => {
+      if (t.fairnessKey) actualCounts[t.fairnessKey] = (actualCounts[t.fairnessKey] || 0) + 1;
+    });
+
+    const actualPct = labels.map((k) => (((actualCounts[k] || 0) / dispatched.length) * 100).toFixed(1));
+    const expectedPct = labels.map((f) => {
+      const fk = fairnessKeys.find((x) => x.key === f);
+      return totalWeight > 0 ? ((fk.weight / totalWeight) * 100).toFixed(1) : 0;
+    });
+
+    const gridColor = isDark ? "#333" : "#e5e7eb";
+    const labelColor = isDark ? "#d1d5db" : "#374151";
+
+    if (chartRef.current._chart) {
+      const chart = chartRef.current._chart;
+      chart.data.labels = labels;
+      chart.data.datasets[0].data = actualPct;
+      chart.data.datasets[1].data = expectedPct;
+      chart.options.scales.y.grid.color = gridColor;
+      chart.options.scales.x.grid.color = gridColor;
+      chart.options.scales.y.ticks.color = labelColor;
+      chart.options.scales.x.ticks.color = labelColor;
+      chart.options.plugins.legend.labels.color = labelColor;
+      chart.update();
+    } else {
+      chartRef.current._chart = new Chart(chartRef.current, {
+        type: "bar",
+        data: {
+          labels,
+          datasets: [
+            {
+              label: "Actual dispatch %",
+              backgroundColor: "#3b82f6",
+              borderRadius: 4,
+              data: actualPct,
+            },
+            {
+              label: "Target weight %",
+              backgroundColor: isDark ? "#374151" : "#d1d5db",
+              borderRadius: 4,
+              data: expectedPct,
+            },
+          ],
+        },
+        options: {
+          responsive: true,
+          animation: { duration: 250 },
+          plugins: {
+            legend: {
+              position: "top",
+              labels: { color: labelColor },
+            },
+          },
+          scales: {
+            y: {
+              max: 100,
+              title: { display: true, text: "% of dispatches", color: labelColor },
+              grid: { color: gridColor },
+              ticks: { color: labelColor },
+            },
+            x: {
+              grid: { color: gridColor },
+              ticks: { color: labelColor },
+            },
+          },
+        },
+      });
+    }
+  }, [dispatched, fairnessKeys, isDark]);
+
+  // Cleanup chart on unmount
+  useEffect(() => {
+    return () => {
+      if (chartRef.current && chartRef.current._chart) {
+        chartRef.current._chart.destroy();
+      }
+    };
+  }, []);
+
+  const hasFairnessKeys = fairnessKeys.length > 0;
+  const canStep = simStarted && stepIndex < dispatchOrder.length;
+  const canDispatchAll = simStarted && stepIndex < dispatchOrder.length;
+  const canRestart = simStarted && stepIndex > 0;
+  const showChart = hasFairnessKeys && dispatched.length > 0;
+
+  return (
+    <div className={styles.root}>
+      {/* ── Top bar ── */}
+      <div className={styles.topBar}>
+        <div className={styles.topBarLeft}>
+          <select
+            className={styles.select}
+            defaultValue="0"
+            onChange={(e) => loadPreset(e.target.value)}
+          >
+            {PRESETS.map((p, i) => (
+              <option key={i} value={i}>
+                {p.label}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div className={styles.topBarRight}>
+          {!simStarted ? (
+            <button
+              className={styles.btnPrimary}
+              disabled={!queue.length}
+              onClick={runSim}
+            >
+              Run Simulation
+            </button>
+          ) : (
+            <>
+              <button className={styles.btn} disabled={!canStep} onClick={stepForward}>
+                Step
+              </button>
+              <button className={styles.btn} disabled={!canDispatchAll} onClick={dispatchAll}>
+                Dispatch All
+              </button>
+              <button className={styles.btnOutline} disabled={!canRestart} onClick={restart}>
+                Restart
+              </button>
+              <button className={styles.btnOutline} onClick={() => resetSim()}>
+                Reset
+              </button>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* ── Main layout ── */}
+      <div className={styles.layout}>
+        {/* ── Left: Config panel ── */}
+        <div className={styles.configPanel}>
+          {/* Fairness Keys */}
+          <div className={styles.card}>
+            <div className={styles.cardHeader}>
+              <h4 className={styles.cardTitle}>Fairness Keys</h4>
+              {!hasFairnessKeys && (
+                <span className={styles.modeTag}>Priority only</span>
+              )}
+              {hasFairnessKeys && (
+                <span className={`${styles.modeTag} ${styles.modeTagFairness}`}>
+                  Fairness active
+                </span>
+              )}
+            </div>
+
+            {!hasFairnessKeys && (
+              <p className={styles.hint}>
+                No fairness keys — tasks dispatch in strict priority order (FIFO within same
+                priority).
+              </p>
+            )}
+
+            {fairnessKeys.map((fk) => (
+              <div key={fk.key} className={styles.fkRow}>
+                <span
+                  className={styles.fkDot}
+                  style={{ background: fkColorMap[fk.key] }}
+                />
+                <span className={styles.fkName}>{fk.key}</span>
+                <label className={styles.weightLabel}>weight</label>
+                <input
+                  type="number"
+                  className={styles.weightInput}
+                  value={fk.weight}
+                  min={0.1}
+                  step={0.5}
+                  disabled={simStarted}
+                  onChange={(e) => updateWeight(fk.key, e.target.value)}
+                />
+                <button
+                  className={styles.removeBtn}
+                  disabled={simStarted}
+                  onClick={() => removeFairnessKey(fk.key)}
+                >
+                  ×
+                </button>
+              </div>
+            ))}
+
+            {!simStarted && (
+              <div className={styles.addRow}>
+                <input
+                  className={styles.textInput}
+                  placeholder="key name"
+                  value={newFkName}
+                  onChange={(e) => setNewFkName(e.target.value)}
+                  onKeyDown={(e) => e.key === "Enter" && addFairnessKey()}
+                />
+                <input
+                  className={styles.weightInput}
+                  type="number"
+                  placeholder="weight"
+                  value={newFkWeight}
+                  min={0.1}
+                  step={0.5}
+                  onChange={(e) => setNewFkWeight(e.target.value)}
+                />
+                <button className={styles.btnSmall} onClick={addFairnessKey}>
+                  + Add
+                </button>
+              </div>
+            )}
+          </div>
+
+          {/* Add Task */}
+          {!simStarted && (
+            <div className={styles.card}>
+              <h4 className={styles.cardTitle}>Add Task</h4>
+              <div className={styles.addTaskRow}>
+                <div className={styles.field}>
+                  <label className={styles.fieldLabel}>Priority key</label>
+                  <select
+                    className={styles.select}
+                    value={newTaskPriority}
+                    onChange={(e) => setNewTaskPriority(+e.target.value)}
+                  >
+                    {[1, 2, 3, 4, 5].map((p) => (
+                      <option key={p} value={p}>
+                        {p} – {PRIORITY_META[p].label}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+                {hasFairnessKeys && (
+                  <div className={styles.field}>
+                    <label className={styles.fieldLabel}>Fairness key</label>
+                    <select
+                      className={styles.select}
+                      value={newTaskFairnessKey}
+                      onChange={(e) => setNewTaskFairnessKey(e.target.value)}
+                    >
+                      <option value="">— none —</option>
+                      {fairnessKeys.map((fk) => (
+                        <option key={fk.key} value={fk.key}>
+                          {fk.key}
+                        </option>
+                      ))}
+                    </select>
+                  </div>
+                )}
+                <button className={styles.btnPrimary} onClick={addTask}>
+                  + Task
+                </button>
+              </div>
+            </div>
+          )}
+
+          {/* Priority legend */}
+          <div className={styles.card}>
+            <h4 className={styles.cardTitle}>Priority Key Legend</h4>
+            <div className={styles.legendGrid}>
+              {[1, 2, 3, 4, 5].map((p) => (
+                <div key={p} className={styles.legendRow}>
+                  <span
+                    className={styles.priorityChip}
+                    style={{
+                      background: PRIORITY_META[p].color,
+                      color: PRIORITY_META[p].textColor,
+                    }}
+                  >
+                    P{p}
+                  </span>
+                  <span className={styles.legendLabel}>{PRIORITY_META[p].label}</span>
+                  {p === 3 && <span className={styles.defaultTag}>default</span>}
+                </div>
+              ))}
+            </div>
+          </div>
+        </div>
+
+        {/* ── Right: Visualizer ── */}
+        <div className={styles.vizPanel}>
+          {/* Task Queue Backlog */}
+          <div className={styles.card}>
+            <div className={styles.cardHeader}>
+              <h4 className={styles.cardTitle}>Task Queue</h4>
+              <div className={styles.queueStats}>
+                <span className={styles.statBadge}>
+                  {simStarted ? remainingIds.size : queue.length} waiting
+                </span>
+                {simStarted && (
+                  <span className={`${styles.statBadge} ${styles.statBadgeDone}`}>
+                    {dispatched.length} dispatched
+                  </span>
+                )}
+              </div>
+            </div>
+
+            {queue.length === 0 ? (
+              <p className={styles.hint}>
+                Load a scenario from the dropdown above, or add tasks manually.
+              </p>
+            ) : (
+              <div className={styles.queueGrid}>
+                {queue.map((t) => {
+                  const isDispatched = simStarted && !remainingIds.has(t.id);
+                  return (
+                    <div
+                      key={t.id}
+                      className={`${styles.taskChip} ${isDispatched ? styles.taskChipDone : ""}`}
+                      style={
+                        !isDispatched
+                          ? { borderColor: PRIORITY_META[t.priorityKey].color }
+                          : {}
+                      }
+                    >
+                      <span
+                        className={styles.priorityChip}
+                        style={
+                          !isDispatched
+                            ? {
+                                background: PRIORITY_META[t.priorityKey].color,
+                                color: PRIORITY_META[t.priorityKey].textColor,
+                              }
+                            : {}
+                        }
+                      >
+                        P{t.priorityKey}
+                      </span>
+                      {t.fairnessKey && (
+                        <span
+                          className={styles.fkChip}
+                          style={
+                            !isDispatched
+                              ? { background: fkColorMap[t.fairnessKey] || "#888" }
+                              : {}
+                          }
+                        >
+                          {t.fairnessKey}
+                        </span>
+                      )}
+                      {isDispatched && <span className={styles.doneCheck}>✓</span>}
+                      {!simStarted && (
+                        <button
+                          className={styles.chipRemove}
+                          onClick={() => removeTask(t.id)}
+                        >
+                          ×
+                        </button>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+
+          {/* Dispatch Log */}
+          {simStarted && (
+            <div className={styles.card}>
+              <div className={styles.cardHeader}>
+                <h4 className={styles.cardTitle}>Dispatch Order</h4>
+                <span className={styles.progressText}>
+                  {stepIndex} / {dispatchOrder.length}
+                </span>
+              </div>
+
+              {dispatched.length === 0 ? (
+                <p className={styles.hint}>
+                  Click <strong>Step</strong> to dispatch one task at a time, or{" "}
+                  <strong>Dispatch All</strong> to run the full simulation.
+                </p>
+              ) : (
+                <div className={styles.logList}>
+                  {dispatched.map((t, i) => (
+                    <div
+                      key={`log-${t.id}-${i}`}
+                      className={`${styles.logRow} ${i === dispatched.length - 1 ? styles.logRowLatest : ""}`}
+                    >
+                      <span className={styles.logNum}>#{i + 1}</span>
+                      <span
+                        className={styles.priorityChip}
+                        style={{
+                          background: PRIORITY_META[t.priorityKey].color,
+                          color: PRIORITY_META[t.priorityKey].textColor,
+                        }}
+                      >
+                        P{t.priorityKey}
+                      </span>
+                      {t.fairnessKey ? (
+                        <span
+                          className={styles.fkChip}
+                          style={{ background: fkColorMap[t.fairnessKey] || "#888" }}
+                        >
+                          {t.fairnessKey}
+                        </span>
+                      ) : (
+                        <span className={styles.logLabel}>
+                          {PRIORITY_META[t.priorityKey].label}
+                        </span>
+                      )}
+                      <span className={styles.taskRef}>task #{t.id}</span>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* Fairness Distribution Chart */}
+          {showChart && (
+            <div className={styles.card}>
+              <h4 className={styles.cardTitle}>Fairness Distribution</h4>
+              <p className={styles.chartCaption}>
+                Actual dispatch percentage vs. target weight percentage per fairness key.
+              </p>
+              <canvas ref={chartRef} />
+            </div>
+          )}
+
+          {/* Placeholder canvas (hidden) when chart not showing but ref needed */}
+          {!showChart && <canvas ref={chartRef} style={{ display: "none" }} />}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/HowItWorks.js b/src/components/elements/PriorityFairnessWalkthrough/HowItWorks.js
new file mode 100644
index 0000000000..f0a5020ee7
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/HowItWorks.js
@@ -0,0 +1,79 @@
+import React from 'react';
+import styles from './walkthrough.module.css';
+
+const STEPS = [
+  {
+    title: 'Worker polls the Task Queue',
+    body: 'When a Worker is ready, it sends a poll request to the Task Queue. Temporal evaluates all waiting tasks and applies Priority and Fairness rules to decide which one to return.',
+  },
+  {
+    title: 'Priority tier is selected first',
+    body: 'Temporal finds the lowest priorityKey among all waiting tasks. Every task at priority 1 will be dispatched before any task at priority 2 moves, and so on. Tasks at the same level compete under Fairness rules.',
+  },
+  {
+    title: 'Fairness distributes capacity within the tier',
+    body: 'Within a priority tier, Temporal tracks how many tasks each fairnessKey has received relative to its fairnessWeight. The key that is furthest behind its expected share gets the next dispatch. This prevents any single tenant from consuming disproportionate capacity, even if they have a deep backlog.',
+  },
+  {
+    title: 'No fairnessKey means strict FIFO within the tier',
+    body: 'If you set priorityKey but omit fairnessKey, tasks at the same priority level are dispatched in arrival order. Fairness only applies when at least one task in the tier carries a fairnessKey.',
+  },
+  {
+    title: 'Priority and Fairness are per Task Queue',
+    body: 'The rules apply independently per Task Queue. Workers on the same Task Queue share the same dispatch ordering. Workers on separate Task Queues are unaffected by each other.',
+  },
+];
+
+const WHEN_ROWS = [
+  { scenario: 'Payments should never wait behind inventory syncs', use: 'Priority', badge: 'badgePriority' },
+  { scenario: 'Premium users should not be blocked by a large free-tier tenant', use: 'Fairness', badge: 'badgeFairness' },
+  { scenario: 'SLAs differ across customer tiers and tenants vary in volume', use: 'Both', badge: 'badgeBoth' },
+];
+
+export default function HowItWorks({ onNext }) {
+  return (
+    <div className={styles.section}>
+      <p className={styles.lead}>
+        When a Worker polls for the next task, Temporal applies two rules in sequence: Priority
+        determines which tier goes first, and Fairness distributes capacity among tenants within
+        each tier.
+      </p>
+
+      <div className={styles.stepList}>
+        {STEPS.map((step, i) => (
+          <div key={i} className={styles.step}>
+            <div className={styles.stepNum}>{i + 1}</div>
+            <div className={styles.stepContent}>
+              <p className={styles.stepTitle}>{step.title}</p>
+              <p className={styles.stepBody}>{step.body}</p>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <h3 className={styles.sectionHeading}>When to use Priority vs Fairness</h3>
+      <table className={styles.whenTable}>
+        <thead>
+          <tr>
+            <th>Scenario</th>
+            <th>Use</th>
+          </tr>
+        </thead>
+        <tbody>
+          {WHEN_ROWS.map((row, i) => (
+            <tr key={i}>
+              <td>{row.scenario}</td>
+              <td>
+                <span className={`${styles.badge} ${styles[row.badge]}`}>{row.use}</span>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      <button className={styles.nextBtn} onClick={onNext}>
+        SDK Examples
+      </button>
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/Overview.js b/src/components/elements/PriorityFairnessWalkthrough/Overview.js
new file mode 100644
index 0000000000..e28598a75d
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/Overview.js
@@ -0,0 +1,90 @@
+import React from 'react';
+import styles from './walkthrough.module.css';
+
+const PILLS = [
+  { label: 'P1', desc: 'Critical', bg: '#ef4444', fg: '#fff' },
+  { label: 'P2', desc: 'High', bg: '#f97316', fg: '#fff' },
+  { label: 'P3', desc: 'Normal (default)', bg: '#3b82f6', fg: '#fff' },
+  { label: 'P4', desc: 'Low', bg: '#22c55e', fg: '#000' },
+  { label: 'P5', desc: 'Batch', bg: '#94a3b8', fg: '#fff' },
+];
+
+export default function Overview({ onNext }) {
+  return (
+    <div className={styles.section}>
+      <p className={styles.lead}>
+        The core idea of Task Queue Priority and Fairness is that when tasks from different workloads
+        compete for the same Workers, Priority controls which ones get picked first, and Fairness
+        ensures no single tenant can run away with all the capacity.
+      </p>
+
+      <div className={styles.featureGrid}>
+        {/* Priority card */}
+        <div className={styles.featureCard}>
+          <div className={styles.featureCardHeader}>
+            <svg width="24" height="24" viewBox="0 0 24 24" fill="none" style={{ flexShrink: 0, marginTop: 1 }}>
+              <path d="M3 3h18v3.5H3V3zm0 7.25h13v3.5H3v-3.5zm0 7.25h8v3.5H3v-3.5z" fill="url(#ov-prio-grad)" />
+              <defs>
+                <linearGradient id="ov-prio-grad" x1="21" y1="3" x2="3" y2="21" gradientUnits="userSpaceOnUse">
+                  <stop stopColor="#1FF1A5" />
+                  <stop offset="1" stopColor="#C3FF62" />
+                </linearGradient>
+              </defs>
+            </svg>
+            <strong className={styles.featureCardTitle}>Priority</strong>
+          </div>
+          <p className={styles.featureCardBody}>
+            Every task carries a <code>priorityKey</code> from <code>1</code> (critical) to{' '}
+            <code>5</code> (batch), with <code>3</code> as the default. When a Worker polls, it
+            always picks the lowest-numbered task first regardless of arrival time. This lets you
+            share a single Worker pool across very different workloads and guarantee that
+            time-sensitive work never waits behind low-urgency jobs.
+          </p>
+        </div>
+
+        {/* Fairness card */}
+        <div className={styles.featureCard}>
+          <div className={styles.featureCardHeader}>
+            <svg width="24" height="24" viewBox="0 0 24 24" fill="none" style={{ flexShrink: 0, marginTop: 1 }}>
+              <path
+                d="M11 2h2v3.5h-2V2zm0 16.5h2V22h-2v-3.5zM4 7.5h7v9H4v-9zm9 0h7v9h-7v-9zm-2 1.5H4.5V8H11v1zM13 8h6.5v1H13V8z"
+                fill="url(#ov-fair-grad)"
+              />
+              <defs>
+                <linearGradient id="ov-fair-grad" x1="21" y1="2" x2="3" y2="22" gradientUnits="userSpaceOnUse">
+                  <stop stopColor="#1FF1A5" />
+                  <stop offset="1" stopColor="#C3FF62" />
+                </linearGradient>
+              </defs>
+            </svg>
+            <strong className={styles.featureCardTitle}>Fairness</strong>
+          </div>
+          <p className={styles.featureCardBody}>
+            Without Fairness, tasks at the same priority dispatch strictly FIFO, so a backlog-heavy
+            tenant can block everyone else at that level indefinitely. Fairness groups tasks by{' '}
+            <code>fairnessKey</code> and dispatches proportionally by <code>fairnessWeight</code>. A
+            key with weight <code>5</code> gets roughly 5x more dispatches than a key with weight{' '}
+            <code>1</code>, but no key is ever completely locked out.
+          </p>
+        </div>
+      </div>
+
+      <p className={styles.useBoth}>
+        Use both together when you need SLA ordering across workload types and fair distribution
+        across tenants within each tier.
+      </p>
+
+      <div className={styles.pillStrip}>
+        {PILLS.map(({ label, desc, bg, fg }) => (
+          <div key={label} className={styles.pill} style={{ background: bg, color: fg }}>
+            {label} · {desc}
+          </div>
+        ))}
+      </div>
+
+      <button className={styles.nextBtn} onClick={onNext}>
+        Try It
+      </button>
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/SDK.js b/src/components/elements/PriorityFairnessWalkthrough/SDK.js
new file mode 100644
index 0000000000..93f48e6c4a
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/SDK.js
@@ -0,0 +1,178 @@
+import CodeBlock from '@theme/CodeBlock';
+import React, { useState } from 'react';
+import styles from './walkthrough.module.css';
+
+const LANGS = ['Go', 'Java', 'Python', 'TypeScript', '.NET'];
+
+const EXAMPLES = {
+  priorityOnly: {
+    title: 'Workflow - Priority only',
+    Go: `workflowOptions := client.StartWorkflowOptions{
+  ID:        "my-workflow-id",
+  TaskQueue: "my-task-queue",
+  Priority:  temporal.Priority{PriorityKey: 1},
+}
+we, err := c.ExecuteWorkflow(ctx, workflowOptions, MyWorkflow)`,
+    Java: `WorkflowOptions options = WorkflowOptions.newBuilder()
+  .setTaskQueue("my-task-queue")
+  .setPriority(Priority.newBuilder().setPriorityKey(1).build())
+  .build();
+MyWorkflow workflow = client.newWorkflowStub(MyWorkflow.class, options);
+workflow.run();`,
+    Python: `await client.start_workflow(
+  MyWorkflow.run,
+  id="my-workflow-id",
+  task_queue="my-task-queue",
+  priority=Priority(priority_key=1),
+)`,
+    TypeScript: `const handle = await client.workflow.start(MyWorkflow, {
+  workflowId: "my-workflow-id",
+  taskQueue: "my-task-queue",
+  priority: { priorityKey: 1 },
+});`,
+    '.NET': `var handle = await Client.StartWorkflowAsync(
+  (MyWorkflow wf) => wf.RunAsync(),
+  new StartWorkflowOptions("my-workflow-id", "my-task-queue")
+  {
+    Priority = new Priority(priorityKey: 1),
+  }
+);`,
+  },
+  priorityAndFairness: {
+    title: 'Workflow - Priority + Fairness',
+    Go: `workflowOptions := client.StartWorkflowOptions{
+  ID:        "my-workflow-id",
+  TaskQueue: "my-task-queue",
+  Priority: temporal.Priority{
+    PriorityKey:    1,
+    FairnessKey:    "tenant-acme",
+    FairnessWeight: 3.0,
+  },
+}
+we, err := c.ExecuteWorkflow(ctx, workflowOptions, MyWorkflow)`,
+    Java: `WorkflowOptions options = WorkflowOptions.newBuilder()
+  .setTaskQueue("my-task-queue")
+  .setPriority(Priority.newBuilder()
+    .setPriorityKey(1)
+    .setFairnessKey("tenant-acme")
+    .setFairnessWeight(3.0)
+    .build())
+  .build();
+MyWorkflow workflow = client.newWorkflowStub(MyWorkflow.class, options);
+workflow.run();`,
+    Python: `await client.start_workflow(
+  MyWorkflow.run,
+  id="my-workflow-id",
+  task_queue="my-task-queue",
+  priority=Priority(priority_key=1, fairness_key="tenant-acme", fairness_weight=3.0),
+)`,
+    TypeScript: `const handle = await client.workflow.start(MyWorkflow, {
+  workflowId: "my-workflow-id",
+  taskQueue: "my-task-queue",
+  priority: { priorityKey: 1, fairnessKey: "tenant-acme", fairnessWeight: 3.0 },
+});`,
+    '.NET': `var handle = await Client.StartWorkflowAsync(
+  (MyWorkflow wf) => wf.RunAsync(),
+  new StartWorkflowOptions("my-workflow-id", "my-task-queue")
+  {
+    Priority = new Priority(
+      priorityKey: 1,
+      fairnessKey: "tenant-acme",
+      fairnessWeight: 3.0
+    ),
+  }
+);`,
+  },
+};
+
+const LANG_META = {
+  Go: 'go',
+  Java: 'java',
+  Python: 'python',
+  TypeScript: 'typescript',
+  '.NET': 'csharp',
+};
+
+export default function SDK() {
+  const [activeLang, setActiveLang] = useState('Go');
+
+  return (
+    <div className={styles.section}>
+      <p className={styles.lead}>
+        Set <code>priorityKey</code>, <code>fairnessKey</code>, or both when starting Workflows or
+        scheduling Activities. Priority and Fairness are enabled by default - no configuration
+        required for Temporal Cloud or self-hosted clusters running Temporal 1.26+.
+      </p>
+
+      {/* Language picker */}
+      <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: '1.5rem' }}>
+        {LANGS.map((lang) => (
+          <button
+            key={lang}
+            onClick={() => setActiveLang(lang)}
+            style={{
+              border: '1px solid',
+              borderColor: activeLang === lang ? 'var(--pfw-nav-active)' : 'var(--pfw-border)',
+              background: activeLang === lang ? 'var(--pfw-badge-bg)' : 'transparent',
+              color: activeLang === lang ? 'var(--pfw-nav-active)' : 'var(--pfw-muted)',
+              padding: '5px 14px',
+              fontSize: 13,
+              fontWeight: 600,
+              cursor: 'pointer',
+              borderRadius: 0,
+              fontFamily: 'var(--ifm-font-family-base)',
+              transition: 'all 0.15s',
+            }}
+          >
+            {lang}
+          </button>
+        ))}
+      </div>
+
+      {/* Priority only */}
+      <div className={styles.sdkGroup}>
+        <div className={styles.sdkGroupTitle}>Priority only</div>
+        <CodeBlock language={LANG_META[activeLang]}>
+          {EXAMPLES.priorityOnly[activeLang]}
+        </CodeBlock>
+      </div>
+
+      {/* Priority + Fairness */}
+      <div className={styles.sdkGroup}>
+        <div className={styles.sdkGroupTitle}>Priority + Fairness</div>
+        <CodeBlock language={LANG_META[activeLang]}>
+          {EXAMPLES.priorityAndFairness[activeLang]}
+        </CodeBlock>
+      </div>
+
+      {/* CLI */}
+      <div className={styles.sdkGroup}>
+        <div className={styles.sdkGroupTitle}>Temporal CLI</div>
+        <CodeBlock language="bash">{`temporal workflow start \\
+  --type MyWorkflow \\
+  --task-queue my-task-queue \\
+  --workflow-id my-workflow-id \\
+  --priority-key 1 \\
+  --fairness-key tenant-acme \\
+  --fairness-weight 3.0`}</CodeBlock>
+      </div>
+
+      <div style={{ marginTop: '2rem', paddingTop: '1.5rem', borderTop: '1px solid var(--pfw-border)' }}>
+        <p style={{ fontSize: '0.875rem', color: 'var(--pfw-muted)', margin: '0 0 0.5rem' }}>
+          Next steps
+        </p>
+        <ul style={{ margin: 0, paddingLeft: '1.25rem', fontSize: '0.875rem', lineHeight: 1.8 }}>
+          <li>
+            <a href="/develop/task-queue-priority-fairness">Task Queue Priority and Fairness - full reference</a>
+          </li>
+          <li>
+            <a href="/task-queue">Task Queue overview</a>
+          </li>
+          <li>
+            <a href="/develop/worker-performance">Worker performance tuning</a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/TryIt.js b/src/components/elements/PriorityFairnessWalkthrough/TryIt.js
new file mode 100644
index 0000000000..e59ec78822
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/TryIt.js
@@ -0,0 +1,23 @@
+import React from 'react';
+import PriorityFairnessSimulator from '../PriorityFairnessSimulator';
+import styles from './walkthrough.module.css';
+
+export default function TryIt({ onNext }) {
+  return (
+    <div className={styles.section} style={{ maxWidth: '100%', padding: '32px 0 64px' }}>
+      <div style={{ maxWidth: 860, margin: '0 auto', padding: '0 24px 24px' }}>
+        <p className={styles.lead} style={{ marginBottom: '0.5rem' }}>
+          Load a preset or build your own queue. Use <strong>Step</strong> to dispatch one task at a
+          time and watch which task gets picked next, or <strong>Dispatch All</strong> to see the
+          full order at once.
+        </p>
+      </div>
+      <PriorityFairnessSimulator />
+      <div style={{ maxWidth: 860, margin: '0 auto', padding: '0 24px' }}>
+        <button className={styles.nextBtn} onClick={onNext}>
+          How It Works
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/index.js b/src/components/elements/PriorityFairnessWalkthrough/index.js
new file mode 100644
index 0000000000..7b2d5e7d80
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/index.js
@@ -0,0 +1,45 @@
+import React, { useState } from 'react';
+import HowItWorks from './HowItWorks';
+import Overview from './Overview';
+import SDK from './SDK';
+import TryIt from './TryIt';
+import styles from './walkthrough.module.css';
+
+const NAV = [
+  { id: 'overview', label: 'Overview' },
+  { id: 'tryit', label: 'Try It' },
+  { id: 'howitworks', label: 'How It Works' },
+  { id: 'sdk', label: 'SDK Examples' },
+];
+
+export default function PriorityFairnessWalkthrough() {
+  const [active, setActive] = useState('overview');
+
+  function next(current) {
+    const idx = NAV.findIndex((n) => n.id === current);
+    if (idx < NAV.length - 1) setActive(NAV[idx + 1].id);
+  }
+
+  return (
+    <div className={styles.shell}>
+      <nav className={styles.nav} aria-label="Priority and Fairness walkthrough sections">
+        <span className={styles.navLogo}>Priority &amp; Fairness</span>
+        {NAV.map((item) => (
+          <button
+            key={item.id}
+            className={`${styles.navBtn} ${active === item.id ? styles.navBtnActive : ''}`}
+            onClick={() => setActive(item.id)}
+            aria-current={active === item.id ? 'page' : undefined}
+          >
+            {item.label}
+          </button>
+        ))}
+      </nav>
+
+      {active === 'overview' && <Overview onNext={() => next('overview')} />}
+      {active === 'tryit' && <TryIt onNext={() => next('tryit')} />}
+      {active === 'howitworks' && <HowItWorks onNext={() => next('howitworks')} />}
+      {active === 'sdk' && <SDK />}
+    </div>
+  );
+}
diff --git a/src/components/elements/PriorityFairnessWalkthrough/walkthrough.module.css b/src/components/elements/PriorityFairnessWalkthrough/walkthrough.module.css
new file mode 100644
index 0000000000..6175c0a2e9
--- /dev/null
+++ b/src/components/elements/PriorityFairnessWalkthrough/walkthrough.module.css
@@ -0,0 +1,331 @@
+/*
+ * PriorityFairnessWalkthrough.module.css
+ * Adapted from NexusDemo CSS vars for light/dark mode support.
+ */
+
+/* ── Per-theme accent vars ─────────────────────────────── */
+:global([data-theme='dark']) {
+  --pfw-surface: #1a1a2e;
+  --pfw-surface2: #252540;
+  --pfw-border: rgba(255, 255, 255, 0.08);
+  --pfw-muted: #94a3b8;
+  --pfw-nav-inactive: #94a3b8;
+  --pfw-nav-hover: #d4d7ff;
+  --pfw-nav-active: #7f86f1;
+  --pfw-uv: #444ce7;
+  --pfw-teal: #1ff1a5;
+  --pfw-lime: #c3ff62;
+  --pfw-badge-bg: rgba(68, 76, 231, 0.2);
+  --pfw-step-num-bg: #7f86f1;
+  --pfw-step-num-text: #fff;
+  --pfw-card-bg: rgba(255, 255, 255, 0.03);
+  --pfw-card-border: rgba(127, 134, 241, 0.2);
+  --pfw-priority-card-border: linear-gradient(255deg, #444ce7 0%, #b664ff 100%);
+}
+
+:global([data-theme='light']) {
+  --pfw-surface: #f4f6f9;
+  --pfw-surface2: #ffffff;
+  --pfw-border: rgba(0, 0, 0, 0.08);
+  --pfw-muted: #64748b;
+  --pfw-nav-inactive: #64748b;
+  --pfw-nav-hover: #3a41cc;
+  --pfw-nav-active: #444ce7;
+  --pfw-uv: #3a41cc;
+  --pfw-teal: #059669;
+  --pfw-lime: #65a30d;
+  --pfw-badge-bg: rgba(58, 65, 204, 0.1);
+  --pfw-step-num-bg: #444ce7;
+  --pfw-step-num-text: #fff;
+  --pfw-card-bg: #ffffff;
+  --pfw-card-border: rgba(0, 0, 0, 0.09);
+  --pfw-priority-card-border: linear-gradient(255deg, #444ce7 0%, #b664ff 100%);
+}
+
+/* ── Shell ─────────────────────────────────────────────── */
+.shell {
+  font-family: var(--ifm-font-family-base);
+  color: var(--ifm-font-color-base);
+  background: var(--ifm-background-color);
+  min-height: 60vh;
+}
+
+/* ── Nav ───────────────────────────────────────────────── */
+.nav {
+  position: sticky;
+  top: var(--ifm-navbar-height);
+  z-index: 50;
+  background: var(--ifm-background-color);
+  border-bottom: 1px solid var(--pfw-border);
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0 24px;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.nav::-webkit-scrollbar {
+  display: none;
+}
+
+.navLogo {
+  font-weight: 700;
+  font-size: 13px;
+  color: var(--ifm-color-primary);
+  margin-right: 16px;
+  white-space: nowrap;
+  flex-shrink: 0;
+  letter-spacing: 0.01em;
+}
+
+.navBtn {
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--pfw-nav-inactive);
+  padding: 14px 12px;
+  white-space: nowrap;
+  border-bottom: 2px solid transparent;
+  transition: color 0.15s, border-color 0.15s;
+  margin-bottom: -1px;
+  font-family: var(--ifm-font-family-base);
+}
+
+.navBtn:hover {
+  color: var(--pfw-nav-hover);
+}
+
+.navBtnActive {
+  color: var(--pfw-nav-active);
+  border-bottom-color: var(--pfw-nav-active);
+}
+
+/* ── Section container ─────────────────────────────────── */
+.section {
+  max-width: 860px;
+  margin: 0 auto;
+  padding: 40px 24px 64px;
+}
+
+.sectionHeading {
+  font-size: 1.15rem;
+  font-weight: 600;
+  margin: 2rem 0 1rem;
+  color: var(--ifm-font-color-base);
+}
+
+.lead {
+  font-size: 1.05rem;
+  line-height: 1.7;
+  color: var(--ifm-font-color-base);
+  margin-bottom: 1.5rem;
+}
+
+/* ── Feature cards (gradient border, no rounded corners) ── */
+.featureGrid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin: 1.75rem 0 1.25rem;
+}
+
+@media (max-width: 640px) {
+  .featureGrid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.featureCard {
+  border: 1px solid transparent;
+  background-image:
+    linear-gradient(var(--ifm-background-color, #13111b), var(--ifm-background-color, #13111b)),
+    linear-gradient(255deg, #444ce7 0%, #b664ff 100%);
+  background-origin: padding-box, border-box;
+  background-clip: padding-box, border-box;
+  border-radius: 0;
+  padding: 1.25rem 1.25rem 1.25rem 1rem;
+}
+
+.featureCardHeader {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.875rem;
+  margin-bottom: 0.75rem;
+}
+
+.featureCardTitle {
+  font-size: 1.05rem;
+  font-weight: 300;
+  letter-spacing: 0.01em;
+  margin: 0;
+  line-height: 1.5;
+}
+
+.featureCardBody {
+  font-size: 0.9rem;
+  line-height: 1.7;
+  margin: 0;
+  color: var(--ifm-font-color-base);
+}
+
+/* ── Priority pills ────────────────────────────────────── */
+.pillStrip {
+  display: flex;
+  gap: 6px;
+  margin: 1.25rem 0 0.5rem;
+  flex-wrap: wrap;
+}
+
+.pill {
+  border-radius: 0;
+  padding: 5px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  font-family: var(--ifm-font-family-monospace);
+  white-space: nowrap;
+}
+
+/* ── Use-both callout ──────────────────────────────────── */
+.useBoth {
+  font-size: 0.9rem;
+  line-height: 1.7;
+  color: var(--pfw-muted);
+  margin: 1.25rem 0 0;
+}
+
+/* ── How It Works steps ────────────────────────────────── */
+.stepList {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  margin: 1.5rem 0;
+}
+
+.step {
+  display: flex;
+  gap: 1rem;
+  align-items: flex-start;
+  background: var(--pfw-card-bg);
+  border: 1px solid var(--pfw-card-border);
+  border-radius: 0;
+  padding: 1.25rem;
+}
+
+.stepNum {
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  background: var(--pfw-step-num-bg);
+  color: var(--pfw-step-num-text);
+  border-radius: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  font-weight: 700;
+  margin-top: 1px;
+}
+
+.stepContent {
+  flex: 1;
+}
+
+.stepTitle {
+  font-weight: 600;
+  font-size: 0.95rem;
+  margin: 0 0 0.35rem;
+}
+
+.stepBody {
+  font-size: 0.875rem;
+  line-height: 1.65;
+  margin: 0;
+  color: var(--ifm-font-color-base);
+}
+
+/* ── When-to-use table ─────────────────────────────────── */
+.whenTable {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+  margin: 1rem 0 2rem;
+}
+
+.whenTable th,
+.whenTable td {
+  border: 1px solid var(--pfw-border);
+  padding: 0.65rem 1rem;
+  text-align: left;
+}
+
+.whenTable th {
+  background: var(--pfw-card-bg);
+  font-weight: 600;
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--pfw-muted);
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  font-size: 11px;
+  font-weight: 600;
+  border-radius: 0;
+  font-family: var(--ifm-font-family-monospace);
+}
+
+.badgePriority {
+  background: var(--pfw-badge-bg);
+  color: var(--pfw-nav-active);
+}
+
+.badgeFairness {
+  background: rgba(31, 241, 165, 0.12);
+  color: var(--pfw-teal);
+}
+
+.badgeBoth {
+  background: rgba(182, 100, 255, 0.12);
+  color: #b664ff;
+}
+
+/* ── SDK section ───────────────────────────────────────── */
+.sdkGroup {
+  margin-bottom: 2.5rem;
+}
+
+.sdkGroupTitle {
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--pfw-muted);
+  margin-bottom: 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--pfw-border);
+}
+
+/* ── Next button ───────────────────────────────────────── */
+.nextBtn {
+  margin-top: 2rem;
+  display: inline-block;
+  background: var(--pfw-uv);
+  color: #fff;
+  border: none;
+  padding: 10px 22px;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  border-radius: 0;
+  font-family: var(--ifm-font-family-base);
+  transition: opacity 0.15s;
+}
+
+.nextBtn:hover {
+  opacity: 0.85;
+}
diff --git a/src/components/elements/priority-fairness-simulator.module.css b/src/components/elements/priority-fairness-simulator.module.css
new file mode 100644
index 0000000000..878ad4528f
--- /dev/null
+++ b/src/components/elements/priority-fairness-simulator.module.css
@@ -0,0 +1,495 @@
+/* ── Root ──────────────────────────────────────────────────────────────────── */
+.root {
+  font-size: 0.9rem;
+  margin: 1.5rem 0;
+}
+
+/* ── Top Bar ─────────────────────────────────────────────────────────────────*/
+.topBar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  margin-bottom: 1rem;
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 8px;
+  background: var(--ifm-background-surface-color);
+}
+
+.topBarLeft {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.topBarRight {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+/* ── Layout ──────────────────────────────────────────────────────────────────*/
+.layout {
+  display: flex;
+  gap: 1rem;
+  align-items: flex-start;
+}
+
+.configPanel {
+  flex: 0 0 300px;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.vizPanel {
+  flex: 1 1 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+@media (max-width: 900px) {
+  .layout {
+    flex-direction: column;
+  }
+  .configPanel {
+    flex: 1 1 auto;
+  }
+}
+
+/* ── Card ────────────────────────────────────────────────────────────────────*/
+.card {
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 8px;
+  padding: 0.85rem 1rem;
+  background: var(--ifm-background-surface-color);
+}
+
+.cardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 0.6rem;
+  gap: 0.5rem;
+}
+
+.cardTitle {
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ifm-color-emphasis-700);
+  margin: 0 0 0.6rem 0;
+}
+
+.cardHeader .cardTitle {
+  margin-bottom: 0;
+}
+
+/* ── Mode Tag ────────────────────────────────────────────────────────────────*/
+.modeTag {
+  font-size: 0.7rem;
+  font-weight: 600;
+  padding: 0.15em 0.55em;
+  border-radius: 999px;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-700);
+  white-space: nowrap;
+}
+
+.modeTagFairness {
+  background: #dbeafe;
+  color: #1d4ed8;
+}
+
+[data-theme="dark"] .modeTagFairness {
+  background: #1e3a5f;
+  color: #93c5fd;
+}
+
+/* ── Hint text ───────────────────────────────────────────────────────────────*/
+.hint {
+  font-size: 0.8rem;
+  color: var(--ifm-color-emphasis-500);
+  margin: 0 0 0.5rem 0;
+  line-height: 1.5;
+}
+
+/* ── Fairness key rows ───────────────────────────────────────────────────────*/
+.fkRow {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-bottom: 0.4rem;
+}
+
+.fkDot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.fkName {
+  flex: 1;
+  font-size: 0.82rem;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.weightLabel {
+  font-size: 0.72rem;
+  color: var(--ifm-color-emphasis-500);
+  white-space: nowrap;
+}
+
+.weightInput {
+  width: 56px;
+  padding: 0.2em 0.4em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 4px;
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.82rem;
+  text-align: right;
+}
+
+/* ── Add row ─────────────────────────────────────────────────────────────────*/
+.addRow {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  margin-top: 0.6rem;
+}
+
+.textInput {
+  flex: 1;
+  padding: 0.3em 0.5em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 4px;
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.82rem;
+  min-width: 0;
+}
+
+.textInput::placeholder {
+  color: var(--ifm-color-emphasis-400);
+}
+
+/* ── Add task row ────────────────────────────────────────────────────────────*/
+.addTaskRow {
+  display: flex;
+  align-items: flex-end;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  flex: 1;
+  min-width: 100px;
+}
+
+.fieldLabel {
+  font-size: 0.72rem;
+  color: var(--ifm-color-emphasis-600);
+  font-weight: 600;
+}
+
+/* ── Legend ──────────────────────────────────────────────────────────────────*/
+.legendGrid {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.legendRow {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.legendLabel {
+  font-size: 0.82rem;
+  flex: 1;
+}
+
+.defaultTag {
+  font-size: 0.68rem;
+  color: var(--ifm-color-emphasis-500);
+  font-style: italic;
+}
+
+/* ── Queue stats ─────────────────────────────────────────────────────────────*/
+.queueStats {
+  display: flex;
+  gap: 0.4rem;
+}
+
+.statBadge {
+  font-size: 0.72rem;
+  font-weight: 600;
+  padding: 0.15em 0.55em;
+  border-radius: 999px;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-700);
+}
+
+.statBadgeDone {
+  background: #dcfce7;
+  color: #15803d;
+}
+
+[data-theme="dark"] .statBadgeDone {
+  background: #14532d;
+  color: #86efac;
+}
+
+/* ── Queue grid ──────────────────────────────────────────────────────────────*/
+.queueGrid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+}
+
+/* ── Task chip ───────────────────────────────────────────────────────────────*/
+.taskChip {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  padding: 0.25em 0.5em;
+  border-radius: 6px;
+  border: 2px solid var(--ifm-color-emphasis-300);
+  background: var(--ifm-background-color);
+  font-size: 0.78rem;
+  transition: opacity 0.2s;
+  position: relative;
+}
+
+.taskChipDone {
+  opacity: 0.35;
+  border-color: var(--ifm-color-emphasis-200) !important;
+  filter: grayscale(1);
+}
+
+.doneCheck {
+  font-size: 0.7rem;
+  color: #16a34a;
+}
+
+.chipRemove {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--ifm-color-emphasis-400);
+  font-size: 0.9rem;
+  line-height: 1;
+  padding: 0 0 0 0.1rem;
+  margin: 0;
+}
+
+.chipRemove:hover {
+  color: #ef4444;
+}
+
+/* ── Priority chip ───────────────────────────────────────────────────────────*/
+.priorityChip {
+  display: inline-block;
+  padding: 0.1em 0.45em;
+  border-radius: 4px;
+  font-size: 0.72rem;
+  font-weight: 700;
+  line-height: 1.4;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-font-color-base);
+  white-space: nowrap;
+}
+
+/* ── Fairness key chip ───────────────────────────────────────────────────────*/
+.fkChip {
+  display: inline-block;
+  padding: 0.1em 0.45em;
+  border-radius: 4px;
+  font-size: 0.72rem;
+  font-weight: 600;
+  line-height: 1.4;
+  color: #fff;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100px;
+}
+
+/* ── Dispatch log ────────────────────────────────────────────────────────────*/
+.progressText {
+  font-size: 0.75rem;
+  color: var(--ifm-color-emphasis-500);
+  font-variant-numeric: tabular-nums;
+}
+
+.logList {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  max-height: 280px;
+  overflow-y: auto;
+}
+
+.logRow {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.25em 0.4em;
+  border-radius: 6px;
+  background: var(--ifm-background-color);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: background 0.25s;
+}
+
+.logRowLatest {
+  background: #eff6ff;
+  border-color: #bfdbfe;
+}
+
+[data-theme="dark"] .logRowLatest {
+  background: #1e3a5f;
+  border-color: #2563eb44;
+}
+
+.logNum {
+  font-size: 0.72rem;
+  font-variant-numeric: tabular-nums;
+  color: var(--ifm-color-emphasis-500);
+  width: 2rem;
+  text-align: right;
+  flex-shrink: 0;
+}
+
+.logLabel {
+  font-size: 0.78rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.taskRef {
+  font-size: 0.7rem;
+  color: var(--ifm-color-emphasis-400);
+  margin-left: auto;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+/* ── Chart ───────────────────────────────────────────────────────────────────*/
+.chartCaption {
+  font-size: 0.78rem;
+  color: var(--ifm-color-emphasis-500);
+  margin: -0.2rem 0 0.6rem 0;
+}
+
+/* ── Buttons ─────────────────────────────────────────────────────────────────*/
+.btn,
+.btnPrimary,
+.btnOutline,
+.btnSmall,
+.removeBtn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25em;
+  border-radius: 6px;
+  font-size: 0.82rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: opacity 0.15s, background 0.15s;
+  white-space: nowrap;
+}
+
+.btn {
+  padding: 0.35em 0.75em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+}
+
+.btn:hover:not(:disabled) {
+  background: var(--ifm-color-emphasis-100);
+}
+
+.btnPrimary {
+  padding: 0.35em 0.85em;
+  border: none;
+  background: var(--ifm-color-primary);
+  color: #fff;
+}
+
+.btnPrimary:hover:not(:disabled) {
+  opacity: 0.88;
+}
+
+.btnOutline {
+  padding: 0.35em 0.75em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: transparent;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.btnOutline:hover:not(:disabled) {
+  border-color: var(--ifm-color-emphasis-500);
+  color: var(--ifm-font-color-base);
+}
+
+.btnSmall {
+  padding: 0.25em 0.6em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.78rem;
+}
+
+.btnSmall:hover:not(:disabled) {
+  background: var(--ifm-color-emphasis-100);
+}
+
+.removeBtn {
+  padding: 0.1em 0.35em;
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--ifm-color-emphasis-400);
+  font-size: 1rem;
+}
+
+.removeBtn:hover:not(:disabled) {
+  color: #ef4444;
+  border-color: #fca5a5;
+  background: #fef2f2;
+}
+
+.btn:disabled,
+.btnPrimary:disabled,
+.btnOutline:disabled,
+.btnSmall:disabled,
+.removeBtn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ── Select ──────────────────────────────────────────────────────────────────*/
+.select {
+  padding: 0.3em 0.55em;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 6px;
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.82rem;
+  cursor: pointer;
+  max-width: 100%;
+}
diff --git a/src/components/index.js b/src/components/index.js
index 07b4ad9ef6..7e2cc96cb0 100644
--- a/src/components/index.js
+++ b/src/components/index.js
@@ -1,5 +1,7 @@
 // Website components
 export { default as RetrySimulator } from './elements/RetrySimulator';
+export { default as PriorityFairnessSimulator } from './elements/PriorityFairnessSimulator';
+export { default as PriorityFairnessWalkthrough } from './elements/PriorityFairnessWalkthrough';
 export { default as HomePageHero } from './elements/HomePageHero';
 export { SdkLogos } from './elements/SdkLogos';
 export { SdkLogosAsBlocks } from './elements/SdkLogosAsBlocks';