cleanup of the working tree. Created docs/{policies,reports} folders to keep documentation organized

1 files changed, 217 insertions, 0 deletions

diff --git a/docs/policies/COLOR-REFERENCE.md b/docs/policies/COLOR-REFERENCE.md
new file mode 100644
index 0000000..20d8171
--- /dev/null
+++ b/docs/policies/COLOR-REFERENCE.md
@@ -0,0 +1,217 @@
+# Color Reference — Quick Copy-Paste for Week 2+
+
+Use this file when building components. All values are CSS custom properties—**never hard-code colors**.
+
+---
+
+## Base Colors
+
+### Dark Mode (Default)
+```css
+--bg:          #060b10    /* Primary background (darkest) */
+--bg2:         #0c1520    /* Secondary background */
+--surface:     #101e2d    /* Card/container surface */
+--border:      #182840    /* Border color */
+--text:        #c4d6e8    /* Primary text (light) */
+--text-dim:    #7a9bb8    /* Secondary/dimmed text */
+--muted:       #304860    /* Muted text, icons */
+--accent:      #a855f7    /* Purple — primary interaction */
+--accent2:     #00ff88    /* Neon green — secondary, highlights */
+--accent-glow: rgba(168, 85, 247, 0.12)  /* Purple glow for shadows */
+```
+
+### Light Mode (html.theme-light)
+```css
+--bg:          #ffffff    /* Primary background (white) */
+--bg2:         #f8f9fa    /* Secondary background */
+--surface:     #f0f3f7    /* Card/container surface */
+--border:      #d9dfe8    /* Border color */
+--text:        #1f2937    /* Primary text (dark) */
+--text-dim:    #374151    /* Secondary/dimmed text */
+--muted:       #d1d5db    /* Muted text, icons */
+--accent:      #9333ea    /* Purple — slightly darker for contrast */
+--accent2:     #10b981    /* Emerald — secondary, softer than dark green */
+--accent-glow: rgba(147, 51, 234, 0.1)   /* Purple glow, lighter */
+```
+
+---
+
+## Article Type Colors
+
+### Dark Mode
+```css
+--type-tech:   #a855f7    /* Purple — technical articles */
+--type-life:   #f59e0b    /* Amber — personal essays */
+--type-quote:  #00ff88    /* Neon green — quotes */
+--type-link:   #38bdf8    /* Cyan — bookmarks */
+--type-photo:  #ec4899    /* Pink — photo essays */
+```
+
+### Light Mode
+```css
+--type-tech:   #7c3aed    /* Purple (darker) */
+--type-life:   #d97706    /* Amber (darker) */
+--type-quote:  #008f5a    /* Green (darker) */
+--type-link:   #0284c7    /* Cyan (darker) */
+--type-photo:  #be185d    /* Pink (darker) */
+```
+
+---
+
+## Semantic Usage Guidelines
+
+| Use Case | Dark Mode | Light Mode | Notes |
+|---|---|---|---|
+| **Primary CTA Button** | `--accent` (#a855f7) | `--accent` (#9333ea) | Use for main actions, large text recommended |
+| **Secondary Button** | `--accent2` (#00ff88) | `--accent2` (#10b981) | Highlights, progress, secondary actions |
+| **Link Color** | `--accent` (#a855f7) | `--accent` (#9333ea) | Visited links can be dimmed |
+| **Button Text (inverted)** | `#ffffff` or `--text` | `#ffffff` on dark buttons | Maintain 4.5:1 contrast |
+| **Badge Background** | `rgba(var, 0.1)` | Lighter shade | Use type colors, dim with opacity |
+| **Border** | `--border` (#182840) | `--border` (#d9dfe8) | Dividers, card edges |
+| **Icon Color** | Inherit text color | Inherit text color | Or use `--accent2` for highlights |
+| **Disabled State** | `--text-dim` (#7a9bb8) | `--text-dim` (#374151) | Lower contrast for inactive elements |
+| **Focus Ring** | `--accent` (#a855f7) | `--accent` (#9333ea) | 2px ring with offset |
+| **Shadow/Glow** | `--accent-glow` | `--accent-glow` | Box-shadow for cards, depth |
+
+---
+
+## Tailwind Utilities Available
+
+```html
+<!-- Background Colors -->
+<div class="bg-bg"></div>      <!-- Primary background -->
+<div class="bg-bg2"></div>     <!-- Secondary background -->
+<div class="bg-surface"></div> <!-- Card surface -->
+
+<!-- Text Colors -->
+<p class="text-text"></p>         <!-- Primary text -->
+<p class="text-text-dim"></p>     <!-- Secondary text -->
+<p class="text-accent"></p>       <!-- Accent (purple) -->
+<p class="text-accent2"></p>      <!-- Accent2 (green/emerald) -->
+<p class="text-muted"></p>        <!-- Muted text -->
+
+<!-- Border Colors -->
+<div class="border border-border"></div>
+
+<!-- Type Badge Colors (pre-defined) -->
+<span class="type-tech"></span>   <!-- Tech: purple bg -->
+<span class="type-life"></span>   <!-- Life: amber bg -->
+<span class="type-quote"></span>  <!-- Quote: green bg -->
+<span class="type-link"></span>   <!-- Link: cyan bg -->
+<span class="type-photo"></span>  <!-- Photo: pink bg -->
+```
+
+---
+
+## WCAG AA Contrast Ratios
+
+**Dark Mode:**
+- `--text` on `--bg`: 13.2:1 ✅ (normal text safe)
+- `--accent` on `--bg`: 3.8:1 ⚠️ (large text only, ≥18pt)
+- `--accent2` on `--bg`: 4.1:1 ⚠️ (large text only, ≥18pt)
+- `--text-dim` on `--bg`: 7.0:1 ✅ (secondary text safe)
+
+**Light Mode:**
+- `--text` on `--bg`: 14.8:1 ✅ (excellent)
+- `--accent` on `--bg`: 4.8:1 ✅ (all text safe)
+- `--accent2` on `--bg`: 5.1:1 ✅ (all text safe)
+
+**Recommendation for buttons:**
+- Dark mode: Use `--text` or `--accent` on `--surface` (lighter background for better contrast)
+- Light mode: Any color on `--bg` is safe
+
+---
+
+## Font Families
+
+```css
+font-family: 'Oxanium', monospace;      /* Headings, display (700, 800) */
+font-family: 'IBM Plex Sans', sans-serif; /* Body, UI text (300, 400, 600) */
+font-family: 'JetBrains Mono', monospace; /* Code, metadata (400, 600) */
+```
+
+---
+
+## Quick Reference: Building a Button
+
+```html
+<!-- Primary Button -->
+<button class="px-4 py-2 bg-accent text-white rounded font-bold hover:opacity-80 focus:ring-2 focus:ring-accent focus:ring-offset-2 disabled:opacity-50">
+  Click me
+</button>
+
+<!-- CSS (in main.css, @layer components) -->
+.btn {
+  @apply px-4 py-2 rounded font-bold transition-opacity duration-200;
+  @apply focus:ring-2 focus:ring-offset-2;
+  background-color: var(--accent);
+  color: #ffffff;
+  ring-offset-color: var(--bg);
+}
+
+.btn:hover {
+  opacity: 0.8;
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+---
+
+## Quick Reference: Building a Badge
+
+```html
+<!-- Type Badge -->
+<span class="type-tech px-2 py-1 rounded text-sm font-mono">
+  Tech Article
+</span>
+
+<!-- CSS (in main.css, @layer components) -->
+.badge {
+  @apply px-2 py-1 rounded text-sm font-mono;
+}
+
+/* Type variants use existing .type-* classes */
+```
+
+---
+
+## Matrix Rain Opacity Settings
+
+```css
+/* Dark theme, inner pages */
+html.theme-dark #matrix-rain {
+  opacity: 0.13;
+}
+
+/* Light theme, inner pages */
+html.theme-light #matrix-rain {
+  opacity: 0.18;
+}
+
+/* Dark theme, home page (more prominent) */
+html.theme-dark body[data-page-kind="home"] #matrix-rain {
+  opacity: 0.28;
+}
+
+/* Light theme, home page */
+html.theme-light body[data-page-kind="home"] #matrix-rain {
+  opacity: 0.35;
+}
+```
+
+---
+
+## Remember
+
+- **Always use CSS custom properties** (`var(--accent)`) — never hard-code colors
+- **Test in both dark and light modes** — use `theme-dark` and `theme-light` classes on `html`
+- **Check contrast** on new text/background combinations
+- **Rebuild CSS** after template changes: `npm run build`
+- **Use semantic names** — `--accent`, not `--purple`
+
+Good luck with Week 2! 🚀
+