initial commit

samples/design-specification.md

@@ -0,0 +1,81 @@
+# Project Brief: Technical Web Architecture & Blog
+
+**Project Type:** Personal Blog & Technical Documentation Site
+**Design Philosophy:** High-signal, low-noise. Developer-centric minimalism.
+**Vibe/Comparisons:** Zed Editor, Ghostty, Noctalia.dev.
+**Strictly Avoid:** Raycast, Astro, Vercel-style "SaaS" aesthetics.
+
+## 1. Executive Summary
+This project requires a web interface that feels like a native development environment or terminal emulator, not a marketing page. The design must prioritize raw performance, keyboard navigability, and information density. It should evoke the craftsmanship of tiling window managers and modal text editors.
+
+The content will heavily feature deep technical writing, including CTF write-ups, network routing diagrams, Docker/Traefik architectures, and raw code snippets (Lua, POSIX `sh`, and Python). The design must accommodate high-density information without visual clutter.
+
+---
+
+## 2. Global Rules & Anti-Patterns
+
+To achieve the correct aesthetic, the designer must adhere to strict constraints.
+
+> **The "Do Not Use" List**
+> *   **NO Glassmorphism:** Zero use of `backdrop-filter: blur()`, frosted glass, or translucent overlays.
+> *   **NO Glows or Drop Shadows:** Elements should not float, glow, or cast shadows. Depth is created through crisp 1px borders and distinct surface colors.
+> *   **NO Gradients:** Avoid sweeping linear or radial gradients. Stick to solid colors.
+> *   **NO Spring Animations:** Avoid floaty, delayed transitions. 
+> *   **NO Rounded Blobs:** Keep border-radii minimal (0px to 4px max). Sharp corners are preferred.
+
+---
+
+## 3. Typography System
+
+The typographical hierarchy is a hybrid system utilizing monospace fonts for structural elements and a clean sans-serif for long-form reading.
+
+| Usage | Font Family Preference | Weight | Role |
+| :--- | :--- | :--- | :--- |
+| **Structural / UI** | IBM Plex Mono, JetBrains Mono | Regular (400), Medium (500) | Navigation links, metadata, dates, tags, timestamps, buttons. |
+| **Code Blocks** | JetBrains Mono, Fira Code | Regular (400) | Inline code snippets, terminal command blocks, scripts. |
+| **Body Prose** | Inter, Geist Sans, Roboto | Regular (400) | Standard article paragraphs, lists. |
+| **Headings (H1-H3)**| IBM Plex Mono (or Sans variant) | Bold (700) | Article titles, section headers. |
+
+**Typographical Constraints:**
+*   **Line Height:** `1.6` to `1.7` for prose.
+*   **Max Width:** Cap article text at `65ch` (characters) for optimal readability.
+
+---
+
+## 4. Color Palette (Dark Mode Native)
+
+The site does not need a light mode. It should be built as a dark-mode native experience using a muted, low-saturation charcoal palette, mimicking a modern terminal or IDE.
+
+*   **Base Canvas (`#121417` or `#0d0f12`):** A deep slate/charcoal. Not pure black (`#000000`), which causes eye strain.
+*   **Surface / Card (`#1c1f26`):** Slightly lighter than the canvas for article blocks or terminal windows.
+*   **Borders & Dividers (`#2b303b`):** Subtle, low-contrast 1px solid lines used to define grids and separate content.
+*   **Primary Text (`#e0e6f0`):** Off-white/light ash for prose.
+*   **Muted Text (`#8a95a5`):** For timestamps, metadata, and non-essential UI text.
+*   **Accent Color (Designer's Choice):** One single, vibrant terminal color (e.g., ANSI Green, Amber, or Cyan) used sparingly for active states, link hovers, or terminal prompts (like `>`).
+
+---
+
+## 5. Layout & Component Architecture
+
+The layout should be heavily grid-based, feeling structural and deliberate.
+
+### Core Components Needed
+1.  **Terminal-Style Code Blocks:** Must support syntax highlighting. Should include a simple header (e.g., showing the filename like `config.lua` or `docker-compose.yml`) with a 1px border.
+2.  **Metadata Tags:** Small, monospaced inline blocks for categorizing posts (e.g., `[#homelab]`, `[#ctf]`, `[#hyprland]`).
+3.  **Keyboard Shortcut Hints:** Visual styling for `<kbd>` elements, rendering as crisp, bordered boxes (e.g., `Ctrl` + `K`).
+4.  **Index/Archive List:** A dense, tabular list for older posts, prioritized by date, title, and tags, rather than large image thumbnails.
+
+### Spacing & Grid
+*   Use a rigid 4pt or 8pt baseline grid.
+*   Padding inside code blocks and cards should be dense but mathematically consistent.
+*   Full-bleed horizontal dividers (`<hr>`) should be used to separate major sections instead of large margins.
+
+---
+
+## 6. Interaction & Motion
+
+Interactivity should mirror command-line interfaces: fast, binary, and unembellished.
+
+*   **Hover States:** Immediate state changes. Instead of fading a button's background over `300ms`, snap the background color instantly or invert the text/background colors.
+*   **Focus States:** Explicit, high-visibility 1px or 2px solid outlines (using the accent color) when navigating via the `Tab` key. Accessibility and keyboard navigation are paramount.
+*   **Active Elements:** Use structural indicators (like a `>` prepended to an active navigation link, or a solid left-border block) rather than changing font sizes or scaling elements up.