[Draft] Docs v2 Redesign (#144)

.env.example

@@ -0,0 +1,8 @@
+# Grid Docs Environment Variables
+# Copy this file to .env and fill in the values
+# DO NOT commit .env to the repository
+
+# Central Icons React Library License
+# Get your license key from https://www.npmjs.com/package/@central-icons-react/all
+# Required for npm run build:icons
+CENTRAL_LICENSE_KEY=your-license-key-here

.gitignore

@@ -32,3 +32,9 @@ local.properties
 # Figma design tokens (local reference only)
 mintlify/tokens/
 
+# Development reference files
+refs/
+figma-*.md
+
+# Cursor IDE rules (personal config)
+.cursor/rules/

CLAUDE.md

@@ -155,6 +155,32 @@ Webhooks use **P-256 ECDSA signatures** in the `X-Grid-Signature` header for ver
 - Use relative paths for internal links
 - The mintlify subdirectory has its own CLAUDE.md with additional guidance
 
+### Mintlify CLI Version (Important)
+
+**Use Mintlify CLI version 4.2.284** for local development. Newer versions (e.g., 4.2.312) have a bug where the API reference pages render blank when using the palm theme with OpenAPI auto-generation.
+
+```bash
+# Check current version
+mintlify --version
+
+# If needed, install the working version
+npm install -g mintlify@4.2.284 --force
+```
+
+### Troubleshooting: API Reference Not Showing
+
+If the API reference pages appear blank (only showing title and navigation, no endpoint details):
+
+1. **Restart the dev server** - hot reload sometimes fails:
+   ```bash
+   pkill -f "mint.*dev"
+   cd mintlify && mint dev
+   ```
+
+2. **Check CLI version** - ensure you're on 4.2.284 (see above)
+
+3. **Verify OpenAPI spec** - run `mint openapi-check openapi.yaml` in the mintlify folder
+
 ### Documentation Philosophy
 
 - **Document just enough** for user success - balance between too much and too little

mintlify/api-reference/authentication.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Authentication"
+icon: "/images/icons/key2.svg"
 ---
 import { topLevelProductName } from '/snippets/variables.mdx'
 

mintlify/api-reference/environments.mdx

@@ -1,5 +1,6 @@
 ---
 title: 'Environments'
+icon: "/images/icons/globe.svg"
 ---
 import { topLevelProductName } from '/snippets/variables.mdx'
 

mintlify/api-reference/terminology.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Core Concepts"
 description: "Core concepts and terminology for the Grid API"
+icon: "/images/icons/file-text.svg"
 ---
 
 import Terminology from '/snippets/terminology.mdx';

mintlify/developer-resources/samples.mdx

@@ -1,12 +1,13 @@
 ---
 title: "Samples"
+icon: "/images/icons/github.svg"
 ---
 
 <Note>
 Explore end-to-end sample apps and snippets in our public repository.
 </Note>
 
-<Card title="Grid Samples on GitHub" icon="github" href="https://github.com/lightsparkdev/grid-api/tree/main/samples">
+<Card title="Grid Samples on GitHub" icon="/images/icons/github.svg" href="https://github.com/lightsparkdev/grid-api/tree/main/samples">
 Browse runnable examples for quickstarts and integrations.
 </Card>
 

mintlify/docs.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "mint",
+  "theme": "palm",
   "name": "Grid API Documentation",
   "description": "The Grid API enables modern financial institutions to easily send and receive global payments.  The following documentation helps developers understand the Grid API and how to integrate with it.",
   "colors": {
@@ -17,53 +17,65 @@
   "fonts": {
     "heading": {
       "family": "Suisse Intl",
-      "source": "/fonts/suisse-intl/SuisseIntl-Medium.woff2",
-      "format": "woff2",
       "weight": 500
     },
     "body": {
       "family": "Suisse Intl",
-      "source": "/fonts/suisse-intl/SuisseIntl-Regular.woff2",
-      "format": "woff2",
       "weight": 400
     }
   },
-  "favicon": "/favicon.svg",
+  "favicon": {
+    "light": "/favicon-dark.svg",
+    "dark": "/favicon-light.svg"
+  },
   "navigation": {
     "tabs": [
       {
-        "tab": "Home",
-        "pages": ["index"]
-      },
-      {
-        "tab": "Platform Overview",
-        "pages": [
+        "tab": "Get started",
+        "groups": [
           {
-            "group": "Introduction",
+            "group": "Overview",
             "pages": [
+              "index",
               "platform-overview/introduction/what-is-grid",
+              "platform-overview/capabilities",
+              "platform-overview/use-cases",
               "platform-overview/introduction/faq"
             ]
           },
           {
-            "group": "Core Concepts",
+            "group": "Quickstart",
+            "pages": [
+              "platform-overview/quickstart/payouts",
+              "platform-overview/quickstart/ramps",
+              "platform-overview/quickstart/rewards",
+              "platform-overview/quickstart/p2p"
+            ]
+          },
+          {
+            "group": "Core concepts",
             "pages": [
               "platform-overview/core-concepts/entities",
               "platform-overview/core-concepts/quote-system",
               "platform-overview/core-concepts/account-model",
               "platform-overview/core-concepts/transaction-lifecycle",
-              "platform-overview/core-concepts/currencies-and-rails"
+              "platform-overview/core-concepts/currencies-and-rails",
+              "platform-overview/configuration"
             ]
           }
         ]
       },
       {
         "tab": "Payouts & B2B",
-        "pages": [
-          "payouts-and-b2b/index",
-          "payouts-and-b2b/terminology",
-          "payouts-and-b2b/onboarding/implementation-overview",
-          "payouts-and-b2b/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "payouts-and-b2b/index",
+              "payouts-and-b2b/terminology",
+              "payouts-and-b2b/onboarding/implementation-overview"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -101,11 +113,15 @@
       },
       {
         "tab": "Ramps",
-        "pages": [
-          "ramps/index",
-          "ramps/terminology",
-          "ramps/onboarding/implementation-overview",
-          "ramps/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "ramps/index",
+              "ramps/terminology",
+              "ramps/onboarding/implementation-overview"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -141,11 +157,15 @@
       },
       {
         "tab": "Rewards",
-        "pages": [
-          "rewards/index",
-          "rewards/terminology",
-          "rewards/developer-guides/implementation-overview",
-          "rewards/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "rewards/index",
+              "rewards/terminology",
+              "rewards/developer-guides/implementation-overview"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -179,11 +199,15 @@
       },
       {
         "tab": "Global P2P",
-        "pages": [
-          "global-p2p/index",
-          "global-p2p/terminology",
-          "global-p2p/getting-started/implementation-overview",
-          "global-p2p/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "global-p2p/index",
+              "global-p2p/terminology",
+              "global-p2p/getting-started/implementation-overview"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -247,28 +271,26 @@
   "navbar": {
     "links": [
       {
-        "label": "Github",
+        "label": "GitHub",
         "href": "https://github.com/lightsparkdev/grid-api",
         "icon": "github"
+      },
+      {
+        "label": "Contact sales",
+        "href": "https://lightspark.com/grid#signup"
       }
-    ],
-    "primary": {
-      "type": "button",
-      "label": "Contact Sales",
-      "href": "https://lightspark.com/grid#signup"
-    }
+    ]
+  },
+  "modeToggle": {
+    "default": "light",
+    "isHidden": false
   },
   "contextual": {
     "options": ["copy", "view", "chatgpt", "claude"]
   },
-  "footer": {
-    "socials": {
-      "x": "https://x.com/lightspark",
-      "github": "https://github.com/lightsparkdev",
-      "linkedin": "https://linkedin.com/company/lightspark-group"
-    }
-  },
+  "footer": {},
   "head": {
+    "raw": "<style>#header:empty,#page-title:empty{display:none!important}</style><script>if(location.pathname==='/'||location.pathname==='/index'||location.pathname===''){document.write('<style>header#header,#page-title,#page-context-menu-button,#page-context-menu,.eyebrow,#pagination,[class*=\"space-y-2\"]>*{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important;margin:0!important;padding:0!important}</style>');document.documentElement.classList.add('is-homepage');}</script><style>html.is-homepage #pagination,body.is-homepage #pagination,html.is-homepage #footer,body.is-homepage #footer,html.is-homepage header#header,body.is-homepage header#header,html.is-homepage #page-title,body.is-homepage #page-title,html.is-homepage #page-context-menu-button,body.is-homepage #page-context-menu-button,html.is-homepage #page-context-menu,body.is-homepage #page-context-menu,html.is-homepage .eyebrow,body.is-homepage .eyebrow{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important}</style>",
     "links": [
       {
         "rel": "preload",

mintlify/global-p2p/country-support.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Supported Countries"
 description: "Grid availability and payment support"
+icon: "/images/icons/globe.svg"
 ---
 import CountrySupport from '/snippets/country-support.mdx';
 

mintlify/global-p2p/getting-started/implementation-overview.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Implementation Overview"
 description: "High-level implementation plan for configuring, onboarding, funding, and moving money"
+icon: "/images/icons/code.svg"
 ---
 This page gives you a 10,000‑ft view of an end‑to‑end implementation. It is intentionally generalized because the flow supports multiple customer types and external account types (e.g., CLABE, IBAN, US accounts, UPI). The detailed guides that follow provide concrete fields, edge cases, and step‑by‑step instructions.
 

mintlify/global-p2p/getting-started/platform-configuration.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Platform Configuration"
 description: "Configuring credentials, webhooks and currencies for your platform global P2P payments"
+icon: "/images/icons/settings-gear2.svg"
 ---
 import PlatformConfigAPI from '/snippets/platform-config-currency-api-webhooks.mdx';
 import { topLevelProductName } from '/snippets/variables.mdx';

mintlify/global-p2p/index.mdx

@@ -1,23 +1,32 @@
 ---
-title: "Introduction"
-description: "Overview of Global P2P: capabilities, flows"
+title: "Global P2P"
+sidebarTitle: "Introduction"
+icon: "/images/icons/at.svg"
+mode: "wide"
 ---
 import { remittanceProductName, topLevelProductName } from '/snippets/variables.mdx';
 import PaymentFlow from '/snippets/payment-flow.mdx';
+import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx';
+
+<img 
+  src="/images/heroes/hero-globalp2p.jpg" 
+  alt="Global P2P hero"
+  style={{ width: '100%', borderRadius: '8px' }}
+/>
 
 With {remittanceProductName}, you can send and receive low cost real-time payments to bank accounts and UMA addresses worldwide through a single, simple API. {topLevelProductName} automatically routes each payment across its network of Grid switches, handling FX, blockchain settlement, and instant banking off-ramps for you.
 
-<CardGroup cols={3}>
-  <Card title="Single API, global reach" icon="bolt">
-     {remittanceProductName} interacts with the Money Grid to route your payments globally.
-  </Card>
-  <Card title="No Crypto Handling" icon="shield-check">
+<FeatureCardGrid cols={3}>
+  <FeatureCard icon="/images/icons/globe.svg" title="Single API, global reach">
+    {remittanceProductName} interacts with the Money Grid to route your payments globally.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/shield.svg" title="No Crypto Handling">
     Leverages local instant banking rails and global low latency crypto rails to settle payments in real-time.
-  </Card>
-  <Card title="Instant Delivery" icon="rocket">
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/paper-plane-top-right.svg" title="Instant Delivery">
     Leverages local instant banking rails and global low latency crypto rails to settle payments in real-time.
-  </Card>
-</CardGroup>
+  </FeatureCard>
+</FeatureCardGrid>
 
 <Note>For background on the UMA protocol itself, see the UMA Standard documentation: [UMA Standard—Introduction](https://docs.uma.me/uma-standard/introduction).</Note>
 

mintlify/global-p2p/managing-accounts/external-accounts.mdx

@@ -1,6 +1,7 @@
 ---
 title: "External Accounts"
 description: "Register and manage beneficiary bank accounts"
+icon: "/images/icons/bank.svg"
 ---
 
 import ExternalAccounts from '/snippets/external-accounts.mdx';

mintlify/global-p2p/managing-accounts/internal-accounts.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Internal Accounts"
 description: "Create and manage internal accounts"
+icon: "/images/icons/wallet1.svg"
 ---
 
 import InternalAccounts from '/snippets/internal-accounts.mdx';

mintlify/global-p2p/managing-accounts/plaid.mdx

@@ -1,6 +1,7 @@
 ---
 title: "External Accounts with Plaid"
 description: "Simplify bank account linking with Plaid"
+icon: "/images/icons/IconPlaid.svg"
 ---
 
 import PlaidIntegration from '/snippets/plaid-integration.mdx';