PolicyEngine · SakshiKekre · Oct 31, 2025 · Nov 2, 2025 · Nov 2, 2025 · Nov 3, 2025
diff --git a/app/package-lock.json b/app/package-lock.json
diff --git a/app/package.json b/app/package.json
@@ -31,13 +31,17 @@
     "@tabler/icons-react": "^3.34.0",
     "@tanstack/react-query": "^5.84.1",
     "@tanstack/react-query-devtools": "^5.83.0",
+    "@uiw/codemirror-extensions-langs": "^4.25.2",
+    "@uiw/codemirror-theme-github": "^4.25.2",
+    "@uiw/react-codemirror": "^4.25.2",
     "dayjs": "^1.11.13",
     "framer-motion": "^12.23.24",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-plotly.js": "^2.6.0",
     "react-redux": "^9.2.0",
     "react-router-dom": "^7.9.3",
+    "thememirror": "^2.0.1",
     "wordwrapjs": "^5.1.1"
   },
   "devDependencies": {
@@ -76,4 +80,4 @@
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.3"
   }
-}
+}
diff --git a/app/src/Router.tsx b/app/src/Router.tsx
@@ -6,6 +6,7 @@ import { PolicyCreationFlow } from './flows/policyCreationFlow';
 import { PopulationCreationFlow } from './flows/populationCreationFlow';
 import { ReportCreationFlow } from './flows/reportCreationFlow';
 import { SimulationCreationFlow } from './flows/simulationCreationFlow';
+import APIPage from './pages/API.page';
 import DashboardPage from './pages/Dashboard.page';
 import DonatePage from './pages/Donate.page';
 import HomePage from './pages/Home.page';
@@ -101,6 +102,21 @@ const router = createBrowserRouter(
             },
           ],
         },
+        // Static pages that need metadata - use MetadataLazyLoader + StaticLayout
+        {
+          element: <MetadataLazyLoader />,
+          children: [
+            {
+              element: <StaticLayout />,
+              children: [
+                {
+                  path: 'api',
+                  element: <APIPage />,
+                },
+              ],
+            },
+          ],
+        },
         // Routes that don't need metadata at all (no guard)
         {
           element: <Layout />,

diff --git a/app/src/components/home-header/DesktopNavigation.tsx b/app/src/components/home-header/DesktopNavigation.tsx
@@ -11,12 +11,14 @@ interface NavLink {
 interface DesktopNavigationProps {
   navLinks: NavLink[];
   aboutLinks: NavLink[];
+  learnLinks: NavLink[];
   onNavClick: (path?: string) => void;
 }
 
 export default function DesktopNavigation({
   navLinks,
   aboutLinks,
+  learnLinks,
   onNavClick,
 }: DesktopNavigationProps) {
   const countryId = useCurrentCountry();
@@ -74,6 +76,31 @@ export default function DesktopNavigation({
           {link.label}
         </Anchor>
       ))}
+
+      <Menu shadow="md" width={200} zIndex={1001} position="bottom" offset={10}>
+        <Menu.Target>
+          <UnstyledButton>
+            <Group gap={4} align="center">
+              <Text
+                c={colors.text.inverse}
+                fw={typography.fontWeight.medium}
+                size="18px"
+                style={{ fontFamily: typography.fontFamily.primary }}
+              >
+                Learn
+              </Text>
+              <IconChevronDown size={18} color={colors.text.inverse} />
+            </Group>
+          </UnstyledButton>
+        </Menu.Target>
+        <Menu.Dropdown>
+          {learnLinks.map((link) => (
+            <Menu.Item key={link.label} onClick={() => onNavClick(link.path)}>
+              {link.label}
+            </Menu.Item>
+          ))}
+        </Menu.Dropdown>
+      </Menu>
     </Group>
   );
 }
diff --git a/app/src/components/home-header/HeaderContent.tsx b/app/src/components/home-header/HeaderContent.tsx
@@ -15,6 +15,7 @@ interface HeaderContentProps {
   onClose: () => void;
   navLinks: NavLink[];
   aboutLinks: NavLink[];
+  learnLinks: NavLink[];
   onNavClick: (path?: string) => void;
 }
 
