From 53270c694e78b9f065bb4e5619caac9d4b7cd1f0 Mon Sep 17 00:00:00 2001 From: Keith Solomon Date: Sun, 5 Jul 2026 10:32:35 -0500 Subject: [PATCH] docs(blog-card): add post card styling implementation plan --- .../plans/2026-07-05-blog-post-card.md | 289 ++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-05-blog-post-card.md diff --git a/docs/superpowers/plans/2026-07-05-blog-post-card.md b/docs/superpowers/plans/2026-07-05-blog-post-card.md new file mode 100644 index 0000000..00c0021 --- /dev/null +++ b/docs/superpowers/plans/2026-07-05-blog-post-card.md @@ -0,0 +1,289 @@ +# Blog Post Card Styling Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Restyle the blog post card to match `blog-post-card.png` — a vertical card with a featured image on top and a solid blue content area below containing the title, byline, and an orange "Read more" link. + +**Architecture:** A targeted CSS update to `styles/components/post-list.css` (the card body, title, byline, image border, and a new `.post-list__read-more` rule), a one-line markup addition in `index.php` to render the "Read more" anchor, and a single new assertion in the existing `tests/blog-page.spec.js`. The dist CSS is rebuilt once at the end. + +**Tech Stack:** WordPress 6.x, PHP 8.x, Tailwind CSS v4, Playwright, axe-core, PHPCS (WordPress standard). + +## Global Constraints + +- Tabs for PHP indentation (project standard; see `composer.json` and existing files). +- The theme's Tailwind build outputs `static/dist/theme.css`; that file is gitignored but committed with `git add -f` per project convention. +- PHPCS uses the WordPress coding standard; `composer lint` must pass. Pre-existing CRLF errors on untouched files are out of scope. +- All design colors use the project's existing CSS custom properties from `styles/base/colors.css`. No hardcoded hex values for theme colors. +- The card width behavior stays the same: `grid-cols-[repeat(auto-fit,minmax(20rem,1fr))]`. No layout refactor. +- The "Read more" link reuses the post's permalink — it's the same destination as the title link. +- The H1 page title and `search.php` are explicitly out of scope for this plan. + +--- + +## File Structure + +| File | Responsibility | Created/Modified | +| --- | --- | --- | +| `index.php` | Render the "Read more" link after the byline. | Modify | +| `styles/components/post-list.css` | Style the card body, image border, title, byline, and the new `.post-list__read-more`. | Modify | +| `static/dist/theme.css` | Rebuilt via `npm run build`. | Modified (committed with `git add -f`). | +| `tests/blog-page.spec.js` | Add a single assertion that the "Read more" link is visible in the first card. | Modify | + +--- + +### Task 1: Add the "Read more" link in `index.php` + +**Files:** +- Modify: `index.php:44-53` + +**Interfaces:** +- Consumes: the standard WordPress loop (`have_posts()`, `the_post()`). +- Produces: a `Read more →` element inside `.post-list__details`, after the `.post-list__byline` div. + +- [ ] **Step 1: Add the "Read more" anchor** + +In `index.php`, after the `
...
` block (which ends on line 52 with ``), and before the closing `` of `.post-list__details` (line 53), add the new anchor. The result is: + +```php +
+ +

