---
name: eleventy-tiling-blog
description: >-
  Use this skill when developing, refactoring, or building the Eleventy blog, modularizing CSS into tokens and components, creating Nunjucks layouts and partials from sample designs, or configuring Eleventy build pipelines.
---

# Eleventy Tiling Blog Development Skill

This skill guides the agent in modularizing templates and CSS from `sample-designs/` into a clean, DRY Eleventy (11ty) static publication site.

> [!IMPORTANT]
> **User Content Sovereignty:** Files in `sample-designs/` are layout and CSS references ONLY. Never extract or re-inject titles, service names, or text from `sample-designs/` over user-defined or sanitized content. User-authored text and naming conventions are the highest level of truth.

---

## 1. CSS Modularization Workflow

When extracting CSS from `sample-designs/*.html` into `src/assets/css/`:

1. **Tokens (`src/assets/css/tokens.css`):**
   Extract all `:root` custom properties:
   ```css
   :root {
     --bg-canvas: #0d0f12;
     --bg-surface: #121417;
     --bg-elevated: #1c1f26;
     --border-color: #2b303b;
     --text-primary: #e0e6f0;
     --text-muted: #8a95a5;
     --accent-cyan: #00f0ff;
     --accent-green: #00e676;
     --accent-amber: #ffb700;
     --accent-red: #ff5252;
     --font-mono: 'IBM Plex Mono', monospace;
     --font-code: 'JetBrains Mono', monospace;
     --font-prose: 'Inter', sans-serif;
   }
   ```

2. **Reset & Base (`src/assets/css/reset.css`):**
   - Universal box-sizing reset (`box-sizing: border-box; margin: 0; padding: 0;`).
   - Body font defaults, base line-height (`1.6`), instant hover transitions (`transition: none;`).
   - Explicit 1px/2px focus ring styling for keyboard accessibility.

3. **Layout Grid (`src/assets/css/layout.css`):**
   - `.tiling-layout`: Centered flex column, `max-width: 1120px` to `1160px`.
   - `.split-grid`: 2-column or multi-tile layout with rigid gaps (`16px`).
   - `.article-workspace-grid`: Left sticky sidebar (`290px`) + main article reading view (`1fr`).

4. **Component Modules (`src/assets/css/components/`):**
   - `global-bar.css`: `.global-bar`, `.brand-group`, `.status-indicator`, `.bar-nav`, `.bar-link`.
   - `tiles.css`: `.tile`, `.tile-header`, `.tile-title`, `.tile-meta`, `.hero-tile`.
   - `code-box.css`: `.terminal-code-box`, `.code-titlebar`, `.code-content`.
   - `article.css`: Prose typography capped at `65ch`, inline `<kbd>`, tables, callouts.

---

## 2. Nunjucks (`.njk`) Component Architecture

1. **Layout Inheritance:**
   - `src/_includes/layouts/base.njk`:
     ```html
     <!DOCTYPE html>
     <html lang="en">
     <head>
       <meta charset="UTF-8">
       <title>{{ title }} | {{ site.title or site.name }}</title>
       <link rel="stylesheet" href="/assets/css/main.css">
     </head>
     <body>
       <main class="tiling-layout">
         {% include "partials/global-bar.njk" %}
         {{ content | safe }}
         {% include "partials/footer.njk" %}
       </main>
     </body>
     </html>
     ```
   - `src/_includes/layouts/post.njk`:
     Extends `layouts/base.njk`, injecting the `.article-workspace-grid` with the table of contents sidebar and article body.

2. **Reusable Partials:**
   - `src/_includes/partials/global-bar.njk`
   - `src/_includes/partials/hero-tile.njk`
   - `src/_includes/partials/post-card.njk`
   - `src/_includes/partials/stats-sidebar.njk`
   - `src/_includes/partials/code-box.njk`

---

## 3. Explaining Changes to the User

When writing or modifying Eleventy files:
- Explain **how Nunjucks blocks and layout inheritance prevent template duplication**.
- Explain **how CSS custom properties cascade and ensure dark-mode consistency**.
- Point out how the resulting build outputs raw static HTML in `_site/` with zero runtime JavaScript overhead.

---

## 4. Validation & Verification

Run these commands to test Eleventy builds:
```bash
# Validate Eleventy configuration and build static output
npx @11ty/eleventy --dryrun

# Build to _site directory
npx @11ty/eleventy

# Launch local dev server with auto-refresh
npx @11ty/eleventy --serve
```