[Product Homepage Design] Implementation

.claude/skills/astro-build-testing/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: astro-build-testing
+description: Use when writing integration tests for Astro sites that need to build the site and parse output HTML. Covers the linkedom-based parse pattern and concurrency guard for parallel test files.
+scope: project
+---
+
+See [README.md](references/README.md) for full documentation.

.claude/skills/astro-build-testing/references/README.md

@@ -0,0 +1,33 @@
+# Astro Build Testing
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## When to Use This Skill
+
+Use this skill when users request:
+
+- [TODO: Example request 1]
+- [TODO: Example request 2]
+
+## Core Capabilities
+
+### 1. [TODO: Capability Name]
+
+[TODO: Description and examples]
+
+## Best Practices
+
+- [TODO: Best practice 1]
+- [TODO: Best practice 2]
+
+## Resources
+
+### scripts/
+
+[TODO: Describe helper scripts, or delete this section if none]
+
+### references/
+
+- `README.md` - This documentation

.claude/skills/astro-component-testing/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: astro-component-testing
+description: Test Astro components by reading source files and data files directly instead of full Astro builds. Use when testing Astro .astro components, CSS modules, or JSON data files in the MirDB homepage project.
+metadata:
+  scope: project
+---
+
+See [README.md](references/README.md) for full documentation.

.claude/skills/astro-component-testing/references/README.md

@@ -0,0 +1,111 @@
+# Astro Component Testing Pattern
+
+## Overview
+
+In the MirDB homepage project, Astro components are tested by reading source files (`.astro`, `.json`, `.module.css`) directly rather than requiring a full `astro build`. This pattern is faster, more reliable, and tests the same invariants as rendered HTML.
+
+## When to Use This Skill
+
+Use this skill when users request:
+
+- Testing any `.astro` component in the MirDB homepage project
+- Validating JSON data file structure and content
+- Checking CSS module rules (breakpoints, selectors, property values)
+- Testing graceful fallback/empty state handling in components
+
+## Test Pattern
+
+### 1. Define file paths
+
+```typescript
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HOMEPAGE_DIR = join(__dirname, '..', '..', '..');
+const DATA_FILE = join(HOMEPAGE_DIR, 'src', 'data', 'my-data.json');
+const COMPONENT_FILE = join(HOMEPAGE_DIR, 'src', 'components', 'MySection', 'MySection.astro');
+const CSS_FILE = join(HOMEPAGE_DIR, 'src', 'components', 'MySection', 'MySection.module.css');
+```
+
+### 2. Create read helpers
+
+```typescript
+function readData() {
+  const raw = readFileSync(DATA_FILE, 'utf-8');
+  return JSON.parse(raw);
+}
+
+function readComponent() {
+  return readFileSync(COMPONENT_FILE, 'utf-8');
+}
+
+function readCss() {
+  return readFileSync(CSS_FILE, 'utf-8');
+}
+```
+
+### 3. Test data structure
+
+```typescript
+it('has required fields', () => {
+  const data = readData();
+  expect(data).toHaveProperty('sectionTitle');
+  expect(typeof data.sectionTitle).toBe('string');
+  expect(data.sectionTitle.length).toBeGreaterThan(0);
+});
+```
+
+### 4. Test component renders elements
+
+```typescript
+it('renders heading elements', () => {
+  const source = readComponent();
+  expect(source).toContain('<h2');
+  expect(source).toContain('{sectionTitle}');
+});
+```
+
+### 5. Test graceful fallbacks
+
+For testing empty state or missing data:
+- Temporarily modify the data file with `writeFileSync`
+- Use `try/finally` to restore the original data
+- Verify the component handles the modified state
+
+```typescript
+it('handles empty data gracefully', () => {
+  const original = readFileSync(DATA_FILE, 'utf-8');
+  try {
+    const modified = { ...readData(), components: [] };
+    writeFileSync(DATA_FILE, JSON.stringify(modified, null, 2), 'utf-8');
+    const reloaded = readData();
+    expect(reloaded.components).toHaveLength(0);
+  } finally {
+    writeFileSync(DATA_FILE, original, 'utf-8');
+  }
+});
+```
+
+### 6. Test CSS structure
+
+```typescript
+it('has responsive breakpoints', () => {
+  const css = readCss();
+  expect(css).toContain('max-width: 1279px'); // tablet
+  expect(css).toContain('max-width: 767px');  // mobile
+});
+```
+
+## Best Practices
+
+- Always use `try/finally` when modifying data files in tests to ensure restoration
+- Test both positive (data present) and negative (empty/null data) cases
+- Check for CSS class names in the component to verify styling is wired up
+- Use regex for CSS property validation (e.g., `/\\.feature-grid\\s*\\{[^}]*grid-template-columns/`)
+- Prefer source-file testing over full Astro builds unless testing component composition
+
+## Running Tests
+
+```bash
+node node_modules/vitest/vitest.mjs run tests/unit/components/MyComponent.test.ts
+```

