88 lines
5.5 KiB
Markdown
88 lines
5.5 KiB
Markdown
# Technical Blog System Rules & Architecture Directives
|
|
|
|
## 1. Core Invariant: User Content Sovereignty (Highest Priority)
|
|
1. **User Edits Are Absolute Ground Truth:**
|
|
- The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
|
|
- They strictly take precedence over any background content description, sample design mockup (`sample-designs/*`), skill instructions, or default boilerplate.
|
|
2. **Strict Prohibition on Unsolicited Rewriting or Renaming:**
|
|
- You must **NEVER** revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
|
|
- Do not reintroduce removed text or names from prior mockups or commits.
|
|
3. **Mandatory Clarification Gate:**
|
|
- If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must **NOT** unilaterally modify it.
|
|
- You must ask the user for specific clarification before altering any user-authored writing or naming.
|
|
4. **Sample Designs Are Layout References Only:**
|
|
- Files in `sample-designs/` serve solely as visual, CSS, and structural layout references.
|
|
- Never extract or re-inject titles, domain names, service labels, or technical copy from `sample-designs/` into active templates or site data without explicit instruction.
|
|
|
|
---
|
|
|
|
## 2. 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.
|
|
|
|
---
|
|
|
|
## 3. 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.
|
|
|
|
---
|
|
|
|
## 4. 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.
|
|
|
|
---
|
|
|
|
## 5. 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.
|
|
|
|
---
|
|
|
|
## 6. 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.
|