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

341 lines
17 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`.
**The overriding principle: the site must behave and look the same as it does
today — only cleaner, more readable and more accessible. Do not break any
existing markup, class name or ID.**
## 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. **Do not rename any existing HTML class name or ID.** The site owner may
have custom CSS under Appearance → Customize → Additional CSS that targets
them. Keep all of these exactly as they are: `.header-menu-class`,
`#nav-grid`, `.logo`, `.entry-title`, `.entry-meta`, `.entry-content`,
`.date`, `.categories`, `.author`, `.pagination`, `.prev`, `.page-numbers`,
`.next`, `.search-container`, `.search-form`, `.search-field`,
`.search-submit`, `.footer-logo`, `#logout`, `#org-nr`, `.rss-feed`,
`.rss-title`, `.super-simple-slideshow`, `.super-simple-slide`, every
`.bbp-*`, every `.wp-block-*`, `.screen-reader-text`, `.alignnone`,
`.has-fixed-layout`.
You may **add** new class names, but never remove or rename an existing one.
2. **Keep every third-party class name working.** 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`.
3. **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. It stays invisible to the eye — it
just becomes readable by screen readers again.
4. **Keep the nav menu location slug `header-menu`.** Renaming it would make
the site lose its menu assignment on theme switch.
5. **Keep content, pagination, slideshow, search and RSS exactly where they are
today.** Do not move them, do not add conditional guards around them beyond
the shortcode check described below.
6. **No external requests.** No Google Fonts, no CDNs. No webfont is
downloaded.
7. **No build step.** Plain CSS in `style.css`. No npm, no minification.
8. **No `!important`** outside the preserved hide list.
9. Escape all output: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()`.
10. 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
Palette. The current `#38629F` only reaches 6.1:1 with white text, and the
muted colour `#AAA` on it fails at 2.6:1. The new palette stays in the same
blue family but is darker, so that **all text reaches AAA (7:1)** and all
functional borders reach 3:1. A second surface colour makes it impossible for
form fields to end up white-on-white.
| Token | Value | Role |
|---|---|---|
| `--sswt-bg` | `#1F3E6B` | page background |
| `--sswt-surface` | `#2A4E80` | form fields, notice boxes, table headers |
| `--sswt-text` | `#FFFFFF` | body text, headings |
| `--sswt-text-muted` | `#C6D3E8` | date, category, feed source, meta text |
| `--sswt-link` | `#FFD479` | links |
| `--sswt-link-hover` | `#FFFFFF` | link hover |
| `--sswt-rule` | `#6C8CBF` | decorative separators |
| `--sswt-border` | `#8FA9D4` | form field and button borders |
| `--sswt-accent-bg` | `#FFD479` | button background |
| `--sswt-accent-text` | `#1F3E6B` | button text |
| `--sswt-focus` | `#FFFFFF` | focus outline |
Measured contrasts — do not regress these:
| Combination | Contrast | Level |
|---|---|---|
| `--sswt-text` on `--sswt-bg` | 10.7:1 | AAA |
| `--sswt-text` on `--sswt-surface` | 8.4:1 | AAA |
| `--sswt-text-muted` on `--sswt-bg` | 7.1:1 | AAA |
| `--sswt-text-muted` on `--sswt-surface` | 5.6:1 | AA |
| `--sswt-link` on `--sswt-bg` | 7.6:1 | AAA |
| `--sswt-link` on `--sswt-surface` | 6.0:1 | AA |
| `--sswt-accent-text` on `--sswt-accent-bg` | 7.6:1 | AAA |
| `--sswt-rule` on `--sswt-bg` | 3.1:1 | ≥3:1 (UI) |
| `--sswt-border` on `--sswt-surface` | 3.5:1 | ≥3:1 (UI) |
| `--sswt-focus` on `--sswt-bg` | 10.7:1 | AAA |
Typography and layout:
| Token | Value |
|---|---|
| `--sswt-font` | `Manrope, system-ui, -apple-system, "Segoe UI", Roboto, "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 |
Manrope stays first in the stack but is **not downloaded**. Visitors who have it
locally get it; everyone else gets their system font. No external requests, no
layout shift.
`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. Do not add anything else. No new features.
### 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="…">`. These are new classes — adding them
is fine.
5. **Keep** the existing container class `header-menu-class` and the existing
id `nav-grid` on the menu wrapper. Do not rename them.
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. **Leave the pagination block where it is and as it is.** Do not add
conditions, do not move it.
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 and keep `the_content()`. 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. The class name
`entry-title` stays untouched.
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-focus); 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. The element must remain
invisible in normal use.
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. **Keep the existing
`.header-menu-class` and `#nav-grid` names.**
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. **Keep these rules exactly as they are** — they are deliberate fixes dated
2026-03-05 and must keep working:
`h3.wp-block-heading { font-size: inherit; }`,
`a.wp-block-file__button { display: none; }`,
`.is-vertical .wp-block-file` margin, 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. Form fields (`.search-field`, `.bbp-form input`, `.bbp-form textarea`):
`background: var(--sswt-surface)`, `color: var(--sswt-text)`,
`border: 1px solid var(--sswt-border)`. This fixes
`.bbp-form input#user_login`, which today sets white text on a white
background.
6. Buttons (`.search-submit`, `.bbp-submit-wrapper button`, submit inputs):
`background: var(--sswt-accent-bg)`, `color: var(--sswt-accent-text)`.
Never white-on-light-grey.
7. Give bbPress buttons and links a visible `:focus-visible` style.
### 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`),
an old → new CSS variable mapping table, 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.
- Existing Additional CSS still applies — no class name or ID was renamed.
- `[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.