Merge pull request #865 from karrioapi/fix/web-dark-mode-readability

[fix] dark mode readability in docs

Author: akaylia123

apps/web/src/app/docs/api-reference/page.tsx

@@ -20,8 +20,21 @@ declare global {
 }
 
 export default function ApiReferencePage() {
-  const { theme } = useTheme();
+  const { resolvedTheme } = useTheme();
   const [mounted, setMounted] = useState(false);
+  const getStoredTheme = (): 'light' | 'dark' => {
+    if (typeof window === 'undefined') return 'light';
+    try {
+      const stored = window.localStorage.getItem('theme-content');
+      if (stored === 'dark' || stored === 'light') return stored;
+      if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
+    } catch { }
+    return 'light';
+  };
+  // Revert to light-mode-only code styling (rely on component defaults for dark)
+  useEffect(() => {
+    if (!mounted) return;
+  }, [mounted]);
 
   useEffect(() => {
     setMounted(true);
@@ -30,11 +43,21 @@ export default function ApiReferencePage() {
   return (
     <div className="w-full h-full bg-background dark:bg-neutral-950">
       <elements-api
+        key={(mounted ? (resolvedTheme as 'light' | 'dark' | undefined) : undefined) ?? getStoredTheme()}
         apiDescriptionUrl="/openapi.yml"
         router="hash"
         layout="responsive"
-        theme={mounted ? (theme === 'dark' ? 'dark' : 'light') : 'light'}
-        className="w-full h-[calc(100vh-56px)]"
+        theme={((mounted ? resolvedTheme : undefined) ?? getStoredTheme()) === 'dark' ? 'dark' : 'light'}
+        className="w-full h-[calc(100vh-56px)] custom-docs-theme"
+        data-theme={(mounted ? (resolvedTheme as 'light' | 'dark' | undefined) : undefined) ?? getStoredTheme()}
+        style={{
+          background: 'transparent',
+          // Attempt to override internal surface variables used by some web components
+          ['--color-canvas' as any]: 'transparent',
+          ['--color-bg' as any]: 'transparent',
+          ['--sl-color-bg' as any]: 'transparent',
+          ['--sl-color-surface' as any]: 'transparent'
+        } as React.CSSProperties}
         hideSchemas="true"
         hideTryIt="true"
       />

apps/web/src/app/docs/developing/carrier-integration/page.mdx

@@ -32,8 +32,7 @@ flowchart TD
     Test --> Validate[Validate Integration]
     Validate --> End([Complete])
 
-    style Start fill:#f9f,stroke:#333,stroke-width:2px
-    style End fill:#9f9,stroke:#333,stroke-width:2px
+    
 ```
 
 ## Prerequisites

apps/web/src/app/docs/developing/dashboard-guide/developer-tools/page.mdx

@@ -105,16 +105,11 @@ Direct links to common developer tasks:
 - **Check Logs**: Monitor recent API activity
 - **Configure Webhooks**: Set up event notifications
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Developer Dashboard Benefits
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    The developer dashboard provides real-time visibility into your integration
-    health, helping you monitor performance, debug issues, and optimize your
-    implementation.
-  </p>
-</div>
+> [!TIP]
+>
+> **Developer Dashboard Benefits**
+>
+> The developer dashboard provides real-time visibility into your integration health, helping you monitor performance, debug issues, and optimize your implementation.
 
 ## API Keys Management
 
@@ -244,16 +239,11 @@ Handle webhook events effectively:
 }
 ```
 
-<div className="bg-orange-50 dark:bg-orange-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-orange-700 dark:text-orange-300 mb-2">
-    ⚠️ Webhook Security
-  </div>
-  <p className="text-sm text-orange-600 dark:text-orange-400">
-    Always validate webhook signatures to ensure events come from Karrio. Store
-    webhook secrets securely and use HTTPS endpoints for receiving
-    notifications.
-  </p>
-</div>
+> [!WARNING]
+>
+> **Webhook Security**
+>
+> Always validate webhook signatures to ensure events come from Karrio. Store webhook secrets securely and use HTTPS endpoints for receiving notifications.
 
 ## API Logs and Monitoring
 
@@ -544,16 +534,11 @@ Built-in debugging assistance:
 - **Endpoint Efficiency**: Choose optimal API endpoints
 - **Batch Processing**: Reduce API call overhead
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Developer Best Practices
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    Use the developer tools regularly to monitor integration health, debug
-    issues proactively, and optimize performance. Set up appropriate alerts and
-    monitoring to catch issues before they impact users.
-  </p>
-</div>
+> [!TIP]
+>
+> **Developer Best Practices**
+>
+> Use the developer tools regularly to monitor integration health, debug issues proactively, and optimize performance. Set up appropriate alerts and monitoring to catch issues before they impact users.
 
 ## API Usage Optimization
 

apps/web/src/app/docs/developing/dashboard-guide/document-templates/page.mdx

@@ -142,16 +142,11 @@ Build templates with the visual designer:
 - **Shipping Info**: Carriers, services, tracking
 - **Company Details**: Business information
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Template Variables
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    Use template variables like `{order.order_id}` or `{customer.name}` to
-    dynamically populate document content. The system automatically replaces
-    these with actual data when generating documents.
-  </p>
-</div>
+> [!TIP]
+>
+> **Template Variables**
+>
+> Use template variables like `{order.order_id}` or `{customer.name}` to dynamically populate document content. The system automatically replaces these with actual data when generating documents.
 
 ## Template Designer Features
 
@@ -302,16 +297,11 @@ Show content based on conditions:
 {{formatTime shipment.pickup_time "h:mm A"}}
 ```
 
-<div className="bg-orange-50 dark:bg-orange-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-orange-700 dark:text-orange-300 mb-2">
-    ⚠️ Data Availability
-  </div>
-  <p className="text-sm text-orange-600 dark:text-orange-400">
-    Template variables depend on the context where the template is used. Not all
-    data is available in every situation. Test templates thoroughly with
-    different data scenarios.
-  </p>
-</div>
+> [!WARNING]
+>
+> **Data Availability**
+>
+> Template variables depend on the context where the template is used. Not all data is available in every situation. Test templates thoroughly with different data scenarios.
 
 ## Template Management
 

apps/web/src/app/docs/developing/dashboard-guide/label-creation/page.mdx

@@ -125,16 +125,11 @@ Add optional services:
 - **Declared Value**: Custom value declaration
 - **Hold at Location**: Delivery to pickup location
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Smart Defaults
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    The form remembers your preferences and automatically populates common
-    options like currency, shipping date, and package types based on your
-    previous shipments.
-  </p>
-</div>
+> [!TIP]
+>
+> **Smart Defaults**
+>
+> The form remembers your preferences and automatically populates common options like currency, shipping date, and package types based on your previous shipments.
 
 ### 4. Rate Comparison
 
@@ -211,15 +206,11 @@ For each item in the shipment:
 - **Unit Value**: Price per item
 - **Origin Country**: Country of manufacture
 
-<div className="bg-orange-50 dark:bg-orange-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-orange-700 dark:text-orange-300 mb-2">
-    ⚠️ Customs Accuracy
-  </div>
-  <p className="text-sm text-orange-600 dark:text-orange-400">
-    Accurate customs information is required for international shipments.
-    Incorrect declarations can cause delays, additional fees, or customs holds.
-  </p>
-</div>
+> [!WARNING]
+>
+> **Customs Accuracy**
+>
+> Accurate customs information is required for international shipments. Incorrect declarations can cause delays, additional fees, or customs holds.
 
 ## Payment and Billing
 

apps/web/src/app/docs/developing/dashboard-guide/page.mdx

@@ -97,10 +97,6 @@ flowchart TD
     F --> G[Automatic Tracking]
     G --> H[Delivery Updates]
 
-    style A fill:#e1f5fe
-    style D fill:#fff3e0
-    style F fill:#e8f5e8
-    style H fill:#f3e5f5
 ```
 
 ## Best Practices

apps/web/src/app/docs/developing/dashboard-guide/test-mode/page.mdx

@@ -49,15 +49,11 @@ Test mode uses carrier sandbox APIs and test credentials, allowing you to:
 - **Tracking**: Monitor simulated package deliveries
 - **Error Handling**: Test edge cases and error scenarios
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Test Mode Indicators
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    Test mode is clearly indicated throughout the dashboard with visual cues
-    including orange badges, test data watermarks, and sandbox API endpoints.
-  </p>
-</div>
+> [!TIP]
+>
+> **Test Mode Indicators**
+>
+> Test mode is clearly indicated throughout the dashboard with visual cues including orange badges, test data watermarks, and sandbox API endpoints.
 
 ### Test Mode Features
 
@@ -241,15 +237,11 @@ Live mode connects to production carrier APIs for real shipping operations:
 - **Tracking Updates**: Real delivery status notifications
 - **Label Printing**: Functional shipping labels
 
-<div className="bg-orange-50 dark:bg-orange-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-orange-700 dark:text-orange-300 mb-2">
-    ⚠️ Production Considerations
-  </div>
-  <p className="text-sm text-orange-600 dark:text-orange-400">
-    Live mode processes real transactions. Ensure your integrations are
-    thoroughly tested in test mode before switching to live operations.
-  </p>
-</div>
+> [!WARNING]
+>
+> **Production Considerations**
+>
+> Live mode processes real transactions. Ensure your integrations are thoroughly tested in test mode before switching to live operations.
 
 ## Switching Between Modes
 

apps/web/src/app/docs/developing/dashboard-guide/trackers/page.mdx

@@ -125,15 +125,11 @@ Karrio supports tracking from major carriers:
 - **Canada Post**: Domestic and international services
 - **And many more**: Regional and specialty carriers
 
-<div className="bg-blue-50 dark:bg-blue-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-blue-700 dark:text-blue-300 mb-2">
-    💡 Smart Carrier Detection
-  </div>
-  <p className="text-sm text-blue-600 dark:text-blue-400">
-    Karrio can often detect the carrier automatically based on tracking number
-    format, making the tracking setup process faster and more accurate.
-  </p>
-</div>
+> [!TIP]
+>
+> **Smart Carrier Detection**
+>
+> Karrio can often detect the carrier automatically based on tracking number format, making the tracking setup process faster and more accurate.
 
 ## Tracking Status Codes
 
@@ -261,16 +257,11 @@ Trackers automatically link with:
 - **Customer Updates**: Automatic tracking notifications
 - **Delivery Confirmation**: Order completion tracking
 
-<div className="bg-orange-50 dark:bg-orange-900 rounded-lg p-4 my-6">
-  <div className="text-sm text-orange-700 dark:text-orange-300 mb-2">
-    ⚠️ Tracking Limitations
-  </div>
-  <p className="text-sm text-orange-600 dark:text-orange-400">
-    Tracking accuracy depends on carrier data quality and update frequency. Some
-    carriers provide more detailed information than others, and rural deliveries
-    may have fewer tracking events.
-  </p>
-</div>
+> [!WARNING]
+>
+> **Tracking Limitations**
+>
+> Tracking accuracy depends on carrier data quality and update frequency. Some carriers provide more detailed information than others, and rural deliveries may have fewer tracking events.
 
 ## Analytics and Reporting
 

apps/web/src/app/docs/platform/app-store/api-integration/page.mdx

@@ -43,7 +43,7 @@ Karrio provides comprehensive APIs that allow your apps to:
 Karrio offers multiple API interfaces to suit different use cases:
 
 ```mermaid
-graph TB
+graph LR
     A[Your Karrio App] --> B[Authentication Layer]
     B --> C[GraphQL API]
     B --> D[REST API v1]
@@ -61,10 +61,7 @@ graph TB
     E --> M[Real-time Updates]
     E --> N[Event Notifications]
 
-    style A fill:#e3f2fd
-    style C fill:#e8f5e8
-    style D fill:#fff3e0
-    style E fill:#fce4ec
+    
 ```
 
 ## GraphQL API

apps/web/src/app/docs/platform/app-store/deployment/page.mdx

@@ -32,7 +32,7 @@ Learn how to deploy your Karrio Apps to production with confidence, including te
 Karrio Apps can be deployed in several ways depending on your architecture and requirements:
 
 ```mermaid
-graph TB
+graph LR
     A[Development] --> B[Testing]
     B --> C[Staging]
     C --> D[Production]
@@ -67,10 +67,7 @@ graph TB
     C --> K
     D --> N
 
-    style A fill:#e3f2fd
-    style B fill:#e8f5e8
-    style C fill:#fff3e0
-    style D fill:#fce4ec
+    
 ```
 
 ## Development Setup