.claude/skills/astro-performance-testing/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: astro-performance-testing
+description: Use when writing performance validation tests for Astro sites that verify page load speed, interaction responsiveness, asset optimization, and Lighthouse readiness. Covers the proxy-assertion pattern for CI environments without browser access.
+scope: project
+---
+
+See [README.md](references/README.md) for full documentation.

.claude/skills/astro-performance-testing/references/README.md

@@ -0,0 +1,172 @@
+# Astro Performance Testing
+
+## Overview
+
+This skill enables writing performance validation tests for Astro static sites that run in CI without a headless browser. It uses proxy assertions (checking factors that correlate with real metrics) and production build output inspection to validate performance requirements.
+
+## When to Use This Skill
+
+Use this skill when users request:
+
+- Performance testing for an Astro/static site
+- Lighthouse performance score validation
+- FCP/TTI measurement in CI
+- Interaction responsiveness verification
+- Asset optimization and page weight budget checks
+- NFR-1 (Performance) compliance testing
+
+## Core Capabilities
+
+### 1. Production Build Inspection Pattern
+
+Build the site in production mode, then inspect the dist/ output:
+
+```typescript
+import { execSync } from 'node:child_process';
+
+function buildSite() {
+  const astroBin = join(HOMEPAGE_DIR, 'node_modules', 'astro', 'astro.js');
+  execSync(`node "${astroBin}" build`, {
+    cwd: HOMEPAGE_DIR,
+    stdio: 'pipe',
+    env: { ...process.env, NODE_ENV: 'production' },
+  });
+}
+```
+
+Parse the output HTML with linkedom (same pattern as accessibility tests):
+
+```typescript
+import { parseHTML } from 'linkedom';
+
+function parseBuiltHtml(): Document {
+  const html = readFileSync(INDEX_HTML, 'utf-8');
+  return parseHTML(html).document;
+}
+```
+
+### 2. Lighthouse Proxy Assertions
+
+When Chrome is unavailable, validate individual Lighthouse audit factors:
+
+- **Viewport meta** → Mobile-friendly score
+- **Semantic landmarks** (`<main>`, `<nav>`, `<footer>`) → Accessibility sub-score
+- **Image width/height attributes** → CLS prevention (Cumulative Layout Shift)
+- **Font-display strategy** → Text visibility during load
+- **No parser-blocking scripts in `<head>`** → FCP/TTI
+- **lang attribute on `<html>`** → SEO best practice
+- **Favicon + robots.txt existence** → Best practices audit
+
+### 3. Page Weight Budget Enforcement
+
+Walk the dist directory and sum file sizes:
+
+```typescript
+function getDistFiles(): { path: string; size: number }[] {
+  const result: { path: string; size: number }[] = [];
+  function walk(dir: string) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) result.push({ path: full, size: statSync(full).size });
+    }
+  }
+  walk(DIST_DIR);
+  return result;
+}
+
+// Enforce 500KB budget (excluding large binary assets if needed)
+const weightExcludingLogo = distFiles
+  .filter((f) => !f.path.endsWith('logo.gif'))
+  .reduce((sum, f) => sum + f.size, 0);
+expect(weightExcludingLogo).toBeLessThanOrEqual(512000);
+```
+
+### 4. Interaction Responsiveness Validation
+
+Instead of measuring actual elapsed time (unreliable in Node), verify that event handlers are synchronous:
+
+```typescript
+// Verify navigation click handler is synchronous
+it('nav link click handler is synchronous (no artificial delays)', () => {
+  const { document: pageDoc } = parseHTML(buildFullPageHTML());
+  const link = pageDoc.querySelector('[data-nav-link="features"]')!;
+  const target = pageDoc.getElementById('features')!;
+
+  let calledWith: any = null;
+  target.scrollIntoView = (opts?: any) => { calledWith = opts; };
+
+  link.addEventListener('click', (e: Event) => {
+    e.preventDefault();
+    pageDoc.getElementById('features')?.scrollIntoView({ behavior: 'smooth' });
+  });
+
+  link.dispatchEvent(new Event('click', { bubbles: true, cancelable: true }));
+
+  // Handler calls scrollIntoView immediately — no setTimeout before it
+  expect(calledWith).toEqual({ behavior: 'smooth' });
+});
+```
+
+Key checks for each interactive element:
+- **Navigation clicks**: `scrollIntoView` called synchronously, no debounce/throttle
+- **Copy buttons**: `classList.add('copied')` before any `setTimeout`
+- **Mobile menu**: `classList.add('open')` before focus trap `setTimeout`
+- **CSS transitions**: Verify transition durations are ≤ 250ms
+
+### 5. Resource Blocking Analysis
+
+Check for render-blocking and parser-blocking resources:
+
+```typescript
+// No external stylesheets that block rendering
+const externalStylesheets = document.querySelectorAll('link[rel="stylesheet"][href]');
+expect(externalStylesheets.length).toBeLessThanOrEqual(2);
+
+// No synchronous scripts in head
+const blockingScripts = Array.from(headScripts).filter((s) => {
+  return !s.getAttribute('type') && !s.hasAttribute('defer') && !s.hasAttribute('async');
+});
+expect(blockingScripts.length).toBe(0);
+
+// No third-party scripts
+const thirdPartyScripts = Array.from(externalScripts).filter((s) => {
+  const src = s.getAttribute('src') || '';
+  return src.startsWith('http') || src.startsWith('//');
+});
+expect(thirdPartyScripts.length).toBe(0);
+```
+
+### 6. Build Output Minification Verification
+
+```typescript
+// HTML should not have large comment blocks
+const largeComments = rawHtml.match(/<!--[\s\S]{50,}-->/g);
+expect(largeComments).toBeNull();
+
+// HTML should not have runs of 4+ consecutive spaces
+expect(/[ ]{4,}/.test(rawHtml)).toBe(false);
+
+// No source maps should leak to production
+const sourceMaps = distFiles.filter((p) => p.endsWith('.map'));
+expect(sourceMaps.length).toBe(0);
+```
+
+## Best Practices
+
+- Always build with `NODE_ENV=production` to get production-optimized output
+- Parse HTML once in `beforeAll` and reuse across test cases
+- Keep tests deterministic — avoid `performance.now()` or `setTimeout`-based measurements
+- Use source code inspection for configuration checks (e.g., verify IntersectionObserver usage in NavBar.astro)
+- Map each proxy assertion to a specific Lighthouse audit category
+- Keep the page weight budget separate for known-large assets (like animated GIFs) that can't be optimized without format conversion
+
+## Resources
+
+### scripts/
+
+*(No helper scripts needed — tests are self-contained vitest files)*
+
+### references/
+
+- `README.md` — This documentation

