# Firmennamen Generator - Tool Documentation

**Last Updated:** 2026-03-04

Complete documentation for the Firmennamen Generator tool.

## Tool Overview

### Basic Information

- **Tool Name:** Firmennamen Generator
- **Slug:** firmennamen-generator
- **URL:** `https://www.ordio.com/tools/firmennamen-generator`
- **Status:** Available
- **Last Updated:** 2026-03-04

### Purpose

The Firmennamen Generator helps users generate creative German company name suggestions based on industry, style preferences, optional keywords, and business description. It uses AI (Gemini API) to create unique, memorable company names with explanations. The tool is designed for entrepreneurs, startups, freelancers, and businesses looking to rebrand or create new product lines.

### Recent Improvements (2026-03-04)

- **Business Description Field**: Added optional textarea (300 chars) matching competitor patterns (Qonto, Squarespace, Canva, Logopony)
- **Improved Keyword Handling**: Smart parsing of multiple keywords (2-5 optimal), automatic prioritization, warnings for >5 keywords
- **Quality Scoring**: Names are automatically scored and filtered for quality (length, brandability, relevance)
- **Performance Optimization**: Optimized prompts (~33% reduction), faster model options (Flash-Lite), response caching
- **Enhanced UX**: Character counters, keyword count display, example inputs button, tooltips, progress indicators

### Use Cases

- Startup founders seeking a memorable company name
- Freelancers establishing their brand identity
- Existing businesses rebranding or launching new product lines
- Entrepreneurs exploring name options before company registration
- Marketing agencies helping clients with naming strategies

### Key Features (2026-03-04 Update)

- **Business Description Field**: Optional textarea (300 chars) for detailed business context - matches competitor patterns (Qonto, Squarespace, Canva)
- **Improved Keyword Handling**: Smart parsing of multiple keywords (2-5 optimal), automatic prioritization
- **Quality Scoring**: Names are scored and filtered for quality (length, brandability, relevance)
- **Performance Optimization**: Optimized prompts, faster model options, response caching
- **Enhanced UX**: Character counters, keyword warnings, example inputs, tooltips

### Target Audience

- **Primary:** Entrepreneurs, startup founders, freelancers
- **Secondary:** Existing business owners, marketing professionals, branding consultants
- **Tertiary:** Students, hobbyists exploring business ideas

## Competitor Analysis & Improvements

### Competitor Research (2026-03-04)

**Competitors Analyzed:**
- Qonto (`qonto.com/de/tools/company-name-generator`)
- Squarespace (`de.squarespace.com/tools/business-name-generator`)
- Canva (`canva.com/de_de/firmennamen-generator/`)
- Logopony (`logopony.de/name-generator/`)

**Key Findings:**

1. **Input Patterns:**
   - All competitors use single textarea for business description (80-400 chars)
   - Character counters are standard
   - No structured fields (industry dropdown, style selection) in competitors
   - Focus on natural language description

2. **Our Advantages:**
   - Structured inputs (industry, style) improve AI prompts
   - Can combine structured + descriptive for best results
   - More control with style selection and keyword options

3. **Improvements Implemented:**
   - Added business description textarea (300 chars) matching competitor pattern
   - Added character counters for all text inputs
   - Improved keyword handling (2-5 optimal, warnings for >5)
   - Enhanced UX with tooltips, examples, progress indicators

### Visual Description

**Hero Section:**

- Layout: Centered hero with gradient background blur effect
- Headline: Large H1 with blue accent color: "KI-Firmennamen Generator 2026: Kreative Namen mit künstlicher Intelligenz"
- Description: Subtitle explaining the tool's purpose with KI emphasis
- Badge/CTA: Trust indicators (100% kostenlos, Ohne Anmeldung, DSGVO-konform)

**Calculator Form:**

