diff --git a/README.md b/README.md new file mode 100644 index 0000000..b84a031 --- /dev/null +++ b/README.md @@ -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, `
` landmark and a single `

` 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 `
`, a skip link and a single `

` 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.