I started building an Astro portfolio around my own needs as an AI engineer.
Most templates I found were either general developer portfolios or futuristic-looking AI pages. Projects usually appeared as a screenshot, a short description, and a list of technologies.
For the work I wanted to present, I needed space to explain the architecture, evaluation method, tradeoffs, and my individual contribution. A screenshot could show an interface, but much of the engineering happened elsewhere.
I eventually turned the portfolio into a reusable template.
Here are three decisions—and one theme bug—that shaped it.
Giving projects their own case studies
I organized the project pages around a consistent set of questions:
What problem was the system intended to solve?
How was it designed?
Which decisions did the engineer make?
How was the work evaluated?
What limitations or tradeoffs remained?
What outcome could be supported with evidence?
This structure was particularly relevant to work inside private systems, infrastructure, and evaluation pipelines, where a public application screenshot might not be available.
The sample projects and metrics in the template are fictional. Their purpose is to demonstrate the structure. Anyone adapting it needs to replace them with their own work and results they can substantiate.
The contrast bug that appeared between themes
One implementation challenge was keeping text readable across light and dark themes.
Some sections used an inverted surface: dark in the light theme, then cream-colored in the dark theme. However, some text and accent colors were hardcoded as white or mint.
When the background changed, those foreground colors stayed the same. Text that worked on the dark surface became difficult to read on the lighter one.
This affected parts of the AI Systems Lab, metrics, writing card, and proof bar.
I addressed it with semantic color tokens, including --inverse-ink and --inverse-accent. Their values change with the theme, so the foreground colors correspond to the surface they appear on.
The useful shift was naming colors by their role in the interface. A component could request the text color for an inverted surface without assuming that color should always be white.
I also kept the AI Systems Lab on a deliberately dark background in both themes. Its interface was designed around that presentation, so changing every surface between themes was not the right choice for that section.
This fix addressed the contrast issue I encountered. It should not be read as a claim that the entire template has passed an accessibility audit.
Keeping personal content in one place
I wanted customization to be straightforward for someone comfortable editing code.
The profile and other portfolio content live in src/data/site.ts. For example, the sample profile uses this structure:
export const profile = {
name: 'Alex Morgan',
shortName: 'Alex',
initials: 'AM',
role: 'AI Product Engineer',
location: 'Berlin, Germany',
availability: 'Open to remote AI engineering roles',
email: 'hello@example.com',
bio: 'AI engineer building evaluated LLM applications, retrieval systems, and dependable ML products.',
resume: '/resume-placeholder.pdf',
portrait: '/avatar-placeholder.svg',
};
Users keep the structure and replace the sample values. They also replace the assets in public/, including the avatar, résumé, favicon, and social images.
Before deployment, the setup includes setting SITE_URL, running the project checks and production build, and reviewing links, mobile layouts, keyboard navigation, and both themes.
Centralizing the content reduces the number of places someone needs to edit. It still requires working with source files and running the project locally.
Being precise about what the AI visualization does
The AI Systems Lab demonstrates a RAG pipeline, an agent workflow, and a voice-intelligence pipeline.
Visitors can switch modes and replay animations showing information moving through the architecture.
It is a front-end visualization with predefined sample data. It does not call an AI model, vector database, or speech service. The homepage inference demonstration also uses predefined examples.
Labels such as “live” and “system online” are interface styling; they do not indicate a running production model. That distinction matters when explaining what someone is looking at.
The portfolio’s purpose is to help someone communicate their actual engineering work. Its demonstration content provides a structure they can replace with their own evidence.
Have you run into a similar theme problem where the background changed correctly but the text or accent colors did not? How did you organize your color tokens?
Top comments (0)