Perseus documentation improvements (#2778)

ivyolamit · web-flow · commit 2793cebe0d03 · 2025-08-08T16:26:33.000-07:00
## Summary: Perseus documentation improvements: 1. Add favicon Perseus logo <img width="90" height="44" alt="image" src="https://github.com/user-attachments/assets/27c03f24-86b7-45a7-ba2c-38f7ef05948a" /> 2. Adjust TOC width | | | | ------- | ----- | | Before | <img width="506" height="284" alt="Screenshot 2025-08-08 at 10 12 19 AM" src="https://github.com/user-attachments/assets/2b0665c8-d1da-4455-b0d0-9c89144a4deb" /> | | After | <img width="537" height="238" alt="Screenshot 2025-08-08 at 10 58 30 AM" src="https://github.com/user-attachments/assets/15e1d659-beb8-4b46-bc3f-118b73255869" /> | Author: ivyolamit Reviewers: SonicScrewdriver, ivyolamit Required Reviewers: Approved By: SonicScrewdriver Checks: ✅ 10 checks were successful Pull Request URL: #2778
diff --git a/.changeset/thirty-candles-taste.md b/.changeset/thirty-candles-taste.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.storybook/global.css b/.storybook/global.css
@@ -13,7 +13,7 @@ body {
         "Helvetica", "Corbel", sans-serif;
     font-size: 14px;
     margin: 0;
-    color: var(--wb-semanticColor-text-primary);
+    color: var(--wb-semanticColor-core-foreground-neutral-strong);
     line-height: 1.4;
     min-width: 0;
 }
diff --git a/.storybook/manager-head.html b/.storybook/manager-head.html
@@ -0,0 +1,2 @@
+<link rel="icon" type="image/svg+xml" href="./perseus-favicon.svg" />
+<link rel="shortcut icon" href="./perseus-favicon.svg" />
diff --git a/.storybook/preview-head.html b/.storybook/preview-head.html
@@ -57,3 +57,25 @@
 />
 
 <link rel="stylesheet" href="./lato.css" />
+
+<link
+    rel="stylesheet"
+    href="https://fonts.googleapis.com/css?family=Inconsolata"
+/>
+<link
+    href="https://fonts.googleapis.com/css2?family=Source+Serif+Pro&display=swap"
+    rel="stylesheet"
+/>
+<link rel="stylesheet" href="./storybook-styles/preview.css" />
+<style>
+    body {
+        font-family: "Lato", sans-serif;
+        font-size: 16px !important;
+    }
+
+    /* Overrides the ArgTypes table tabs to avoid some z-index issues with
+    components that rely on PopperJS (specially Dropdown) */
+    .os-padding {
+        z-index: initial !important;
+    }
+</style>
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
@@ -131,7 +131,11 @@ const preview: Preview = {
         },
         docs: {
             toc: {
+                // Useful for MDX pages
                 headingSelector: "h2, h3",
+                // Prevents including generic headings like "Stories" and "Usage".
+                ignoreSelector:
+                    ".docs-story h2, .docs-story h3, .sbdocs #stories, .sbdocs #usage, .sbdocs-subtitle, .sbdocs h2:first-of-type, .sbdocs .sb-anchor[id='stories'] + h2, .sbdocs .sb-anchor[id='usage'] + h2",
             },
         },
     },
