# product-pages Full Instructions

## Content Writing Best Practices

**See:** `.cursor/rules/content-writing.mdc` for comprehensive content writing guidelines.

### Natural Language Writing

When creating or updating product page content:

- ✅ **Human-first content:** Write for humans first, optimize for search engines second
- ✅ **Natural language:** Use conversational tone, vary sentence structures
- ✅ **AI content avoidance:** Avoid AI content tells (overly formal language, repetitive structures)
- ✅ **No repeated value phrases:** Avoid repeating the same value phrase (e.g. "Keine Menüs, einfach fragen") in hero, section intros, benefits, and FAQ; each section should add new information or angle.
- ✅ **Specific examples:** Include concrete examples, use cases, and scenarios
- ✅ **E-E-A-T:** Demonstrate Experience, Expertise, Authoritativeness, Trustworthiness

**Key Resources:**

- `docs/content/CONTENT_WRITING_BEST_PRACTICES_2026.md` - Comprehensive content writing guide
- `docs/content/AI_CONTENT_AVOIDANCE_GUIDE.md` - AI content avoidance guide
- `docs/content/META_TAGS_OPTIMIZATION_GUIDE.md` - Meta tags optimization guide

## Product Page Purpose

Market Ordio features (8 pages: Schichtplanung, Zeiterfassung, Abwesenheiten, Lohnabrechnung, Aufgabenverwaltung, Mobile Apps, Integrationen, Urlaubsplanung) with benefit-driven copy and clear conversion path.

## Unique Requirements

### Benefit-Driven Copy Pattern

**Transform features into benefits:**

- ❌ BAD (feature): "Zeiterfassung-Feature"
- ✅ GOOD (benefit): "erfasst du Arbeitszeiten gesetzeskonform und minutengenau"

- ❌ BAD (feature): "Automatische Schichtplanung"
- ✅ GOOD (benefit): "sparst du bis zu 5 Stunden pro Woche bei der Dienstplanung"

- ❌ BAD (feature): "Mobile App verfügbar"
- ✅ GOOD (benefit): "erfassen deine Mitarbeiter Zeiten direkt am Smartphone"

**Formula:** [Action] du [Outcome] [Context/Constraint if relevant]

### CTA Hierarchy

**Primary CTA (Hero):**

- Text: "Demo vereinbaren", "Kostenlos testen" or "Jetzt starten"
- Link: `/demo-vereinbaren` (never `/kostenlos-testen` in internal links — paid LP)
- Prominent button, above fold
- Class: `.product-cta` (from product-pages.css)

**Secondary CTAs (Throughout page):**

- Softer language: "Mehr erfahren", "Demo ansehen", "Funktionen entdecken"
- Same styling, less prominent placement
- Scattered after benefits section, comparison table, FAQ

**CTA frequency:** Every 2-3 sections have a CTA (not every paragraph, not once at bottom)

### Feature Sections Structure

Typical product page structure:

1. **Hero** – Feature name, primary benefit, CTA, hero image
2. **Benefits List** – 3-5 key outcomes (du tone, benefit-focused)
3. **Product Screenshots** – Show feature in action (preload first image)
4. **Social Proof** – Testimonials, ratings (4.9/5, 54 reviews), customer logos
5. **Comparison Table** – Ordio vs. manual/competitor approaches
6. **Detailed Features** – Secondary features with icons/images (see product-feature-cards.mdc for card copy: 70–95 chars, benefit-driven)
7. **Integrations** – Compatible systems (DATEV, Personio, etc.) if relevant
8. **FAQ** – Common objections, implementation questions
9. **Final CTA** – Soft close, trial/demo offer

### Scroll-Based Visual Switching Layout

**Pattern:** Unified scroll-based visual switching (inspired by nesto-software.com)

**Use Case:** When showcasing multiple related features that benefit from synchronized visual/text presentation.

**Layout Structure:**
- **Left Column:** All text sections stacked vertically (scrollable)
- **Right Column:** Single sticky visual container that changes based on active text section
- **Visual Switching:** Smooth crossfade transitions triggered by scroll position

