# Technical Blog System Rules & Architecture Directives

## 1. Pedagogical Explanations (Interactive Learning)
1. **Explain the Code:** Whenever creating or refactoring code (Eleventy configuration, Nunjucks templates, CSS modules, build scripts), provide a clear, educational breakdown.
2. **Break Down Key Concepts:** Explain *why* a particular Eleventy filter, Nunjucks tag, or CSS variable structure was used so the user learns the foundational concepts.
3. **No Magic:** Avoid opaque or overly clever abstractions; prioritize readable, idiomatic code with commentary explaining tricky points.

---

## 2. CSS Architecture & Isolation
1. **Zero Monolithic Inlines:** Do not inject raw `<style>` blocks into HTML templates.
2. **Modular File Structure:**
   - Put global tokens in `src/assets/css/tokens.css`.
   - Put reset and base typography in `src/assets/css/reset.css`.
   - Put layout structures (tiling layout, split grids) in `src/assets/css/layout.css`.
   - Put scoped component styles in `src/assets/css/components/<component-name>.css`.
3. **Design System Token Integrity:** Always use CSS custom properties defined in `tokens.css`:
   - Canvas: `var(--bg-canvas)` (`#0d0f12`)
   - Surface: `var(--bg-surface)` (`#121417`)
   - Elevated: `var(--bg-elevated)` (`#1c1f26`)
   - Borders: `var(--border-color)` (`#2b303b`)
   - Text: `var(--text-primary)` (`#e0e6f0`), `var(--text-muted)` (`#8a95a5`)
   - Accents: `var(--accent-cyan)` (`#00f0ff`), `var(--accent-green)` (`#00e676`), `var(--accent-amber)` (`#ffb700`)
4. **Hard Aesthetic Constraints:**
   - No glassmorphism (`backdrop-filter`).
   - No box-shadows or glows.
   - No linear/radial gradients.
   - Border radius strictly bounded between `0px` and `4px`.
   - Transition durations set to `none` or `0s` for instant snap responses on hover.

---

## 3. Templating Guidelines (Eleventy + Nunjucks)
1. **Layout Hierarchy:**
   - Root template: `src/_includes/layouts/base.njk` (contains HTML structure, `<head>`, metadata, scripts, stylesheets).
   - Content layouts: `src/_includes/layouts/post.njk` (for articles), `src/_includes/layouts/page.njk` (for landing/catalog).
2. **Component Partials:**
   - Isolated partials in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `stats-sidebar.njk`, `code-box.njk`, `footer.njk`).
   - Pass dynamic data via Nunjucks macros or contextual variables.

---

## 4. Obsidian Content Pipeline
1. **Frontmatter Specification:** Every post ingested from Obsidian must adhere to:
   ```yaml
   title: "Article Title"
   date: YYYY-MM-DD
   tags: ["#tag1", "#tag2"]
   excerpt: "Single paragraph summary"
   readingTime: "X MIN READ"
   draft: false
   ```
2. **Obsidian Normalization:**
   - Wikilinks `[[slug]]` or `[[slug|Label]]` must be transformed into standard web URLs (`/posts/slug/`).
   - Callout blocks (`> [!NOTE]`, `> [!WARNING]`, etc.) must render as terminal-style alert callouts.
   - Images must be processed into `src/assets/images/posts/` and linked via standard `<img>` or Markdown image syntax.