softspm_www/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project status

The site is **built and live in this repo** as static HTML/CSS: [index.html](index.html), [szkolenia.html](szkolenia.html), [konsulting.html](konsulting.html), [index-en.html](index-en.html), sharing [assets/styles.css](assets/styles.css).

There is no build system, package manager, test suite, or linter — edit the HTML/CSS directly. The repo lives under an XAMPP `htdocs` directory, so preview by opening the files or via `http://localhost/softspm_page_2026/`.

To check a change visually, headless Edge works:
`"/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" --headless --disable-gpu --hide-scrollbars --window-size=1400,2000 --screenshot=out.png --virtual-time-budget=8000 "file:///C:/Programy/xampp/htdocs/softspm_page_2026/index.html"`
Note it lays out narrow windows at a 481px minimum, so a 390px shot is cropped, not overflowing — verify real overflow by comparing `documentElement.scrollWidth` with `clientWidth`.

## What the site is

SoftSPM is a Polish software house (**25+ years in IT**) that has served the water & sewage (`wod-kan`) sector since 2014. The site sells **turnkey applications, consulting, training and webinars** - in that order of prominence (owner brief, 2026-09-01).

**Two timelines, do not conflate them:** 25+ years of IT experience, and wod-kan specialisation since 2014. The hero and the numbers sheet both carry the pair.

**The pump-control heritage is deliberately out of scope.** On the owner's instruction (2026-08-31) all pump diagnostics, SCADA/IoT, energy-optimisation and telemetry content was removed. Do not reintroduce it — no pumps, wells, SUW energy audits, sensors, or failure prediction. Course topics are now regulatory and organisational: water law and tariff applications, utility management, public procurement, customer service and billing, digitisation.