.claude/skills/astro-seo-meta-tags/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: astro-seo-meta-tags
+description: Use when adding SEO metadata, Open Graph tags, or semantic HTML to an Astro/static site. Covers the layered constant -> utility -> component pattern for SEO.
+scope: project
+---
+
+See [README.md](references/README.md) for full documentation.

.claude/skills/astro-seo-meta-tags/references/README.md

@@ -0,0 +1,33 @@
+# Astro Seo Meta Tags
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## When to Use This Skill
+
+Use this skill when users request:
+
+- [TODO: Example request 1]
+- [TODO: Example request 2]
+
+## Core Capabilities
+
+### 1. [TODO: Capability Name]
+
+[TODO: Description and examples]
+
+## Best Practices
+
+- [TODO: Best practice 1]
+- [TODO: Best practice 2]
+
+## Resources
+
+### scripts/
+
+[TODO: Describe helper scripts, or delete this section if none]
+
+### references/
+
+- `README.md` - This documentation

.claude/skills/css-contrast-ratio-testing/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: css-contrast-ratio-testing
+description: Use when validating color contrast ratios against WCAG 2.1 AA/AAA thresholds. Implements the official relative luminance formula for programmatic contrast computation from CSS custom properties.
+---
+
+See [README.md](references/README.md) for full documentation.