Yojahny.dev - Personal Portfolio & Technical Blog

A futuristic, Matrix-inspired portfolio and technical blog platform built from the ground up with Astro v5, showcasing professional experience, projects, and technical writing. The site demonstrates modern web development best practices through its sophisticated theme system, performance-optimized architecture, and accessibility-first design approach. Built to serve dual purposes: establishing professional presence for career opportunities and contributing technical knowledge to the developer community.

Key Features

• Advanced Multi-Theme System - Implemented three complete theme variations (Matrix, Dark, Light) using Tailwind CSS v4’s native @theme directive with real-time switching and zero flash of unstyled content (FOUC). All design tokens—colors, typography, spacing, shadows—are centrally managed through CSS custom properties, enabling instant theme transitions without JavaScript overhead.

• Sophisticated Animation Control System - Built a comprehensive animation management layer that respects user preferences, device capabilities, and accessibility requirements. Features granular control over GSAP animations, CSS transitions, and scroll behaviors with automatic detection of prefers-reduced-motion, device type, and user toggles. Reduces motion sickness triggers while maintaining engaging visuals for capable devices.

• Type-Safe Content Collections - Leveraged Astro’s content collections with Zod schema validation for structured blog posts and project portfolios. Enforces frontmatter requirements at build time, preventing deployment of incomplete content. Supports rich metadata including SEO optimization, reading time estimation, featured content flagging, and multi-format categorization.

• Dynamic Maintenance Mode - Architected a flexible maintenance mode system using Astro middleware that intercepts requests during deployment or maintenance windows. Intelligently exempts static assets, API routes, and the maintenance page itself, ensuring graceful degradation without breaking existing functionality. Controlled via environment variables for seamless CI/CD integration.

• Performance-Optimized Asset Pipeline - Implemented custom font loading strategy using variable fonts with font-display: swap for optimal perceived performance. Integrated Swiper.js with lazy loading for project galleries and Three.js for background animations, carefully managing bundle size to maintain sub-3-second page loads on 3G connections.

• Progressive Enhancement Architecture - Designed component hierarchy following the islands architecture pattern, hydrating interactive elements only where necessary. Static-first rendering generates HTML at build time, with selective client-side JavaScript for forms, theme switching, and animations. Achieves 95+ Lighthouse scores across all categories.

• Markdown Content Engine with Syntax Highlighting - Configured GitHub Flavored Markdown support with Shiki syntax highlighter for technical articles. Custom prose styling with Matrix-inspired aesthetics ensures code examples remain readable while maintaining brand identity. Supports smart typography, tables, blockquotes, and inline code formatting.

• Responsive Design System - Built entirely with Tailwind CSS v4 using fluid typography and spacing via clamp() functions. Eliminates layout shift across viewport sizes from mobile (320px) to ultra-wide displays (1920px+). Touch targets meet WCAG AA standards (44px minimum) for accessible mobile interactions.

Technical Implementation

Architecture & Framework Choice

Selected Astro v5 for its static-site generation capabilities and partial hydration model, which dramatically reduces JavaScript shipped to clients. The framework’s file-based routing eliminates complex configuration while maintaining flexibility for dynamic routes via getStaticPaths(). Content collections provide type-safe access to markdown files with automatic frontmatter validation through Zod schemas.

Theme System Engineering

The theme system represents a significant departure from traditional CSS-in-JS approaches. By leveraging Tailwind CSS v4’s @theme directive, all design tokens live in a single global.css file with theme-specific overrides applied via CSS classes on the <html> element. This approach:

• Eliminates JavaScript from the theming critical path
• Enables instant theme switching without re-renders
• Prevents FOUC through visibility control until theme initialization
• Supports SSR without hydration requirements
• Maintains single source of truth for design tokens

Theme persistence uses localStorage with a synchronous inline script that runs before page render, ensuring the correct theme applies before the browser paints. The ThemeSystem.astro component handles user-initiated theme changes with smooth transitions and proper state synchronization.

Animation Control System (Technical Highlight)

The animation system solves a critical UX challenge: providing engaging motion for capable users while respecting accessibility preferences and device limitations. The implementation operates at three levels:

1. CSS Layer - Base animations defined with CSS custom properties (--animations-enabled) that gate all transitions and animations. The .animations-disabled class applies globally, forcing animation durations to near-zero (0.01ms) without removing animation definitions.

2. JavaScript Detection - Client-side detection identifies device type, screen size, and user preferences via matchMedia('(prefers-reduced-motion)'). Mobile/tablet devices receive reduced animations by default due to performance constraints, while desktop users get full animations unless they explicitly opt out.

3. GSAP Integration - Before initializing any GSAP timeline or animation, the system checks for the .animations-disabled class on the <html> element. This prevents animation registration entirely rather than just suppressing execution, reducing memory overhead on low-powered devices.

The system maintains state in localStorage and synchronizes across tabs using the storage event, ensuring consistent user experience. Animation toggles persist across page navigations via Astro’s View Transitions API.

Maintenance Mode Middleware

Implemented Astro middleware that intercepts all requests at the server level, enabling zero-downtime deployments. The middleware:

• Checks MAINTENANCE_MODE environment variable (injected at build time)
• Exempts static assets (fonts, images, CSS, JS) by file extension
• Allows API routes to continue functioning for monitoring
• Redirects all other traffic to /maintenance route
• Includes npm scripts for quick enable/disable workflows

This pattern provides more control than Netlify/Vercel’s built-in maintenance pages while keeping the implementation portable across hosting platforms.

Content Management Strategy

Content lives in /src/content/ with separate collections for blog posts and projects. Each collection defines a Zod schema that validates:

• Required fields (title, description, technologies)
• Data types (dates, arrays, enums)
• String constraints (minimum lengths, URL formats)
• Optional metadata (SEO overrides, reading time, images)

Build fails fast if any content violates the schema, preventing invalid data from reaching production. The schema serves as living documentation for content contributors, eliminating ambiguity about frontmatter requirements.

Business Impact & Use Cases

Professional Brand Establishment

The portfolio serves as the primary online presence for career opportunities, featuring:

• Comprehensive project showcase with detailed case studies
• Technical blog demonstrating expertise and communication skills
• Direct contact form integration via EmailJS for inquiry management
• Resume/career timeline visualization

Designed to make strong first impressions with recruiters and hiring managers through polished visuals and clear technical storytelling.

Developer Community Contribution

The technical blog component positions the site as a knowledge-sharing platform:

• In-depth tutorials on modern web development patterns
• Case studies exploring architectural decisions
• Performance optimization strategies
• Accessibility best practices

Content targets mid-to-senior developers seeking to understand complex implementation details, not just surface-level tutorials.

Portfolio as Portfolio

The site itself demonstrates technical competency through its implementation:

• Source code available on GitHub for technical evaluation
• Architecture choices reflect understanding of modern web standards
• Performance metrics validate optimization claims
• Accessibility features show inclusive design mindset

Hiring managers can evaluate code quality, git practices, and documentation standards directly from the repository.

Development Workflow & Status

Current State

The project is in active development with core functionality complete and deployed to production at yojahny.dev. Recent work focuses on:

• Content migration from previous portfolio versions
• SEO optimization and Open Graph metadata
• Performance fine-tuning for mobile devices
• Android Chrome rendering bug fixes for markdown content

Build & Deployment Pipeline

Built as a static site with CI/CD automation:

• Development: Local dev server with hot module replacement
• Staging: Test deployments on test.yojahny.dev subdomain
• Production: Automated builds on push to main branch
• Maintenance: Environment variable toggles for controlled downtime

Testing Approach

Quality assurance includes:

• Manual cross-browser testing (Chrome, Firefox, Safari, Edge)
• Mobile device testing on iOS and Android
• Lighthouse audits for performance, accessibility, SEO, and best practices
• Content validation via Zod schemas at build time
• Visual regression testing for theme switching

Future Enhancements

Planned improvements include:

• Blog post search and filtering
• Tag-based content navigation
• Reading progress indicators
• Dark mode for code syntax highlighting variations
• Comment system for blog engagement
• RSS feed for blog subscribers
• Advanced analytics for content performance tracking

The codebase is structured for extensibility, with clear separation between layout components, UI primitives, content sections, and animation systems. This modularity enables rapid iteration without risking regressions in stable features.