- Layout: Max-width container with centered form
- Styling: White background, rounded borders, shadow effects
- Form elements:
  - Industry dropdown (required) with 13 options (with tooltip explaining purpose)
  - Style radio buttons (4 options: Modern, Klassisch, Kreativ, Professionell) (with tooltip)
  - **Business description textarea** (optional, 300 characters max, with character counter) - **NEW**
    - Placeholder: "z.B. Ein nachhaltiges Café mit lokalen Produkten und modernem Ambiente..."
    - Helper text: "Beschreibe dein Unternehmen in wenigen Sätzen"
    - Character counter: "X / 300"
  - Keywords input (optional, 100 characters max, with keyword count and warning for >5 keywords)
    - Keyword count display: "X Keywords"
    - Warning when >5 keywords: "⚠️ Tipp: Verwende 2-5 Keywords für beste Ergebnisse"
    - Border color changes to yellow when >5 keywords
  - Count slider (1-10 names)
  - Example button: "📝 Beispiel-Eingaben anzeigen" (loads random example)
  - Generate button with loading state and progress bar
  - Keywords text input (optional, max 100 characters)
  - Count slider (1-10 names)
  - Generate button (blue, disabled when industry not selected)
- Responsive behavior: Grid adapts from 2 columns (mobile) to 4 columns (desktop) for style selection

**Result Display:**

- Layout: Grid layout (1 column mobile, 2 columns desktop)
- Cards/Sections: Each name displayed in a card with:
  - Company name (large, bold)
  - Explanation text (smaller, gray)
  - Copy button (icon + text)
- Typography: Inter font family, various sizes and weights
- Visualizations: None (text-based results)

### UI/UX Flow

**Initial Load:**

- Form displays with default values:
  - Industry: Empty (required selection)
  - Style: "modern" (default)
  - Keywords: Empty
  - Count: 10 (default)
- Generate button is disabled until industry is selected
- No results displayed initially

**User Interaction Flow:**

1. User selects industry from dropdown
2. User optionally selects style (defaults to "modern")
3. User optionally enters keywords
4. User adjusts count slider (1-10 names)
5. User clicks "Namen generieren" button
6. Loading state displays with spinner
7. API call made to `/v2/api/generate-company-names.php`
8. Results displayed in grid layout below form
9. Page scrolls smoothly to results section
10. User can copy individual names or export all as CSV

**Error Handling Flow:**

- Validation errors: Displayed in red box above form
- API errors: Displayed in red box with user-friendly message
- Network errors: Generic error message displayed
- Copy failures: Error message displayed, fallback to manual copy

## Technical Documentation

### File Structure

- **PHP File:** `v2/pages/tools_firmennamen_generator.php` (~1656 lines)
- **JavaScript Files:** Inline Alpine.js component in PHP file
- **CSS:** Uses shared `v2/css/tools-pages.min.css`
- **API Endpoint:** `v2/api/generate-company-names.php`

### Calculation Modes

**Single Mode: Name Generation**

- **Visual Description:** Form-based interface with dropdown, radio buttons, text input, and slider
- **Purpose:** Generate creative German company names using AI
- **Input Fields:**
  - Industry (select, required): 13 options (Technologie, Gastronomie, Handwerk, etc.)
  - Style (radio, optional): 4 options (modern, klassisch, kreativ, professionell), defaults to "modern"
  - Keywords (text, optional): Max 100 characters, comma-separated keywords
  - Count (range slider, optional): 1-10 names, defaults to 5
- **Output Fields:**
  - Names array: Each name object contains:
    - `name`: Company name string
    - `explanation`: Short explanation (1 sentence)
  - Results displayed in grid cards
  - Copy buttons for individual names
  - Export CSV button for all names
- **Formula:** AI-based generation using Gemini API (`gemini-2.5-flash` model)
- **Calculation Steps:**
  1. Validate industry selection (required)
  2. Sanitize inputs (industry, style, keywords, count)
  3. Build prompt with industry, style, keywords, count
  4. Call Gemini API with retry logic (3 attempts, exponential backoff)
  5. Parse JSON response
  6. Validate response structure
  7. Return array of name objects
- **Example:**
  - Input: Industry="Technologie", Style="modern", Keywords="innovativ, digital", Count=5
  - Calculation: API generates 5 names matching criteria
  - Output: Array of 5 name objects with explanations
- **Edge Cases:** 
  - Missing industry: Validation error displayed
  - API failure: Retry logic (3 attempts), then error message
  - Invalid response: Error message displayed
  - Empty results: Error message displayed

### Constants and Thresholds

**2026 Values:**