**Implementation:**
- **JavaScript:** `v2/js/mobile-app-visual-switcher.js` (uses Intersection Observer API)
- **CSS:** Sticky positioning, crossfade transitions in `mobile-app-components.css`
- **HTML:** Text sections with `data-visual-id` attributes, visual containers with matching IDs

**Key Requirements:**
- Each text section needs unique ID and `data-visual-id` attribute
- First section must have class `.mobile-app-text-section-first`
- Last section must have class `.mobile-app-text-section-last`
- Visual containers must have matching IDs (`visual-{id}`)
- Intersection Observer configuration: `rootMargin: '0px 0px -50% 0px'`, `threshold: [0, 0.25, 0.5, 0.75, 1.0]`
- Visual switching threshold: `switchThreshold: 0.25` (switches when section is ≥25% visible)
- Sticky positioning: `position: sticky; top: 50%; transform: translateY(-50%)` (centered vertically, disabled on mobile <1024px)
- Crossfade transitions: `opacity 0.5s cubic-bezier(0.4, 0, 0.2, 1)`

**Scroll-Based Positioning:**
- Visual scrolls dynamically with user scroll
- Calculate: `offset = sectionCenter - viewportCenter`
- Apply transform: `translateY(calc(-50% + ${offset}px))` to sticky wrapper
- Use `requestAnimationFrame` for smooth 60fps updates
- Throttle scroll listener (passive: true)

**Boundary Detection:**
- Visual appears only when first section (`.mobile-app-text-section-first`) enters viewport
- Visual disappears when last section (`.mobile-app-text-section-last`) exits viewport
- Visual hidden when features section (`#mobile-app-features`) is out of viewport
- Transform reset when boundaries are exceeded

**Best Practices:**
- Use Intersection Observer (not scroll listeners) for visual switching performance
- Use scroll listener with `requestAnimationFrame` for smooth position updates
- **CRITICAL**: Do NOT use CSS fallback to show first visual - JavaScript manages all visual state
- All visuals start with `opacity: 0`, only `.active` class sets `opacity: 1`
- Visual switching threshold: ≥25% section visibility
- Handle edge cases: multiple sections visible (prioritize by intersection ratio), rapid scrolling, page load with section in view
- Responsive: Disable sticky on mobile (<1024px), stack visuals vertically
- Accessibility: Ensure text sections remain keyboard navigable
- Debug mode: Set `CONFIG.debug = true` in JavaScript for troubleshooting
- Clean implementation: Rebuilt from scratch - simple, maintainable code

**Reference:** `docs/content/pages/product-pages/mobile-app-visual-integration-guide.md`

### Zeiterfassung Sticky Feature Sections

**Pattern:** Six feature cards use `position: sticky` to cascade at the top as the user scrolls (folder-tab effect). Each card has `h-[600px]`, `top-[150px]` through `top-[200px]` (10px increments), and `z-[10]` through `z-[60]`.

**Requirements when adding or modifying sticky sections:**

- **CRITICAL:** The sticky section must be a **direct child of body**—not inside the content div (`body > div`). The content div gets `overflow-x: hidden` from head.php, which creates a scroll container and breaks sticky for cards 4–6.
- Add class `zeiterfassung-sticky-section` to the section wrapper
- Maintain `overflow: visible !important` on `.zeiterfassung-sticky-section` and its `.container` in `product-pages.css`
- **WARNING:** Do not add `overflow: hidden` (or `overflow-x: hidden`) to any ancestor of sticky sections—it creates a new scroll container and breaks `position: sticky`

**Reference:** `docs/content/product-features/zeiterfassung-documentation.md` (Sticky Feature Sections subsection)

---

## Schema Requirements (Product-Specific)

### SoftwareApplication Schema

