Add README.md

English documentation: installation, what the theme is for, the
third-party markup it styles, the sswt_* customisation filters, the
old to new CSS variable mapping table, the markup contracts, the
screenshot.png note and the 2.0.0 changelog.
This commit is contained in:
ai-bot committed 2026-10-14 08:38:06 +00:00
1 parent f8a226ecc9
commit 3dce684aef
1 file changed
+281
+281
View File
@@ -0,0 +1,281 @@
# Super Simple WordPress Theme
A small, dependency-free classic WordPress theme for
[Norske Tau- og Kabelbaners Forening](https://www.taubaneforeningen.no/) —
a Norwegian association site (Nynorsk) about cable cars and aerial tramways.
Plain PHP and plain CSS. No frameworks, no build step, no npm, no minification
and no external requests (no Google Fonts, no CDN, no downloaded webfont).
| | |
|---|---|
| **Version** | 2.0.0 |
| **Text domain** | `super-simple-wp-theme` |
| **Requires at least** | WordPress 5.9 |
| **Requires PHP** | 7.4 |
| **License** | GPL-2.0-or-later |
| **Previous name** | NTKF (1.0) |
## What the theme is for
The theme renders a simple, highly readable single-column blog for an
association site:
- Front page / blog index (`index.php`)
- Single post (`single.php`) and static page (`page.php`)
- Category (`category.php`), author (`author.php`) and search (`search.php`)
archives
- A shared header with the logo and a nav menu (`header.php`)
- A shared footer with the slideshow, pagination, a search form, the footer
logo, a logout link and the organisation number (`footer.php`)
It is deliberately not a block theme. There is no `theme.json`, no Full Site
Editing and no template parts. Content is edited with the classic editor or
with blocks inside `the_content()`.
The design goal for 2.0.0 is **accessibility and readability**, not a redesign:
- 18 px body text, `line-height: 1.6`, `letter-spacing: 0.01em`
- Every text colour reaches at least AA, most reach AAA
- Every functional border reaches at least 3:1
- Visible focus outline on every interactive element
- Skip link, `<main>` landmark and a single `<h1>` per page
- Minimum 44 px tall navigation targets
- No fixed pixel widths, so the layout reflows down to 320 px
- `prefers-reduced-motion` is respected
Manrope is first in the font stack but is **never downloaded**. Visitors who
happen to have it installed locally get it; everyone else gets their system
font. If Manrope is ever wanted for real, put the files in `assets/fonts/`
with `@font-face` and `font-display: swap`.
## Installation
1. Copy the theme folder to `wp-content/themes/super-simple-wp-theme/`, or
upload a zip through **Appearance → Themes → Add New → Upload Theme**.
2. Activate **Super Simple WordPress Theme** under **Appearance → Themes**.
3. Under **Appearance → Menus**, assign a menu to the **Header Menu**
location. The location slug is `header-menu` and has not changed, so an
existing assignment is kept when switching from the old theme.
4. Set the site language to **Norsk (nynorsk)** under **Settings → General**.
The theme ships Nynorsk strings as the source language and loads
translations from `languages/` (create that folder when you add `.po`
files).
5. Set a site icon under **Appearance → Customize → Site Identity**. Without
one, the logo image is simply omitted and the site name is shown alone.
### Optional: forum login
If bbPress is active, anonymous visitors are redirected to the login screen on
forum pages. This is the existing behaviour of the theme and is unchanged.
## Third-party markup this theme styles
The theme contains no plugin code. It only styles markup produced by other
plugins. Do not remove these class names — the styles and the site owner's
Additional CSS depend on them.
### bbPress
All `.bbp-*` selectors, `#bbp_*` ids, `.forums`, `.favorite-toggle`,
`#subscription-toggle`, `.pw-weak`, `#new-post`, `.bbp-form` and
`.bbp-submit-wrapper` keep working: forum list, topic view, reply view,
new-topic form, user profile and edit-profile screens.
A list of bbPress elements is intentionally hidden with
`display: none !important`, copied verbatim from the old theme:
```
.bbp-breadcrumb-home, .bbp-breadcrumb-sep:first-of-type,
.bbp-template-notice.info, .bbp-pagination, .bbp-topic-voice-count,
.bbp-author-avatar, .bbp-forum-info .bbp-forums-list, .bbp-footer,
.bbp-forum-freshness p.bbp-topic-meta, .bbp-topic-freshness p.bbp-topic-meta,
.forums.bbp-replies li.bbp-header, li.bbp-forum-topic-count,
.favorite-toggle, .bbp-reply-permalink,
.bbp-reply-author div.bbp-author-role, .bbp-reply-author div.bbp-reply-ip,
#bbp-user-profile h2.entry-title
```
Plus `li.bbp-forum-reply-count` and `li.bbp-topic-reply-count` below 48rem.
This is the only place in `style.css` where `!important` is used.
### super-simple-slideshow
`.super-simple-slideshow`, `img.super-simple-slide` and `.active` are styled.
Slides fill the available width and keep a 16:9 ratio with
`object-fit: cover`.
`footer.php` calls the shortcode only when it is registered:
```php
if ( shortcode_exists( 'super_simple_slideshow' ) ) {
echo do_shortcode( '[super_simple_slideshow]' );
}
```
With the plugin deactivated, nothing is printed — no raw shortcode text.
### super-simple-rssreader
`.rss-feed` and `.rss-title` are styled. The feed source name uses
`--sswt-text-muted` (7.1:1 on the page background); the old `#AAA` only
reached 2.6:1.
`index.php` guards the shortcode the same way as the slideshow, with
`shortcode_exists( 'super_simple_rssreader' )`.
### WordPress blocks
Styles are provided for image, file, list, details, quote, caption, table and
the 16:9 embed wrapper, plus `.alignnone` and `.has-fixed-layout`. The
`.wp-block-*` class names are untouched.
## Customisation filters
All filters are optional. Add them to a child theme or a small
site-specific plugin — not to the theme, so they survive updates.
| Filter | Default | Purpose |
|---|---|---|
| `sswt_org_number` | `'995 268 698'` | Organisation number shown in the footer. |
| `sswt_mail_from` | `'info@taubaneforeningen.no'` | From address used by `wp_mail()`. |
| `sswt_mail_from_name` | `'Norske Tau- og Kabelbaners Forening'` | From name used by `wp_mail()`. |
| `sswt_redirect_bbpress_profile` | `false` | Set to `true` to redirect the bbPress single user profile to `forums/`. |
Example:
```php
add_filter( 'sswt_org_number', function () {
return '123 456 789';
} );
add_filter( 'sswt_redirect_bbpress_profile', '__return_true' );
```
## CSS variables: old to new
The `:root` custom properties were renamed in 2.0.0 so that every variable
shares the `--sswt-` prefix. The old names no longer exist, so **any
Additional CSS that uses `var(--bg-color)` and friends must be updated**.
| Old variable | Old value | New variable | New value | Role |
|---|---|---|---|---|
| `--bg-color` | `#38629F` | `--sswt-bg` | `#1F3E6B` | Page background |
| `--txt-color` | `#FFF` | `--sswt-text` | `#FFFFFF` | Body text, headings |
| `--a` | `#DDD` | `--sswt-link` | `#FFD479` | Links |
| `--a-hover` | `#AAA` | `--sswt-link-hover` | `#FFFFFF` | Link hover |
| `--border-color` | `#FFF` | `--sswt-rule` | `#6C8CBF` | Decorative separators, container borders |
| `--border-color` | `#FFF` | `--sswt-border` | `#8FA9D4` | Form field and button borders |
| `--font` | `Manrope, sans-serif` | `--sswt-font` | `Manrope, system-ui, …` | Font stack |
`--border-color` was used for both jobs in the old theme; it is now split into
`--sswt-rule` and `--sswt-border`.
New variables with no old equivalent:
| Variable | Value | Role |
|---|---|---|
| `--sswt-surface` | `#2A4E80` | Form fields, notice boxes, table headers |
| `--sswt-text-muted` | `#C6D3E8` | Date, category, feed source, meta text |
| `--sswt-accent-bg` | `#FFD479` | Button background |
| `--sswt-accent-text` | `#1F3E6B` | Button text |
| `--sswt-focus` | `#FFFFFF` | Focus outline |
| `--sswt-measure` | `42rem` | Body text column |
| `--sswt-wide` | `64rem` | Header, nav, footer |
| `--sswt-radius` | `0.25rem` | Form field and button radius |
| `--sswt-target` | `2.75rem` | Minimum interactive target height (44 px) |
Measured contrast:
| 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 |
## Markup contracts
These names must not be renamed. The site owner may have custom CSS under
**Appearance → Customize → Additional CSS** that targets them.
- Layout and header: `.header-menu-class`, `#nav-grid`, `.logo`,
`.footer-logo`, `#logout`, `#org-nr`
- Content: `.entry-title`, `.entry-meta`, `.entry-content`, `.date`,
`.categories`, `.author`
- Navigation: `.pagination`, `.prev`, `.page-numbers`, `.next`
- Search: `.search-container`, `.search-form`, `.search-field`,
`.search-submit`
- Third-party: `.rss-feed`, `.rss-title`, `.super-simple-slideshow`,
`.super-simple-slide`, every `.bbp-*`
- WordPress: every `.wp-block-*`, `.screen-reader-text`, `.alignnone`,
`.has-fixed-layout`
New class names added in 2.0.0 (safe to ignore, safe to use):
`.site-header`, `.site-nav`, `.site-main`, `.skip-link`.
`.screen-reader-text` changed meaning in 2.0.0. It used to be
`display: none !important`, which hid the text from screen readers too. It is
now the standard visually-hidden technique, so the skip link becomes visible
when it receives keyboard focus.
## Screenshot
`screenshot.png` is still the old NTKF screenshot and **must be replaced**
with a 1200 × 900 px image of the new front page before release.
## Testing notes
The theme was written without a running WordPress installation. Before
release, check:
1. `php -l` on every PHP file.
2. Appearance → Themes shows "Super Simple WordPress Theme" at version 2.0.0.
3. Front page, single post, page, category, author and search render with no
PHP notices while `WP_DEBUG` is on.
4. Reflow at 320 px, 768 px and 1440 px with no horizontal scrolling, and
200% text zoom with no loss of content.
5. Keyboard walkthrough: skip link → menu → content → pagination → search →
footer, with a visible focus ring at every stop.
6. bbPress forum list, topic view, reply view, new-topic form, user profile
and edit-profile screen.
7. The slideshow fills the width and keeps 16:9. This relies on the plugin
setting image `width`/`height` attributes rather than inline styles, now
that the old `!important` overrides are gone.
8. WordPress Theme Check.
9. No requests to external domains on the front end.
## Changelog
### 2.0.0
- Renamed from NTKF to Super Simple WordPress Theme; text domain
`super-simple-wp-theme`; version 2.0.0.
- Added `wp_head()`, `wp_footer()`, `body_class()`, `wp_body_open()` and
`title-tag` support.
- Added `<main id="main">`, a skip link and a single `<h1>` on posts and
pages.
- New `--sswt-*` design tokens; all text reaches AAA, all functional borders
reach 3:1.
- Rem-based typography, 18 px body text, heading scale `h1`–`h4`.
- One global `:focus-visible` outline; every `outline: none` removed.
- `.screen-reader-text` is now a real visually-hidden class.
- Flex navigation with 44 px targets; fluid search field; no fixed pixel
widths; no overflow clearfix.
- Form fields and buttons no longer produce white-on-white; this fixes
`.bbp-form input#user_login`.
- Shortcode output is guarded with `shortcode_exists()`.
- Deleted the dead `rss-feed.php`, which called `simplexml_load_file()`
against a remote URL.
- No HTML class name or ID was renamed or removed.
### 1.0.0
- Initial NTKF theme.