- Count range: 1-10 names (min: 1, max: 10, default: 5)
- Keywords max length: 100 characters
- API retry attempts: 3
- API retry delays: [3, 6, 12] seconds (exponential backoff)
- API timeout: 60 seconds

### Validation Rules

- Industry: Required, must be one of 13 predefined options
- Style: Optional, defaults to "modern" if invalid, must be one of: modern, klassisch, kreativ, professionell
- Keywords: Optional, max 100 characters, sanitized with htmlspecialchars
- Count: Optional, clamped between 1-10, defaults to 5

### Edge Cases Handled

- Missing industry: Client-side validation shows error, form submission prevented
- Invalid style: Defaults to "modern" on server side
- Count out of range: Clamped to 1-10 on server side
- API timeout: Retry logic with exponential backoff
- Network errors: User-friendly error message displayed
- Empty API response: Error message displayed
- Invalid JSON response: Error message displayed
- Copy API failure: Fallback to document.execCommand

### Dependencies

- External Libraries:
  - Alpine.js (via CDN): For reactive UI components
  - AOS (Animate On Scroll): For scroll animations
- APIs:
  - Gemini API (`gemini-2.5-flash`): For name generation
- Alpine.js: Version loaded from CDN, used for form state management

### Code Organization

**File Structure:**

- PHP: `v2/pages/tools_firmennamen_generator.php` (~1656 lines)
- JavaScript: Inline in PHP file (lines 172-366)
- CSS: `v2/css/tools-pages.min.css` (shared across tools)
- API: `v2/api/generate-company-names.php` (~245 lines)

**Code Patterns:**

- Alpine.js component pattern: `firmennamenGenerator()` function returns state object
- Async/await pattern: Used for API calls and clipboard operations
- Error handling: Try-catch blocks with user-friendly messages
- Retry logic: Exponential backoff for API failures

### Functions & Methods

**Main Component Function:**

- Function Name: `firmennamenGenerator()`
- Location: `v2/pages/tools_firmennamen_generator.php:173-352`
- Purpose: Alpine.js component managing form state and name generation
- Returns: State object with data and methods

**API Functions:**

- `generateNames()`: Async function that calls API endpoint, handles response, displays results
  - Location: `v2/pages/tools_firmennamen_generator.php:211-260`
  - Parameters: None (uses component state)
  - Returns: None (updates component state)
  - Error handling: Try-catch with user-friendly error messages

**Copy Functions:**

- `copyName(index)`: Copies individual name to clipboard
  - Location: `v2/pages/tools_firmennamen_generator.php:263-295`
  - Parameters: `index` (number) - index of name to copy
  - Returns: None (updates `copiedIndex` state)
  - Fallback: Uses `document.execCommand` for older browsers

- `copyAllNames()`: Copies all names to clipboard (newline-separated)
  - Location: `v2/pages/tools_firmennamen_generator.php:297-326`
  - Parameters: None
  - Returns: None (updates `copiedIndex` to -1)
  - Fallback: Uses `document.execCommand` for older browsers

**Export Functions:**

- `exportCSV()`: Exports all names to CSV file
  - Location: `v2/pages/tools_firmennamen_generator.php:328-345`
  - Parameters: None
  - Returns: None (triggers file download)
  - Format: CSV with BOM, UTF-8 encoding, columns: Firmenname, Erklärung
  - File name: `firmennamen_YYYY-MM-DD.csv`

**Utility Functions:**

- `reset()`: Resets form state (names, error, copiedIndex)
  - Location: `v2/pages/tools_firmennamen_generator.php:347-351`
  - Parameters: None
  - Returns: None

### State Management

**Alpine.js State Variables:**

- `industry`: String, purpose: Selected industry, initial value: ''
- `style`: String, purpose: Selected style, initial value: 'modern'
- `keywords`: String, purpose: Optional keywords, initial value: ''
- `count`: Number, purpose: Number of names to generate, initial value: 10
- `names`: Array, purpose: Generated names, initial value: []
- `loading`: Boolean, purpose: API request in progress, initial value: false
- `error`: String|null, purpose: Error message, initial value: null
- `copiedIndex`: Number|null, purpose: Index of copied name (-1 for all), initial value: null
- `industryOptions`: Array, purpose: Available industries, static array
- `styleOptions`: Array, purpose: Available styles with labels, static array

