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, szkolenia.html, konsulting.html, index-en.html, sharing 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 - trade portal: articles, cases, regulatory analysis, reader Q&A. Reader questions become webinar topics.
  • 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 — "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	Hero · By the numbers (spec sheet) · Offer · Subject tracks · Upcoming dates · Course platform · Ecosystem · Testimonial · Newsletter
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	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	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.

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 — 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/, 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/ 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 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/ 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.

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 platform name and URL (the "Przejdź do platformy" links point at #).
• Course prices and the annual webinar package price.
• Training dates are deliberately absent. The schedule tables carry a .tag-soon "Wkrótce" / "Soon" chip instead of a date, and the CTA is "Powiadom mnie" / "Notify me" — the site collects interest rather than taking bookings. Do not reintroduce concrete dates until real ones are confirmed; if they are, restore the Data/Date column heading and the "Zapisz się" CTAs together with them.
• 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/ 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 is inherited from an even earlier "AquaNexis" branding and is stale; verify a file exists before referencing it.

Forms

All four forms — newsletter (index.html), contact (index-en.html), training signup (szkolenia.html), consulting (konsulting.html) — post JSON to api/send.php, which relays to api.softspm.pl/send_email_api.php (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. 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 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.