Overview

Portfolio OS is a personal portfolio website built with an "OS-informed web" design philosophy: standard web navigation and patterns enhanced with a systematic, tactical visual language drawn from operating systems and heads-up displays. The site is built on Astro 6 with static site generation and React 19 islands for interactive components.

The platform serves two audiences through progressive disclosure: recruiters and hiring managers see a polished, professional portfolio with project case studies, a skills matrix, and career timeline; technically curious visitors discover interactive experiments (generative fiction engine, performance dashboard), a command palette with 17 shortcuts, and animated canvas backgrounds.

Content is managed through Astro Content Collections with Zod schema validation, ensuring type-safe frontmatter across all MDX files. The skills page aggregates stack arrays from every project and experiment at build time, producing a derived proficiency matrix. A BelmontOS CMS integration provides live sync of career data, tags, and domain metadata while maintaining full static-site independence.

The design system uses a dark-only brass/teal/orange palette with 54 CSS custom properties, zero border-radius, chamfered clip-path corners, and HUD bracket ornaments. All colors flow from a single TypeScript theme module consumed by both CSS variables and React canvas code.

Non-Technical Summary

Portfolio OS is a personal portfolio website that presents professional work through a distinctive, carefully crafted visual style inspired by operating system interfaces and tactical displays. Rather than using a generic template, it builds a unique identity through a custom design language: dark surfaces, brass and teal accents, corner bracket ornaments, and monospace typography that feels technical and precise without being difficult to navigate.

The site showcases three major projects (XR development work, AI personas, technical training), two interactive experiments that visitors can try directly in the browser, and a comprehensive skills overview. It is designed to serve two audiences: hiring managers who need a quick, professional overview of capabilities, and technically curious visitors who want to explore deeper into the interactive experiments and implementation details.

Behind the scenes, the site connects to a personal content management system (BelmontOS) that keeps project information, career details, and skill data synchronized. A development toolset (invisible to visitors) provides content editing, validation, and management features directly in the browser during development.

Highlights

Designed and built a complete portfolio platform in Astro 6 with React 19 islands, serving 3 project case studies, 2 interactive experiments, and a 51-skill proficiency matrix across 7 categories
Engineered a tactical HUD design system with brass/teal/orange palette, CSS custom property architecture, and 54 design tokens, enforcing strict color discipline through a single-source-of-truth theme module
Built an experiment sandboxing system with three hydration tiers (light, medium, heavy), React error boundaries, and performance-aware launch gates that prevent heavy WebGL/audio experiments from auto-loading on mobile
Integrated BelmontOS CMS with digest-based staleness detection, enabling live sync of project content, career data, tags, and domain metadata while maintaining full offline-first static generation
Developed a comprehensive dev admin panel with inline content editing, Zod schema validation, scaffolding generators, and career data management, all excluded from production builds via Vite plugin middleware

Quick Highlights

OS-informed design language - Tactical HUD aesthetic with brass/teal palette, monospace labels, corner brackets, and chamfered clip-path shapes without sacrificing standard web usability
Experiment sandbox - Interactive React islands with three hydration tiers, error boundaries, and performance-aware mobile gating for heavy WebGL/audio experiments
51-skill proficiency matrix - Derived at build time from project and experiment stacks across 7 categories (language, engine, XR, Unity, framework, tool, platform)
BelmontOS CMS integration - Digest-based staleness detection with live sync of projects, career profile, tags, and domain metadata
Dev content tooling - In-browser admin panel with inline MDX editing, Zod validation dashboard, scaffolding generators, and career data management
Animated canvas backgrounds - Circuit Trace and Constellation Map algorithms with prefers-reduced-motion support and tab-visibility pausing

Technical Breakdown

Astro Static Shell & Island Architecture