**Computed Properties:**

- None (all values are direct state variables)

**Watchers:**

- None (reactive updates handled by Alpine.js automatically)

**localStorage:**

- None (no persistence implemented)

**URL Parameters:**

- None (no URL parameter parsing implemented)

## Calculation Logic

### Formula Documentation

**Primary Formula:**

```
Names = GeminiAPI.generate({
  industry: selectedIndustry,
  style: selectedStyle,
  keywords: optionalKeywords,
  count: selectedCount
})
```

**Step-by-Step Process:**

1. User selects industry (required)
2. User optionally selects style (defaults to "modern")
3. User optionally enters keywords
4. User adjusts count slider (1-10)
5. User clicks generate button
6. Client validates industry selection
7. Client sends POST request to `/v2/api/generate-company-names.php`
8. Server validates and sanitizes inputs
9. Server builds prompt for Gemini API
10. Server calls Gemini API with retry logic (3 attempts)
11. Server parses JSON response
12. Server validates response structure
13. Server returns JSON array of names
14. Client displays results in grid layout
15. Page scrolls to results section

### Example Calculation

**Input:**

- Industry: "Technologie"
- Style: "modern"
- Keywords: "innovativ, digital"
- Count: 5

**Calculation:**

```
API Request:
POST /v2/api/generate-company-names.php
{
  "industry": "Technologie",
  "style": "modern",
  "keywords": "innovativ, digital",
  "count": 5
}

API Response:
{
  "success": true,
  "names": [
    {
      "name": "Nexiom Digital",
      "explanation": "Kombiniert 'next' mit innovativem Klang..."
    },
    ...
  ],
  "count": 5
}
```

**Expected Result:**

- Array of 5 name objects displayed in grid
- Each name has copy button
- Export CSV button available
- Results scroll into view

### Legal Basis

- **Markenrecht:** Names should be checked for trademark availability at DPMA (Deutsches Patent- und Markenamt)
- **Firmenrecht:** Company name registration requirements vary by legal form (GmbH, UG, etc.)
- **Disclaimer:** Generated names are suggestions and should be legally verified before use

## Content Documentation

### Hero Section

- **H1:** "Firmennamen Generator 2026: Kreative Namen für dein Unternehmen"
- **Description:** "Generiere kostenlos passende Firmennamen für deine Branche. Mit Erklärungen, Markenrechts-Check & Export. Ohne Anmeldung."

### Educational Content Sections

1. **So funktioniert der Firmennamen-Generator**
   - Explains how the tool works
   - Step-by-step guide
   - Tips for best results

2. **Was macht einen guten Firmennamen aus?**
   - Branchenrelevanz
   - Einprägsamkeit und Aussprache
   - Rechtliche Aspekte
   - Markenrecht und Markenanmeldung

3. **Für wen ist der Generator geeignet?**
   - Gründer
   - Existenzgründer
   - Weitere Zielgruppen

4. **Tipps für die Namensfindung**
   - Tipp 1: Branchenrelevanz
   - Tipp 2: Einprägsamkeit
   - Tipp 3: Rechtliche Prüfung
   - Tipp 4: Internationale Aussprache

5. **Weitere kostenlose Tools für deine Unternehmensgründung**
   - Related tools and resources
   - Links to other Ordio tools

6. **Starte noch heute deine kostenlose Probe-Website**
   - CTA section
   - Related services

### FAQ Section

- **Total FAQs:** 15
- **FAQ Topics:**
  - Tool functionality: 5 FAQs
  - Name generation: 4 FAQs
  - Legal aspects: 3 FAQs
  - Usage tips: 3 FAQs

**Sample FAQs:**

1. Wie funktioniert der Firmennamen Generator?
   - Explains the generation process and AI usage

2. Ist der Generator kostenlos?
   - Confirms free usage, no registration required

3. Kann ich die generierten Namen verwenden?
   - Explains legal verification requirements

### Meta Tags

- **Title:** "Firmennamen Generator 2026: Kreative Namen für dein Unternehmen - Ordio"
- **Description:** "Firmennamen Generator 2026: Generiere kostenlos passende Firmennamen für deine Branche. Mit Erklärungen, Markenrechts-Check & Export. Ohne Anmeldung."
- **Keywords:** firmennamen generator, unternehmensname generator, firmenname erstellen, etc.