Required for all product pages:

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Ordio [Feature]",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web, iOS, Android",
  "offers": {
    "@type": "Offer",
    "price": "89",
    "priceCurrency": "EUR",
    "priceSpecification": {
      "@type": "UnitPriceSpecification",
      "price": "89",
      "priceCurrency": "EUR",
      "unitText": "per Standort per Monat"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.9",
    "reviewCount": "54",
    "bestRating": "5",
    "worstRating": "1"
  },
  "featureList": [
    "[Feature 1: specific capability]",
    "[Feature 2: specific capability]",
    "[Feature 3: specific capability]",
    "[Feature 4: specific capability]",
    "[Feature 5: specific capability]"
  ],
  "screenshot": "https://www.ordio.com/v2/img/[product-screenshot].webp",
  "author": {
    "@type": "Organization",
    "name": "Ordio GmbH"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Ordio GmbH"
  },
  "datePublished": "2025-11-20",
  "softwareVersion": "2.0"
}
```

**Critical fields to keep current:**

- `price`: €89/Standort/Monat (standard pricing, update if changed)
- `aggregateRating`: 4.9/5 with 54 reviews (update quarterly)
- `featureList`: 5-8 specific features (not generic benefits)

### Service Schema

Also include:

```json
{
  "@type": "Service",
  "serviceType": "[Feature Name]",
  "provider": {
    "@type": "Organization",
    "name": "Ordio GmbH"
  },
  "areaServed": {
    "@type": "Country",
    "name": "Deutschland"
  },
  "audience": {
    "@type": "Audience",
    "audienceType": "Unternehmen mit Mitarbeitern"
  }
}
```

### Standard Schemas

Also include (from global.mdc):

- WebPage schema
- BreadcrumbList schema

---

## CSS Guidelines (Product-Specific)

### Shared CSS File

```php
<link rel="stylesheet" href="/v2/css/product-pages.css?v=<?php echo filemtime($_SERVER['DOCUMENT_ROOT'] . '/v2/css/product-pages.css'); ?>" media="print" onload="this.media='all'">
<noscript><link rel="stylesheet" href="/v2/css/product-pages.css"></noscript>
```

**⚠️ NEVER inline styles except for page-specific animations (e.g., FAQ collapsible arrows).**

### Available CSS Classes

From product-pages.css:

- `.product-feature` – Feature card container
- `.benefits-list` – Benefit list styling
- `.product-cta` – Primary CTA button
- `.product-screenshot` – Screenshot container
- `.testimonial-card` – Customer testimonial
- `.product-comparison-table` – Comparison table styling
- `.integration-badge` – Integration logo badge
- `.feature-icon` – Icon for features
- `.product-stat` – Statistics display
- `.product-faq` – FAQ section
- `.product-video` – Video container
- `.pricing-card` – Pricing display
- `.demo-section` – Demo section container

Use these classes; don't create new ones unless page-specific need arises.

---

## Meta Tags (Product-Specific)

### Title Pattern

```html
<title>[Feature Name]: [Key Benefit] - Ordio</title>
```

Examples:

- "Zeiterfassung: Arbeitszeiten digital & gesetzeskonform erfassen - Ordio"
- "Schichtplanung: Dienstpläne in Minuten erstellen - Ordio"

Max 60 characters, include feature, benefit, "Ordio"

### Description Pattern

```html
<meta
  name="description"
  content="[Feature] von Ordio: [Primary Benefit]. [Secondary Benefit]. [Outcome]. Kostenlos testen."
/>
```

155-160 characters, du tone, benefit-driven, include CTA

---

## Copy Patterns (Product-Specific)

See `.cursor/rules/shared-patterns.mdc` for universal copy guidelines (du tone, Ordio mentions, competitor language, copy quality).

### Hero Headline

Pattern: [Feature Name] – [Primary Benefit in 5-10 words]

Examples:

- "Zeiterfassung – Arbeitszeiten digital & gesetzeskonform erfassen"
- "Schichtplanung – Dienstpläne in Minuten statt Stunden erstellen"
- "Urlaubsplanung – Urlaub digital beantragen und genehmigen"

### Hero Subheadline

Pattern: [How it helps] [for whom] [key differentiator]

Examples:

- "Mit Ordio erfasst du Arbeitszeiten minutengenau per App, Desktop oder Terminal – rechtssicher nach §16 MiLoG."
- "Erstelle faire Dienstpläne mit automatischen Vorschlägen, berücksichtige Qualifikationen und Wünsche deiner Mitarbeiter."

### Benefits List Pattern

**Structure:** Icon + Headline (benefit) + 1-2 sentence explanation

Example:

```html
<div class="feature-icon">[Icon]</div>
<h3>Spare Zeit bei der Dienstplanung</h3>
<p>
  Erstelle Dienstpläne 70% schneller mit automatischen Vorschlägen. Ordio
  berücksichtigt Verfügbarkeiten, Qualifikationen und Mitarbeiterwünsche.