The site is built on Astro 6 with static site generation and a cloudflare() adapter for deployment. Three layout layers compose the page structure: BaseLayout.astro handles meta tags, font preloading, JSON-LD schema, and the ClientRouter for view transitions; ShellLayout.astro wraps content with navigation, footer, and the Ninja Keys command palette; ExperimentLayout.astro adds breadcrumb navigation, metadata headers, fullscreen toggle, and a table of contents sidebar with scroll-spy.

React islands use three hydration tiers defined in experiment frontmatter: light (client:visible, loads when scrolled into view), medium (client:only, loads immediately but skips SSR), and heavy (manual launch button + client:only, requires user interaction to load). The ExperimentWrapper.tsx component dynamically imports experiment modules from a static map and wraps them in ExperimentErrorBoundary.tsx to prevent crashes from breaking the shell.

Content Collections & Zod Schema Validation

Projects and experiments are MDX files under src/content/ with Zod-validated frontmatter defined in content.config.ts. The project schema includes structured section fields: overview, highlights[], quickHighlights[], technicalBreakdown, roleSummary[], nonTechnicalSummary, systemsUsed[], impactResults[], deepDive, plus metadata like versions[], tags[], cvReady, aiBadge, domain, and links. Astro validates all frontmatter at build time.

Derived Skills Aggregation

The getSkills() function in src/lib/skills.ts aggregates stack arrays from every project and experiment at build time, producing a Skill[] array with name, count (reference frequency), categories (multi-category: language, engine, XR, Unity, framework, tool, platform), proficiency (60-95 based on metadata), description, and back-references to source projects. The SkillMatrix.tsx React island renders an interactive, filterable visualization with category breakdowns and proficiency bars.

Design Token Architecture

All colors are defined in src/lib/theme.ts as a TypeScript object (theme.accent.default, theme.secondary.glow, etc.) with an rgba() helper for alpha variants. The same values are mirrored as CSS custom properties in the :root block of src/styles/global.css, consumed via Tailwind v4's @theme directive. This dual-channel approach allows React canvas code to import theme directly while Astro/CSS components use var(--accent). 54 design tokens cover surfaces (4 tiers), text (3 tiers), accent (4 states), secondary (5 states), tertiary, and borders.

HUD Visual System

The tactical aesthetic is implemented through CSS utility classes: .hud-bracket adds teal corner brackets via ::before/::after pseudo-elements that expand on hover; .clip-notch applies a polygon clip-path for chamfered bottom-right corners; .clip-button chamfers the top-right corner of primary CTAs; .tac-label styles uppercase, tracked labels in the tertiary color; .panel provides surface-raised cards with subtle borders. All interaction states use the secondary (teal) color, never the accent.

Animated Canvas Backgrounds

HomeBg.tsx randomly selects between two algorithms: Circuit Trace (PCB-inspired paths with connection nodes) and Constellation Map (star-field with proximity-based connections). Both skip on mobile (<768px) and prefers-reduced-motion, pause on tab hidden via visibilitychange, and use canvas.clientWidth for sizing in Astro's client:only mode.

BelmontOS Content Sync

The scripts/sync.ts pipeline syncs project content, career data (roles, presentations, education, profile), tags, and domain metadata from BelmontOS via MCP tools. A digest-based staleness monitor (DevSidebar.tsx) tracks content freshness and highlights out-of-date fields with dashed outlines (gold for synced fields, teal for manual). The career editor becomes read-only when BelmontOS is the source of truth, with a sync button to pull latest data into src/data/career.json.

Dev Admin Panel

A Vite dev middleware plugin (src/lib/dev-admin-plugin.ts) injects the admin panel only in development builds. Components include DevAdminPanel.tsx (main interface), DevSidebar.tsx (collapsible left navigation with page-aware buttons), ContentEditor.tsx (inline MDX editing), SkillEditor.tsx (skill metadata management), CareerEditor.tsx (career data editor), and HealthDashboard.tsx (build/validation status). Scaffolding and validation scripts (scripts/scaffold.ts, scripts/validate.ts) provide CLI-level content tooling.