- Primary CTAs: enroll in training / book a consultation / describe your project.
- **Turnkey software is a first-class offering** (owner brief, 2026-09-01), not an afterthought: custom web systems and **mobile apps** (Android/iOS), built to the client's requirements, delivered end to end without subcontractors, with source code and docs handed to the client. It also covers **advisory on large integrated-system rollouts** (ERP, GIS, billing) - always on the buyer's side, never the vendor's. Carried by `index.html#aplikacje` (section 06 + sheet 03), the `02.1` offer card, and area `02.5` on the consulting page. The course platform, Wodociagowiec and Gielda Komunalna are cited as our own builds - the proof.
- **Offer card order is fixed**: aplikacje pod klucz, konsulting, szkolenia, webinaria.
- The **ecosystem is a headline theme**, not a footnote. `index.html#ekosystem` carries it with a diagram and three "loop" cards.
  - **[wodociagowiec.pl](https://wodociagowiec.pl/)** - trade portal: articles, cases, regulatory analysis, reader Q&A. Reader questions become webinar topics.
  - **[akademiawodociagowca.pl](https://akademiawodociagowca.pl/)** - the **course platform**, added 2026-09-03. Live webinars, on-demand courses, tests, certificates, one company account. `index.html#platforma` (section 05) is its marketing home; it also feeds the schedule tables via its public API. Section 05 carries the "knowledge propagation" argument: taught first-hand, knowledge stays in-house, questions feed the programme.
  - **[gieldakomunalna.pl](https://gieldakomunalna.pl/)** - a **new, free marketplace** for the municipal sector (owner brief, 2026-08-31). Two jobs, and copy must reflect both: (1) users **list, buy, sell and swap free of charge** the stock **sitting idle in their warehouses** - project surplus, equipment replaced in upgrades, spares for discontinued machines; (2) it **brings together manufacturers and contractors** in a genuinely **niche, specialist** trade where there may be only a handful nationwide. It is **not** a tender/RFQ portal - do not describe it as "zapytania ofertowe", "miejsce wymiany ofert" or a procurement channel.
- Content language is **Polish**, plus an English mirror of the homepage.

## Authoritative source of truth

[doc/SoftSPM_projekt.doc](doc/SoftSPM_projekt.doc) — "SoftSPM — projekt nowej strony internetowej", spec v1.0, August 2026. Despite the `.doc` extension it is plain HTML (Word-flavored, **CP1250-encoded**); read it with an explicit encoding, not as UTF-8. This document defines the site structure, the design system, and the open questions. **When any other file in `doc/` contradicts it, this spec wins.**

## Site structure (as built)

| Page | Sections |
|---|---|
| [index.html](index.html) | Hero · By the numbers (spec sheet) · Offer · Subject tracks · Upcoming dates · **Akademia Wodociągowca** (05) · Turnkey software · **Ecosystem** · Testimonial · Newsletter |
| [szkolenia.html](szkolenia.html) | Hero · Training format (spec sheet) · Course catalogue (tracks 01-08 with prices, plus an RFQ workshop) · Schedule · Annual webinar package · Signup form |
| [konsulting.html](konsulting.html) | Hero · 7 service areas (02.7 is `.cell-span` full-width) · 3-step process · Deliverables + projects (spec sheet) · Team · Testimonial · Contact form |
| [index-en.html](index-en.html) | English mirror of the homepage - same eight tracks, same ecosystem loop cards; keep it in step when the Polish homepage changes |

The **eight** subject tracks on `index.html#tematy`, in fixed order: 01 water law & tariff applications, 02 utility management, 03 public procurement, 04 customer service/contracts/billing, then the technical block - 05 SCADA management & network monitoring, 06 security audits & NIS2 compliance, 07 integration with ERP/CRM/tax systems - and 08 digitisation last, framed as the track that ties the others together. Tracks 07 and 08 use a wide `.course` card with a `.split` inside (graphic on opposite sides, mirrored). `szkolenia.html` mirrors the same eight tracks and numbering (ids `sciezka-01`..`sciezka-08`, plus `sciezka-rfq` for the workshop, which sits last and carries no track number). Consulting areas 02.6 (security/NIS2) and 02.7 (integrations) are the advisory counterparts of tracks 06 and 07.

## Design system — "Industry" / HydroNexis

A **light wireframe/blueprint** aesthetic: light technical ground, a single steel-blue accent, square corners with registration-cross ("+") marks, cards drawn as line art with no fill, photos duotoned in the accent. Numbers and parameters are presented as **technical spec sheets** — a table with a title block carrying a drawing code, revision, and sheet number.

Motion: entrance animations are opt-in via `data-reveal` + [assets/reveal.js](assets/reveal.js) (IntersectionObserver, counters in `.stats`). The hiding styles only apply once the script adds `.js-reveal` to `<html>`, so content stays visible without JavaScript, and everything is disabled under `prefers-reduced-motion`. `assets/img/akademia.svg` animates itself: line-drawing via `pathLength="1"` plus dashoffset, a flowing arrow dash and a pulsing LIVE dot, all declared inside the file so they run from an `<img>`, with the same reduced-motion guard.

Rule: **one accent color only.** No extra decorative colors; hover/pressed states come from the tonal 100–900 ramp.

| Role | Value |
|---|---|
| Background | `#f2f2f3` |
| Text | `#1d1f20` |
| Accent (steel) | `#5980a6` |
| Accent for paragraph-size text / pressed | `--color-accent-700` (`#416180`) |

Typography: **Barlow Condensed** (600) for headings, uppercase in section and table titles; **Barlow** for body. Vertical rhythm is a **24px leading unit** with a 12px half-step — line heights and block margins are multiples of it. Icons: Lucide, stroke 1.5.

Components per spec: primary button is the only fully-filled object (accent fill, square corners, corner marks); ghost buttons are outlined. Offer cards are a hairline frame plus 4 corner crosses, no background. The dates table uses tabular figures, Barlow Condensed topics, Szkolenie/Webinar tags, and a "Zapisz się →" link — rows collapse into cards on mobile.

The tokens and components above are implemented in [assets/styles.css](assets/styles.css) — the single stylesheet all four pages share. Key classes: `.plate` + `.title-block` (technical sheet), `.corner` (registration crosses, four spans per framed object), `.cell-frame` (line-art card), `.course` (course card with cover), `.kicker` + `.caption-rule` (numbered section label), `.table.spec` / `.table.sched` (both collapse to cards under 760px), `.checks`, `.steps`, `.eco-item`, `.cta-band`.

### Imagery — custom SVG line art

Photographs were dropped along with the pump content. All illustrations are **hand-authored SVGs in [assets/img/](assets/img/)**, drawn in the accent colour on a blueprint grid: `szkolenia`, `webinaria`, `konsulting`, `platforma`, `ekosystem` (the ecosystem loop diagram), plus six 480×270 course covers (`kurs-*.svg`). They are already in the system palette, so they use `.plot`, **not** `.duotone`.

**The English page has its own copies.** [assets/img/en/](assets/img/en/) holds the fourteen graphics `index-en.html` uses — same filenames, same geometry, English labels and `<title>`. Polish pages read from `assets/img/`, `index-en.html` reads only from `assets/img/en/`. Edit a drawing's geometry and you must edit both copies; `konsulting.svg` and `webinaria.svg` have no English twin because no English page uses them.

Labels use `textLength` + `lengthAdjust="spacingAndGlyphs"` so a string fits its slot whatever the loaded font — keep that attribute when translating, and set the width from the slot, not the word. Too tight a `textLength` swallows the spaces between words (`FIELD CREWAPP`); check the render, not just the markup. Watch for text overflowing its frame and for labels colliding with the corner marks — both bit during the build.

### The reference mockup

[doc/SoftSPM_makieta.html](doc/SoftSPM_makieta.html) is the approved homepage mockup and the best guide to markup, section order, and Polish copy. It is a **self-extracting bundle**: the real page lives in a JSON string inside `<script type="__bundler/template">`, with assets base64'd in `__bundler/manifest` and the design system (`_ds_bundle.js`, `styles.css`) in `__bundler/ext_resources`. To read the actual markup, parse out the template script and JSON-decode it rather than reading the file top-down.

`styles.css` in that bundle is the token/component source of truth for the system — it defines `--color-*` ramps, `--font-*`, `--space-*`, `--radius-*`, `--shadow-*`, and classes including `.btn`/`.btn-primary`/`.btn-ghost`, `.card`, `.table`, `.tag`, `.input`, `.field`, `.nav`, `.dialog`, `.blueprint`, `.duotone`. The extracted template carries only page-level scaffolding (`--leading`, `--half`, `--edge`, `--measure`, `.wrap`, `.hero`, `.plate`, `.kicker`) and pulls everything visual from those tokens. Preserve that split when building real pages: layout in the page, look in the shared stylesheet.

The mockup also uses an `<image-slot>` custom element for photos and supports a baseline-grid overlay (append `?baselines` to the URL, or press `B`).

## The competing dark design (do not build from it by default)

[doc/stitch_softspm_academy_consulting/](doc/stitch_softspm_academy_consulting/) holds four Google Stitch mockups — homepage, training catalog, consulting, and a student dashboard (`panel_kursanta`) — with `screen.png` renders beside each `code.html`. These use a **completely different direction**: dark "Hydro-Tech" theme on `#101415`, Space Grotesk + Hanken Grotesk, Tailwind CDN with an inline `tailwind.config`, and Material Symbols icons. Its tokens are documented in [DESIGN.md](doc/stitch_softspm_academy_consulting/hydro_tech_intelligence/DESIGN.md).

This contradicts the approved spec. Treat these as exploratory alternatives and as a **content/IA source** — particularly the training catalog and student dashboard, which have no counterpart in the makieta. If a task seems to call for the dark theme, confirm with the user first. Note their copy mixes Polish and English and their dates say 2024 while the spec is 2026.

## Content that is deliberately placeholder

The spec lists these as unconfirmed — do not present them as fact, and flag them when touching:

- Stats in "Doświadczenie w liczbach" (480+ trained, 24 webinars/year, 60+ advisory projects) — sample values.
- Testimonials and quotes — samples, to be replaced with real references.
- Course prices and the annual webinar package price.
- **The static schedule rows are the fallback, not the plan.** The `.tag-soon` "Wkrótce" / "Soon" rows in `index.html` (8) and `szkolenia.html` (11) show only when the Akademia API returns nothing or is unreachable — see **Schedule** below. Keep them plausible and on-topic; they are what visitors see when the platform has no open dates.
- Team member names — the consulting page lists teams, not people, pending real bios.
- Nothing else. The forms are live — see **Forms** below.

Every such block already carries a visible caveat (`.sheet-note` or `.form-note`) in the built pages — keep it when editing values.

Known real details: SoftSPM · Ławy, 97-400 Bełchatów · info@softspm.com.

## Logos and images

[images/](images/) holds the brand assets: `spm_logo_new.png` is the **full lockup used in every nav and footer**, `softspm_large.png` / `softspm_small.png` are the drop mark alone, `softspm_full.png` an older lockup, and `favicon.ico` the tab icon. The logo's steel-blue drop matches the `#5980a6` accent, which is why the palette works with it.

The folder also holds AI-generated photos from the previous direction (SCADA, control rooms, dashboards, blog imagery). **The built pages no longer reference any of them** — they belong to the dropped pump/monitoring theme. [images/README.md](images/README.md) is inherited from an even earlier "AquaNexis" branding and is stale; verify a file exists before referencing it.

## Schedule

The `04 · Harmonogram` tables in `index.html` and `szkolenia.html` are filled at runtime by [assets/schedule.js](assets/schedule.js) from [api/schedule.php](api/schedule.php), which proxies the **Akademia Wodociągowca** public API v1 (`/webinars` + `/courses`, `X-API-Key` header, docs at `akademiawodociagowca/docs/api_public_v1.html`). Key stays server-side, response cached 5 min. Setup is in [api/README.md](api/README.md).

When live items arrive the script swaps the rows, the `Termin` → `Data` column heading, the section heading, the intro and the sheet note (`data-schedule-*` hooks mark all of them). When the API is empty, unreachable or unconfigured it does nothing, so the static rows in the HTML stay — never leave that table without plausible static rows.

## Forms

All four forms — newsletter (`index.html`), contact (`index-en.html`), training signup (`szkolenia.html`), consulting (`konsulting.html`) — post JSON to [api/send.php](api/send.php), which relays to `api.softspm.pl/send_email_api.php` ([doc/manual_send_email.html](doc/manual_send_email.html)). **Never call that API from the browser**: it authenticates with a Bearer key, and a key in client-side JS is a public key. The proxy keeps it server-side and pins the recipient to server config, so the endpoint cannot be used to mail arbitrary addresses.

Setup, the exact entry for `/etc/hydronexis/config.php`, the anti-bot layers and post-deploy tests live in [api/README.md](api/README.md). Needs PHP 7.4+.

**Message bodies are plain text, never HTML.** The remote API sanitises the body before dropping it into its own template, so any markup arrives in the mailbox as visible `<p style="...">`. This bit once, in production. The layout also survives a template that does not turn `\n` into `<br>`: one `Label: value` per line, readable even when collapsed into a paragraph.

Front-end is [assets/forms.js](assets/forms.js) plus the `.verify`, `.consent`, `.hp` and `.form-status` blocks in the stylesheet. Every form carries, in this order: fields, a **required** marketing-consent checkbox (`data-consent`, its text stored with the message as proof of what was agreed), a slider (`data-verify`), the submit button, a `data-form-status` live region, and a `<noscript>` fallback pointing at info@softspm.com.

Adding a form means adding it in **three** places: the markup, the `spm_forms()` whitelist in `api/send.php` (fields, labels, limits, subject line — the server ignores anything not listed), and nothing else. Field `name` attributes must match the whitelist keys. Keep `firma_www` as the honeypot name.

## Conventions

- Polish content needs correct diacritics and `<html lang="pl">` (`lang="en"` on `index-en.html`); always write files as UTF-8.
- **Never use an em dash (`—`) in user-visible copy.** The owner asked for a plain hyphen (`-`) throughout: `Uczymy tego, co sami robimy - a tematy bierzemy z rynku.` This covers page text, SVG `<title>` elements, and CSS comments. The en dash (`–`) survives only in numeric ranges such as `8–16 h`.
- Keep the numbering grammar of the section kickers (`02 · Oferta`, `03 · Ścieżki tematyczne`, …) — sections read as numbered notes around the drawn spec sheets. Renumber consistently when inserting a section.
- Every framed object (`.plate`, `.cell-frame`, `.course`, `.figure`, `.cta-band`, `.eco-item`) needs its four `<span class="corner tl/tr/bl/br">` children — that is the system's card grammar, not decoration.
- Spec sheets carry a title block with a drawing code, revision and sheet number (`Arkusz NN z 06`); keep the sequence unique across pages - index 01-03, szkolenia 04-05, konsulting 06. `index-en.html` mirrors sheets 01-03 as `Sheet NN of 06`. Update the denominator on every sheet when adding one.
- The nav collapses under 900px to logo + `.nav-keep` items (EN switch and the CTA); mark anything that must survive on mobile with `nav-keep`.