From 9b76d7bacfac7d00f4308bddb081b06579f81a08 Mon Sep 17 00:00:00 2001 From: Keith Solomon Date: Sun, 5 Jul 2026 10:29:26 -0500 Subject: [PATCH] docs(blog-card): add post card styling design spec --- .../specs/2026-07-05-blog-post-card-design.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-05-blog-post-card-design.md diff --git a/docs/superpowers/specs/2026-07-05-blog-post-card-design.md b/docs/superpowers/specs/2026-07-05-blog-post-card-design.md new file mode 100644 index 0000000..9c9dcbb --- /dev/null +++ b/docs/superpowers/specs/2026-07-05-blog-post-card-design.md @@ -0,0 +1,128 @@ +# Blog Post Card Styling Design + +> **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 a "Read more" link in orange. + +**Architecture:** A targeted CSS update to `styles/components/post-list.css` (the card body, title, byline, and a new `.post-list__read-more` rule), and a one-line markup addition in `index.php` to render the "Read more" anchor. No template structure changes. No new Playwright tests beyond a single new assertion in the existing `tests/blog-page.spec.js`. + +**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). +- 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 ("Blog" page title) and `search.php` are explicitly **out of scope** for this change. The working tree currently has the H1 removed and `search.php` untouched; this design does not address either. + +## Reference Mockup + +`blog-post-card.png` (426×644, vertical 2:3) at the theme root. The mockup shows: +- **Image area** (top ~38%): light gray placeholder. Real implementation uses the post's featured image via `has_post_thumbnail()`. +- **Content area** (bottom ~62%): solid `#90c9e7` background. This color is the hex equivalent of `--color-cwc-blue-03` (`oklch(80.63% 0.0724 230.4)`). +- **Title:** multi-line, dark blue text (matches `--color-cwc-blue-01`). +- **Byline:** smaller dark text near the bottom of the content area. +- **"Read more" link:** orange (`#d24d32`, matches `--color-secondary` / `--color-cwc-orange-01`) at the bottom-left of the card. + +## File Structure + +| File | Responsibility | Created/Modified | +| --- | --- | --- | +| `styles/components/post-list.css` | Add card body, title, byline, and `.post-list__read-more` styles. | Modify | +| `index.php` | Add a "Read more" link after the byline in `.post-list__details`. | 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 exists in the first card. | Modify | + +--- + +## Design Details + +### CSS additions to `styles/components/post-list.css` + +The card already has the following structure (from `index.php`): + +```html +
+
+ +
+
+

Title

 +
+ Author + Date +
+
+
+``` + +The styling changes: + +1. **`.post-list__post`** — Override the gray `border-secondary` so the card border disappears (the blue background extends edge-to-edge inside the card). Keep the rounded corners and shadow. The current classes in `index.php` set `border border-secondary`; we override via CSS to `border-color: var(--color-cwc-blue-03)`. + +2. **`.post-list__post`** and **`.post-list__img`** — Set `border: 0` (or `border-color: transparent`) on the figure so the existing `border-b border-secondary` does not show. The visual change is that the image and the blue content area flow as separate blocks without a divider line between them. The card itself keeps its `rounded-md` corners; the figure keeps `rounded-t-md` so the image rounds with the card. + +3. **`.post-list__title`** — Set `color: var(--color-cwc-blue-01)`, `font-weight: 700` (override the `font-normal` in the markup). Keep the existing `text-25px` size and `line-clamp-4` truncation. The title is the project's standard H2 typography. + +4. **`.post-list__byline`** — Set `color: var(--color-cwc-blue-01)`, `font-size: 0.875rem` (smaller than the title, but readable on the blue background). Keep `mt-auto` so the byline sits at the bottom of the available space. + +5. **`.post-list__read-more`** (new) — `color: var(--color-secondary)`, `font-weight: 600`, `margin-top: 0.75rem`, `text-decoration: none`. Hover: underline. The text content is "Read more →" (em dash and arrow, no period). + +### Markup change in `index.php` + +Inside `.post-list__details`, after the `.post-list__byline` div, add: + +```html +Read more → +``` + +No other markup changes. The title link, image, byline, and pagination are untouched. + +### What stays the same + +- Card structure: `figure` for image, `div.post-list__details` for content. +- Grid layout: `grid-cols-[repeat(auto-fit,minmax(20rem,1fr))] gap-6`. +- Image aspect ratio: `aspect-video` (16:9). +- Image hover effect: `hover:prose-img:scale-110` with `duration-500` transition. +- Empty state ("Nothing here yet…"). +- Pagination. +- Card padding: `px-4 py-6` on `.post-list__details`. +- The H1 / `search.php` / sidebar — all untouched. + +### Test updates + +Add a single assertion to the desktop test in `tests/blog-page.spec.js`: + +```js +// First card has a "Read more" link. +await expect(firstCard.locator(".post-list__read-more")).toBeVisible(); +await expect(firstCard.locator(".post-list__read-more")).toHaveAttribute( + "href", + /\/[a-z0-9-]+\/?$/ +); +``` + +No new spec file. The existing 4 tests stay as they are. + +### Out of Scope + +- The H1 page title — the working tree currently has the H1 markup removed. The previous blog plan added it (commit `66073c0`) and the design tokens (commit `cb0c886`); both are present in git history. Whether to re-add the H1 is a separate decision. +- `search.php` — still a separate template, still has the old card structure, still has the `$featimg` case-sensitivity bug. Separate work. +- `static/dist/theme.css` pre-existing changes from other work in the working tree (`header.php`, `views/partials/page-hero-services.php`, etc.) are unrelated and not touched. +- Dark mode. +- Animations on the "Read more" link beyond a basic underline-on-hover. +- The H2 font family (Quincy vs sans) — the existing card uses the default font family for the title. The mockup's title appears to be a clean sans-serif weight-700. We do not change the font family. + +--- + +## Self-Review Notes + +- **Spec coverage:** One CSS file, one PHP file, one test file, one dist rebuild. Every spec section is covered. +- **Placeholder scan:** No "TBD", "TODO", or vague requirements. The "→" arrow and "Read more" text are spelled out explicitly. +- **Type consistency:** Class names follow the existing BEM convention (`__read-more`). +- **Spec section "Out of Scope"** is explicit: H1, search.php, dark mode, font family changes, animations — all out. +- **Design tokens:** All colors reference existing CSS custom properties. No new colors introduced. +- **Indentation:** Tabs for PHP (project standard).