Systems Used

Astro Content Collections - Type-safe MDX content with Zod schema validation for projects and experiments, enforcing structured frontmatter at build time
Island Architecture - Astro static HTML shell with React islands for interactive components using three hydration tiers (light/medium/heavy)
Derived Skills Aggregation - Build-time skill matrix computed from project and experiment stack arrays with proficiency scoring and multi-category classification
Experiment Sandboxing - React error boundaries and hydration modes isolating interactive experiments from the portfolio shell with mobile performance gating
Tactical HUD Design System - 54 CSS custom properties with brass/teal/orange palette, HUD bracket ornaments, clip-notch shapes, and dual-channel theme distribution (TypeScript + CSS vars)
BelmontOS Content Sync - Digest-based staleness detection with live sync of projects, career data, tags, and domain metadata from BelmontOS CMS
Dev Admin Panel - Vite dev middleware providing in-browser content editing, Zod validation dashboard, scaffolding generators, and career data management
Command Palette - Ninja Keys web component with 17 navigational commands organized by section (navigation, projects, experiments, external links, actions)
Reactive Story Engine - Branching interactive fiction with Tone.js audio synthesis, dynamic theming, soul tracking, and canvas waveform visualization
Career Profile System - Structured career data (roles, presentations, education, profile) with date formatting utilities and BelmontOS sync

Impact & Results

51 skills cataloged across 7 categories with proficiency scoring derived automatically from project and experiment metadata
3 project case studies with structured sections supporting All/Technical/Non-Technical view modes and table of contents with scroll-spy
2 interactive experiments sandboxed with error boundaries and performance-tiered hydration
Full accessibility audit: prefers-reduced-motion support, ARIA labels on all canvas elements, focus-visible rings, skip-to-content link, semantic HTML
Zero-config deployment via Cloudflare Pages with auto-deploy from main branch, sitemap generation, and JSON-LD structured data
Dev tooling productivity: inline content editing, scaffolding generators, and validation dashboards eliminate context-switching between IDE and CMS

Deep Dive

Design Philosophy: OS-Informed Web

The central design decision was positioning the site on an "OS-informed web" spectrum, using standard web patterns (scrolling, clicking, navigation) while borrowing the visual language of operating systems. This means monospace accents for metadata, structured key-value pairs, panel borders, status indicators, and breadcrumb paths that feel like file system navigation, without the usability cost of actually simulating an OS. The result is a site that signals technical depth to engineering audiences while remaining fully navigable for non-technical visitors.

Progressive Disclosure Architecture

Content is layered for two audiences. The surface layer (project cards, skills overview, career timeline) serves recruiters who need a 30-second scan. The middle layer (command palette, HUD bracket ornaments, tactical labels, animated backgrounds) rewards technically curious visitors. The deep layer (interactive experiments with audio synthesis, generative narrative, and performance dashboards) demonstrates real engineering capability beyond portfolio presentation.

Content Collection Design

The Zod schema for projects evolved significantly during development. Initially simple (title, summary, stack), it expanded to include structured section fields (overview, technicalBreakdown, roleSummary, etc.) following the BelmontOS project template. This allows the same content to render in three modes (All, Technical, Non-Technical) via a view toggle in the table of contents sidebar. The schema also includes versions[] for projects that evolved through multiple architectures, tags[] synced from BelmontOS, and cvReady as a publish gate.

Experiment Sandboxing Decisions

The three-tier hydration system (light/medium/heavy) was designed to balance user experience against resource consumption. Light experiments load lazily when scrolled into view, which works well for simple interactive components. Medium experiments use client:only to skip SSR entirely, necessary for components that access browser APIs immediately. Heavy experiments (Reactive Story Engine, Performance Dashboard) require an explicit launch button because they initialize audio contexts, WebGL canvases, or large data structures that would degrade page load. React error boundaries wrap every experiment so a crash in canvas rendering or audio synthesis never breaks the portfolio shell.

