CLAUDE.md

CLAUDE.md

Persona: Kairos Status: Action Research Portfolio Update - In Progress Latest Dev Update: claude-dev/DEV_UPDATE_2025-12-23_action_research_ui.md Next: Add more action research projects, update existing portfolio items

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. In this project, I go by Kairos.

Project Overview

A personal portfolio Jekyll site with a “mycopunk” cyberpunk aesthetic - blending earth-toned mycelial network metaphors with electric neon accents. Built for GitHub Pages deployment.

Development Commands

Running the site

bundle install                  # Install dependencies
bundle exec jekyll serve        # Start dev server at http://localhost:4000

Important: Changes to _config.yml require server restart.

Testing & Build

bundle exec jekyll build        # Build site to _site/

Architecture

Content Organization

  • _posts/: Blog posts in format YYYY-MM-DD-title.html (migrated from WordPress)
  • _portfolio/: Portfolio projects collection with custom frontmatter
  • _layouts/: Page templates (default, home, post, page, project)
  • _includes/: Reusable components including custom mycopunk visual effects
  • _data/navigation.yml: Site navigation structure (main, footer, social)

Collections Configuration

Portfolio is configured as a Jekyll collection in _config.yml:

collections:
  portfolio:
    output: true
    permalink: /portfolio/:path/

Design System

The site uses CSS custom properties (design tokens) defined in assets/css/main.css:

Color Palette (assets/css/main.css:1-16):

  • Core: Fungal Brown (#4B3621), Charcoal Black (#0A0A0A), Sporeskin Beige (#D4CFC7)
  • Electric Accents: Crypto Lime (#CCFF00), Myco Magenta (#FF00CC), Biolume Cyan (#00FFFF)
  • Access via CSS variables: var(--color-primary), var(--color-crypto-lime), etc.

Typography (assets/css/main.css:30-33):

  • Headings: VT323 (monospace cyberpunk)
  • Body: IBM Plex Sans
  • Code: Source Code Pro
  • Access via var(--font-heading), var(--font-body), var(--font-mono)

Spacing, Shadows, Effects: All use design tokens with var(--spacing-*), var(--shadow-*), var(--effect-*) notation

Custom Visual Components

The _includes/ directory contains mycopunk-themed visual effects:

  • circuit-pattern.html: SVG circuit board background patterns
  • cyber-divider.html: Neon divider lines with glow effects
  • data-stream.html: Animated data stream effects
  • mycelial-network.html: Organic network pattern overlays
  • pulse-accents.html: Pulsing neon accent elements

Use these by including in layouts: `<div class="mycelial-network" aria-hidden="true">

</div>`

JavaScript Features

assets/js/main.js implements:

  • Dark/light theme toggle with localStorage persistence (main.js:1-20)
  • Smooth scroll for anchor links (main.js:22-34)
  • Reading time calculation for blog posts (main.js:36-50)
  • Custom cursor with distortion effects

Frontmatter Standards

Blog Posts:

layout: post
title: "Post Title"
date: YYYY-MM-DD
categories: [category1, category2]
tags: [tag1, tag2]

Portfolio Projects (standard):

title: "Project Title"
description: "Short description"
date: YYYY-MM-DD
featured: true
categories: [design, development]
technologies: [Jekyll, JavaScript]

Portfolio Projects (action research):

title: "Project Title"
description: "Short description"
date: YYYY-MM-DD
time_period: 2024–Ongoing
status: ongoing              # ongoing, completed, archived
project_type: action_research
featured: true
thumbnail: /assets/images/portfolio/project/thumbnail.jpg
featured_image: /assets/images/portfolio/project/feature.jpg
categories: [serious play, action research]
context: "Domain/setting being studied"
role: "Researcher role(s)"
inquiry:
  question: "The central research question"
  methods:
    - action research
    - method two
  ethics:
    - ethical commitment one
    - ethical commitment two
technologies: [JavaScript, Python]
skills: [Skill One, Skill Two]
links:
  - text: "Link Text"
    url: https://example.com
    icon: ph ph-icon-name

Plugins & SEO

Enabled plugins (_config.yml:35-38):

  • jekyll-feed: RSS feed at /feed.xml
  • jekyll-seo-tag: Automatic meta tags via `
CLAUDE.md | Mathew Mark Mytka - m3

`

  • jekyll-sitemap: Automatic sitemap.xml
  • jekyll-paginate: Blog pagination (10 posts per page)

SEO is handled via jekyll-seo-tag in _layouts/default.html:8. Additional Open Graph and Twitter Card meta tags are explicitly defined in default.html:23-33.

Dark Mode Implementation

Theme persistence via localStorage (_layouts/default.html:36-40):

  • Script runs before page render to prevent flash
  • Toggle handled in main.js with smooth transitions
  • Data attribute data-theme="dark" or data-theme="light" on <html>
  • CSS responds to [data-theme="dark"] selectors

Privacy & Analytics

Site is configured for privacy-safe analytics (_config.yml:77-78):

  • Default: no analytics (provider: false)
  • Supports Plausible or Matomo when enabled
  • External fonts loaded from Google Fonts (consider self-hosting for full privacy)

Key Design Principles

  1. Accessibility: WCAG 2.2 AA target, skip-link included (_layouts/default.html:50)
  2. No inline styles: All styling via assets/css/main.css
  3. Design tokens only: Use CSS custom properties, never hardcoded values
  4. Semantic HTML: Proper heading hierarchy, ARIA labels where needed
  5. Responsive-first: Mobile-first breakpoints in CSS

Specifications Reference

  • claude-spec.md: Detailed functional/non-functional requirements
  • style-guide.md: Brand voice, logo usage, visual language
  • README.md: User-facing setup and content management guide

WordPress Migration Notes

Blog posts in _posts/ were imported from WordPress and retain .html extension. New posts can be Markdown (.md) or HTML. HTML posts may contain WordPress-specific markup requiring cleanup.

Session Handoff Workflow

To ensure continuity across Claude Code sessions:

At Session End

  1. Create dev update in /claude-dev/ following naming convention:
    • Format: DEV_UPDATE_YYYY-MM-DD_phase_N_description.md
    • Include: What was accomplished, what’s next, key decisions, code locations
  2. Update CLAUDE.md status header (top of this file) with:
    • Current phase/status
    • Latest dev update filename
    • Commit hash and tag if applicable
    • Next steps or decision points

At Session Start

  1. Read CLAUDE.md status header (top of file) for quick orientation
  2. Read latest dev update (linked in status header) for full context
  3. Check git status to see uncommitted changes
  4. Review recent commits if needed: git log --oneline -5

Dev Update Template

# Dev Update: [Brief Title]
**Date:** YYYY-MM-DD
**Status:** [Phase N Complete/In Progress/Blocked]
**Commit:** [hash if applicable]

## What We Accomplished
- Bullet points of what was done

## What's Next
- Decision points or next phase tasks

## Key Files Modified
- File paths with line numbers

## Context for Next Session
- Any important notes for continuation