docs: update theme and add overview page

docs/astro.config.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { defineConfig } from 'astro/config';
+import { defineConfig, passthroughImageService } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import { additionalFilesPlugin } from '@dfinity/starlight/additional-files';
 import { markdownUrlsPlugin } from '@dfinity/starlight/markdown-urls';
@@ -10,6 +10,9 @@ import { libsPlugin } from '@dfinity/starlight/libs';
 export default defineConfig({
   site: 'https://js.icp.build/',
   base: '/core/',
+  image: {
+    service: passthroughImageService(),
+  },
   integrations: [
     starlight({
       title: 'ICP JS SDK Core',
@@ -42,8 +45,8 @@ export default defineConfig({
       ],
       sidebar: [
         {
-          label: 'Release Notes',
-          autogenerate: { directory: 'release-notes', collapsed: true },
+          label: 'Upgrading',
+          autogenerate: { directory: 'upgrading', collapsed: true },
         },
       ],
     }),

docs/plugins/package.json

@@ -36,7 +36,10 @@
   "exports": {
     ".": "./src/mod.ts",
     "./assets/icp.svg": "./src/assets/icp.svg",
+    "./assets/layers.css": "./src/assets/layers.css",
     "./assets/theme.css": "./src/assets/theme.css",
+    "./assets/overrides.css": "./src/assets/overrides.css",
+    "./assets/elements.css": "./src/assets/elements.css",
     "./additional-files": "./src/additional-files.ts",
     "./libs": "./src/libs.ts",
     "./markdown-urls": "./src/markdown-urls.ts",

docs/plugins/src/assets/elements.css

@@ -0,0 +1,28 @@
+@layer elements {
+  /**
+   * Common
+   */
+  :root {
+    .dfn-text-highlight {
+      color: var(--sl-color-accent);
+    }
+
+    .dfn-text-gradient {
+      background-image: linear-gradient(
+        90deg,
+        var(--dfn-color-text-gradient-start),
+        var(--dfn-color-text-gradient-end)
+      );
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+
+    .dfn-bg-gradient {
+      background-image: linear-gradient(
+        0deg,
+        var(--dfn-color-bg-gradient-start),
+        var(--dfn-color-bg-gradient-end)
+      );
+    }
+  }
+}

docs/plugins/src/assets/layers.css

@@ -0,0 +1 @@
+@layer starlight, theme, overrides, elements;

docs/plugins/src/assets/overrides.css

@@ -0,0 +1,9 @@
+@layer overrides {
+  .sl-link-button {
+    border-radius: var(--dfn-border-radius);
+  }
+
+  .card {
+    border-radius: var(--dfn-border-radius);
+  }
+}

docs/plugins/src/assets/theme.css

@@ -1,58 +1,86 @@
 /* Available props: https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css */
 
-:root {
-  --sl-font-system:
-    "CircularXX", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
-    "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif,
-    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol",
-    "Noto Color Emoji";
-
-  --dfn-color-black: hsl(259, 0%, 13%);
-  --dfn-color-gray-7: hsl(259, 4%, 13%);
-  --dfn-color-gray-6: hsl(259, 4%, 17%);
-  --dfn-color-gray-5: hsl(259, 4%, 40%);
-  --dfn-color-gray-4: hsl(259, 4%, 46%);
-  --dfn-color-gray-3: hsl(259, 4%, 56%);
-  --dfn-color-gray-2: hsl(259, 4%, 80%);
-  --dfn-color-gray-1: hsl(259, 4%, 93%);
-  --dfn-color-white: hsl(259, 0%, 100%);
-
-  --dfn-pink: hsl(312, 100%, 45%);
-  --dfn-purple: hsl(250, 100%, 81%);
-  --dfn-dark-purple: hsl(259, 100%, 36%);
-
-  --dfn-color-bg-navbar: var(--dfn-color-black);
-  --dfn-color-bg-sidebar: var(--dfn-color-black);
-
-  --sl-color-accent: var(--dfn-dark-purple);
-  --sl-color-accent-low: var(--dfn-color-black);
-  --sl-color-accent-high: var(--dfn-purple);
-
-  --sl-color-bg-nav: var(--dfn-color-bg-navbar);
-  --sl-color-bg-sidebar: var(--dfn-color-bg-sidebar);
-
-  --sl-color-white: var(--dfn-color-white);
-  --sl-color-gray-1: var(--dfn-color-gray-1);
-  --sl-color-gray-2: var(--dfn-color-gray-2);
-  --sl-color-gray-3: var(--dfn-color-gray-3);
-  --sl-color-gray-4: var(--dfn-color-gray-4);
-  --sl-color-gray-5: var(--dfn-color-gray-5);
-  --sl-color-gray-6: var(--dfn-color-gray-6);
-  --sl-color-gray-7: var(--dfn-color-gray-7);
-  --sl-color-black: var(--dfn-color-black);
-}
+@layer theme {
+  /**
+   * Common
+   */
+  :root {
+    --sl-font-system:
+      'CircularXX', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+      'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+      'Segoe UI Symbol', 'Noto Color Emoji';
+
+    --dfn-color-black: #181818;
+    --dfn-color-gray-7: hsl(259, 4%, 13%);
+    --dfn-color-gray-6: hsl(259, 4%, 17%);
+    --dfn-color-gray-5: hsl(259, 4%, 20%);
+    --dfn-color-gray-4: hsl(259, 4%, 46%);
+    --dfn-color-gray-3: hsl(259, 4%, 56%);
+    --dfn-color-gray-2: hsl(259, 4%, 80%);
+    --dfn-color-gray-1: hsl(259, 4%, 93%);
+    --dfn-color-white: #ffffff;
+
+    --dfn-color-infinite: #3b00b9;
+    --dfn-color-dark-infinite: #1e005d;
+    --dfn-color-razzmatazz: #ed1e79;
+    --dfn-color-meteorite: #522785;
+    --dfn-color-picton-blue: #29abe2;
+    --dfn-color-flamingo: #f15a24;
+    --dfn-color-sea-buckthorn: #fbb03b;
+
+    --dfn-color-text-gradient-start: #6a85f1;
+    --dfn-color-text-gradient-end: #c572ef;
+
+    --dfn-border-radius: 0.75rem;
+  }
+
+  /**
+   * Dark mode
+   */
+  :root {
+    --sl-color-accent-low: var(--dfn-color-black);
+    --sl-color-accent: var(--dfn-color-picton-blue);
+    --sl-color-accent-high: var(--dfn-color-sea-buckthorn);
+
+    --sl-color-white: var(--dfn-color-white);
+    --sl-color-gray-1: var(--dfn-color-gray-1);
+    --sl-color-gray-2: var(--dfn-color-gray-2);
+    --sl-color-gray-3: var(--dfn-color-gray-3);
+    --sl-color-gray-4: var(--dfn-color-gray-4);
+    --sl-color-gray-5: var(--dfn-color-gray-5);
+    --sl-color-gray-6: var(--dfn-color-gray-6);
+    --sl-color-gray-7: var(--dfn-color-gray-7);
+    --sl-color-black: var(--dfn-color-black);
+
+    --sl-color-bg-nav: var(--dfn-color-black);
+    --sl-color-bg-sidebar: var(--dfn-color-black);
+
+    --dfn-color-bg-gradient-start: #0e031f;
+    --dfn-color-bg-gradient-end: #281447;
+  }
+
+  /**
+   * Light mode
+   */
+  :root[data-theme='light'] {
+    --sl-color-accent-low: var(--dfn-color-dark-infinite);
+    --sl-color-accent: var(--dfn-color-infinite);
+    --sl-color-accent-high: var(--dfn-color-flamingo);
+
+    --sl-color-white: var(--dfn-color-black);
+    --sl-color-gray-1: var(--dfn-color-gray-7);
+    --sl-color-gray-2: var(--dfn-color-gray-6);
+    --sl-color-gray-3: var(--dfn-color-gray-5);
+    --sl-color-gray-4: var(--dfn-color-gray-4);
+    --sl-color-gray-5: var(--dfn-color-gray-3);
+    --sl-color-gray-6: var(--dfn-color-gray-2);
+    --sl-color-gray-7: var(--dfn-color-gray-1);
+    --sl-color-black: var(--dfn-color-white);
+
+    --sl-color-bg-nav: #e8e4ed;
+    --sl-color-bg-sidebar: #f1eef5;
 
-:root[data-theme="light"] {
-  --dfn-color-bg-navbar: #e8e4ed;
-  --dfn-color-bg-sidebar: #f1eef5;
-
-  --sl-color-white: var(--dfn-color-black);
-  --sl-color-gray-1: var(--dfn-color-gray-7);
-  --sl-color-gray-2: var(--dfn-color-gray-6);
-  --sl-color-gray-3: var(--dfn-color-gray-5);
-  --sl-color-gray-4: var(--dfn-color-gray-4);
-  --sl-color-gray-5: var(--dfn-color-gray-3);
-  --sl-color-gray-6: var(--dfn-color-gray-2);
-  --sl-color-gray-7: var(--dfn-color-gray-1);
-  --sl-color-black: var(--dfn-color-white);
+    --dfn-color-bg-gradient-start: #c0d9ff;
+    --dfn-color-bg-gradient-end: #f0b9e5;
+  }
 }

docs/plugins/src/theme.ts

@@ -1,18 +1,22 @@
-import type { StarlightPlugin } from "@astrojs/starlight/types";
+import type { StarlightPlugin } from '@astrojs/starlight/types';
 
 export function dfinityStarlightTheme(): StarlightPlugin {
   return {
-    name: "@dfinity/starlight/theme",
+    name: '@dfinity/starlight/theme',
     hooks: {
-      "config:setup": (ctx) => {
+      'config:setup': ctx => {
         ctx.updateConfig({
           logo: {
-            src: "@dfinity/starlight/assets/icp.svg",
-            alt: "Internet Computer Logo",
+            src: '@dfinity/starlight/assets/icp.svg',
+            alt: 'Internet Computer Logo',
+            replacesTitle: true,
           },
           customCss: [
             ...(ctx.config.customCss || []),
-            "@dfinity/starlight/assets/theme.css",
+            '@dfinity/starlight/assets/layers.css',
+            '@dfinity/starlight/assets/theme.css',
+            '@dfinity/starlight/assets/overrides.css',
+            '@dfinity/starlight/assets/elements.css',
           ],
         });
       },

docs/src/pages/index.astro

@@ -0,0 +1,113 @@
+---
+// Import the `<StarlightPage>` component first to set up cascade layers.
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { Card, CardGrid, LinkButton } from '@astrojs/starlight/components';
+import icpSvg from '@dfinity/starlight/assets/icp.svg';
+---
+
+<StarlightPage
+  frontmatter={{
+    title: 'ICP JavaScript SDK Core',
+    template: 'splash',
+    banner: {
+      content: `Still using <code>@dfinity/agent</code>? Migrate to <a href="/core/latest/upgrading/v4">@icp-sdk/core</a>!`,
+    },
+    next: false,
+    prev: false,
+    hero: {
+      title: `ICP JavaScript SDK <span class="dfn-text-gradient">Core</span>`,
+      tagline:
+        'Build applications that interact with the Internet Computer from browsers, Node.js, and other JavaScript runtimes.',
+      image: {
+        file: icpSvg,
+        alt: 'Internet Computer Logo',
+      },
+    },
+  }}
+>
+  <section>
+    <h3>Modules</h3>
+
+    <CardGrid>
+      <Card title="Agent">
+        Build applications that interact with the Internet Computer from browsers, Node.js, and
+        other JavaScript runtimes.
+
+        <LinkButton href="libs/agent" variant="minimal" icon="right-caret" iconPlacement="start">
+          See <code class="dfn-text-highlight">@icp-sdk/core/agent</code> docs
+        </LinkButton>
+      </Card>
+
+      <Card title="Candid">
+        Build applications that interact with the Internet Computer from browsers, Node.js, and
+        other JavaScript runtimes.
+
+        <LinkButton href="libs/candid" variant="minimal" icon="right-caret" iconPlacement="start">
+          See <code class="dfn-text-highlight">@icp-sdk/core/candid</code> docs
+        </LinkButton>
+      </Card>
+
+      <Card title="Identity">
+        Build applications that interact with the Internet Computer from browsers, Node.js, and
+        other JavaScript runtimes.
+
+        <LinkButton href="libs/identity" variant="minimal" icon="right-caret" iconPlacement="start">
+          See <code class="dfn-text-highlight">@icp-sdk/core/identity</code> docs
+        </LinkButton>
+      </Card>
+
+      <Card title="Principal">
+        Build applications that interact with the Internet Computer from browsers, Node.js, and
+        other JavaScript runtimes.
+
+        <LinkButton
+          href="libs/principal"
+          variant="minimal"
+          icon="right-caret"
+          iconPlacement="start"
+        >
+          See <code class="dfn-text-highlight">@icp-sdk/core/principal</code> docs
+        </LinkButton>
+      </Card>
+    </CardGrid>
+  </section>
+
+  <section>
+    <h3>Upgrading</h3>
+
+    <CardGrid>
+      <Card title="ICP JS SDK Core">
+        <p>
+          If you're using <code>@dfinity/agent</code> version 3.x, you can migrate to
+          <code>@icp-sdk/core</code> with the help of our automated migration tools or manual migration
+          guide.
+        </p>
+
+        <LinkButton
+          href="upgrading/v4"
+          variant="minimal"
+          icon="right-caret"
+          iconPlacement="start"
+        >
+          Migrate to <code class="dfn-text-highlight">@icp-sdk/core</code>
+        </LinkButton>
+      </Card>
+
+      <Card title="Agent JS v3">
+        <p>
+          If you're still using <code>@dfinity/agent</code> version 2.x, you can migrate to 3.x with
+          the help of our migration guide.
+        </p>
+
+        <LinkButton
+          href="upgrading/v3"
+          variant="minimal"
+          icon="right-caret"
+          iconPlacement="start"
+        >
+          Migrate to <code class="dfn-text-highlight">@dfinity/agent@v3</code>
+        </LinkButton>
+      </Card>
+    </CardGrid>
+  </section>
+</StarlightPage>