Files
super-simple-wp-theme/AI_CODER_PROMPT.md
T

289 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI coder prompt — Super Simple WordPress Theme
Copy everything below the line into the AI coder. It is self-contained.
---
## Role
You are a senior WordPress theme developer. You write plain PHP and plain CSS —
no frameworks, no build step, no dependencies. You prioritise correct, simple,
robust and maintainable code. You do not over-engineer.
## Repository
- Project key: `super-simple-wp-theme`
- Repository: `ai-bot/super-simple-wp-theme`
- Base branch: `main`
- Work on a new branch: `theme-refresh-2.0`
## Objective
Refresh and rename the WordPress theme currently called **NTKF** into
**Super Simple WordPress Theme** (version `2.0.0`, text domain
`super-simple-wp-theme`).
The theme runs the site <https://www.taubaneforeningen.no/> — a Norwegian
association site (Nynorsk) about cable cars and aerial tramways. It must stay
easy to read for both older and younger visitors, on desktop and on mobile.
This is a refresh, not a redesign. Do not add features, do not change the
information architecture, do not introduce a block theme or `theme.json`.
## Deliverables
| File | Action |
|---|---|
| `style.css` | Rewrite (keep the theme header comment at the top) |
| `functions.php` | Rewrite |
| `header.php` | Rewrite |
| `footer.php` | Rewrite |
| `index.php` | Update |
| `single.php` | Update |
| `page.php` | Update |
| `category.php` | Update |
| `author.php` | Update |
| `search.php` | Update |
| `rss-feed.php` | **Delete** |
| `README.md` | Create (English) |
| `screenshot.png` | Leave alone, note in README that it should be replaced |
## Non-negotiable constraints
1. **Keep every third-party class name.** These must keep working unchanged:
- RSS plugin: `.rss-feed`, `.rss-title`
- Slideshow plugin: `.super-simple-slideshow`, `img.super-simple-slide`, `.active`
- bbPress: every `.bbp-*`, `#bbp_*`, `.forums`, `.favorite-toggle`,
`#subscription-toggle`, `.pw-weak`, `#new-post`, `.bbp-form`,
`.bbp-submit-wrapper`
- WordPress core: `.screen-reader-text`, `.wp-block-*`, `.alignnone`,
`.has-fixed-layout`, `.pagination`, `.page-numbers`, `.entry-title`,
`.entry-meta`, `.entry-content`, `.search-container`, `.search-form`,
`.search-field`, `.search-submit`
2. **Everything hidden today must stay hidden.** Copy the existing
`display: none !important` selector list for bbPress verbatim, reindented
only. The single exception is `.screen-reader-text`, which must be changed
to a proper visually-hidden technique (see task H below).
3. **Keep the nav menu location slug `header-menu`.** Renaming it would make
the site lose its menu assignment on theme switch.
4. **No external requests.** No Google Fonts, no CDNs. Everything local.
5. **No build step.** Plain CSS in `style.css`. No npm, no minification.
6. **No `!important`** outside the preserved hide list.
7. Escape all output: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()`.
8. Comments in code in English. User-facing strings in Norwegian Nynorsk,
wrapped in `__()` / `esc_html__()` / `esc_attr__()` with the text domain
`super-simple-wp-theme`.
## Design tokens to implement
Colour palette. The current `#38629F` only reaches 6.1:1 with white text and
the muted colour `#AAA` on it fails at 2.6:1. Move to a darker blue so both
body text and meta text pass AAA.
| Token | Value | Role | Contrast on `--sswt-bg` |
|---|---|---|---|
| `--sswt-bg` | `#1F3E6B` | page background | – |
| `--sswt-text` | `#FFFFFF` | body text, headings | 10.7:1 (AAA) |
| `--sswt-text-muted` | `#C6D3E8` | date, category, feed source | 7.1:1 (AAA) |
| `--sswt-link` | `#FFD479` | links | 7.6:1 (AAA) |
| `--sswt-link-hover` | `#FFFFFF` | link hover and focus | 10.7:1 |
| `--sswt-border` | `#6C8CBF` | rules and borders | 3.1:1 (≥3:1 UI) |
| `--sswt-accent-bg` | `#FFD479` | button background | – |
| `--sswt-accent-text` | `#1F3E6B` | button text | 7.6:1 |
Typography and layout:
| Token | Value |
|---|---|
| `--sswt-font` | `Manrope, "Segoe UI", system-ui, -apple-system, "Helvetica Neue", Arial, sans-serif` |
| `body` | `font-size: 1.125rem` (18 px), `line-height: 1.6`, `letter-spacing: 0.01em` |
| `--sswt-measure` | `42rem` — body text column |
| `--sswt-wide` | `64rem` — header, nav, footer |
| `h1` | `2.25rem` |
| `h2` | `1.75rem` |
| `h3` | `1.375rem` |
| `h4` | `1.15rem` |
| interactive target | minimum `44px` tall |
`html` must be `font-size: 100%` — never a pixel value. All sizes in `rem` so
that user font-size settings are respected.
## Work order
Work through the tasks in this order. One file at a time. Finish a file, verify
it, then move on. Do not batch unrelated changes.
### A. Preparation
1. Create branch `theme-refresh-2.0`.
2. Delete `rss-feed.php`. It is dead code — the `include` is commented out in
`index.php` — and it fetches a remote URL with `simplexml_load_file()`. The
`super-simple-rssreader` plugin replaces it.
### B. `functions.php`
1. Prefix every function with `sswt_`.
2. `sswt_setup()` hooked on `after_setup_theme`:
`load_theme_textdomain( 'super-simple-wp-theme', get_template_directory() . '/languages' )`,
and `add_theme_support()` for `title-tag`, `post-thumbnails`, `automatic-feed-links`,
`responsive-embeds`, `customize-selective-refresh-widgets`, `align-wide`, and
`html5` with `search-form`, `comment-form`, `comment-list`, `gallery`, `caption`, `style`, `script`.
3. `sswt_register_menus()` hooked on `init` — register location `header-menu`
with the label `Header Menu`. Keep the slug exactly as it is today.
4. `sswt_enqueue_assets()` — `wp_enqueue_style( 'sswt-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) )`.
Remove the manual `<link rel="stylesheet">` from `header.php`.
5. Replace `remove_private_title_prefix()` with filters on
`private_title_format` and `protected_title_format` that return `'%s'`.
Drop the locale-dependent `str_replace( 'Privat: ', ... )`.
6. Keep the bbPress login redirect. Guard `is_bbpress()` with `function_exists()`.
7. Keep the commented-out bbPress profile redirect, but make it toggleable via
`apply_filters( 'sswt_redirect_bbpress_profile', false )`.
8. Keep the logout link helper as `sswt_logout_link()`. Escape the URL.
9. Keep the `wp_mail_from` / `wp_mail_from_name` filters, but read the values
through `apply_filters( 'sswt_mail_from', ... )` and
`apply_filters( 'sswt_mail_from_name', ... )` so they are configurable.
10. Add a small helper `sswt_shortcode_exists()` or use `shortcode_exists()`
directly — see tasks D and E.
### C. `header.php`
1. Add `wp_head()` inside `<head>`. Add `body_class()` on `<body>` and
`wp_body_open()` right after it.
2. Remove the hardcoded `<title>`; `title-tag` support now handles it.
3. Add a skip link as the first element in `<body>`:
`<a class="skip-link screen-reader-text" href="#main">` with the Nynorsk
label `Hopp til innhald`.
4. Wrap the header in `<header class="site-header">` and the menu in
`<nav class="site-nav" aria-label="…">`.
5. Rename the theme-internal class `.header-menu-class` to `.site-nav-menu`
and the id `#nav-grid` to `.nav-grid`. These are theme-internal only.
6. Give the logo `<img>` an `alt` attribute and handle the case where
`get_site_icon_url()` returns an empty string.
7. Open `<main id="main" class="site-main">` after the header.
8. Keep the viewport meta tag.
### D. `footer.php`
1. Close `</main>` before the footer.
2. Add `wp_footer()` before `</body>`.
3. Guard the slideshow call:
`if ( shortcode_exists( 'super_simple_slideshow' ) ) { echo do_shortcode( '[super_simple_slideshow]' ); }`
Today, a deactivated plugin prints the raw shortcode text on the page.
4. Only render the pagination block when `is_archive() || is_home() || is_search()`.
5. Keep the search form, but replace `get_search_query()` with
`esc_attr( get_search_query() )` and use a single text domain.
6. Keep the footer logo and the organisation number, but move the number into
`apply_filters( 'sswt_org_number', '995 268 698' )`.
7. Use `sswt_logout_link()` instead of the old function name.
### E. Templates
1. `index.php`, `category.php`, `author.php`, `search.php`: keep the existing
structure. Wrap the archive heading strings in `esc_html__()` /
`esc_html()` and use the correct text domain.
2. `single.php` and `page.php`: the post title must be `<h1 class="entry-title">`,
not `<h2>`. Right now no template outputs an `<h1>` at all.
3. `index.php`: guard the RSS call with
`if ( shortcode_exists( 'super_simple_rssreader' ) )`.
4. Remove commented-out dead code from the templates.
### F. `style.css` — header and tokens
1. Write a complete theme header:
`Theme Name: Super Simple WordPress Theme`, `Theme URI`, `Author`,
`Author URI`, `Description`, `Version: 2.0.0`, `Requires at least`,
`Tested up to`, `Requires PHP`, `License`, `License URI`,
`Text Domain: super-simple-wp-theme`, `Tags`.
2. Replace the old `--bg-color`, `--txt-color`, `--a`, `--a-hover`,
`--border-color`, `--font` variables with the `--sswt-*` tokens above.
Delete the commented-out dark palette block.
3. Organise the file in this order and label the sections with comments:
tokens → base → typography → links and focus → layout (header, nav, main,
footer) → entry (title, meta, content) → pagination → search → WordPress
blocks → third-party (slideshow, RSS) → bbPress → utilities → media queries.
### G. `style.css` — base, typography and focus
1. `html { font-size: 100%; }`, `* { box-sizing: border-box; }`.
2. `body`: 18 px, `line-height: 1.6`, `letter-spacing: 0.01em`. Drop the
`0.08rem` letter spacing — it slows reading down.
3. Heading scale `h1`–`h4` per the tokens table. No fixed `3rem` titles.
4. Links: keep an underline, add `text-underline-offset: 0.15em`. Remove the
underline on hover.
5. Add `:focus-visible { outline: 3px solid var(--sswt-link); outline-offset: 2px; }`
and delete every `outline: none` rule, including the one on `.bbp-form` inputs.
6. Replace `display: none` on `.screen-reader-text` (and the
`h2.screen-reader-text` rule) with the standard visually-hidden technique:
`clip-path: inset(50%)`, `position: absolute`, `width: 1px`, `height: 1px`,
`overflow: hidden`, plus a `:focus` rule that reveals it — that is what
makes the skip link appear on keyboard focus.
7. Add `@media (prefers-reduced-motion: reduce)` that disables transitions
and animations.
### H. `style.css` — layout and components
1. Header, nav and footer use `--sswt-wide`. Body content uses `--sswt-measure`.
2. Replace the `float: left` menu and the `overflow: hidden` clearfix with
flex or grid. Menu links must be at least 44 px tall.
3. Remove the no-op `align-items: center` on `header` (it has no `display`).
4. Search input: remove `calc(640px - 8rem)` and the `100vw` patch in the
media query. Use fluid widths.
5. Images: `.wp-block-image img, .alignnone { max-width: 100%; height: auto; }`
— not `width: 100%`, which upscales small images.
6. Tables: `.wp-block-table { overflow-x: auto; }` so wide tables scroll
horizontally on mobile instead of breaking the page.
7. Keep the 16:9 embed wrapper.
8. Keep block styles for image, file, list, details, quote and caption.
9. **Ask before changing these three**, they look deliberate: `h3.wp-block-heading { font-size: inherit; }`,
`a.wp-block-file__button { display: none; }`, and the `.wp-block-details` rules.
### I. `style.css` — third-party and bbPress
1. Slideshow: keep `.super-simple-slideshow`, `img.super-simple-slide`,
`.active`, and `aspect-ratio: 16 / 9` with `object-fit: cover`.
2. RSS: keep `.rss-feed` and `.rss-title`. Change the source span from
`--a-hover` to `--sswt-text-muted` — the current colour is 2.6:1.
3. bbPress: copy the entire `display: none !important` list verbatim, minus
`.screen-reader-text`. Keep every other bbPress selector working.
4. bbPress tables, forms, reply pages, user pages and the new-topic form: keep
the selectors, but convert fixed pixel widths to `rem` or percentages.
5. Fix `.bbp-form input#user_login`: it currently sets `color: var(--txt-color)`
with `background-color: var(--border-color)`, i.e. white text on white.
6. Give bbPress buttons and links a visible `:focus-visible` style.
7. Give all bbPress buttons a proper background and text colour pair so that
white-on-light-grey never happens again.
### J. Responsive and accessibility
1. Verify reflow at 320 px, 768 px and 1440 px with no horizontal scrolling.
2. Verify 200% text zoom without loss of content or function.
3. Keyboard walkthrough: skip link → menu → content → pagination → search → footer.
4. Optional: a compact mobile menu using a button with `aria-expanded` and a
small `assets/js/nav.js`. The default is a stacked menu with no JavaScript.
If you add JavaScript it must degrade — the menu must be visible when JS
is off.
### K. Verification
1. `php -l` on every PHP file.
2. Re-check every colour pair in the tokens table against the background it is
actually used on.
3. Run the WordPress Theme Check plugin.
4. Write `README.md` in English: installation, what the theme is for, the
third-party markup it styles, the customisation filters (`sswt_org_number`,
`sswt_mail_from`, `sswt_mail_from_name`, `sswt_redirect_bbpress_profile`),
and a note that `screenshot.png` needs replacing.
5. Bump `Version` to `2.0.0` and add a short changelog comment in `style.css`.
## Acceptance criteria
- The theme appears as "Super Simple WordPress Theme" in Appearance → Themes.
- The menu is still attached to the "Header Menu" location.
- Front page, single post, page, category, author and search render with no PHP
notices while `WP_DEBUG` is on.
- All previously hidden bbPress elements are still hidden.
- `[super_simple_rssreader]` and `[super_simple_slideshow]` render correctly —
and print **no raw shortcode text** when the plugins are deactivated.
- Slideshow images fill the width and keep a 16:9 ratio.
- bbPress forum list, topic view, reply view, new-topic form, user profile and
edit-profile screen all render correctly.
- No horizontal scrolling at 320 px.
- Every interactive element has a visible focus indicator.
- No white-on-white or other sub-4.5:1 text.
- No requests to external domains on the front end.
## Reporting
After each file, report: the file path, what changed, and anything you had to
decide or could not verify. If a requirement conflicts with the existing site
behaviour, stop and ask instead of guessing.