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:
1 parent
f8a226ecc9
commit
3dce684aef
1 file changed
+281
@@ -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.
|
||||||
Reference in new issue
Block a user