# tools-pages-alg1-calculator Full Instructions

## Legal Compliance Requirements

### Legal Basis (SGB III)

All calculations MUST be based on:

- **SGB III §127**: Anspruchsdauer (Duration calculation)
- **SGB III §150**: Höhe des Arbeitslosengeldes (Amount calculation)
- **SGB III §157**: Nebenverdienst (Side income calculation)

### Constants (2026)

```javascript
// MUST be updated annually - verify with Bundesagentur für Arbeit
maxALGWest: 2390,        // Westdeutschland: 2.390 €/Monat
maxALGEast: 2320,        // Ostdeutschland: 2.320 €/Monat
algPercentageNoChildren: 60,   // 60% of netto income
algPercentageWithChildren: 67, // 67% of netto income
freibetrag: 165,         // Monthly Freibetrag: 165 €/Monat
```

## Children Impact - CRITICAL RULES

### What Children Affects

**Children ONLY affects:**

- ALG percentage (60% → 67%)
- Base ALG calculation (higher with children)
- Final ALG amount (unless capped)
- Side income reduction (indirectly, because it's based on baseALG)

**Children does NOT affect:**

- Duration (Anspruchsdauer) - depends ONLY on employment months and age
- Maximum cap (Höchstbetrag) - same for everyone
- Netto income calculation - same for everyone

### Code Pattern

```javascript
// Calculate ALG 1 percentage (SGB III §150)
// IMPORTANT: Children ONLY affects the percentage rate (60% → 67%)
// Children does NOT affect: duration, maximum cap, side income calculations
const algPercentage = this.hasChildren
  ? this.algPercentageWithChildren
  : this.algPercentageNoChildren;

// Calculate base ALG 1 amount
// When children=true: baseALG increases because algPercentage increases (60% → 67%)
let baseALG = nettoIncome * (algPercentage / 100);

// Duration calculation - NOT affected by children
// Duration depends ONLY on employment months and age (SGB III §127)
let durationMonths = calculateDuration(employmentMonths, age); // No children parameter
```

### UI Pattern - Visual Feedback

```html
<!-- Helper text explaining children impact -->
<p class="text-xs text-gray-500 mt-2" x-show="hasChildren">
  Mit Kindern erhöht sich der ALG 1 Satz von 60% auf 67% und damit auch dein
  Basis-ALG 1.
</p>

<!-- Basis-ALG 1 card with visual indicator -->
<div
  class="summary-card"
  :class="calculationBreakdown.hasChildren ? 'ring-2 ring-blue-200 bg-blue-50/30' : ''"
>
  <div
    class="card-number"
    x-text="formatCurrency(calculationBreakdown.baseALG)"
  ></div>
  <div class="card-label">
    Basis-ALG 1
    <span
      x-show="calculationBreakdown.hasChildren"
      class="text-xs text-blue-600 font-semibold ml-1"
      x-cloak
    >
      (mit Kindern: +7%)
    </span>
  </div>
</div>
```

## Calculation Logic Patterns

### Duration Calculation (SGB III §127)

```javascript
// Duration is NOT affected by children
// Formula: Base Duration = min(floor(employmentMonths / 2), 12)
// Age Increase (if age >= 50): min((age - 50) * 2, 12)
// Final Duration = min(Base Duration + Age Increase, 24)

let durationMonths = 0;
if (employmentMonthsValue >= 12) {
  durationMonths = Math.min(Math.floor(employmentMonthsValue / 2), 12);
  if (ageValue >= 50) {
    const ageIncrease = Math.min((ageValue - 50) * 2, 12);
    durationMonths = Math.min(durationMonths + ageIncrease, 24);
  }
}
```

### Amount Calculation (SGB III §150)

```javascript
// Step 1: Convert brutto to netto (if needed)
let nettoIncome = income;
if (this.incomeType === "brutto") {
  nettoIncome = income * 0.8; // 20% pauschal deduction
}

// Step 2: Calculate ALG percentage (children affects this)
const algPercentage = this.hasChildren ? 67 : 60;

// Step 3: Calculate base ALG
let baseALG = nettoIncome * (algPercentage / 100);

// Step 4: Apply maximum cap
const maxALG = this.region === "west" ? 2390 : 2320;
if (baseALG > maxALG) {
  baseALG = maxALG;
}
```

### Side Income Calculation (SGB III §157)

```javascript
// Side income reduction is based on baseALG
// Since children affects baseALG, it indirectly affects side income reduction
let finalALG = baseALG;
if (sideIncomeAmount > this.freibetrag) {
  const excess = sideIncomeAmount - this.freibetrag;
  // Discrete 100€ steps: each 100€ over Freibetrag = 20% reduction
  const reductionSteps = Math.floor(excess / 100);
  const reductionPercentage = reductionSteps * 0.2;
  sideIncomeReduction = baseALG * reductionPercentage;

  // Maximum reduction: 80% of ALG 1
  const maxReduction = baseALG * 0.8;
  if (sideIncomeReduction > maxReduction) {
    sideIncomeReduction = maxReduction;
  }
  finalALG = baseALG - sideIncomeReduction;
}
```

## Input Impact Matrix

| Input                 | Affects Amount     | Affects Duration | Affects Other | Legal Basis  |
| --------------------- | ------------------ | ---------------- | ------------- | ------------ |
| Income (Netto/Brutto) | ✅ Yes             | ❌ No            | ❌ No         | SGB III §150 |
| Age                   | ❌ No              | ✅ Yes (if ≥50)  | ❌ No         | SGB III §127 |
| Children              | ✅ Yes (60%→67%)   | ❌ No            | ❌ No         | SGB III §150 |
| Employment Months     | ❌ No              | ✅ Yes           | ❌ No         | SGB III §127 |
| Side Income           | ✅ Yes (reduction) | ❌ No            | ❌ No         | SGB III §157 |
| Region                | ✅ Yes (max cap)   | ❌ No            | ❌ No         | SGB III §150 |

## Testing Requirements

### Automated Tests

Run comprehensive test suite:

```bash
python3 tests/arbeitslosengeld_rechner_comprehensive_test.py
```

**Required Test Coverage:**

- Children impact tests (low income, high income, medium income, with side income)
- All inputs impact tests (income, age, employment months, side income, region)
- Edge case tests (exact caps, thresholds, boundaries)
- Duration calculation tests (verify children does NOT affect duration)

### Manual Testing Checklist

See `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-comprehensive-testing-guide.md` for complete checklist.

**Critical Tests:**

- [ ] Children toggle updates ALG percentage (60% → 67%)
- [ ] Children toggle updates baseALG card value
- [ ] Children toggle updates final ALG amount (unless capped)
- [ ] Children toggle does NOT update duration
- [ ] Visual feedback shows when children affects calculation
- [ ] Helper text explains children impact

## Code Comments Pattern

Always include comments explaining:

1. **Legal basis** (SGB III section)
2. **Why children doesn't affect duration** (per SGB III §127)
3. **Why children affects amount** (per SGB III §150)
4. **Formula derivation** (with examples)

Example:

```javascript
// Calculate ALG 1 percentage (SGB III §150)
// IMPORTANT: Children ONLY affects the percentage rate (60% → 67%)
// Children does NOT affect: duration, maximum cap, side income calculations
// This is legally correct per SGB III §150 - children only increases the benefit rate
const algPercentage = this.hasChildren
  ? this.algPercentageWithChildren
  : this.algPercentageNoChildren;

// Calculate base ALG 1 amount
// When children=true: baseALG increases because algPercentage increases (60% → 67%)
// Example: 2000€ netto → 1200€ (no children) vs 1340€ (with children)
let baseALG = nettoIncome * (algPercentage / 100);
```

## Documentation Requirements

### Required Documentation Files

1. **Legal Research:** `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-legal-research-2025.md`

   - Legal basis (SGB III sections)
   - Constants and formulas
   - Children impact explanation

2. **Calculation Formulas:** `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-calculation-formulas-2025.md`

   - Detailed formulas with examples
   - Edge cases
   - Children impact examples

3. **Testing Guide:** `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-comprehensive-testing-guide.md`
   - Test cases
   - Expected behaviors
   - Browser testing checklist

### Documentation Updates

- **Annual:** Update constants (maxALG, freibetrag) for new year
- **When laws change:** Update formulas and legal basis
- **When bugs found:** Document fixes and add test cases

## Common Pitfalls

### ❌ WRONG: Children affects duration

```javascript
// WRONG - Duration should NOT depend on children
let durationMonths = this.hasChildren ? 12 : 6; // ❌ INCORRECT
```

### ✅ CORRECT: Duration depends only on employment months and age

```javascript
// CORRECT - Duration calculation does NOT use hasChildren
let durationMonths = calculateDuration(employmentMonths, age); // ✅ CORRECT
```

### ❌ WRONG: Children affects maximum cap

```javascript
// WRONG - Maximum cap is same for everyone
const maxALG = this.hasChildren ? 2500 : 2390; // ❌ INCORRECT
```

### ✅ CORRECT: Maximum cap depends only on region

```javascript
// CORRECT - Maximum cap depends only on region
const maxALG = this.region === "west" ? 2390 : 2320; // ✅ CORRECT
```

## Validation Checklist

Before deploying ALG 1 calculator changes:

- [ ] All calculations match SGB III 2026 regulations
- [ ] Children correctly affects ALG percentage and baseALG
- [ ] Children does NOT affect duration
- [ ] All inputs affect outputs as per legal requirements
- [ ] UI clearly shows when children affects calculation
- [ ] Comprehensive test suite passes (17/17 tests)
- [ ] Manual testing completed (see testing guide)
- [ ] Documentation updated with changes
- [ ] Code comments explain legal basis
- [ ] No console errors in browser
- [ ] Export functionality works correctly

## References

- Legal Research: `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-legal-research-2025.md`
- Calculation Formulas: `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-calculation-formulas-2025.md`
- Testing Guide: `docs/guides/tools-pages/testing/arbeitslosengeld-rechner/alg1-comprehensive-testing-guide.md`
- Test Script: `tests/arbeitslosengeld_rechner_comprehensive_test.py`
- Code Implementation: `v2/pages/tools_arbeitslosengeld_rechner.php`
# tools-pages-content-blocks Full Instructions

## Reader-facing copy (no research or implementation meta)

**Published** `v2/pages/tools_*.php` and `v2/includes/tools/**` prose must read as product/help content for visitors — not as notes from keyword research, outlines, or schema work.

**Do not** put on the page (German or English):

- References to **FAQ-JSON**, **strukturierte Daten**, **Schema/JSON-LD parity**, or “1:1 abgestimmt” between data files and HTML
- Framing like **typische Suchanfragen**, **Suchbegriffe**, **SERP(-Abschnitte)**, **PAA**, **Outline**, or “was Nutzer googeln” as the reason content exists
- Any explanation that visible FAQs exist **for SEO** or to match machine-readable markup

**Do** keep research, PAA/SERP maps, and parity checks in `docs/content/tools/{slug}/`, validators, and PR notes — **never** in user-visible paragraphs or headings.

**Do** integrate important phrases **in natural sentences** (questions readers actually have, definitions, steps). Prefer “Du findest Antworten zu …” over “Die FAQs decken Suchanfragen ab …”.

**Do** run a **keyword→surface pass** before ship using committed `keywords-candidate.json` + checklist (`docs/content/tools/_templates/TOOL_KEYWORD_SURFACE_CHECKLIST.md`, `TOOLS_CONTENT_WORKFLOW.md` § 4b) — still without exposing research language on the page.

## Research gate (blocking: new tools & major content overhauls)

Before **shipping a new** `v2/pages/tools_*.php` or **rewriting most** SEO blocks / FAQ on an existing tool:

1. **Run the improvement pipeline** so durable data lives under `docs/content/tools/{slug}/` (keywords, PAA, competitor JSON, `SERP_ANALYSIS.md`, `CONTENT_OUTLINE.md`). Minimum: **Phase 1–2** of `php v2/scripts/tools/run-tools-improvement-pipeline.php --tool={slug}` (Phase 1 = SISTRIX + competitors + depth; Phase 2 = SERP skeleton + outline). Convenience: `make tool-research TOOL={slug}` runs **Phase 1 only** – still run Phase 2 afterward unless you document why not.
2. **Exemption:** If API keys, credits, or time genuinely block the run, record **exemption + reason** in the tool’s guide (`docs/guides/tools-pages/*-documentation.md`) and the PR. Do not treat “ship fast” as an undocumented skip.
3. **MCP pass (interactive):** After JSON exists, use **Serper** for live PAA/titles, **Fetch** for top-URL structure, **Firecrawl** markdown scrape only when competitor extractions are sparse – see [TOOLS_SERP_MCP_GUIDE.md](docs/guides/tools-pages/TOOLS_SERP_MCP_GUIDE.md) and `mcp-usage.mdc`.

Aligns with `.cursor/rules/tools-prioritization.mdc`.

## Publication checklist (new or relaunched tools)

Before marking a tool **live**:

1. **OG image:** `og-image-specs.json` → if using `--gemini-visuals`, add `VISUAL_DESCRIPTIONS` + `VISUAL_ONLY_PROMPTS` for the slug → generate → `validate-og-images.py` + `validate-og-logo.py` → `v2/config/og-image-registry.php`. See `NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md`.
2. **Tools index:** Add the tool to `v2/data/tools_index_data.php` with `status: available` when it should appear in listings.
3. **Tools carousel:** Add `tools_*` filename → slug mapping in `v2/base/tools_carousel.php` (`$filenameToSlugMap`).
4. **Include order:** `include '../base/tools_carousel.php'` (or `__DIR__` equivalent) **immediately before** the FAQ section—not after.
5. **Drift audit:** `python3 v2/scripts/og-images/audit-og-publish-readiness.py` (optional `--require-gemini-prompts`).

Copy-paste todo: `docs/content/_templates/NEW_TOOL_PUBLICATION_TODO.md`.

## Content Block Structure

### Target Word Count

- **Minimum:** 500 words total (content blocks only)
- **Optimal:** 600-800 words
- **Benchmark:** Arbeitslosengeld Rechner (~800+ words)

### Section Count

- **Minimum:** 3 H2 sections
- **Typical:** 3-4 sections
- **Structure:** "Wie funktioniert...", "Was wird berechnet...", "Für wen geeignet...", optional topic-specific H2

### H3 Subsection Pattern

Use H3 subsections to align with HowTo schema and improve scanability:

- Section 1 (How it works): Eingabe, Ergebnis, Export (or equivalent)
- Section 2 (What is calculated): Topic-specific H3s (e.g. Freibeträge, Steuersätze, Zusätzliche Abgaben)

## SERP/Competitor Research

**Sparse competitor data:** If `competitor-analysis.json` has sparse FAQs, empty headings, or word_count &lt; 100 for key competitors, use **firecrawl_scrape** with `formats: ['markdown']` (1 credit); avoid firecrawl_extract. Document findings in SERP_ANALYSIS.md. See [TOOLS_SERP_MCP_GUIDE.md](docs/guides/tools-pages/TOOLS_SERP_MCP_GUIDE.md).

## Keyword Integration from SISTRIX

### Process

1. **Run SISTRIX:** Use `collect-tool-keywords-sistrix.php --tool={slug}` (or bulk collectors with `--input=` where documented)
2. **Map keywords:** Assign top 15-20 keywords to target sections
3. **Integrate naturally:** No stuffing; use in context
4. **Verify:** Run `audit-tools-content-blocks.py --keywords=path` to check presence

### Keyword Placement

- **Primary keyword:** H1, Section 1 first paragraph
- **Secondary keywords:** Throughout content blocks in context
- **Long-tail:** In audience cards, callout boxes, examples

## Internal Linking

### Opportunity-Driven (Not Count-Driven)

- **1:1 lexikon terms (mandatory):** When content mentions a term with a dedicated lexikon post (e.g. Minijob, Gleitzone, Arbeitszeit), add a link on first meaningful mention.
- **Primary keywords:** When content discusses a topic that matches a tool, template, or product page from the mapping, add the link.
- **Context over count:** Add all contextually relevant links from the mapping; never force links to hit a minimum. A page with 1 highly relevant link beats 3 forced links.
- **Typical range:** Most tools have 2+ links when mapping suggests targets. The audit flags tools with missing suggested links—prioritize applying those over hitting a count.

### Target Pages and Mapping

- **Mapping:** See `docs/data/tools-internal-link-mapping.json` for suggested lexikon, templates, products, related tools per tool slug
- Related tools (e.g. Brutto-Netto-Rechner for tax calculators)
- Product pages when relevant (e.g. Lohnabrechnung)

### Audit Script

Run `php v2/scripts/tools/audit-tools-internal-links.php` to compare current links against mapping and report gaps. Output: `docs/data/tools-internal-links-audit.json`.

### Ordio Product Links

When adding product links: match section topic to Ordio feature (Lohnabrechnung→/payroll, Urlaub→/abwesenheiten, Zeiterfassung→/arbeitszeiterfassung). See ordio-promotion-contextual.mdc and blog-product-feature-mapping.json.
- Webinars/content when adding value

## Concrete Calculation Examples

### Pattern

When the tool calculates a value, add 4-5 concrete examples (like Arbeitslosengeld Rechner):

```html
<div class="bg-gray-50 p-6 rounded-xl mb-6">
  <div class="space-y-4">
    <div class="border-l-4 border-blue-500 pl-4">
      <p class="font-semibold text-gray-900 mb-1">Bei X € [input]</p>
      <p class="text-gray-700">[Result]: ca. Y € · [Additional context]</p>
    </div>
    <!-- Repeat for 4-5 examples -->
  </div>
</div>
```

### Requirements

- Use exact values from calculator (verify with live tool)
- State assumptions (e.g. Steuerklasse I, keine Kinder)
- Include year reference (2026)
- Vary input ranges (low, mid, high)

## Audience Card Expansion

### Pattern

Each audience card should have 2-3 sentences, not 1:

- **Sentence 1:** Primary benefit, keyword if relevant
- **Sentence 2:** Secondary benefit or how to use
- **Optional 3:** Internal link when relevant

### Example (Angestellte)

```html
<p>Einkommensteuer basierend auf Bruttojahresgehalt und Steuerklasse – ideal für Steuerplanung und Lohnsteuer-Vorauszahlung.</p>
<p>Willst du deine Steuerklasse berechnen oder den Steuerklassen-Vergleich durchspielen, nutze den Vergleichsmodus. Für die monatliche Umrechnung hilft unser <a href="/tools/brutto-netto-rechner">Brutto-Netto-Rechner</a>.</p>
```

## Callout Boxes

Use for important disclaimers or context:

```html
<div class="bg-blue-50 rounded-lg p-4 border border-blue-200 mb-6">
  <p class="text-blue-800">
    <strong>Wichtig:</strong> [Disclaimer or key info]
  </p>
</div>
```

## Comparison Mode Output (Vergleich)

When a tool has a comparison mode (e.g. Einkommensteuer Rechner Vergleich), follow these patterns:

### Structure

1. **Header block:** Icon, title ("Vergleich der Szenarien"), subtitle ("Unterschiede zwischen Szenario 1 und 2"). Use `comparison-header` class, `bg-ordio-blue/5`.
2. **Summary line:** Different styling for same vs different results. When different: green-tinted background + "Mehr Netto" badge.
3. **Comparison bar chart:** CSS-based horizontal bar chart (4 rows: Nettoeinkommen, Einkommensteuer, Zu versteuerndes Einkommen, Effektiver Steuersatz). Two bars per row (S1 = #4D8EF3, S2 = #6b7280). Helper: `getComparisonChartData()`. Classes: `comparison-bar-chart`, `comparison-chart-row`, `comparison-chart-bar`. No Chart.js; zero deps.
4. **Scenario cards:** `content-block-card`, input context (e.g. "50.000 € • Steuerklasse I"), winner badge on advantageous scenario. Metrics: primary values first, optional (Solidaritätszuschlag, Kirchensteuer) when > 0.
5. **Differenz block:** When scenarios differ, show Netto-Differenz and Steuer-Differenz with green/red color-coding. Use `comparison-diff-block`.
6. **Disclaimer and CTA:** Separate `content-block-callout` for legal disclaimer; prominent CTA button.

### Helpers

- `getScenarioInputSummary(scenarioNum)` – formatted input string (e.g. "50.000 € • Steuerklasse I")
- `getComparisonChartData()` – returns `{ rows: [{ label, s1, s2, s1Pct, s2Pct }] }` for chart

### Reference

- [einkommensteuer-rechner-documentation.md](../../docs/guides/tools-pages/einkommensteuer-rechner-documentation.md) - Mode 3 structure
- [tools_zinseszinsrechner.php](../../v2/pages/tools_zinseszinsrechner.php) - Zinseszins comparison layout

## Styling Reference (Minijob/Arbeitslosengeld)

Match reference tools for consistent content block styling:

- **Section:** `bg-white`, `prose prose-lg max-w-none text-gray-600`
- **H2:** `font-gilroybold text-3xl sm:text-4xl leading-[102%] tracking-[-1.5px] text-[#333333] mb-8`
- **H3:** `font-inter600 text-xl`
- **Colored cards:** `bg-green-50`, `bg-orange-50`, `bg-blue-50`, `bg-purple-50`, `rounded-xl`, `border`
- **Example wrapper:** `bg-gray-50 p-6 rounded-xl mb-6`
- **FAQ:** `[&>summary::-webkit-details-marker]:hidden [&>summary::marker]:content-none group`, `font-inter600 text-lg cursor-pointer flex items-center justify-between hover:text-ordio-blue`, chevron icon

## Tools Improvement Pipeline

When to run: Before expanding content for a tool, or when adding a new tool with SEO content blocks.

**Data directory:** `docs/content/tools/{tool-slug}/data/` with `keywords-sistrix.json`, `paa-questions.json`, `competitor-analysis.json`, `competitive-depth-analysis.md`.

**Pipeline:** `php v2/scripts/tools/run-tools-improvement-pipeline.php --tool=elterngeld-rechner [--phase=N] [--dry-run]`

See [TOOLS_CONTENT_WORKFLOW.md](../../docs/guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md).

## Audit Script

Run content block audit:

```bash
python3 v2/scripts/tools/audit-tools-content-blocks.py [tool_slug] [--format-check] [--keywords=path]
```

When `--keywords` omitted and tool_slug given, auto-loads from `docs/content/tools/{tool}/data/keywords-sistrix.json`. Use `--paa=path` or `--outline=path` for PAA/outline coverage checks.

Output: word count, H2/H3 structure, internal links, keywords found/missing, format variety (with --format-check).

## Benchmark Reference

**Arbeitslosengeld Rechner** (`tools_arbeitslosengeld_rechner.php`): Reference implementation with:

- 4+ content sections
- Concrete calculation examples (5+ scenarios)
- 3 internal links in content
- Expanded audience cards (2-3 sentences)
- Callout box ("Wichtig: ALG 1 zeitlich begrenzt")
- Collapsible "Detaillierte Beispielrechnungen"

## Related Documentation

- [EINKOMMENSTEUER_RECHNER_SEO_AUDIT.md](../../docs/content/tools/EINKOMMENSTEUER_RECHNER_SEO_AUDIT.md) - Full audit example
- [AI_CONTENT_AVOIDANCE_GUIDE.md](../../docs/content/AI_CONTENT_AVOIDANCE_GUIDE.md) - Natural writing
# tools-pages-core-design Full Instructions

## Content Writing Best Practices

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

### Natural Language Writing

When creating or updating tools 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)
- ✅ **Specific examples:** Include concrete examples, calculation scenarios, and use cases
- ✅ **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

## Tools Page Purpose

Provide interactive calculators and utilities (15 pages: Arbeitstage-Rechner, Kostenrechner, Brutto-Netto-Rechner, ROI-Rechner, Überstunden-Rechner, etc.) with real-time calculations, validation, and export functionality.

## Unique Requirements

### Design System Principles

**Modern No-Gradient Design Philosophy:**

- **Solid colors with depth via shadows:** Avoid gradients; use layered shadows for visual hierarchy
- **Clean, sleek aesthetic:** White backgrounds, subtle borders, elevated shadows
- **Micro-interactions:** Smooth transitions (`0.2s cubic-bezier(0.4, 0, 0.2, 1)`) on all interactive elements
- **Progressive disclosure:** Collapsible sections with count badges
- **Responsive touch targets:** Minimum 44px height on mobile

**Design Tokens:**

```css
/* Colors */
--ordio-primary: #4d8ef3;
--ordio-primary-hover: #3b82f6;
--ordio-text-primary: #374151;
--ordio-text-secondary: #6b7280;
--ordio-border: #e5e7eb;
--ordio-background: #ffffff;

/* Shadows (layered for depth) */
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08), 0 4px 16px rgba(0, 0, 0, 0.04); /* Standard elevation */
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08), 0 2px 6px rgba(0, 0, 0, 0.04); /* Result cards */
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 2px 8px rgba(0, 0, 0, 0.08); /* Tab container */

/* Spacing Scale */
--spacing-xs: 0.25rem; /* 4px */
--spacing-sm: 0.5rem; /* 8px */
--spacing-md: 1rem; /* 16px */
--spacing-lg: 1.5rem; /* 24px */
--spacing-xl: 2rem; /* 32px */

/* Border Radius */
--radius-sm: 0.5rem; /* 8px - buttons, tabs */
--radius-md: 0.75rem; /* 12px - containers */
--radius-lg: 1rem; /* 16px - cards, forms */

/* Typography Scale */
--text-xs: 0.75rem; /* 12px */
--text-sm: 0.875rem; /* 14px */
--text-base: 1rem; /* 16px */
--text-lg: 1.125rem; /* 18px */
--text-xl: 1.25rem; /* 20px */
--text-2xl: 1.5rem; /* 24px */
```

### Results report pattern (calculator output)

- **One focal metric:** Lead with the single outcome users care about most; use a secondary card or row for supporting figures. **Do not** show the same headline value again in a summary tile (e.g. Kurzarbeitergeld: **Summe Netto + KUG** only in the hero pair, not a fourth tile).
- **Reference pages:** [`v2/pages/tools_stundenlohnrechner.php`](../../v2/pages/tools_stundenlohnrechner.php) — dual gradient KPI cards with `w-12 h-12` icon wells (`rounded-xl`), then a row of simple bordered metric cards; [`v2/pages/tools_arbeitstage_rechner.php`](../../v2/pages/tools_arbeitstage_rechner.php) — large result number, thick progress bar, colored summary cards. Kurzarbeitergeld: [`v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php`](../../v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php) + scoped styles in [`v2/pages/tools_kurzarbeitergeld_rechner.php`](../../v2/pages/tools_kurzarbeitergeld_rechner.php).
- **Progressive disclosure:** Full input recap and step lists belong in `<details>` with an accessible `<summary>` (`focus-visible:ring-2`, `list-none` + chevron where needed). Optional: open by default on large viewports only (e.g. Alpine `x-init` + `matchMedia('(min-width: 1024px)')`) — document in PR if used.
- **Gradient exception:** Form shells follow the flat/shadow-first guidance above; **result hero cards** may use the same subtle blue/green gradients as Stundenlohn for cross-tool consistency.

### Calculator Form Patterns

**Enhanced Calculator Form Styling (Modern No-Gradient Design):**

- **Clean white background:** `background: white` (no gradients) for modern, sleek aesthetic
- **Enhanced box-shadow:** `0 2px 8px rgba(0, 0, 0, 0.08), 0 4px 16px rgba(0, 0, 0, 0.04)` for subtle depth through shadows
- **CSS containment:** `contain: layout style;` for performance optimization
- **Border-radius:** Consistent `1rem` (16px) for modern rounded corners
- **Border:** Subtle `1px solid #e5e7eb` for definition
- **Depth through layering:** Use elevated shadows instead of gradients

**Input Types:**

- **Number inputs:** With validation (min/max, step), real-time calculation trigger
- **Select dropdowns:** Styled with custom arrow, semantic options
- **Radio groups:** Horizontal button-style for 2-4 options
- **Toggle switches:** For boolean options (enable/disable features)
- **Input with addon:** Currency ("€"), percentage ("%"), or unit suffixes

**Card selection vs native select (tools forms):**

- **Small option sets (about 2–6 short labels):** Prefer **bordered selectable cards** with `type="radio"` or `type="checkbox"` inside `<label>` (same interaction model as [`v2/pages/tools_mehrwertsteuer_rechner.php`](../../v2/pages/tools_mehrwertsteuer_rechner.php): `border-2`, `rounded-lg`, `p-4`, hover border). Use **`fieldset` + `legend`** for the group name; avoid duplicating `role="radiogroup"` on an inner wrapper when the fieldset already groups radios.
- **Long lists (e.g. Bundesländer):** Keep a **styled `<select>`** — card grids become unwieldy and hurt scan speed.
- **Independent booleans (multi-toggle):** Use **large card toggles** (clickable `<label>`), not a single radio group. Native checkbox may be visually de-emphasized if global `tools-pages.css` checkbox styles clash — scope overrides on the tool page (see [`v2/pages/tools_kurzarbeitergeld_rechner.php`](../../v2/pages/tools_kurzarbeitergeld_rechner.php) `.kug-toggle-card` pattern).
- **Two-column alignment:** Pair fields with **matching hint height** — e.g. a `.kug-hint-slot` with `min-height` so inputs in the same row align when one column has helper text and the other does not.

**Reference implementations:** Kurzarbeitergeld calculator partial [`v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php`](../../v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php); Mehrwertsteuer quick tab radios in `tools_mehrwertsteuer_rechner.php`.

**Example:**

```html
<div class="input-with-addon">
  <input type="number" id="hourly_rate" min="0" max="1000" step="0.01" />
  <span class="addon">€</span>
</div>
```

### Modern Tab Navigation Pattern

**Standard Ordio Tab System** (REQUIRED - used across ALL tools):

```html
<div class="ordio-tabs" role="tablist">
  <button :class="{'active': mode === 'basic'}" class="ordio-tab" role="tab">
    Mode Label
  </button>
</div>
```

**CSS (Standard Pattern):**

```css
.ordio-tabs {
  display: flex;
  background: var(--ordio-background-subtle);
  border-radius: 0.75rem;
  padding: 0.25rem;
  margin-bottom: 1.5rem;
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
  scrollbar-width: thin;
  scroll-snap-type: x mandatory;
}

.ordio-tab {
  font-family: "Inter-500", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
    Helvetica, Arial, sans-serif;
  flex: 1;
  padding: 0.75rem 1rem;
  border-radius: 0.5rem;
  font-size: 0.875rem;
  font-weight: 500;
  text-align: center;
  cursor: pointer;
  transition: all 0.2s ease;
  color: var(--ordio-text-secondary);
  background: transparent;
  border: none;
  white-space: nowrap;
}

.ordio-tab.active {
  background: white;
  color: var(--ordio-primary);
  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
}

.ordio-tab:hover:not(.active) {
  color: var(--ordio-text-primary);
}

/* Mobile Optimization */
@media (max-width: 768px) {
  .ordio-tabs {
    flex-direction: row;
    flex-wrap: nowrap;
    gap: 0.25rem;
  }

  .ordio-tab {
    flex-shrink: 0;
    scroll-snap-align: start;
    min-height: 44px;
  }
}
```

**Multi-Row Variant (For 8+ Tabs - Prozentrechner):**

For tools with many modes where horizontal scrolling would hide tabs, use multi-row layout with icons:

```html
<button class="ordio-tab flex items-center justify-center">
  <svg
    class="w-4 h-4 mr-2 flex-shrink-0"
    fill="none"
    stroke="currentColor"
    viewBox="0 0 24 24"
  >
    <path
      stroke-linecap="round"
      stroke-linejoin="round"
      stroke-width="2"
      d="..."
    ></path>
  </svg>
  <span class="whitespace-nowrap">Label</span>
</button>
```

```css
.ordio-tabs {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  background: var(--ordio-background-subtle);
  border-radius: 0.75rem;
  padding: 0.25rem;
  margin-bottom: 1.5rem;
  gap: 0.25rem;
}

.ordio-tab {
  display: flex;
  align-items: center;
  justify-content: center;
  flex: 0 1 auto;
  /* ... rest of standard styles ... */
}

.ordio-tab svg {
  flex-shrink: 0;
}

@media (max-width: 768px) {
  .ordio-tabs {
    gap: 0.375rem;
  }

  .ordio-tab {
    min-height: 44px;
    font-size: 0.8125rem;
    padding: 0.625rem 0.875rem;
  }
}
```

**Icon Guidelines:**

- Use unique, relevant SVG icons for each tab (16x16px with `w-4 h-4`)
- Icons positioned before text with `mr-2` spacing
- Use `flex-shrink-0` to prevent icon squishing
- Order tabs by popularity (most common use cases first)

**Pattern Consistency:**

- **CRITICAL:** Used across Mehrwertsteuer-Rechner, Stundenlohn-Rechner, Midijob-Rechner, Arbeitstage-Rechner, and ALL other tools
- Standard Ordio design system classes (`.ordio-tabs`, `.ordio-tab`)
- CSS variables for consistent theming (`var(--ordio-primary)`, `var(--ordio-background-subtle)`)
- **Single-row with scroll:** Default for 3-5 tabs
- **Multi-row centered:** For 8+ tabs to ensure all visible
- **NEVER use custom `.tab-container` or `.tab-button` classes**

**Mobile Optimization:**

- Minimum 44px touch target height
- Responsive font sizing for readability
- Proper spacing with gap property

### Compact Input Pattern

**Optimized Input Sizing (2025 Redesign):**

```css
/* Desktop: Compact inputs for better visual density */
.calculator-form input,
.calculator-form select {
  height: 2.75rem;
  min-height: 2.75rem;
  font-size: 0.875rem;
  padding: 0.5rem 0.75rem;
}

/* Mobile: Larger for touch */
@media (max-width: 768px) {
  .calculator-form input,
  .calculator-form select {
    height: 3.25rem;
    min-height: 3.25rem;
    font-size: 1rem;
    padding: 0.75rem 1rem;
  }
}
```

**Benefits:**

- Desktop: More compact, fits more content above fold
- Mobile: Large enough to prevent zoom (16px font minimum)
- Better visual hierarchy with appropriate sizing

### Icon Button Pattern

**Small action buttons with icon-only design:**

```css
.icon-btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 2rem;
  height: 2rem;
  padding: 0;
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  background: white;
  color: #6b7280;
  cursor: pointer;
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}

.icon-btn:hover {
  background: #f3f4f6;
  color: #374151;
  transform: translateY(-1px);
}

.icon-btn svg {
  width: 1rem;
  height: 1rem;
}

/* Danger variant */
.icon-btn-danger {
  color: #ef4444;
}

.icon-btn-danger:hover {
  background: #fef2f2;
  color: #dc2626;
}
```

**Usage:**

- History export/delete actions
- Collapse/expand toggles for helper sections
- Quick actions near results
- Replace text buttons where space is limited

**Results report (multi-KPI tools):** After calculate, present a clear hierarchy: dual KPI hero when two headline numbers matter (see Stundenlohn gradient cards), optional progress/ratio bar for context (see Arbeitstage), compact **settings summary** (user inputs), tinted **Rechenweg** block, collapsible detail tables with emphasized total row, left-border disclaimer. **PDF/CSV** controls in the results card must match the canonical Arbeitstage button classes (PDF primary blue, CSV outline); see `.cursor/rules/tools-pages-patterns-export.mdc` and `docs/guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md` § *Results report layout*.

### Segmented Control Pattern

**Modern alternative to radio buttons and select dropdowns (2025 update):**

```css
.segmented-control {
  display: inline-flex;
  background: #f3f4f6;
  border-radius: 0.5rem;
  padding: 0.25rem;
  gap: 0.125rem;
  width: 100%; /* Full width for better alignment */
  box-sizing: border-box;
}

.segmented-control input[type="radio"] {
  display: none;
}

.segmented-control label {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 0.5rem 1rem; /* Increased for better touch targets */
  font-size: 0.875rem; /* Slightly larger for readability */
  font-weight: 500;
  color: #6b7280;
  background: transparent;
  border-radius: 0.375rem;
  cursor: pointer;
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
  white-space: nowrap;
  flex: 1; /* Equal width segments */
  min-width: 0;
}

.segmented-control input[type="radio"]:checked + label {
  background: white;
  color: #4d8ef3;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06); /* Enhanced shadow */
  font-weight: 600; /* Bolder for active state */
}

.segmented-control label:hover:not(:has(input:checked)) {
  color: #374151;
  background: rgba(77, 142, 243, 0.05); /* Subtle hover effect */
}
```

**Key Improvements (2025):**

- Full width (`width: 100%`) for proper alignment in form groups
- Equal width segments (`flex: 1`) for balanced appearance
- Increased padding (`0.5rem 1rem`) for better touch targets
- Enhanced shadow on active state for clearer indication
- Hover effect on inactive segments

**HTML Example:**

```html
<div class="segmented-control">
  <input type="radio" id="mode-1" name="mode" value="1" x-model="mode" />
  <label for="mode-1">Option 1</label>
  <input type="radio" id="mode-2" name="mode" value="2" x-model="mode" />
  <label for="mode-2">Option 2</label>
</div>
```

**When to Use:**

- 2-4 mutually exclusive options (VAT mode: Netto/Brutto, VAT rate: 19%/7%)
- Replacing select dropdowns with few options
- Replacing radio button groups for cleaner UI
- When all options should be visible simultaneously

### Control density & selection mode

Match the **task** to the control; avoid one oversized “card” pattern for every field (adds height and can imply the wrong selection model).

- **Mutually exclusive, 2 short options** (e.g. ja/nein, Pflichtversichert/nicht): prefer a **single compact row** (two button-style radios, `min-height` ~2.75rem) instead of stacked large cards.
- **Mutually exclusive, ~3–6 short labels** (e.g. Steuerklasse I–VI): **segmented grid** (small cells, clear `:checked` styling) or **select** if vertical space is tight.
- **3–5 options with longer text** (e.g. KV-Art): prefer **`<select>`** when saving vertical space matters; use visible radio cards only when scan-at-a-glance wins over height.
- **Long lists** (Bundesländer, etc.): **`<select>`** only.
- **Independent booleans** (each on/off): **not** a multi-select — use **separate switches or rows** and a **legend** that states they are **unabhängig** / **jeweils einzeln** so users do not confuse them with exclusive radio groups. Optional: “(eine Auswahl)” in the legend for true radio groups.
- **References:** [`v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php`](../../v2/includes/tools/kurzarbeitergeld-rechner/calculator-section.php) (compact segments, KV select, binary RV/ALV, switch rows); Mehrwertsteuer tool for full-width segmented/card patterns where density is less critical.

### Helper Sections Positioning

**Optimal Layout Order (2025 UX Redesign):**

1. **Hero Section** - Page title, description
2. **Tab Navigation** - Mode selection (always visible)
3. **Calculator Form** - Input fields
4. **Results Display** - Calculation output; for multi-step models (e.g. Kurzarbeitergeld), add a compact **Rechenweg** with real figures on-page and keep **PDF/CSV Kennzahlen** in parity with those headline numbers. If PDF/CSV are email-gated, do not hide the same core numeric story on-page (contrast: Arbeitstage-style blur for breakdown-only unlock).
5. **Quick Examples** - Pre-filled scenarios (collapsible, icon toggle)
6. **Calculation History** - Past calculations (collapsible, icon actions, conditional render)

**Rationale:**

- Primary flow: tabs → inputs → results
- Helper content (examples, history) below the fold
- Icon buttons for actions (not text) to save space
- Progressive disclosure (collapse/expand)

**Implementation:**

```html
<!-- After Results Display -->
<div class="mt-8 mb-6">
  <div class="bg-blue-50 border border-blue-200 rounded-lg p-4">
    <div class="flex items-center justify-between mb-3">
      <div class="flex items-center gap-2">
        <svg>...</svg>
        <h3 class="text-sm font-semibold text-gray-800">Schnellbeispiele</h3>
      </div>
      <button @click="showExamples = !showExamples" class="icon-btn">
        <svg>...</svg>
      </button>
    </div>
    <div x-show="showExamples" x-cloak x-transition>
      <!-- Examples grid -->
    </div>
  </div>
</div>

<div x-show="calculationHistory.length > 0" x-cloak x-transition class="mb-6">
  <div class="bg-gray-50 border border-gray-200 rounded-lg p-4">
    <div class="flex items-center justify-between mb-3">
      <div class="flex items-center gap-2">
        <svg>...</svg>
        <h3 class="text-sm font-semibold text-gray-800">Verlauf</h3>
        <span
          class="text-xs text-gray-500"
          x-text="'(' + calculationHistory.length + ')'"
        ></span>
      </div>
      <div class="flex items-center gap-1">
        <button @click="exportHistoryCSV()" class="icon-btn">...</button>
        <button @click="clearHistory()" class="icon-btn icon-btn-danger">
          ...
        </button>
        <button @click="showHistory = !showHistory" class="icon-btn">
          ...
        </button>
      </div>
    </div>
  </div>
</div>
```

### Input Micro-Interactions Pattern

**Focus States with Lift Effect:**

```css
.calculator-form input:focus,
.calculator-form select:focus {
  transform: translateY(-1px);
  box-shadow: 0 0 0 3px rgba(77, 142, 243, 0.1), 0 2px 4px rgba(0, 0, 0, 0.06);
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}
```

**Button Hover Effects:**

```css
.copy-btn:hover,
.example-btn:hover,
.history-item:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.12);
}

.copy-btn:active,
.example-btn:active,
.history-item:active {
  transform: translateY(0); /* Tactile press feedback */
}
```

### Progressive Disclosure Pattern

**Collapsible Sections with Count Badges:**

```html
<div class="flex items-center gap-2">
  <h3 class="text-sm font-semibold text-gray-800">Beispiele</h3>
  <span
    class="text-xs text-gray-500 bg-white px-2 py-0.5 rounded-full"
    x-text="getExamplesForMode(calculationMode).length + ' Beispiele'"
  ></span>
</div>
<button @click="showExamples = !showExamples" :aria-expanded="showExamples">
  <span x-show="!showExamples">Anzeigen</span>
  <span x-show="showExamples">Ausblenden</span>
</button>
```

**Conditional Rendering:**

```html
<!-- Only show history when it contains items -->
<div x-show="calculationHistory.length > 0" x-cloak class="mb-6">
  <!-- History content -->
</div>
```

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.
# tools-pages-documentation Full Instructions

## Parallel content workflows (blog / templates)

When pointing authors or agents at **long-form SEO content** elsewhere in the repo:

- **Blog posts:** Canonical working file `content-draft.html` → `update-post-content.php` → `v2/data/blog/posts/...json`. Do not edit post JSON body directly. See [BLOG_CONTENT_EDIT_WORKFLOW.md](../../docs/content/blog/BLOG_CONTENT_EDIT_WORKFLOW.md).
- **Template pages (blocks):** `template-data/{id}/content/content.md` → `sync-template-content-blocks.php` → `content-blocks.json`. See [TEMPLATE_CONTENT_EDIT_WORKFLOW.md](../../docs/systems/templates/TEMPLATE_CONTENT_EDIT_WORKFLOW.md).

Tools pages themselves are primarily **PHP + JS**; tool **documentation** lives under `docs/guides/tools-pages/` and should stay aligned with those edit-safe patterns when cross-linking or describing processes.

## Documentation Structure and Organization

### File Organization

**Core Documentation:**

- `README.md` - Main index and quick reference
- `TOOL_DOCUMENTATION_TEMPLATE.md` - Standardized template
- `TOOLS_INVENTORY.md` - Complete tool list
- `TOOLS_MAINTENANCE_GUIDE.md` - Annual update process
- `DOCUMENTATION_MAINTENANCE_PROCESS.md` - Documentation maintenance
- `DOCUMENTATION_STRUCTURE.md` - Structure guide

**Tool Documentation (17 files):**

- `*-documentation.md` - One comprehensive file per tool
- Follow standardized template
- Updated when code/content changes
- Updated annually for year references

**Consolidated Status Files:**

- `FINAL_STATUS_2026.md` - Overall project status
- `TESTING_SUMMARY_2026.md` - Testing status and plans
- `VERIFICATION_SUMMARY_2026.md` - Verification results
- `NEXT_STEPS_2026.md` - Next steps and action items

**Detailed Reference Files (Keep for Detail):**

- `COMPLETE_VERIFICATION_SUMMARY_2026.md` - Detailed verification
- `COMPREHENSIVE_TESTING_SUMMARY_2026.md` - Detailed testing
- `VALUE_VERIFICATION_RESULTS_2026.md` - Verification results
- `CODE_ANALYSIS_RESULTS.md` - Code analysis
- `TOOL_BY_TOOL_ANALYSIS.md` - Tool analysis

### File Naming Conventions

**Tool Documentation:**

- Pattern: `[tool-name]-documentation.md`
- Examples: `minijob-rechner-documentation.md`, `midijob-rechner-documentation.md`

**Consolidated Status Files:**

- Pattern: `[CATEGORY]_SUMMARY_2026.md` or `[CATEGORY]_STATUS_2026.md`
- Examples: `FINAL_STATUS_2026.md`, `TESTING_SUMMARY_2026.md`

**Detailed Reference Files:**

- Pattern: `[DESCRIPTIVE_NAME]_2026.md` or `[DESCRIPTIVE_NAME].md`
- Examples: `COMPLETE_VERIFICATION_SUMMARY_2026.md`

## Documentation Update Process

### When to Update Documentation

**Code Changes:**

- Constants change (legal values, rates, thresholds)
- Formulas change (calculation logic)
- Functions change (new features, bug fixes)
- Default values change
- Validation rules change

**Annual Updates:**

- January 1 (or when new year values announced)
- All year references (2025 → 2026, etc.)
- All legal values (rates, thresholds, limits)
- All example calculations
- All content sections (H1, descriptions, FAQs)

**Law Changes:**

- New laws announced
- Legal values change mid-year
- Regulations updated
- Official sources publish updates

### How to Update Documentation

**Step-by-Step Process:**

1. **Identify What Changed**

   - Read code changes
   - Identify affected values
   - Identify affected sections

2. **Read Tool Documentation**

   - Open tool-specific doc (`*-documentation.md`)
   - Review current state
   - Identify sections to update

3. **Update Relevant Sections**

   - Constants section (if values changed)
   - Calculation examples (if formulas changed)
   - Content sections (if text changed)
   - 2026 Update Requirements (mark complete)
   - Change log (add entry)

4. **Update Metadata**

   - Update "Last Updated" date
   - Update version history if major change

5. **Update Consolidated Files**

   - Update `FINAL_STATUS_2026.md` if status changes
   - Update `VERIFICATION_SUMMARY_2026.md` if values verified
   - Update `TESTING_SUMMARY_2026.md` if testing done

6. **Verify Updates**
   - Check all year references updated
   - Check all value references updated
   - Check no "(pending verification)" notes remain
   - Check change log entry added

### Which Files to Update

**Tool-Specific Changes:**

- Update only the affected tool doc (`*-documentation.md`)

**Multiple Tool Changes:**

- Update all affected tool docs
- Update consolidated status files

**Structural Changes:**

- Update `README.md`
- Update `TOOLS_MAINTENANCE_GUIDE.md`
- Update `TOOL_DOCUMENTATION_TEMPLATE.md`

**Status Changes:**

- Update `FINAL_STATUS_2026.md`
- Update `TESTING_SUMMARY_2026.md`
- Update `VERIFICATION_SUMMARY_2026.md`
- Update `NEXT_STEPS_2026.md`

## Tool Documentation Template Usage

### Template Structure

**Required Sections:**

1. Tool Overview (Basic Information, Purpose, Use Cases, Target Audience, Visual Description, UI/UX Flow)
2. Technical Documentation (File Structure, Code Organization, Calculation Modes, Constants, Validation, Edge Cases, Dependencies)
3. Functions & Methods (All functions documented with location, purpose, parameters, returns)
4. Formulas & Calculations (All formulas, legal basis, step-by-step examples)
5. Export Functionality (All export types, email gating)
6. Results & Insights (Result display, smart features)
7. Browser Testing Results (Desktop browsers, mobile, responsive design, accessibility)
8. Code Analysis (Key functions location, constants location, calculation logic flow)
9. Content Documentation (Hero section, educational content, FAQs, meta tags, schema, internal linking)
10. Change Log (Track all updates)
11. Annual Update Checklist (Embedded in each doc)
12. 2026 Update Requirements (What needs updating, when)
13. Version History (Track major changes)
14. Maintenance Notes (Ongoing maintenance requirements)
15. Testing (Test cases, browser testing, export testing)
16. References (Official sources, documentation files)

### Using the Template

**For New Tools:**

1. Copy `TOOL_DOCUMENTATION_TEMPLATE.md`
2. Rename to `[tool-name]-documentation.md`
3. Fill in all sections following template
4. Update "Last Updated" date
5. Add to README.md

**For Existing Tools:**

1. Read existing `*-documentation.md` file
2. Update relevant sections
3. Follow template structure
4. Update "Last Updated" date
5. Add change log entry

## Best Practices for Maintaining Documentation

### For Cursor AI Agents

**Always Read First:**

- Read tool documentation before making changes
- Read consolidated status files for current state
- Read README.md for structure overview

**Update Documentation When Code Changes:**

- Don't skip documentation updates
- Update "Last Updated" date
- Add change log entry

**Use Consolidated Files:**

- Don't create new status files
- Update existing consolidated files
- Reference detailed files when needed

**Follow Naming Conventions:**

- Use `*-documentation.md` for tool docs
- Use consolidated status files for status
- Use descriptive names for reference files

**Verify Before Completing:**

- Check all year references updated
- Check all value references updated
- Check no "(pending verification)" notes remain
- Check change log entry added

### For Human Maintainers

**Regular Reviews:**

- Quarterly: Check for law changes
- Annually: Comprehensive update

**Documentation First:**

- Update docs before major changes
- Keep docs in sync with code

**Consolidate, Don't Duplicate:**

- Update existing files
- Don't create duplicate status files

**Track Changes:**

- Use change logs
- Document sources
- Update dates

## Common Pitfalls

### ❌ Don't

- Update code without updating docs
- Create new status files instead of updating consolidated files
- Skip "Last Updated" date updates
- Leave "(pending verification)" notes in user-facing content
- Create duplicate documentation files
- Use generic file names

### ✅ Do

- Update docs when code changes
- Use consolidated status files
- Update "Last Updated" dates
- Remove verification notes from user content
- Update existing files, don't create duplicates
- Follow naming conventions

## Documentation Quality Standards

### Completeness

**Each Tool Doc Must Include:**

- All calculation modes documented
- All functions documented
- All formulas documented
- All export types documented
- All content sections documented
- All 2026 update requirements documented

### Accuracy

**All Documentation Must:**

- Match actual code implementation
- Use current values (2026)
- Have accurate examples
- Reference correct file paths
- Have valid legal references

### Consistency

**All Documentation Must:**

- Follow standardized template
- Use consistent terminology
- Use consistent formatting
- Use consistent naming conventions
- Have consistent structure

## References

- **Documentation Structure:** `docs/guides/tools-pages/DOCUMENTATION_STRUCTURE.md`
- **Documentation Maintenance Process:** `docs/guides/tools-pages/DOCUMENTATION_MAINTENANCE_PROCESS.md`
- **Tool Documentation Template:** `docs/guides/tools-pages/TOOL_DOCUMENTATION_TEMPLATE.md`
- **Maintenance Guide:** `docs/guides/tools-pages/TOOLS_MAINTENANCE_GUIDE.md`
- **README:** `docs/guides/tools-pages/README.md`


## Annual Update Patterns (2026+)

### Year Reference Updates

**CRITICAL:** All tools must be updated annually for new year:

1. **Meta Tags:**

   - Title: Update "2025" → "2026" (or current year)
   - Description: Update year references
   - Keywords: Update if year-specific

2. **Content:**

   - H1 headings: Update year references
   - Descriptions: Update year references
   - Help text: Update year references
   - Educational content: Update year references
   - FAQs: Review and update year references

3. **Constants:**
   - Update year in constant file comments
   - Update year in object names if applicable (e.g., `RATES_2025` → `RATES_2026`)
   - Update default values if changed

### Law Change Monitoring

**Annual Process (Q4):**

1. Monitor official sources for January 1 changes
2. Research confirmed values
3. Create update checklist
4. Execute updates in January
5. Test and validate

**Sources to Monitor:**

- Minijob-Zentrale: Minijob Grenze
- Bundesagentur für Arbeit: ALG 1, Midijob
- Bundesministerium für Arbeit und Soziales: Social security rates, BBG
- Bundesfinanzministerium: Tax constants

**See:** `docs/guides/tools-pages/TOOLS_MAINTENANCE_GUIDE.md` for complete process.

## Documentation Maintenance Requirements

### When to Update Tool Documentation

**Update Required When:**

- Code changes (constants, formulas, functions)
- Annual updates (year references, legal values)
- Law changes (mid-year updates)
- Content changes (FAQs, educational sections)

**Files to Update:**

- Tool-specific documentation (`*-documentation.md`)
- Update "Last Updated" date
- Update constants section
- Update example calculations
- Update content sections
- Add change log entry

### How to Reference Tool Documentation

**Before Making Changes:**

1. Read tool-specific documentation (`*-documentation.md`)
2. Read consolidated status files (`FINAL_STATUS_2026.md`, etc.)
3. Read README.md for structure overview

**When Making Changes:**

1. Update tool documentation file
2. Update "Last Updated" date
3. Add change log entry
4. Update consolidated status files if needed

**After Making Changes:**

1. Verify all year references updated
2. Verify all value references updated
3. Verify no "(pending verification)" notes remain
4. Verify change log entry added

### Documentation Update Checklist

**For Code Changes:**

- [ ] Read tool documentation file
- [ ] Update constants section (if values changed)
- [ ] Update calculation examples (if formulas changed)
- [ ] Update function documentation (if functions changed)
- [ ] Update "Last Updated" date
- [ ] Add change log entry

**For Annual Updates:**

- [ ] Update all year references (2025 → 2026)
- [ ] Update all legal values
- [ ] Update all example calculations
- [ ] Update content sections (H1, descriptions, FAQs)
- [ ] Update 2026 Update Requirements section (mark complete)
- [ ] Remove any "(pending verification)" notes
- [ ] Update "Last Updated" date
- [ ] Add change log entry

**For Status Updates:**

- [ ] Update consolidated status files (don't create new)
- [ ] Update FINAL_STATUS_2026.md if status changes
- [ ] Update TESTING_SUMMARY_2026.md if testing done
- [ ] Update VERIFICATION_SUMMARY_2026.md if values verified
- [ ] Update NEXT_STEPS_2026.md if next steps change

### File Naming Conventions

**✅ DO:**

- Update existing files
- Use consolidated status files (`FINAL_STATUS_2026.md`, etc.)
- Follow naming pattern: `*-documentation.md` for tool docs

**❌ DON'T:**

- Create new status files (consolidate instead)
- Create duplicate documentation files
- Use generic names like "status.md"

**See:** `docs/guides/tools-pages/DOCUMENTATION_MAINTENANCE_PROCESS.md` for complete process.

### Update Checklist Pattern

For each tool, verify:

- [ ] Constants updated (rates, thresholds, limits)
- [ ] Content updated (year references)
- [ ] Meta tags updated
- [ ] FAQs reviewed and updated
- [ ] Calculations tested with new values
- [ ] Documentation updated

**See:** `docs/guides/tools-pages/IMMEDIATE_UPDATES_CHECKLIST_2026.md` for complete checklist.

## Reference Documentation

For detailed workflows:

- `docs/guides/PAGE_TYPE_GUIDES.md` – Quick reference for tools pages
- `docs/ai/cursor-playbook.md` – Cursor-specific prompting patterns
- `docs/systems/shiftops/seo/SHIFTOPS_SEO_MONITORING_GUIDE.md` – SEO monitoring guide
- `scripts/test-shiftops-seo.py` – SEO testing script
- `docs/guides/tools-pages/TOOLS_MAINTENANCE_GUIDE.md` – Annual update process
- `docs/guides/tools-pages/IMMEDIATE_UPDATES_CHECKLIST_2026.md` – 2026 update checklist

For similar page types:

- Templates pages (templates-pages.mdc) – Similar export and form patterns
- Product pages (product-pages.mdc) – Similar CTA and conversion patterns

## Related Documentation

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../docs/ai/RULE_TO_DOC_MAPPING.md) for complete mapping.
# tools-pages-schema Full Instructions

## Schema Requirements (Tools-Specific)

### HowTo Schema

Required for all tools pages:

```json
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "[Tool Name: Action]",
  "description": "[What the tool does]",
  "totalTime": "PT2M",
  "step": [
    {
      "@type": "HowToStep",
      "name": "[Step 1 Name]",
      "text": "[Step 1 Description]",
      "url": "https://www.ordio.com/tools/[tool-slug]#step1"
    },
    {
      "@type": "HowToStep",
      "name": "[Step 2 Name]",
      "text": "[Step 2 Description]",
      "url": "https://www.ordio.com/tools/[tool-slug]#step2"
    }
  ]
}
```

**Typical steps:**

1. Enter input values
2. Review calculated results
3. Export or save results (optional)

### Standard Schemas

Also include (from global.mdc):

- WebPage schema
- BreadcrumbList schema


## Meta Tags (Tools-Specific)

### Title Pattern

```html
<title>[Tool Name] 2026: [Action] - Ordio</title>
```

Examples:

- "Arbeitstage-Rechner 2026: Arbeitstage berechnen - Ordio"
- "Kostenrechner 2026: Personalkosten berechnen - Ordio"

Include year (2026) for SEO relevance. **CRITICAL:** Update year annually (2026 → 2027, etc.).

### Description Pattern

```html
<meta
  name="description"
  content="[Tool] 2026: [Benefit/Action]. [What it calculates]. [Export option]. Kostenlos & ohne Anmeldung."
/>
```

155-160 characters, mention free/no-registration, export. **CRITICAL:** Update year annually.


## Validation Checklist (Tools-Specific)

Beyond global validation checklist:

- [ ] Calculator works with valid inputs (test multiple scenarios)
- [ ] Validation triggers on invalid inputs (visual feedback: red border)
- [ ] Real-time calculation updates correctly (debounced)
- [ ] Export functionality works (Excel, PDF, CSV as applicable)
- [ ] Excel export follows Ordio branding (no purple, proper widths, no header borders)
- [ ] Responsive layout works (desktop, tablet, mobile)
- [ ] Form inputs have consistent heights (3rem desktop, 3.5rem mobile)
- [ ] HowTo schema validates with correct steps
- [ ] Dotted background pattern present
- [ ] No console errors
- [ ] Edge cases handled (division by zero, negative values, empty inputs)

description: "ALG 1 Calculator specific patterns - Legal compliance, calculation logic, children impact, and testing requirements."
globs:
- v2/pages/tools_arbeitslosengeld_rechner.php
- tests/arbeitslosengeld_rechner*.py
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/ai/rules-archive/tools-pages-alg1-calculator-full.md
description: 'Tools/calculator page patterns - Content Blocks: SEO content block structure,
  keyword integration from SISTRIX, internal linking, concrete calculation examples, audience
  card expansion.'
globs:
- v2/pages/tools_*.php
alwaysApply: false
relatedRules:
- tools-pages-reference-seo.mdc
- tools-pages-faq.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/content/AI_CONTENT_AVOIDANCE_GUIDE.md
- docs/content/WEBSITE_PAGE_PUBLICATION_INDEX.md
- docs/systems/og-images/NEW_PAGE_OG_AND_SOCIAL_CHECKLIST.md
- docs/ai/rules-archive/tools-pages-content-blocks-full.md
description: 'Tools/calculator page patterns - Design System: Design tokens, form
  patterns, tab navigation, input patterns, and UI components.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-faq.mdc
- tools-pages-patterns-export.mdc
- tools-pages-patterns-gated.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- tools-pages-reference-seo.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/ai/rules-archive/tools-pages-core-design-full.md
description: 'Tools/calculator page patterns - Validation & Logic: Form validation
  patterns, calculation logic, result cards, and display patterns.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
description: 'Tools/calculator page patterns - Documentation: Documentation structure,
  maintenance process, template usage, and AI agent guidelines.'
globs:
- docs/guides/tools-pages/*.md
- docs/guides/tools-pages/*-documentation.md
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-seo.mdc
- tools-pages-faq.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/ai/rules-archive/tools-pages-documentation-full.md
description: "Elterngeld Calculator patterns - BEEG compliance, Ersatzrate, Geschwisterbonus, annual updates."
globs:
- v2/pages/tools_elterngeld_rechner.php
- v2/js/elterngeld/*.js
- tests/elterngeld_rechner*.py
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- tools-pages-patterns-gated.mdc
- tools-pages-patterns-export.mdc
- tools-pages-content-blocks.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/elterngeld-rechner-documentation.md
- docs/guides/tools-pages/testing/elterngeld-rechner/elterngeld-legal-research-2026.md
- docs/content/tools/elterngeld-rechner/COMPETITOR_ANALYSIS.md
- docs/content/tools/elterngeld-keywords.json
description: 'Tools/calculator page patterns - FAQ Optimization: FAQ structure requirements,
  schema patterns, internal linking guidelines, SEO/AEO/GEO best practices, and answer
  length recommendations.'
globs:
- v2/pages/tools_*.php
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-seo.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/content/FAQ_WEBSITE_STANDARD.md
- docs/content/FAQ_REWORK_DECISION_TREE.md
- docs/ai/rules-archive/tools-pages-faq-full.md
description: "Kurzarbeitergeld-Rechner — KUG math, shared payroll module, annual BA/BMAS review, disclaimers."
globs:
- v2/pages/tools_kurzarbeitergeld_rechner.php
- v2/includes/tools/kurzarbeitergeld-rechner/*.php
- v2/js/kurzarbeitergeld/*.js
- v2/js/shared/german-monthly-net-from-gross.js
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-reference-core.mdc
- shared-patterns.mdc
relatedDocs:
- docs/content/tools/kurzarbeitergeld-rechner/README.md
- docs/guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md
description: 'Tools/calculator page patterns - Export & Sharing: Excel/PDF export,
  clipboard, calculation history, and share functionality.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-patterns-gated.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/ai/rules-archive/tools-pages-patterns-export-full.md
description: 'Tools/calculator page patterns - Gated Content: Email collection patterns
  and Alpine.js integration for gated calculator features.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- lead-gen-forms-ux.mdc
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- tools-pages-patterns-export.mdc
- tools-pages-reference-core.mdc
- api-endpoints-core.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/guides/tools-pages/GATED_EXPORT_MODAL_SPEC.md
- docs/guides/tools-pages/GATED_FORMS_TROUBLESHOOTING.md
- docs/ai/rules-archive/tools-pages-patterns-gated-full.md
description: 'Tools/calculator page patterns - Reference Core: Alpine.js registration,
  holiday API integration, JavaScript extraction, and tab-based multi-mode calculators.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-reference-edge-cases.mdc
- tools-pages-reference-seo.mdc
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-schema.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/guides/tools-pages/HOLIDAY_API_INTEGRATION.md
- docs/systems/lead-capture/TRIGGER_CONFIGURATION.md
- docs/ai/rules-archive/tools-pages-reference-core-full.md
description: 'Tools/calculator page patterns - Reference Edge Cases: Common pitfalls,
  edge cases, gotchas, and troubleshooting patterns.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-reference-core.mdc
- tools-pages-reference-seo.mdc
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md

## Edge Cases & Gotchas

### Number Formatting

**German format:** 1.234,56 (not 1,234.56)

```javascript
function formatNumber(num) {
  return new Intl.NumberFormat("de-DE", {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }).format(num);
}
```

### Date Handling

**Use ISO format internally:** `2025-11-20` (ALWAYS check with `date +%Y-%m-%d`)  
**Display German format:** `15.01.2025` or `15. Januar 2025`

### State/Bundesland Holidays

Different states have different holidays:

- Bayern, Baden-Württemberg: More holidays (Heilige Drei Könige, Fronleichnam)
- Berlin, Brandenburg: Fewer holidays
- Use accurate holiday data per state

### Leap Years

Account for leap years in date calculations (2024, 2028, 2032 have 366 days).

description: 'Tools/calculator page patterns - Reference SEO: SEO optimization for
  thin content, annual update patterns, and documentation maintenance requirements.'
globs:
- v2/pages/tools_*.php
alwaysApply: false
relatedRules:
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- tools-pages-documentation.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/guides/tools-pages/TOOLS_MAINTENANCE_GUIDE.md
- docs/systems/shiftops/seo/SHIFTOPS_SEO_MONITORING_GUIDE.md
- docs/ai/rules-archive/tools-pages-reference-seo-full.md
description: Tools/calculator page patterns - Reference coordination file. This rule has been split into focused files. See relatedRules for specific topics.
globs:
  - v2/pages/tools_*.php
  - v2/css/tools-pages.css
alwaysApply: false
relatedRules:
  - tools-pages-reference-core.mdc
  - tools-pages-reference-seo.mdc
  - tools-pages-reference-edge-cases.mdc
  - tools-pages-core-design.mdc
  - tools-pages-core-validation.mdc
  - tools-pages-schema.mdc
  - tools-pages-faq.mdc
  - tools-pages-patterns-export.mdc
  - tools-pages-patterns-gated.mdc
  - tools-pages-documentation.mdc
  - shared-patterns.mdc
relatedDocs:
  - docs/guides/tools-pages/README.md
description: 'Tools/calculator page patterns - Schema & Styling: Schema requirements,
  CSS guidelines, meta tags, copy patterns, and Alpine.js registration.'
globs:
- v2/pages/tools_*.php
- v2/css/tools-pages.css
alwaysApply: false
relatedRules:
- tools-pages-core-design.mdc
- tools-pages-core-validation.mdc
- tools-pages-faq.mdc
- tools-pages-patterns-export.mdc
- tools-pages-patterns-gated.mdc
- tools-pages-reference-core.mdc
- tools-pages-reference-edge-cases.mdc
- tools-pages-reference-seo.mdc
- tools-pages-documentation.mdc
- shared-patterns.mdc
relatedDocs:
- docs/guides/tools-pages/README.md
- docs/ai/rules-archive/tools-pages-schema-full.md