### Schema Markup

- **WebPage schema:** Yes (includes name, description, URL)
- **FAQPage schema:** Yes (15 FAQs)
- **HowTo schema:** Yes (step-by-step instructions)
- **BreadcrumbList schema:** Yes (navigation breadcrumbs)

### Internal Linking

- Links to: Related tools, blog posts, product pages
- Link count: 12 internal links

## Change Log

### Update History

**2026-03-04:**

- Initial tool creation
- Implemented Gemini API integration
- Created Alpine.js component
- Added 15 FAQs
- Added 6 content sections (~4862 words)
- Implemented CSV export functionality
- Added copy-to-clipboard functionality
- Performance optimizations (async CSS loading)

## Annual Update Checklist

**For Annual Updates (typically January):**

- [ ] Update "Last Updated" date
- [ ] Update year references in content (2026 → 2027)
- [ ] Update meta tags if needed
- [ ] Review and update FAQs if needed
- [ ] Verify all legal references are current
- [ ] Test API integration still works
- [ ] Update schema markup if needed
- [ ] Document changes in change log

## 2026 Update Requirements

### Immediate Updates (Completed)

**Constants/Values:**

- ✅ Count range: 1-10 names
- ✅ Keywords max length: 100 characters
- ✅ API retry logic: 3 attempts with exponential backoff

**Content:**

- ✅ Updated year references: "2026"
- ✅ Updated meta tags
- ✅ Created 15 FAQs

**Priority:** High (Completed)

### Throughout 2026 Updates

**Scheduled Updates:**

- Monitor API usage and costs
- Review generated name quality
- Collect user feedback

### Monitoring Requirements

- **Gemini API:** Monitor usage, costs, rate limits
- **User feedback:** Collect feedback on name quality
- **Performance:** Monitor page load times, API response times

## Testing

### Test Cases

**Normal Cases:**

- Test 1: Generate names with all fields filled → Expected: 10 names generated
- Test 2: Generate names with only industry → Expected: 10 names generated with default style
- Test 3: Generate names with industry and keywords → Expected: Names include keyword concepts
- Test 4: Copy individual name → Expected: Name copied to clipboard
- Test 5: Copy all names → Expected: All names copied (newline-separated)
- Test 6: Export CSV → Expected: CSV file downloaded with all names

**Edge Cases:**

- Edge case 1: Missing industry → Expected: Validation error displayed
- Edge case 2: API timeout → Expected: Retry logic activates, then error message
- Edge case 3: Empty API response → Expected: Error message displayed
- Edge case 4: Invalid JSON response → Expected: Error message displayed
- Edge case 5: Copy API failure → Expected: Fallback to document.execCommand

### Code Analysis

**Key Functions Location:**

- Main component: `v2/pages/tools_firmennamen_generator.php:173-352`
- API call function: `v2/pages/tools_firmennamen_generator.php:211-260`
- Copy functions: `v2/pages/tools_firmennamen_generator.php:263-326`
- Export function: `v2/pages/tools_firmennamen_generator.php:328-345`

**Constants Location:**

- Industry options: `v2/pages/tools_firmennamen_generator.php:188-202`
- Style options: `v2/pages/tools_firmennamen_generator.php:204-209`
- Default values: `v2/pages/tools_firmennamen_generator.php:176-179`

**Calculation Logic Flow:**

1. User interaction triggers `generateNames()`
2. Client-side validation checks industry
3. POST request sent to API endpoint
4. Server validates and sanitizes inputs
5. Server calls Gemini API with retry logic
6. Server parses and validates response
7. Client receives JSON response
8. Results displayed in grid layout
9. Page scrolls to results

**State Management Flow:**

- Initialization: State initialized with default values
- Updates: Alpine.js reactivity updates UI automatically
- Dependencies: Form inputs trigger API call, results trigger display

**Event Handler Flow:**

- Form submit: Prevents default, calls `generateNames()`
- Copy button click: Calls `copyName(index)` or `copyAllNames()`
- Export button click: Calls `exportCSV()`

### Export Functionality

**CSV Export:**