@@ -24,6 +25,7 @@ export default function HeaderContent({
   onClose,
   navLinks,
   aboutLinks,
+  learnLinks,
   onNavClick,
 }: HeaderContentProps) {
   return (
@@ -41,7 +43,12 @@ export default function HeaderContent({
       <Group justify="space-between" h="100%">
         <Group>
           <HeaderLogo />
-          <DesktopNavigation navLinks={navLinks} aboutLinks={aboutLinks} onNavClick={onNavClick} />
+          <DesktopNavigation
+            navLinks={navLinks}
+            aboutLinks={aboutLinks}
+            learnLinks={learnLinks}
+            onNavClick={onNavClick}
+          />
         </Group>
 
         <Group visibleFrom="lg">
@@ -54,6 +61,7 @@ export default function HeaderContent({
           onClose={onClose}
           navLinks={navLinks}
           aboutLinks={aboutLinks}
+          learnLinks={learnLinks}
           onNavClick={onNavClick}
         />
       </Group>

diff --git a/app/src/components/home-header/MobileMenu.tsx b/app/src/components/home-header/MobileMenu.tsx
@@ -13,6 +13,7 @@ interface MobileMenuProps {
   onClose: () => void;
   navLinks: NavLink[];
   aboutLinks: NavLink[];
+  learnLinks: NavLink[];
   onNavClick: (path?: string) => void;
 }
 
@@ -22,6 +23,7 @@ export default function MobileMenu({
   onClose,
   navLinks,
   aboutLinks,
+  learnLinks,
   onNavClick,
 }: MobileMenuProps) {
   return (
@@ -95,6 +97,37 @@ export default function MobileMenu({
               </Anchor>
             ))}
           </Box>
+
+          <Divider color={colors.border.dark} />
+
+          {/* Learn Section */}
+          <Box>
+            <Text
+              c={colors.text.inverse}
+              fw={typography.fontWeight.medium}
+              size="sm"
+              mb={spacing.xs}
+              style={{ fontFamily: typography.fontFamily.primary }}
+            >
+              Learn
+            </Text>
+            <Stack gap={spacing.xs} pl={spacing.md}>
+              {learnLinks.map((link) => (
+                <Anchor
+                  key={link.label}
+                  c={colors.text.inverse}
+                  variant="subtle"
+                  td="none"
+                  fw={typography.fontWeight.normal}
+                  size="sm"
+                  onClick={() => onNavClick(link.path)}
+                  style={{ fontFamily: typography.fontFamily.primary }}
+                >
+                  {link.label}
+                </Anchor>
+              ))}
+            </Stack>
+          </Box>
         </Stack>
       </Drawer>
     </>

diff --git a/app/src/components/shared/HomeHeader.tsx b/app/src/components/shared/HomeHeader.tsx
@@ -19,6 +19,8 @@ export default function HeaderNavigation() {
     { label: 'Supporters', path: `/${countryId}/supporters` },
   ];
 
+  const learnLinks: NavLink[] = [{ label: 'API', path: `/${countryId}/api` }];
+
   const navLinks: NavLink[] = [{ label: 'Donate', path: `/${countryId}/donate` }];
 
   const handleNavClick = (path?: string) => {
@@ -61,6 +63,7 @@ export default function HeaderNavigation() {
         onClose={close}
         navLinks={navLinks}
         aboutLinks={aboutLinks}
+        learnLinks={learnLinks}
         onNavClick={handleNavClick}
       />
     </div>

diff --git a/app/src/components/shared/static/APIMetadataCard.tsx b/app/src/components/shared/static/APIMetadataCard.tsx
@@ -0,0 +1,116 @@
+import { Badge, Card, Stack, Text } from '@mantine/core';
+import { colors, spacing, typography } from '@/designTokens';
+
+interface ParameterMetadata {
+  type: 'parameter';
+  parameter: string;
+  label?: string;
+  description?: string;
+  unit?: string;
+  period?: string | null;
+  economy?: boolean;
+  household?: boolean;
+  values?: Record<string, number>;
+}
+
+interface VariableMetadata {
+  name: string;
+  label?: string;
+  description?: string;
+  entity?: string;
+  definitionPeriod?: string;
+  unit?: string;
+  category?: string;
+  defaultValue?: number;
+  isInputVariable?: boolean;
+  valueType?: string;
+}
+
+interface APIMetadataCardProps {
+  metadata: ParameterMetadata | VariableMetadata;
+  onClick?: () => void;
+}
+
+export default function APIMetadataCard({ metadata, onClick }: APIMetadataCardProps) {
+  const isParameter = 'type' in metadata && metadata.type === 'parameter';
+  const paramData = isParameter ? (metadata as ParameterMetadata) : null;
+  const varData = !isParameter ? (metadata as VariableMetadata) : null;
+
+  const displayLabel = paramData?.label || varData?.label || varData?.name || '';
+  const description = metadata.description || '';
+  const pythonName = paramData?.parameter || varData?.name || '';
+
+  return (
+    <Card
+      shadow="xs"
+      padding={spacing.md}
+      radius="md"
+      onClick={onClick}
+      style={{
+        cursor: onClick ? 'pointer' : 'default',
+        transition: 'box-shadow 0.2s ease',
+        backgroundColor: colors.white,
+        border: `1px solid ${colors.gray[200]}`,
+        height: '100%',
+      }}
+      styles={{
+        root: {
+          '&:hover': {
+            boxShadow: onClick ? '0 4px 12px rgba(0,0,0,0.1)' : undefined,
+          },
+        },
+      }}
+    >
+      <Stack gap={spacing.sm}>
+        <Badge color={isParameter ? 'primary' : 'blue'} variant="light" size="sm">
+          {isParameter ? 'Parameter' : 'Variable'}
+        </Badge>
+
+        <Text fw={typography.fontWeight.semibold} style={{ fontSize: typography.fontSize.base }}>
+          {displayLabel}
+        </Text>
+
+        {description && (
+          <Text
+            style={{
+              fontSize: typography.fontSize.sm,
+              color: colors.text.secondary,
+              lineHeight: 1.5,
+            }}
+          >
+            {description}
+          </Text>
+        )}
+
+        {varData?.entity && (
+          <Text style={{ fontSize: typography.fontSize.xs, color: colors.text.tertiary }}>
+            <strong>Entity:</strong> {varData.entity}
+          </Text>
+        )}
+
+        {(paramData?.period || varData?.definitionPeriod) && (
+          <Text style={{ fontSize: typography.fontSize.xs, color: colors.text.tertiary }}>
+            <strong>Period:</strong> {paramData?.period || varData?.definitionPeriod}
+          </Text>
+        )}
+
+        {metadata.unit && (
+          <Text style={{ fontSize: typography.fontSize.xs, color: colors.text.tertiary }}>
+            <strong>Unit:</strong> {metadata.unit}
+          </Text>
+        )}
+
+        <Text
+          style={{
+            fontSize: typography.fontSize.xs,
+            color: colors.text.tertiary,
+            wordBreak: 'break-all',
+            fontFamily: typography.fontFamily.mono,
+          }}
+        >
+          <strong>Python name:</strong> {pythonName}
+        </Text>
+      </Stack>
+    </Card>
+  );
+}
diff --git a/app/src/components/shared/static/APIPlayground.tsx b/app/src/components/shared/static/APIPlayground.tsx
@@ -0,0 +1,24 @@
+import { Box } from '@mantine/core';
+import { spacing } from '@/designTokens';
+
+interface APIPlaygroundProps {
+  countryId: string;
+}
+
+export default function APIPlayground({ countryId }: APIPlaygroundProps) {
+  const streamlitUrl = `https://policyengine-policyengine-api-demo-app-xy5rgn.streamlit.app/?embed=true&embed_options=light_theme&embed_options=hide_footer&mode=${countryId}`;
+
+  return (
+    <Box
+      component="iframe"
+      src={streamlitUrl}
+      style={{
+        width: '100%',
+        height: '600px',
+        border: 'none',
+        borderRadius: spacing.radius.lg,
+      }}
+      title="API Playground"
+    />
+  );
+}
diff --git a/app/src/components/shared/static/ActionButton.tsx b/app/src/components/shared/static/ActionButton.tsx
@@ -8,6 +8,7 @@ export interface ActionButtonProps {
   variant?: 'primary' | 'secondary' | 'inverted';
   multiline?: boolean;
   caption?: string;
+  target?: '_blank' | '_self';
 }
 
 export default function ActionButton({
@@ -16,6 +17,7 @@ export default function ActionButton({
   variant = 'primary',
   multiline = false,
   caption,
+  target = '_blank',
 }: ActionButtonProps) {
   const buttonRef = useRef<HTMLAnchorElement>(null);
   const [buttonWidth, setButtonWidth] = useState<number | null>(null);
@@ -64,8 +66,8 @@ export default function ActionButton({
         ref={buttonRef}
         component="a"
         href={href}
-        target="_blank"
-        rel="noopener noreferrer"
+        target={target}
+        rel={target === '_blank' ? 'noopener noreferrer' : undefined}
         size="lg"
         px={spacing.xl}
         py={spacing.lg}