</p>
```

**Formula:**

- Headline: Verb + Outcome (e.g., "Spare Zeit", "Reduziere Fehler", "Erfülle Gesetze")
- Explanation: How + Why/Context + Ordio mention (if not in headline)

### Comparison Table Pattern

**Column 1:** Manual/Competitor Approach  
**Column 2:** Ordio Approach  
**Column 3:** Impact/Benefit (optional)

Example rows:

- Excel-Listen | Digitale Zeiterfassung | -80% Fehler
- WhatsApp-Gruppen | Zentrale Schichtplanung | +5h/Woche gespart
- Papier-Urlaub | Digital genehmigen | 24h statt 5 Tage

**Highlight Ordio advantages** with color or icons; keep comparison neutral (don't bash alternatives).

### FAQ Pattern for Product Pages

**Address common objections and implementation questions:**

- "Ist Ordio DSGVO-konform?" → Yes, explain data protection
- "Wie lange dauert die Einrichtung?" → Quick setup, onboarding support
- "Können Mitarbeiter auch mobil erfassen?" → Yes, iOS/Android apps
- "Was kostet Ordio?" → €89/Standort/Monat, transparent pricing
- "Welche Integrationen gibt es?" → DATEV, Personio, etc.

**Include Ordio mention in 1-2 FAQ answers** (not all), naturally integrated.

### Product Page FAQ Optimization

**Structure:** Single flat list, no H3 subsections. Use same `<details>` pattern as tools pages (see `tools-pages-faq.mdc`).

**Requirements:**

- Unique IDs: `id="faq-1"` through `id="faq-N"`
- Answer length: 40–80 words per FAQ
- One FAQPage JSON-LD from the same FAQ data as HTML (`misc-faqs` + `include-marketing-faq-jsonld.php` after `footer.php`; no duplicate FAQPage in head `@graph`)
- Contextual internal links when FAQs mention lexikon/tool/product terms (1:1 mandatory)
- Logical flow order: Definition → How-to → Features → Compliance → Wechsel → Support

**Reference:** `docs/content/pages/product-pages/PRODUCT_PAGE_FAQ_GUIDE.md` for full workflow (keyword research, GSC, Firecrawl, schema, validation).

---

## Validation Checklist (Product-Specific)

See `.cursor/rules/shared-patterns.mdc` for universal validation checklist.

**Product-Specific:**

- [ ] Hero headline benefit-driven (not feature-focused)
- [ ] Benefits list uses outcome language ("spare Zeit" not "Zeiterfassung")
- [ ] Primary CTA above fold ("Kostenlos testen")
- [ ] Secondary CTAs scattered throughout (every 2-3 sections)
- [ ] Comparison table highlights Ordio advantages
- [ ] SoftwareApplication schema includes current pricing (€89)
- [ ] AggregateRating schema current (4.9/5, 54 reviews)
- [ ] FeatureList in schema has 5-8 specific features
- [ ] Product screenshots/video show feature in action
- [ ] Social proof present (testimonials, customer logos, ratings)
- [ ] FAQ addresses common objections
- [ ] All CTAs link to `/demo-vereinbaren` (or `/preise` / product pages as appropriate); never `/kostenlos-testen`
- [ ] product-pages.css loaded correctly
- [ ] No inline styles (except FAQ arrow animation)

---

## Common Product Page Pitfalls

### Feature Lists Without Benefits

❌ **BAD:**

- Zeiterfassung per App
- Automatische Pausenberechnung
- Export zu DATEV

✅ **GOOD:**

- Erfasse Zeiten unterwegs per App – auch offline
- Berechne Pausen automatisch nach ArbZG – ohne Fehler
- Exportiere Lohndaten direkt zu DATEV – in Sekunden

### Too Many Ordio Mentions

❌ **BAD:** "Mit Ordio kannst du... Ordio bietet... Ordio ermöglicht... Ordio hilft..."

✅ **GOOD:** Mention once in hero, once in benefits, once in FAQ. Let features speak for themselves.

### Generic Testimonials

❌ **BAD:** "Ordio ist toll!" – Max M.

✅ **GOOD:** "Mit Ordio spare ich 5 Stunden pro Woche bei der Dienstplanung. Die automatischen Vorschläge sind genial." – Max Müller, Filialleiter bei [Company]

### Vague CTAs

❌ **BAD:** "Mehr erfahren" (only CTA on page)

✅ **GOOD:** Primary "Kostenlos testen" + Secondary "Demo ansehen" or "Funktionen entdecken"

---

## Edge Cases & Gotchas

### Feature Overlap Between Pages

Some features overlap (e.g., Zeiterfassung mentions Schichtplanung):

- Focus on primary feature for that page
- Link to related feature pages for deeper coverage
- Example: Zeiterfassung page can mention "Verknüpfe mit Schichtplanung" and link to product_schichtplan.php

### Pricing Variations

Standard pricing is €89/Standort/Monat, but some features are add-ons:

- Mention standard pricing in hero or pricing section
- Note add-ons clearly (e.g., "DATEV-Export: +€15/Monat")
- Keep pricing schema at standard €89 (primary offering)

### Mobile vs Desktop Features

Some features have mobile-specific functionality:

- Highlight mobile benefits where relevant (e.g., Zeiterfassung: "erfasse auch offline")
- Show both mobile and desktop screenshots if applicable
- Mention iOS/Android apps explicitly

### Zeiterfassung Feature Sections

The Zeiterfassung product page (`product_timetracking.php`) uses six sticky feature sections with a 3-color palette (blue, pink/coral, neutral). Each section: left half (light bg, title + subtitle), right half (darker bg, visual). Colors: blue (bg-blue-50 + bg-ordio-blue), pink/coral (#FFE9E8 + #FE938C), neutral (white + #fbfbfb). Visuals: product images from `/v2/img/zeiterfassung/` or custom HTML/SVG components.

**Right-half card styling (production parity):** Cards use `rounded-2xl`. Section halves use `rounded-[50px]`. All cards: `shadow-lg`. Section 2 subtitle: "Einfach per App starten und pausieren - Du siehst live wer zu spät ist oder wie lange schon arbeitet." Section 1 Emma time badge: `bg-ordio-blue text-white` for first row. Image wrappers: `overflow-hidden rounded-2xl`. Section 6: `border border-[#EDEFF3]/70`.

**Reference:** `docs/content/product-features/zeiterfassung-documentation.md` (Product Page Feature Blocks, Sticky Feature Sections)

### Mobile App Interactive Components

For the mobile app product page (`product_mobile_app.php`), use interactive components instead of static screenshots:

**Component Location:** `v2/components/mobile-app/`

**Available Components:**

- `calendar-component.php` - Interactive calendar with date selection
- `timer-component.php` - Time tracking timer with circular progress
- `absence-form-component.php` - Absence request form
- `task-list-component.php` - Checklist/task list
- `dashboard-cards-component.php` - Dashboard cards

**CSS File:** `v2/css/mobile-app-components.css`

**Usage Pattern:**

```php
<div class="mobile-device-frame">
    <div class="mobile-device-screen">
        <?php include '../components/mobile-app/component-name.php'; ?>
    </div>
</div>
```

**Best Practices:**

- Use Alpine.js for interactivity (already loaded globally)
- Include ARIA labels and keyboard navigation
- Add lazy loading for below-fold components using `x-intersect`
- Ensure GPU-accelerated animations (`transform: translateZ(0)`)
- Support reduced motion preferences
- Test keyboard navigation and screen readers

**Documentation:**

- See `docs/content/pages/product-pages/mobile-app-components-guide.md` for detailed component specifications

### Nano AI Proactive Hero Component

For the Nano AI product page (`product_nano_ai.php`), use the proactive hero component that showcases Nano's proactive AI suggestions:

**Component Location:** `v2/components/nano-ai/proactive-hero-component.php`

**CSS File:** `v2/css/nano-proactive-hero.css`

**Data File:** `docs/data/nano-proactive-scenarios.json`

**Usage Pattern:**

```php
<div class="max-w-3xl mx-auto" data-aos="fade-up" data-aos-delay="200">
    <?php include '../components/nano-ai/proactive-hero-component.php'; ?>
</div>
```

**Component Features:**

- Auto-cycling through 6 proactive scenarios
- Smooth fade transitions (500ms)
- Pause on hover, resume on leave
- Multiple visual types: shift cards, percentage cards, grid, chart
- Alpine.js state management
- Responsive design (mobile, tablet, desktop)

**Scenario Data Structure:**

- Scenarios defined in `docs/data/nano-proactive-scenarios.json`
- Each scenario has: id, category, title, description, ctaText, ctaAction, visualType, visualData
- Visual types: `shift-cards`, `percentage-cards`, `grid`, `chart`

**Best Practices:**

- Scenarios load from PHP (no initial fetch delay)
- Fallback fetch only if PHP load fails
- Animation lock prevents concurrent transitions
- Respects `prefers-reduced-motion`
- ARIA labels on all interactive elements
- Keyboard navigation support

**Icon System:**

- Icons defined in `v2/components/nano-ai/nano-icons.php`
- All icons are SVG (scalable, no external requests)
- Functions: `nano_icon_refresh()`, `nano_icon_feedback()`, `nano_icon_ai()`, etc.

**Rollback:**

- Old component backed up as `chat-hero-component.php.backup`
- To revert: restore backup and update include in `product_nano_ai.php`

**Documentation:**

- See `docs/content/pages/product-pages/nano-proactive-hero-documentation.md` for complete API documentation
- See `docs/design/nano-ai/FIGMA_SPEC.md` for design specifications
- When implementing from Figma, prefer API when `FIGMA_ACCESS_TOKEN` is set; see `.cursor/rules/figma-api.mdc` and `docs/development/FIGMA_API_INTEGRATION.md`

---

## WebGL section backgrounds (Schichtplan Nano promo)

- **`/schichtplan` Nano block** (`#schichtplan-neu-nano-promo`) uses **vanilla WebGL2** in `v2/js/schichtplan-nano-liquid-metal.js` for a subtle liquid-metal background—**no Three.js** unless explicitly approved as a dependency.
- After JS/CSS changes: **`npm run minify`**. SSOT: **`docs/systems/shared-components/SCHICHTPLAN_NANO_LIQUID_METAL_WEBGL.md`** (fallbacks, tuning, smoke test).
- **Accessibility:** honor `prefers-reduced-motion` (script skips GL); CSS blob fallback when WebGL2 is missing or context is lost.

---

## Reference Documentation

For detailed workflows:

- `docs/guides/PAGE_TYPE_GUIDES.md` – Quick reference for product pages
- `docs/ai/cursor-playbook.md` – Cursor-specific prompting patterns

For similar page types:

- Comparison pages (comparison-pages-core.mdc, comparison-pages-content.mdc) – Similar competitor positioning
- Industry pages (industry-pages.mdc) – Similar audience-specific messaging

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.

**Key Documentation:**

- [docs/guides/PAGE_TYPE_GUIDES.md](../../docs/guides/PAGE_TYPE_GUIDES.md) - `docs/guides/PAGE_TYPE_GUIDES.md` - Page type quick reference
- [docs/content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md](../../docs/content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md) - `docs/content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md` - Product pages list
- [docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md](../../docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md) - `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md` - Feature documentation
- [docs/content/product-features/README.md](../../docs/content/product-features/README.md) - `docs/content/product-features/README.md` - Feature docs index