diff --git a/static/perseus-favicon.svg b/static/perseus-favicon.svg
@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 41 41" width="41" height="41">
+  <defs>
+    <linearGradient id="bgGradient" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" style="stop-color:#32d980;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#28ae7b;stop-opacity:1" />
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="2.0" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background circle for logo -->
+  <circle cx="20.5" cy="20.5" r="20" fill="url(#bgGradient)" stroke="#1fa769" stroke-width="0.7"/>
+
+  <g fill="white" filter="url(#glow)">
+    <!-- Top star cluster -->
+    <polygon points="23.8,1.3 24.0,2.9 25.6,2.9 24.7,3.8 24.9,5.3 23.8,4.7 22.6,5.3 22.8,3.8 21.9,2.9 23.4,2.9" />
+    <polygon points="22.2,6.4 22.4,7.6 23.4,7.6 22.9,8.2 23.2,9.4 22.2,8.8 21.3,9.4 21.5,8.2 20.9,7.6 22.0,7.6" />
+    <polygon points="26.4,6.9 26.7,8.1 27.9,8.1 27.2,8.8 27.4,10.0 26.4,9.4 25.3,10.0 25.6,8.8 24.9,8.1 26.1,8.1" />
+
+    <!-- Center constellation -->
+    <polygon points="20.0,10.7 20.2,11.9 21.4,11.9 20.7,12.5 21.1,13.8 20.0,13.2 18.9,13.8 19.2,12.5 18.6,11.9 19.8,11.9" />
+    <polygon points="24.9,12.2 25.2,13.4 26.4,13.4 25.8,14.1 26.0,15.3 24.9,14.7 23.9,15.3 24.1,14.1 23.4,13.4 24.6,13.4" />
+    <polygon points="33.8,10.9 34.0,12.1 35.2,12.1 34.5,12.8 34.7,14.0 33.8,13.4 32.6,14.0 32.9,12.8 32.3,12.1 33.4,12.1" />
+
+    <!-- Math symbol stars -->
+    <polygon points="14.7,15.2 14.9,16.4 16.1,16.4 15.4,17.1 15.8,18.2 14.7,17.8 13.5,18.2 13.9,17.1 13.2,16.4 14.5,16.4" />
+    <polygon points="25.9,18.2 26.1,19.4 27.3,19.4 26.7,20.1 26.9,21.3 25.9,20.8 24.8,21.3 25.1,20.1 24.5,19.4 25.7,19.4" />
+
+    <!-- Left side constellation -->
+    <polygon points="6.7,15.2 6.9,16.4 8.1,16.4 7.5,17.1 7.8,18.2 6.7,17.8 5.6,18.2 5.9,17.1 5.2,16.4 6.4,16.4" />
+    <polygon points="5.3,11.5 5.6,12.8 6.8,12.8 6.1,13.4 6.4,14.7 5.3,14.1 4.2,14.7 4.6,13.4 3.9,12.8 5.1,12.8" />
+    <polygon points="10.0,10.5 10.2,11.8 11.5,11.8 10.8,12.4 11.1,13.7 10.0,13.1 8.9,13.7 9.2,12.4 8.5,11.8 9.8,11.8" />
+
+    <!-- Bottom constellation -->
+    <polygon points="11.6,25.8 11.9,26.9 13.1,26.9 12.4,27.6 12.7,28.8 11.6,28.2 10.5,28.8 10.8,27.6 10.1,26.9 11.3,26.9" />
+    <polygon points="27.1,23.5 27.3,24.8 28.6,24.8 27.9,25.5 28.1,26.7 27.1,26.1 26.0,26.7 26.2,25.5 25.6,24.8 26.8,24.8" />
+    <polygon points="29.8,28.9 30.0,30.1 31.3,30.1 30.5,30.8 30.8,32.0 29.8,31.4 28.6,32.0 28.9,30.8 28.2,30.1 29.4,30.1" />
+
+    <!-- Final bottom stars -->
+    <polygon points="9.3,31.3 9.6,32.6 10.8,32.6 10.1,33.3 10.4,34.6 9.3,34.0 8.2,34.6 8.5,33.3 7.9,32.6 9.1,32.6" />
+    <polygon points="14.0,32.6 14.2,33.8 15.5,33.8 14.8,34.4 15.1,35.6 14.0,35.1 12.9,35.6 13.2,34.4 12.5,33.8 13.8,33.8" />
+  </g>
+
+  <!-- Constellation connecting lines properly scaled -->
+  <g stroke="white" stroke-width="0.18" stroke-opacity="0.8" fill="none">
+    <!-- Top cluster connections -->
+    <line x1="23.8" y1="2.8" x2="22.2" y2="8.2" />
+    <line x1="22.2" y1="8.2" x2="26.4" y2="8.8" />
+    <line x1="23.8" y1="2.8" x2="26.4" y2="8.8" />
+
+    <!-- Center connections -->
+    <line x1="24.9" y1="13.4" x2="33.8" y2="12.1" />
+    <line x1="21.3" y1="12.0" x2="14.7" y2="16.6" />
+    <line x1="24.9" y1="13.4" x2="25.9" y2="19.9" />
+    <line x1="26.4" y1="8.8" x2="24.9" y2="13.4" />
+
+    <!-- Left side constellation connections -->
+    <line x1="22.2" y1="8.2" x2="20.0" y2="12.0" />
+    <line x1="14.7" y1="16.6" x2="6.7" y2="16.4" />
+    <line x1="6.7" y1="16.4" x2="5.3" y2="12.8" />
+    <line x1="5.3" y1="12.8" x2="10.0" y2="11.8" />
+
+    <!-- Bottom connections -->
+    <line x1="11.6" y1="27.1" x2="14.7" y2="16.6" />
+    <line x1="25.9" y1="21.2" x2="27.1" y2="24.8" />
+    <line x1="27.1" y1="24.8" x2="29.8" y2="30.1" />
+    <line x1="11.6" y1="27.1" x2="27.1" y2="24.8" />
+
+    <!-- Final bottom connections -->
+    <line x1="11.6" y1="27.1" x2="9.3" y2="32.6" />
+    <line x1="9.3" y1="33.9" x2="14.0" y2="35.2" />
+  </g>
+
+  <!-- Educational elements overlay properly positioned -->
+  <g fill="white" fill-opacity="0.9" font-family="Arial, sans-serif" font-size="2.9" font-weight="bold">
+    <!-- Mathematical symbols integrated into design -->
+    <text x="14.1" y="18.4" text-anchor="middle">∑</text>
+    <text x="25.9" y="20.7" text-anchor="middle">π</text>
+    <text x="11.4" y="28.4" text-anchor="middle">∫</text>
+  </g>
+</svg>
diff --git a/static/storybook-styles/preview.css b/static/storybook-styles/preview.css
@@ -0,0 +1,59 @@
+/**
+ * Overrides for the Storybook preview iframe.
+ */
+html {
+    font-size: 62.5%;
+}
+
+/* These overrides depend on a Base 10 font size */
+.sb-show-main.sb-main-padded {
+    padding: 0.8rem;
+}
+
+.sbdocs.sbdocs-wrapper {
+    padding: 0 2rem 3.2rem 2rem;
+    gap: 2.4rem;
+}
+
+.sbdocs ul,
+.sbdocs li,
+.sbdocs p,
+.sbdocs p *:not(a) {
+    color: var(--wb-semanticColor-core-foreground-neutral-strong);
+    font-size: var(--wb-font-size-small);
+    line-height: var(--wb-font-lineHeight-small);
+}
+
+.sbdocs .docblock-argstable p,
+.sbdocs .docblock-argstable ul,
+.sbdocs .docblock-argstable li {
+    font-size: 1em;
+}
+
+/* TOC wrapper */
+.sbdocs-content + div {
+    width: 14rem;
+}
+
+.sbdocs-content + div > * {
+    width: 14rem;
+    padding-top: 6.4rem;
+    padding-bottom: 3.2rem;
+}
+
+/* TOC navigation styling */
+.sbdocs aside {
+    width: 26rem !important;
+}
+
+.sbdocs aside nav {
+    width: 21rem !important;
+}
+
+/* Hide unwanted headings in TOC navigation */
+.sbdocs aside nav a[href="#stories"],
+.sbdocs aside nav a[href="#usage"],
+.sbdocs aside nav a[title="Stories"],
+.sbdocs aside nav a[title="Usage"] {
+    display: none !important;
+}

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ body {`
`13`	`13`	`"Helvetica", "Corbel", sans-serif;`
`14`	`14`	`font-size: 14px;`
`15`	`15`	`margin: 0;`
`16`		`- color: var(--wb-semanticColor-text-primary);`
	`16`	`+ color: var(--wb-semanticColor-core-foreground-neutral-strong);`
`17`	`17`	`line-height: 1.4;`
`18`	`18`	`min-width: 0;`
`19`	`19`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+<link rel="icon" type="image/svg+xml" href="./perseus-favicon.svg" />`
	`2`	`+<link rel="shortcut icon" href="./perseus-favicon.svg" />`