blog/.agents/skills/eleventy-tiling-blog/SKILL.md

name, description

name	description
eleventy-tiling-blog	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:

   :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:

     <!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

Always follow the project TDD standard: write automated tests (including adversarial edge cases) in test/ before modifying functional templates, filters, or configuration. Ensure all test cases pass before presenting the final output.

Run these commands to test and verify builds:

# Run complete test suite (unit tests, filters, server, design rules, build integrity)
npm test

# 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