How I stole the Design of Starlight with AI

Note:

1. The post was published on my own site here.
2. you can view the mermaid diagrams in the original post.

---

Before I left Sydney for Japan, MonaKit was released on Astro as a theme. It is the theme I used for our English Site - the one you are reading now.

Now, the next question is, how can I add new features to MonaKit? I don't want to hardcode everything into it and plan to build a set of resuable & combinable packages.

While I was considering the design, one idea came to my mind: "why not learn from other successful designs?" So, I decided to do some research on Starlight.

High Level Analysis with Gemini

I git cloned the repo and passed the following prompt to Gemini Cli:

---
description: Explain the code base to a new developer
---

## Context

- Current code base: `src/`
- Dependency management: `package.json`
- Project background: `README.md`

## Your task

1. Explain the current code base to a new developer, providing a clear understanding of its structure and functionality.
2. Highlight key components, modules, and their interactions.
3. Draw a mermaid diagram to illustrate the architecture and flow of the application.
4. Write an explanation report including your findings.

## Output

- A detailed code explanation report, including:
  - Overview of the code base structure and functionality, keeping it concise.
  - Key components and modules, their roles, and how they interact.
  - A mermaid diagram illustrating the architecture of the application.
  - A set of sequence diagrams illustrating key workflows or processes within the application.
  - Any other relevant information that would help a new developer understand the code base. Fox example:
    - Computer theory concepts or algorithms used or implemented

Note:

Write your report in `docs/code-explanation.md`:

- if the file does not exist, create it
- if the file exists, delete the file and create a new one

Several minutes later, a detailed report was generated.

Architecture Diagram

In this report, Gemini generated a mermaid architecture diagram based on the codebase:

graph TD
    subgraph User's Astro Project
        A[astro.config.mjs] -->|imports| B(Starlight Integration);
    end

    subgraph Starlight Package
        B --> C{astro:config:setup hook};
        C --> D[Process Plugins & i18n];
        C --> E[Inject Routes];
        C --> F[Add Built-in Integrations];
        C --> G[Configure Vite];
        C --> H[Setup Remark/Rehype Plugins];
    end

    subgraph Vite
        G --> I{Virtual Modules};
        I -->|`virtual:starlight/user-config`| J[Starlight Components];
        I -->|`virtual:starlight/project-context`| J;
    end

    subgraph Astro
        E --> K["Renders `routes/[...slug].astro`"];
        K --> L[Renders `components/Page.astro`];
        L --> J;
    end

    subgraph Content
        M["Docs Content (.md, .mdx)"] -->|astro:content| K;
    end

As you can see, it is a standard Astro integration. In it, I found two interesting things:

• Vite Virtual Modules, exposes the Starlight configuration and other project context to the Astro components
• Inject Routes, injects the Starlight routes for the documentation pages.

Sequence Diagrams

As my prompt requested, two sequence diagrams were also generated.

Build Process

sequenceDiagram
    participant Developer
    participant Astro
    participant Starlight

    Developer->>Astro: Runs `astro build`
    Astro->>Starlight: Executes `astro:config:setup` hook
    Starlight->>Starlight: Processes config, plugins, and integrations
    Starlight->>Astro: Updates Astro config
    Astro->>Astro: Builds all pages and assets
    Astro->>Starlight: Executes `astro:build:done` hook
    Starlight->>Starlight: Runs Pagefind to index content

Page Rendering

sequenceDiagram
    participant User
    participant Astro
    participant Starlight
    participant Vite

    User->>Astro: Requests a page
    Astro->>Starlight: Finds matching route (`[...slug].astro`)
    Starlight->>Astro: Renders `routes/common.astro`
    Astro->>Starlight: Renders `components/Page.astro`
    Starlight->>Vite: Accesses virtual modules for config
    Vite-->>Starlight: Returns config
    Starlight->>Astro: Renders UI components
    Astro-->>User: Returns HTML page

It's not hard to understand:

1. The building process injects the routes and sets up other configurations
2. At the page rendering time, the routes can be consumed.

This is really inpiring! After reading the codebase and Astro docs, I believe Injection functionality and Vite Virtual Modules are exactly what I need: I can build each feature set as an Astro Integration, then use Injection and Virtual Modules to expose the features to MonaKit.

Experiment

However, in order to fully understand and verify my thoughts, I need to do a experiment.

This time, I asked Claude Code to help me. Starting the cli, I inputed the following prompt:

This is a new project for demostrating astro injection feature in astro integration. 

I need you to create some example for the following scenarios:
- injectRoute
- addMiddleware
- injectScript

You can also use the Virtual Modules in vite. You can read the starlight design for reference: @code-explanation.md

Don't code, show me your ideas first

Note: @code-explanation.md was the report generated by Gemini. I copied it to the current project for Claude to read.

After a loop of "discussion -> design -> review -> implementation", finally, I got one Astro Integration and one Astro project which depended on it to demonstrate the injection feature.

Everything worked as expected!

Takeaway

Thanks to Gemini and Claude, I was able to learn from an excellent design and verify my ideas in a short time. I think I will take the similar design for the future versions of MonaKit.

One important thing is that the whole process opened a new way for me to design and implement software. Instead of starting from scratch, the first step might be understanding my requirements and finding similar implementations. Then, learn from them and adapt them to my own needs.

P.S.: I won't waste time pasting the whole report and example code here, because you can generate them with the prompts I provided above. Cheers!