60 lines
3.8 KiB
Markdown
60 lines
3.8 KiB
Markdown
# Technical Blog Project Standards & Architectural Specification
|
|
|
|
This document is a direct reference for the `standards-verification` skill, mirroring the authoritative project standards defined in [`.agents/standards.md`](file:///home/venus/code/blog/.agents/standards.md).
|
|
|
|
---
|
|
|
|
## 1. User Content Sovereignty (Highest Priority)
|
|
- User custom writing, post titles, tags, navigation labels, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups.
|
|
- Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
|
|
- Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.
|
|
|
|
---
|
|
|
|
## 2. Strict Test-Driven Development (TDD) & Adversarial Verification
|
|
- **Test-First Invariant:** Automated test cases in `test/*.test.js` MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts). Never write functional code before tests.
|
|
- **Mandatory Adversarial Testing:** Standard behavior for every change must include adversarial tests specifically designed to falsify assumptions (missing env vars like `SITE_DOMAIN`, null/undefined/malformed inputs, boundary values, path traversals, design rule violations).
|
|
- **Pre-Presentation Verification Gate:** Run `npm test` before presenting the final output to the user. All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.
|
|
|
|
---
|
|
|
|
## 3. Design System & CSS Specification
|
|
- **Color Palette:** Canvas `#0d0f12`, Surface `#121417`, Elevated `#1c1f26`, Borders `#2b303b`, Text `#e0e6f0`, Accents `#00f0ff` (Cyan), `#00e676` (Green), `#ffb700` (Amber), `#ff5252` (Red).
|
|
- **Hard Anti-Patterns:**
|
|
- NO glassmorphism (`backdrop-filter`).
|
|
- NO drop shadows or glows (`box-shadow`, `text-shadow`).
|
|
- NO linear or radial gradients.
|
|
- Border-radius capped at `0px` to `4px` maximum.
|
|
- Transitions must be instant binary snaps (`none` or `0s`).
|
|
- **Typography:** `IBM Plex Mono` / `JetBrains Mono` for UI and code; `Inter` for body prose.
|
|
- **CSS Modularity:** Zero inline `<style>` tags. Decompose into `tokens.css`, `reset.css`, `layout.css`, `components/*.css`.
|
|
|
|
---
|
|
|
|
## 4. Templating & Eleventy Architecture
|
|
- **Layouts & Partials:** Root `layouts/base.njk`, `layouts/post.njk`, `layouts/page.njk`. Isolated partials in `_includes/partials/`.
|
|
- **Collection Filtering:** `collections.posts` and `collections.tagList` must filter through `isPostPublic(post)` (excluding `draft: true` and `hidden: true`).
|
|
- **Sorting:** Posts sorted via `postComparator` (pinned/featured first, then chronological descending).
|
|
- **Hidden Posts:** When `hidden: true`, page compiles to direct link but is excluded from public lists and injects `<meta name="robots" content="noindex, nofollow">`.
|
|
|
|
---
|
|
|
|
## 5. Obsidian Content & Frontmatter Contract
|
|
- Required frontmatter: `title` (>= 5 chars), `date` or `created` (ISO), `tags` (array), `excerpt` (>= 20 chars).
|
|
- Optional: `readingTime`, `draft`, `hidden`, `pinned`, `featured`.
|
|
- Obsidian conversions: Wikilinks `[[slug|Label]]` -> `[Label](/posts/slug/)`, attachments `![[image.png]]` -> ``.
|
|
|
|
---
|
|
|
|
## 6. Server & Security Invariants
|
|
- `server.js`: Native Node HTTP, zero external runtime dependencies.
|
|
- Security headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`.
|
|
- Path traversal defense: Sanitize and verify paths remain inside root.
|
|
- Healthcheck: `/healthz` returns 200 OK JSON `{ status: "ok", uptime: ... }`.
|
|
|
|
---
|
|
|
|
## 7. Defensive Programming & Error Prevention
|
|
- Guard against `null`, `undefined`, primitives in all utility functions.
|
|
- Docker: `node:22-alpine`, non-root / clean entrypoint script as PID 1.
|