venus
e4601dbbcb
- Update AGENTS.md and .agents/rules/blog-system.md with strict TDD mandate - Extract Eleventy custom filters into modular src/_filters/index.js for unit testing - Add npm test script using Node.js native test runner (node:test) - Create test/site-config.test.js for environment validation and fatal error assertions - Create test/filters.test.js for adversarial filter edge cases (dates, limits, reading time, headings) - Create test/frontmatter-schema.test.js enforcing post metadata contracts - Create test/design-rules.test.js enforcing strict anti-patterns (no glassmorphism, no shadows, max 4px radius) - Create test/build-integrity.test.js checking static output, zero 404 links, and TOC anchor targets
72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 5. Test-Driven Development (TDD) & Adversarial Verification
|
|
1. **Red-Green-Refactor Lifecycle:**
|
|
- Write tests in `test/*.test.js` using Node's native test runner (`node:test`, `node:assert/strict`).
|
|
- Test inputs before implementing filters, data loaders, or template macros.
|
|
2. **Adversarial Test Coverage Required:**
|
|
- **Data & Configuration:** Test that missing required environment variables (e.g. `SITE_DOMAIN`) throw fatal errors.
|
|
- **Filters:** Test edge cases: empty strings, undefined values, single-word inputs, massive word counts, non-date objects.
|
|
- **Content Schemas:** Validate all Markdown files in `src/posts/` against frontmatter schemas.
|
|
- **Design Spec Compliance:** Automate regex/AST assertions on `src/assets/css/` ensuring zero violations of the "Do Not Use" list (`backdrop-filter`, `box-shadow`, `text-shadow`, gradients, floaty transitions).
|
|
- **Link & Anchor Integrity:** Verify that every compiled page has zero broken internal links and that all Table of Contents anchor links resolve to valid heading IDs.
|
|
3. **Execution Invariant:**
|
|
- Always run `npm test` before committing. All tests must pass cleanly with 0 failures.
|