Skip to content

Commit 292d126

Browse files
keoboxclaude
keobox
and
claude
authored
002 dark theme restyle (#1)
* feat: restyle site with dark theme inspired by podcast logo Black background, white text, golden yellow (#e8a317) "Py" accent in the title matching the podcast logo. All color changes via CSS custom properties. WCAG AA contrast ratios verified for all combinations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: update Slack invite link to bit.ly shortlink Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add Telegram contact link button Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 85e5636 commit 292d126

File tree

8 files changed

+442
-9
lines changed

8 files changed

+442
-9
lines changed

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
Auto-generated from all feature plans. Last updated: 2026-03-10
44

55
## Active Technologies
6+
- Python 3.13 (Pelican build tooling only; changes are CSS/HTML) + Pelican (latest stable) — no new dependencies (002-dark-theme-restyle)
7+
- N/A (static site) (002-dark-theme-restyle)
68

79
- Python 3.13 + Pelican (latest stable), Markdown (Pelican plugin) (001-static-site-homepage)
810

@@ -22,6 +24,7 @@ cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLO
2224
Python 3.13: Follow standard conventions
2325

2426
## Recent Changes
27+
- 002-dark-theme-restyle: Added Python 3.13 (Pelican build tooling only; changes are CSS/HTML) + Pelican (latest stable) — no new dependencies
2528

2629
- 001-static-site-homepage: Added Python 3.13 + Pelican (latest stable), Markdown (Pelican plugin)
2730

‎specs/002-dark-theme-restyle/checklists/requirements.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Specification Quality Checklist: Dark Theme Restyle
2+
3+
**Purpose**: Validate specification completeness and quality before proceeding to planning
4+
**Created**: 2026-03-11
5+
**Feature**: [spec.md](../spec.md)
6+
7+
## Content Quality
8+
9+
- [x] No implementation details (languages, frameworks, APIs)
10+
- [x] Focused on user value and business needs
11+
- [x] Written for non-technical stakeholders
12+
- [x] All mandatory sections completed
13+
14+
## Requirement Completeness
15+
16+
- [x] No [NEEDS CLARIFICATION] markers remain
17+
- [x] Requirements are testable and unambiguous
18+
- [x] Success criteria are measurable
19+
- [x] Success criteria are technology-agnostic (no implementation details)
20+
- [x] All acceptance scenarios are defined
21+
- [x] Edge cases are identified
22+
- [x] Scope is clearly bounded
23+
- [x] Dependencies and assumptions identified
24+
25+
## Feature Readiness
26+
27+
- [x] All functional requirements have clear acceptance criteria
28+
- [x] User scenarios cover primary flows
29+
- [x] Feature meets measurable outcomes defined in Success Criteria
30+
- [x] No implementation details leak into specification
31+
32+
## Notes
33+
34+
- All items pass validation. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
35+
- The Assumptions section documents reasonable defaults (yellow color approximation, single-line breakpoint, CSS variables approach).
36+
- FR-005 mentions "span or similar markup" which is the minimum necessary to describe the requirement without prescribing a specific implementation.

‎specs/002-dark-theme-restyle/plan.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Implementation Plan: Dark Theme Restyle
2+
3+
**Branch**: `002-dark-theme-restyle` | **Date**: 2026-03-11 | **Spec**: [spec.md](spec.md)
4+
**Input**: Feature specification from `/specs/002-dark-theme-restyle/spec.md`
5+
6+
## Summary
7+
8+
Restyle the Intervista Pythonista site with a dark theme inspired by the podcast logo. The implementation requires two changes: (1) update the CSS custom properties in `style.css` to swap from a light color scheme to a dark one (black background, white text, golden yellow accent), and (2) modify the Jinja2 template `page.html` to wrap the "Py" portion of the title in a `<span>` element for targeted CSS coloring. The existing CSS variables architecture makes the color scheme swap straightforward.
9+
10+
## Technical Context
11+
12+
**Language/Version**: Python 3.13 (Pelican build tooling only; changes are CSS/HTML)
13+
**Primary Dependencies**: Pelican (latest stable) — no new dependencies
14+
**Storage**: N/A (static site)
15+
**Testing**: Manual Lighthouse audit, visual inspection, WCAG contrast ratio verification
16+
**Target Platform**: Web browsers (GitHub Pages deployment)
17+
**Project Type**: Static website (Pelican)
18+
**Performance Goals**: Lighthouse 100/100 in all four categories
19+
**Constraints**: Zero JavaScript, vanilla CSS only, CSS payload under 10 KB
20+
**Scale/Scope**: Single-page site, 1 CSS file (~150 lines), 1 HTML template (43 lines)
21+
22+
## Constitution Check
23+
24+
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
25+
26+
| Principle | Status | Justification |
27+
|-----------|--------|---------------|
28+
| I. Extreme Minimalism | PASS | No JavaScript. Changes are pure CSS variable updates and one `<span>` in HTML template. |
29+
| II. Tooling — Pelican | PASS | All changes within Pelican's theme system (`theme/flavor/`). No custom build scripts. |
30+
| III. Content — Pure Markdown | PASS | No content file changes. Only theme template and stylesheet modified. |
31+
| IV. Styling — Vanilla CSS | PASS | Plain CSS only. CSS custom properties for theming. No preprocessors or frameworks. |
32+
| V. Performance — Perfect Lighthouse | PASS | Color-only changes. No new assets, fonts, or resources. Contrast ratios verified (see research.md). Must validate post-implementation. |
33+
| VI. Portability — Standard CI/CD | PASS | No deployment changes. Same build process produces updated output. |
34+
35+
**Gate result**: ALL PASS — proceed to implementation.
36+
37+
## Project Structure
38+
39+
### Documentation (this feature)
40+
41+
```text
42+
specs/002-dark-theme-restyle/
43+
├── plan.md # This file
44+
├── research.md # Phase 0: color research and contrast verification
45+
├── spec.md # Feature specification
46+
├── checklists/
47+
│ └── requirements.md # Spec quality checklist
48+
└── tasks.md # Phase 2 output (created by /speckit.tasks)
49+
```
50+
51+
### Source Code (repository root)
52+
53+
```text
54+
theme/flavor/
55+
├── static/css/
56+
│ └── style.css # UPDATE: dark color scheme via CSS variables
57+
└── templates/
58+
└── page.html # UPDATE: wrap "Py" in <span> for yellow styling
59+
```
60+
61+
**Structure Decision**: No new files or directories needed. This feature modifies exactly 2 existing files in the Pelican custom theme.
62+
63+
## Complexity Tracking
64+
65+
> No constitution violations. No complexity justifications needed.
66+
67+
## Implementation Details
68+
69+
### File 1: `theme/flavor/static/css/style.css`
70+
71+
**Changes to `:root` CSS variables:**
72+
73+
| Variable | Current Value | New Value | Purpose |
74+
|----------|--------------|-----------|---------|
75+
| `--color-bg` | `#ffffff` | `#000000` | Black background |
76+
| `--color-text` | `#1a1a2e` | `#f0f0f0` | Near-white body text |
77+
| `--color-heading` | `#16213e` | `#ffffff` | White headings |
78+
| `--color-accent` | `#3066be` | `#6ea8fe` | Light blue links (visible on dark bg) |
79+
| `--color-accent-hover` | `#1e4a8e` | `#9ec5fe` | Lighter blue on hover |
80+
| `--color-muted` | `#555` | `#aaa` | Lighter gray for footer/secondary text |
81+
| `--color-border` | `#e0e0e0` | `#333` | Dark gray borders |
82+
83+
**New CSS variable:**
84+
85+
| Variable | Value | Purpose |
86+
|----------|-------|---------|
87+
| `--color-py` | `#e8a317` | Golden yellow for "Py" accent, sampled from logo |
88+
89+
**New CSS rule:**
90+
91+
```css
92+
.py-accent {
93+
color: var(--color-py);
94+
}
95+
```
96+
97+
### File 2: `theme/flavor/templates/page.html`
98+
99+
**Change the `<h1>` from:**
100+
```html
101+
<h1>{{ page.title }}</h1>
102+
```
103+
104+
**To:**
105+
```html
106+
<h1>Intervista <span class="py-accent">Py</span>thonista</h1>
107+
```
108+
109+
This hardcodes the title with the `<span>` wrapping "Py". This is acceptable because:
110+
- The site name is fixed ("Intervista Pythonista")
111+
- The `<span>` is semantically neutral (no accessibility impact)
112+
- The yellow coloring is purely presentational via CSS class
113+
114+
### Contrast Ratio Verification
115+
116+
All proposed color combinations meet WCAG AA (see research.md for calculations):
117+
118+
| Combination | Ratio | Requirement | Status |
119+
|-------------|-------|-------------|--------|
120+
| `#f0f0f0` on `#000000` (body text) | 18.4:1 | 4.5:1 | PASS |
121+
| `#ffffff` on `#000000` (headings) | 21:1 | 4.5:1 | PASS |
122+
| `#e8a317` on `#000000` (Py accent) | 9.7:1 | 3:1 (large text) | PASS |
123+
| `#6ea8fe` on `#000000` (links) | 8.3:1 | 4.5:1 | PASS |
124+
| `#9ec5fe` on `#000000` (link hover) | 11.6:1 | 4.5:1 | PASS |
125+
| `#aaa` on `#000000` (muted/footer) | 9.3:1 | 4.5:1 | PASS |

‎specs/002-dark-theme-restyle/research.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Research: Dark Theme Restyle
2+
3+
**Feature**: 002-dark-theme-restyle
4+
**Date**: 2026-03-11
5+
6+
## Research Topic 1: Logo Yellow Color Identification
7+
8+
**Decision**: Use `#E8A317` as the golden yellow accent color for the "Py" text.
9+
10+
**Rationale**: Visual inspection of the podcast logo (`logo_squared.png`) shows a warm golden yellow used for the letters "py" in "pythonista". The color is a saturated amber/golden yellow, distinct from pure yellow (#FFFF00) or pale yellow. The hex value #E8A317 closely matches the logo's yellow and provides strong contrast on a black background.
11+
12+
**Alternatives considered**:
13+
- `#FFD700` (Gold): Too bright/saturated, doesn't match the warmer tone in the logo
14+
- `#DAA520` (Goldenrod): Slightly too brownish, lacks the vibrancy of the logo yellow
15+
- `#F0A500`: Close match but slightly more orange; #E8A317 is a better middle ground
16+
17+
## Research Topic 2: WCAG AA Contrast Ratios on Black Background
18+
19+
**Decision**: All proposed text colors pass WCAG AA contrast requirements against `#000000`.
20+
21+
**Rationale**: WCAG AA requires a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold). The h1 title qualifies as large text (2rem = ~32px).
22+
23+
### Contrast Calculations
24+
25+
Relative luminance formula: `L = 0.2126 * R + 0.7152 * G + 0.0722 * B`
26+
(where R, G, B are linearized sRGB values)
27+
28+
Contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter color.
29+
30+
| Color | Hex | Relative Luminance | Ratio vs #000 | Min Required | Result |
31+
|-------|-----|-------------------|----------------|--------------|--------|
32+
| Body text | `#f0f0f0` | 0.870 | 18.4:1 | 4.5:1 | PASS |
33+
| Headings | `#ffffff` | 1.000 | 21.0:1 | 4.5:1 | PASS |
34+
| Py accent | `#e8a317` | 0.436 | 9.7:1 | 3.0:1 (large) | PASS |
35+
| Links | `#6ea8fe` | 0.367 | 8.3:1 | 4.5:1 | PASS |
36+
| Link hover | `#9ec5fe` | 0.530 | 11.6:1 | 4.5:1 | PASS |
37+
| Muted text | `#aaaaaa` | 0.402 | 9.0:1 | 4.5:1 | PASS |
38+
39+
All combinations exceed WCAG AA thresholds by comfortable margins.
40+
41+
## Research Topic 3: Dark Theme Best Practices for Static Sites
42+
43+
**Decision**: Use CSS custom properties for the full color scheme swap, keeping the same structural CSS.
44+
45+
**Rationale**: The existing site already uses CSS custom properties (`:root` variables) for all colors. Changing the theme is a matter of updating variable values — no structural CSS changes needed. This approach:
46+
- Minimizes diff size and risk of regressions
47+
- Maintains the existing responsive layout unchanged
48+
- Keeps CSS payload well under the 10 KB constitution limit
49+
- Requires no JavaScript for theme switching (single dark theme, not a toggle)
50+
51+
**Alternatives considered**:
52+
- Adding a `prefers-color-scheme` media query for automatic light/dark switching: Rejected because the spec explicitly calls for a dark theme only, not a toggle
53+
- Using `filter: invert(1)` on the body: Rejected because it inverts images too and provides no fine-grained control over accent colors
54+
55+
## Research Topic 4: Title "Py" Markup Approach
56+
57+
**Decision**: Hardcode the title in the template with a `<span class="py-accent">` wrapping the "Py" letters.
58+
59+
**Rationale**: The site name "Intervista Pythonista" is fixed and will not change. Hardcoding the title with inline `<span>` markup is the simplest approach that satisfies the requirement of CSS-only color treatment. The `<span>` is semantically neutral and does not affect accessibility — screen readers will read the full title naturally.
60+
61+
**Alternatives considered**:
62+
- Using `page.title` with a Pelican/Jinja2 filter to inject the span: Over-engineered for a fixed site name; adds complexity with no benefit
63+
- Using CSS `::first-letter` or text coloring pseudo-elements: CSS cannot target arbitrary letter ranges within a word; a markup element is required
64+
- Using JavaScript to find and wrap "Py": Violates Principle I (Extreme Minimalism — zero JS)

‎specs/002-dark-theme-restyle/spec.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Feature Specification: Dark Theme Restyle
2+
3+
**Feature Branch**: `002-dark-theme-restyle`
4+
**Created**: 2026-03-11
5+
**Status**: Draft
6+
**Input**: User description: "Restyle the site with a dark theme inspired by the podcast logo. Black background, white text, yellow 'Py' highlight in the title, no logo image on site. Maintain accessibility and Lighthouse 100/100 scores."
7+
8+
## User Scenarios & Testing *(mandatory)*
9+
10+
### User Story 1 - Dark Theme Visual Identity (Priority: P1)
11+
12+
A visitor opens the Intervista Pythonista website and immediately sees a dark-themed page with a black background and white text. The site title "Intervista Pythonista" appears on a single line, with the letters "Py" in "Pythonista" displayed in a warm golden yellow color that matches the podcast logo, and the rest of the title in white. The overall impression is clean, minimal, and professional — consistent with the podcast's brand identity.
13+
14+
**Why this priority**: The dark theme and yellow "Py" accent are the core visual identity change. Without this, the feature has no value.
15+
16+
**Independent Test**: Can be fully tested by loading the homepage and verifying the background is black, text is white, the title renders on one line, and the "Py" letters are yellow. Delivers the primary brand-aligned visual identity.
17+
18+
**Acceptance Scenarios**:
19+
20+
1. **Given** a visitor on any modern browser, **When** they load the homepage, **Then** the page background is black and all body text is white or light-colored
21+
2. **Given** the page title "Intervista Pythonista", **When** displayed in the header, **Then** it appears on a single line with "Py" in "Pythonista" colored in golden yellow and all other title characters in white
22+
3. **Given** the yellow color used for "Py", **When** compared to the podcast logo, **Then** the yellow matches or closely complements the logo's golden yellow
23+
4. **Given** the current site, **When** restyled, **Then** the logo image is NOT displayed anywhere on the page
24+
25+
---
26+
27+
### User Story 2 - Readable Content on Dark Background (Priority: P2)
28+
29+
A visitor reads the podcast description and host bios on the dark-themed page. All text content — body paragraphs, host names, host bios, section headings — is clearly legible against the black background. Links stand out from surrounding text and are visually distinct in both default and hover/focus states.
30+
31+
**Why this priority**: Content readability is essential for the site to serve its purpose. A dark theme that makes content hard to read defeats the goal.
32+
33+
**Independent Test**: Can be tested by reading all page content and verifying text contrast, link visibility, and heading hierarchy are all clear and comfortable to read.
34+
35+
**Acceptance Scenarios**:
36+
37+
1. **Given** the dark-themed page, **When** a visitor reads body text, **Then** the text has sufficient contrast against the background for comfortable reading
38+
2. **Given** links on the page, **When** displayed, **Then** they are visually distinguishable from surrounding text and have clear hover/focus states
39+
3. **Given** section headings (h2), **When** displayed, **Then** they are clearly distinguishable from body text and maintain visual hierarchy
40+
4. **Given** host profile sections, **When** displayed, **Then** host names, bios, and photos are clearly visible and well-formatted on the dark background
41+
42+
---
43+
44+
### User Story 3 - Accessibility and Performance Preservation (Priority: P3)
45+
46+
The restyled site maintains its existing high accessibility and performance standards. All text meets WCAG AA contrast requirements against the dark background. The site continues to achieve Lighthouse scores of 100/100 across all categories. No new accessibility issues are introduced by the dark theme.
47+
48+
**Why this priority**: The site currently achieves perfect Lighthouse scores. The restyle must not degrade these standards, but achieving the visual goals (P1, P2) takes precedence in implementation order.
49+
50+
**Independent Test**: Can be tested by running Lighthouse audit on the restyled site and verifying all scores remain at 100/100, and by checking WCAG AA contrast ratios for all text/background combinations.
51+
52+
**Acceptance Scenarios**:
53+
54+
1. **Given** all text/background color combinations on the restyled site, **When** checked with a contrast ratio tool, **Then** all combinations meet WCAG AA minimum contrast ratio (4.5:1 for normal text, 3:1 for large text)
55+
2. **Given** the restyled site, **When** audited with Lighthouse, **Then** all four categories (Performance, Accessibility, Best Practices, SEO) score 100/100
56+
3. **Given** interactive elements (links, buttons), **When** navigated with keyboard, **Then** focus indicators are clearly visible against the dark background
57+
58+
---
59+
60+
### Edge Cases
61+
62+
- What happens when the title wraps on very narrow screens (below 320px)? The title should still display the correct yellow "Py" coloring even if it wraps to a second line.
63+
- How do the podcast and contact link buttons (bordered style) appear on the dark background? Borders and SVG icons must remain visible.
64+
- How do host profile photos (circular, 120x120) appear on the dark background? The circular crop should remain clear.
65+
66+
## Requirements *(mandatory)*
67+
68+
### Functional Requirements
69+
70+
- **FR-001**: The page background MUST be black
71+
- **FR-002**: Body text MUST be white or near-white for readability on the dark background
72+
- **FR-003**: The site title "Intervista Pythonista" MUST appear on a single line in the header
73+
- **FR-004**: The letters "Py" in "Pythonista" MUST be colored in a golden yellow that matches or complements the podcast logo's yellow
74+
- **FR-005**: The yellow "Py" treatment MUST be implemented purely with CSS, using a span or similar markup element in the template for the "Py" portion
75+
- **FR-006**: The rest of the title text (all characters except "Py") MUST be white
76+
- **FR-007**: The podcast logo image MUST NOT appear on the site
77+
- **FR-008**: All links MUST be visually distinct from surrounding text on the dark background and MUST have visible hover and focus states
78+
- **FR-009**: Section headings, host bios, footer text, and all other content MUST be restyled for readability on the dark background
79+
- **FR-010**: Bordered link buttons (podcast and contact sections) MUST have visible borders and icons on the dark background
80+
- **FR-011**: All text/background color combinations MUST meet WCAG AA contrast requirements (4.5:1 for normal text, 3:1 for large text)
81+
- **FR-012**: The site MUST maintain Lighthouse 100/100 scores across all categories after restyling
82+
- **FR-013**: The overall visual feel MUST remain clean and minimal, consistent with the existing site structure
83+
84+
## Success Criteria *(mandatory)*
85+
86+
### Measurable Outcomes
87+
88+
- **SC-001**: 100% of site text meets WCAG AA contrast ratio requirements against the dark background
89+
- **SC-002**: Lighthouse audit scores remain at 100/100 in all four categories (Performance, Accessibility, Best Practices, SEO)
90+
- **SC-003**: The title "Intervista Pythonista" renders on a single line on viewports 375px wide and above
91+
- **SC-004**: The "Py" yellow color has a delta-E (color difference) of less than 10 compared to the logo's yellow, confirming visual consistency with the podcast brand
92+
93+
## Assumptions
94+
95+
- The golden yellow in the podcast logo is approximately #E8A317 (warm golden yellow). The exact hex value will be confirmed during implementation by sampling the logo.
96+
- "Single line" for the title refers to standard mobile and desktop viewports (375px and above). On extremely narrow viewports below 375px, wrapping is acceptable.
97+
- The existing CSS custom properties (CSS variables) approach will be leveraged for the dark theme, making the change primarily a matter of updating variable values.
98+
- No new fonts, images, or external resources are needed — the restyle is purely CSS and minor template markup changes.
99+
- The site does not currently display the logo image, so FR-007 is a constraint to ensure it is not added, not a removal.

0 commit comments

Comments
 (0)