119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
---
|
|
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
|
|
|
|
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:
|
|
```bash
|
|
# 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
|
|
```
|
|
|