Dual-Channel Theme Distribution

A key architectural challenge was making the same color palette available to both Astro/CSS components (which use CSS custom properties) and React canvas code (which needs JavaScript values). The solution: src/lib/theme.ts defines all colors as a TypeScript object with an rgba() helper, while src/styles/global.css mirrors the same values as CSS custom properties consumed via Tailwind v4's @theme directive. This dual-channel approach avoids runtime DOM queries in canvas code while keeping CSS utility classes working normally. The strict rule, no hex values outside theme.ts and the :root block, prevents color drift.

BelmontOS Integration Strategy

The sync pipeline was designed for progressive adoption. The site can build and deploy with zero BelmontOS connectivity; all content exists as local MDX files and JSON. BelmontOS provides the source-of-truth layer: project content, career data, tags, and domain metadata are synced via scripts/sync.ts using MCP tools. A digest-based staleness monitor in DevSidebar.tsx tracks content freshness, showing dashed outlines around stale fields (gold for BelmontOS-synced, teal for manual). When synced content becomes the source of truth, the career editor switches to read-only mode with a sync button, preventing local edits that would be overwritten.

Dev Tooling Architecture

The dev admin panel is implemented as a Vite plugin (dev-admin-plugin.ts) that registers dev middleware, ensuring zero runtime cost in production builds. The panel decomposes into focused components: DevSidebar.tsx provides page-aware navigation (the buttons change based on the current route), ContentEditor.tsx handles inline MDX editing with live preview, SkillEditor.tsx manages the 51-skill metadata catalog, and HealthDashboard.tsx validates Zod schemas and reports build health. Module-level state ensures the sidebar and overlay persist across SPA navigations without React context.

Reactive Story Engine Deep Dive

The story engine experiment demonstrates several advanced patterns. ExperienceProvider.tsx manages soul state through a React context, tracking invisible choice dimensions that determine narrative endings. AudioEngine.ts uses Tone.js to synthesize ambient pads, procedural melodies, and bass lines that shift based on narrative mood. ThemeEngine.ts dynamically swaps CSS custom properties to change the entire visual tone of the story interface. VizEngine.ts renders real-time canvas waveforms synced to the audio output. Stories are defined as data bundles in story-engine/stories/ with arc/cycle/spiral narrative structures, each containing nodes, choices, soul dimension mappings, and audio parameters.

Performance Considerations

The site prioritizes perceived performance through several techniques: font preloading for Space Grotesk, Inter, and JetBrains Mono via <link rel="preload">; staggered entrance animations (fade-in-up with 80ms delays) that create a sequential reveal without blocking rendering; canvas animations that pause on tab hidden and skip entirely on mobile; and static site generation that eliminates server-side rendering latency. The Cloudflare Pages deployment provides edge caching and zero-config CDN distribution.

vv1 — v1.0 — Astro Portfolio with BelmontOS Integration

vv1 Highlights

Designed and built a complete portfolio platform in Astro 6 with React 19 islands, serving 3 project case studies, 2 interactive experiments, and a 51-skill proficiency matrix across 7 categories
Engineered a tactical HUD design system with brass/teal/orange palette, CSS custom property architecture, and 54 design tokens, enforcing strict color discipline through a single-source-of-truth theme module
Built an experiment sandboxing system with three hydration tiers (light, medium, heavy), React error boundaries, and performance-aware launch gates that prevent heavy WebGL/audio experiments from auto-loading on mobile
Integrated BelmontOS CMS with digest-based staleness detection, enabling live sync of project content, career data, tags, and domain metadata while maintaining full offline-first static generation
Developed a comprehensive dev admin panel with inline content editing, Zod schema validation, scaffolding generators, and career data management, all excluded from production builds via Vite plugin middleware

vv1 Overview

vv1 Technical Breakdown