+ + +
+ — + +
+ + Read more → +
+``` + +Specifically: +- Insert one new line after the closing `` of `.post-list__byline` (the line that contains only `` ending the byline block). +- The new line is: `Read more →` +- Indentation: tabs (matching the existing PHP in the file). +- Use `→` (HTML entity) for the arrow — this is consistent with other `—` / `…` / `«` usage in the same file (see lines 50, 64, 95, 96). + +- [ ] **Step 2: Verify the file parses** + +Run: `php -l index.php` +Expected: `No syntax errors detected in index.php`. + +- [ ] **Step 3: Commit** + +```bash +git add index.php +git commit -m "feat(blog): add Read more link to post card" +``` + +--- + +### Task 2: Add card styles to `styles/components/post-list.css` + +**Files:** +- Modify: `styles/components/post-list.css` + +**Interfaces:** +- Consumes: the new `` from Task 1; the existing `.post-list__post`, `.post-list__img`, `.post-list__details`, `.post-list__title`, `.post-list__byline` elements from `index.php`. +- Produces: a card with a solid blue content area, dark blue title and byline, and an orange "Read more" link. Removes the gray bottom border between the image and content area. + +- [ ] **Step 1: Replace the contents of `styles/components/post-list.css`** + +The current file is 11 lines containing only `.post-list__h1`. Replace the entire file with: + +```css +/* Blog/post index listing styles */ + +.post-list__h1 { + color: var(--color-cwc-blue-01); + font-family: var(--font-quincy, 'Quincy', serif); + font-size: var(--h1); + font-weight: 700; + line-height: 1.2; + margin: 0 0 2rem; + text-align: left; +} + +.post-list__post { + border-color: var(--color-cwc-blue-03); + overflow: hidden; +} + +.post-list__img { + border-bottom: 0; +} + +.post-list__details { + background: var(--color-cwc-blue-03); + color: var(--color-cwc-blue-01); +} + +.post-list__title { + color: var(--color-cwc-blue-01); + font-weight: 700; +} + +.post-list__byline { + color: var(--color-cwc-blue-01); + font-size: 0.875rem; +} + +.post-list__read-more { + color: var(--color-secondary); + font-weight: 600; + margin-top: 0.75rem; + text-decoration: none; +} + +.post-list__read-more:hover { + text-decoration: underline; +} +``` + +Notes on the rules: +- `.post-list__post { border-color: var(--color-cwc-blue-03); }` overrides the `border-secondary` class on the element so the card border matches the content area (effectively invisible against the same-colored background). +- `.post-list__post { overflow: hidden; }` ensures the image's `rounded-t-md` corners are clipped by the card's `rounded-md` corners (this is the standard "image fills top of card" pattern). +- `.post-list__img { border-bottom: 0; }` removes the existing `border-b border-secondary` so the image and content area flow as separate blocks without a divider line. +- `.post-list__details { background: var(--color-cwc-blue-03); }` is the solid blue content area (`#90c9e7`). +- `.post-list__title { font-weight: 700; }` overrides the `font-normal` in the markup. +- `.post-list__read-more` uses `--color-secondary` (aliased to `--color-cwc-orange-01`). +- Indentation: 4 spaces (CSS convention, matches the existing `.post-list__h1` rule). + +- [ ] **Step 2: Verify the CSS file parses** + +Tailwind build is the integration test (Task 3). No standalone CSS lint step. + +- [ ] **Step 3: Commit** + +```bash +git add styles/components/post-list.css +git commit -m "feat(blog): style the post card body, title, byline, and Read more link" +``` + +--- + +### Task 3: Add the "Read more" assertion in `tests/blog-page.spec.js` + +**Files:** +- Modify: `tests/blog-page.spec.js:31-35` + +**Interfaces:** +- Consumes: the new `.post-list__read-more` element from Tasks 1 and 2. +- Produces: a passing assertion that the "Read more" link is visible in the first card and points to a post URL. + +- [ ] **Step 1: Add the assertion in the desktop test** + +In `tests/blog-page.spec.js`, after the existing first-card assertions (after `await expect(firstCard.locator(".post-list__byline")).toBeVisible();` on line 35), add the new assertion. The result is: + +```js +// First card: image, title link, byline. +const firstCard = posts.first(); +await expect(firstCard.locator(".post-list__img img")).toBeVisible(); +await expect(firstCard.locator(".post-list__title")).toBeVisible(); +await expect(firstCard.locator(".post-list__byline")).toBeVisible(); + +// First card has a "Read more" link. +const readMore = firstCard.locator(".post-list__read-more"); +await expect(readMore).toBeVisible(); +await expect(readMore).toHaveText(/^Read more\s*\S+$/); +await expect(readMore).toHaveAttribute("href", /\/[a-z0-9-]+\/?$/); +``` + +Notes: +- The text regex `/^Read more\s*\S+$/` matches "Read more" followed by whitespace and any non-whitespace character (the `→` arrow or any other trailing punctuation). This is robust to HTML-entity encoding in the rendered DOM. +- The `href` regex matches a WordPress post permalink like `/my-post-slug/` or `/my-post-slug`. +- Indentation: 4 spaces (matches the existing test file). +- Do NOT remove the existing `.post-list__cats`/`.post-list__excerpt` count assertions (lines 38-39). They guard against the trim being undone and remain valid. + +- [ ] **Step 2: Run the new assertion in isolation** + +Run: `npx playwright test tests/blog-page.spec.js -g "Blog title, post grid"` +Expected: PASS (the new assertion passes, all existing assertions still pass). + +If the test fails: +- "Read more" not found → Task 1's markup change didn't land. +- Text mismatch → confirm `→` was used (not `->` or `→`). +- `href` mismatch → confirm the markup uses `` (not a hardcoded URL). + +- [ ] **Step 3: Commit** + +```bash +git add tests/blog-page.spec.js +git commit -m "test(blog): assert Read more link is present in the first card" +``` + +--- + +### Task 4: Build the dist CSS and run the final quality gate + +**Files:** +- Modify: `static/dist/theme.css` (committed with `git add -f`). + +- [ ] **Step 1: Run the build** + +Run: `npm run build` +Expected: build completes without errors. + +- [ ] **Step 2: Verify the new classes are in the dist** + +Run: `grep -c "post-list__read-more" static/dist/theme.css` +Expected: at least 1 match. + +Run: `grep -c "post-list__details" static/dist/theme.css` +Expected: at least 1 match (the new `background` rule should compile into the dist). + +- [ ] **Step 3: Commit the rebuilt dist** + +```bash +git add -f static/dist/theme.css +git commit -m "build: regenerate dist with blog post card styles" +``` + +- [ ] **Step 4: Run the new test file** + +Run: `npx playwright test tests/blog-page.spec.js` +Expected: all 4 tests pass. + +- [ ] **Step 5: Run the full Playwright suite** + +Run: `npx playwright test` +Expected: same pass/fail count as before this plan. The new test (4th) added 1 passing test; no other tests should regress. The 14 pre-existing failures (12 from prior plans + 2 contact-page pre-existing) are unchanged. + +- [ ] **Step 6: Run PHPCS** + +Run: `composer lint` +Expected: no NEW errors. The 5 pre-existing CRLF errors on untouched files (or 20 pre-existing issues per the prior `composer lint` baseline) remain unchanged. + +- [ ] **Step 7: Final commit (only if anything changed in step 1-6)** + +```bash +git add -A +git commit -m "chore: final pass after Playwright and PHPCS" +``` + +If nothing changed (no dist drift, no PHPCS issues, no other drift), skip the commit. + +--- + +## Self-Review Notes + +- **Spec coverage:** + - "Vertical card (image top, content below)" → already true; the card structure is unchanged. + - "Title + byline + Read more link" → Task 1 adds the link; existing markup already has title and byline. + - "Solid `--color-cwc-blue-03` background" → Task 2 (`.post-list__details`). + - "Title in `--color-cwc-blue-01`, weight 700" → Task 2 (`.post-list__title`). + - "Byline in `--color-cwc-blue-01`, smaller" → Task 2 (`.post-list__byline`). + - "Read more in `--color-secondary` (orange)" → Task 2 (`.post-list__read-more`). + - "Remove gray border between image and content" → Task 2 (`.post-list__img { border-bottom: 0; }`). + - "Card border matches content area" → Task 2 (`.post-list__post { border-color: ...; }`). + - "Single new test assertion" → Task 3. + - "Dist rebuild" → Task 4. + - "All design tokens, no hardcoded hex" → Task 2 uses only `var(--...)` references. + - "Out of scope: H1, search.php" → explicitly noted in Global Constraints. + +- **Placeholder scan:** No TBD/TODO. The "→" character is exact in both `index.php` (`→`) and the test (`→`). The `href` regex is exact. + +- **Type consistency:** Class names: `post-list__read-more` (consistent with `post-list__post`, `post-list__title`, `post-list__byline`). CSS variable names: `--color-cwc-blue-01`, `--color-cwc-blue-03`, `--color-secondary` (all existing tokens). + +- **Indentation:** Tabs for PHP (Task 1), 4 spaces for CSS (Task 2) and JS (Task 3). Each matches the convention in its file.