- **Trigger:** Click "CSV Export" button
- **Email Gating:** None (no email required)
- **Data Included:**
  - Firmenname (company name)
  - Erklärung (explanation)
- **Format:** CSV with BOM, UTF-8 encoding, comma-delimited, quoted fields
- **File Name:** `firmennamen_YYYY-MM-DD.csv`
- **Function:** `exportCSV()` at `v2/pages/tools_firmennamen_generator.php:328-345`

**Email Gating Process:**

- **When Required:** Never (no email gating)
- **Modal Display:** N/A
- **Email Validation:** N/A
- **Storage:** N/A
- **Pre-filling:** N/A
- **Error Handling:** N/A

### Sharing Functionality

**Share URL Generation:**

- **Function:** Not implemented
- **Parameters Included:** N/A
- **URL Format:** N/A
- **Encoding:** N/A

**Shareable Parameters:**

- None (sharing not implemented)

**Share Restoration:**

- **Function:** Not implemented
- **Process:** N/A
- **State Restoration:** N/A

**Social Sharing:**

- **Platforms:** Not implemented
- **Share Content:** N/A
- **Implementation:** N/A

### Results & Insights

**Result Display:**

- **Primary Results:** Generated company names with explanations
- **Secondary Results:** None
- **Result Formatting:** 
  - Names: Large, bold text
  - Explanations: Smaller, gray text
- **Result Styling:** Cards with borders, shadows, hover effects

**Result Breakdowns:**

- None (simple list display)

**Visualizations:**

- **Chart Type:** None
- **Chart Library:** N/A
- **Chart Data:** N/A
- **Chart Styling:** N/A

**Insights Provided:**

- Name explanations: Each name includes a brief explanation
- No additional insights or recommendations

### Browser Testing Results

**Desktop Browsers:**

- **Chrome:** To be tested
- **Firefox:** To be tested
- **Safari:** To be tested
- **Edge:** To be tested

**Mobile Testing:**

- **iOS Safari:** To be tested
- **Android Chrome:** To be tested
- **Mobile UI Differences:** Form adapts to single column, style buttons stack vertically
- **Mobile Interactions:** Touch-friendly buttons, responsive form elements

**Responsive Design:**

- **Desktop (>1024px):** 4-column style grid, 2-column results grid
- **Tablet (768px-1024px):** 2-column style grid, 2-column results grid
- **Mobile (<768px):** Single column for all elements
- **Breakpoints:** Uses Tailwind CSS breakpoints (sm, md, lg)

**Accessibility:**

- **Keyboard Navigation:** All form elements keyboard accessible
- **Screen Reader:** Semantic HTML, ARIA labels on form elements
- **ARIA Labels:** Labels associated with inputs via `for` attribute
- **Focus Management:** Focus states visible, logical tab order
- **Color Contrast:** Meets WCAG AA standards

**Performance:**

- **Page Load Time:** To be measured
- **Calculation Speed:** Depends on Gemini API response time (~2-5 seconds)
- **Export Speed:** Instant (client-side generation)
- **Large Data Handling:** Handles up to 10 names per request efficiently

### Export Testing

- CSV: Implemented, tested with various name counts
- PDF: Not implemented
- Excel: Not implemented

## Maintenance Notes

### Known Issues

- None currently identified

### Future Improvements

- Add PDF export functionality
- Add Excel export functionality
- Implement URL sharing with parameters
- Add name favorites/bookmarking
- Add name history (localStorage)
- Add more industry options
- Add name availability checking (DPMA integration)
- Add logo generation suggestions

### Related Tools

- Other Ordio tools: Related tools for business setup
- Blog posts: Articles about company naming, branding

## References

### Official Sources

- **DPMA (Deutsches Patent- und Markenamt):** https://www.dpma.de
- **Gemini API Documentation:** https://ai.google.dev/docs

### Documentation Files

- **Content Outline:** `docs/content/tools/firmennamen-generator/CONTENT_OUTLINE.md`
- **SERP Analysis:** `docs/content/tools/firmennamen-generator/SERP_ANALYSIS.md`
- **Performance Testing:** `docs/content/tools/firmennamen-generator/PERFORMANCE_TESTING.md`
- **API Documentation:** `docs/content/tools/firmennamen-generator/FIRMENNAMEN_GENERATOR_API.md` (to be created)