# Ordio Template Branding Guide

**Last Updated:** 2025-11-20

## Overview

This guide provides comprehensive branding guidelines for Excel template generation. All templates must adhere to Ordio brand standards to ensure consistency and professional appearance.

## Table of Contents

1. [Color Palette](#color-palette)
2. [Fonts](#fonts)
3. [Cell Style Presets](#cell-style-presets)
4. [Chart Color Palettes](#chart-color-palettes)
5. [Number Formats](#number-formats)
6. [Common Patterns](#common-patterns)
7. [Branding Violations to Avoid](#branding-violations-to-avoid)
8. [Validation](#validation)

## Color Palette

### Primary Colors

**Ordio Blue (Primary):**

- Hex: `#4D8EF3`
- Usage: Headers, primary actions, links, highlights
- RGB: RGB(77, 142, 243)

**Primary Hover:**

- Hex: `#3B82F6`
- Usage: Hover states for primary elements

**Primary Light:**

- Hex: `#EFF6FF`
- Usage: Light backgrounds, subtle highlights

### Text Colors

**Text Primary:**

- Hex: `#374151`
- Usage: Main text, headings
- RGB: RGB(55, 65, 81)

**Text Secondary:**

- Hex: `#6B7280`
- Usage: Secondary text, labels, captions
- RGB: RGB(107, 114, 128)

**Text Muted:**

- Hex: `#9CA3AF`
- Usage: Disabled text, placeholders
- RGB: RGB(156, 163, 175)

### Status Colors

**Success:**

- Hex: `#10B981`
- Usage: Success messages, positive indicators, compliance OK
- RGB: RGB(16, 185, 129)

**Warning:**

- Hex: `#F59E0B`
- Usage: Warnings, caution indicators, compliance warnings
- RGB: RGB(245, 158, 11)

**Error:**

- Hex: `#EF4444`
- Usage: Errors, negative indicators, compliance errors
- RGB: RGB(239, 68, 68)

### Background Colors

**Background:**

- Hex: `#FFFFFF`
- Usage: Main background, cell backgrounds

**Background Subtle:**

- Hex: `#F9FAFB`
- Usage: Alternating rows, subtle backgrounds

**Gray Scale:**

- `gray_100`: `#F5F5F5` - Lightest gray
- `gray_200`: `#E5E5E5` - Light gray
- `gray_300`: `#D4D4D4` - Medium light gray
- `gray_400`: `#A3A3A3` - Medium gray
- `gray_500`: `#737373` - Medium dark gray
- `gray_600`: `#525252` - Dark gray
- `gray_700`: `#404040` - Darker gray
- `gray_800`: `#262626` - Very dark gray
- `gray_900`: `#171717` - Darkest gray

### Border Colors

**Border:**

- Hex: `#D3D8DF`
- Usage: Cell borders, dividers

**Border Light:**

- Hex: `#E5E7EB`
- Usage: Subtle borders, separators

## Fonts

### Primary Fonts

**Inter (Body):**

- Usage: Body text, data cells, most content
- Sizes: 9pt (small), 11pt (body), 12pt (subtitle)
- Weight: Regular (400), Bold (700)

**Gilroy-Bold (Headings):**

- Usage: Titles, headings, dashboard headers
- Sizes: 14pt (heading), 16pt (dashboard header), 18pt (title), 24pt (large metrics)
- Weight: Bold (700) only

### Font Sizes

- **Title:** 18pt (Gilroy-Bold)
- **Heading:** 14pt (Gilroy-Bold)
- **Dashboard Header:** 16pt (Gilroy-Bold)
- **Body:** 11pt (Inter)
- **Subtitle:** 12pt (Inter)
- **Small:** 9pt (Inter)
- **Large Metric:** 24pt (Gilroy-Bold)

### Font Usage Rules

1. **Always use Inter for body text** - Never use Arial, Calibri, or other fonts
2. **Always use Gilroy-Bold for headings** - Never use Inter Bold for headings
3. **Never mix fonts** - Use consistent font families throughout
4. **Respect font sizes** - Use standard sizes from presets

## Cell Style Presets

### Header Styles

**`header`:**

- Blue background (`#4D8EF3`)
- White text (`#FFFFFF`)
- Bold, centered
- No borders (cleaner look)
- Usage: Column headers, table headers

**`header_light`:**

- Light gray background (`#F5F5F5`)
- Dark text (`#374151`)
- Bold, left-aligned
- No borders
- Usage: Subtle headers, section headers

**`dashboard_header`:**

- White background
- Dark text (`#374151`)
- Gilroy-Bold, 16pt
- Bottom border (blue, medium)
- Usage: Dashboard sheet headers

### Data Styles

**`data_cell`:**

- White background
- Dark text (`#374151`)
- Regular weight, left-aligned
- Bottom border (thin, gray)
- Usage: Data entry cells, regular cells

**`formula_cell`:**

- Subtle background (`#F9FAFB`)
- Dark text (`#374151`)
- Regular weight, right-aligned
- Bottom border (thin, gray)
- Usage: Calculated cells, formula results

**`input_cell`:**

- White background
- Dark text (`#374151`)
- Regular weight, left-aligned
- All borders (thin, gray)
- Usage: User input cells

**`locked_cell`:**

- Subtle background (`#F9FAFB`)
- Muted text (`#6B7280`)
- Regular weight, left-aligned
- Protected (locked)
- Usage: Protected formula cells, read-only cells

### Special Styles

**`title`:**

- White background
- Dark text (`#374151`)
- Gilroy-Bold, 18pt
- Left-aligned
- Usage: Sheet titles, main headings

**`subtitle`:**

- White background
- Secondary text (`#6B7280`)
- Inter, 12pt
- Left-aligned
- Usage: Subtitles, descriptions

**`highlight`:**

- Light blue background (`#EFF6FF`)
- Blue text (`#4D8EF3`)
- Bold
- Blue border (thin)
- Usage: Important cells, highlights

**`metric_cell`:**

- White background
- Blue text (`#4D8EF3`)
- Inter, 14pt, bold
- Right-aligned
- Usage: Key metrics, summary values

**`metric_cell_large`:**

- White background
- Blue text (`#4D8EF3`)
- Gilroy-Bold, 24pt
- Right-aligned
- Usage: Large dashboard metrics

**`total_row`:**

- Light gray background (`#F5F5F5`)
- Dark text (`#374151`)
- Bold, right-aligned
- Top border (medium, blue)
- Bottom border (thin, gray)
- Usage: Total rows, summary rows

### Status Styles

**`success_cell`:**

- Light green background (`#ECFDF5`)
- Green text (`#10B981`)
- Bold, centered
- Green border (thin)
- Usage: Success indicators, compliance OK

**`warning_cell`:**

- Light yellow background (`#FFFBEB`)
- Orange text (`#F59E0B`)
- Regular weight, centered
- Usage: Warnings, caution indicators

**`error_cell`:**

- Light red background (`#FEF2F2`)
- Red text (`#EF4444`)
- Regular weight, centered
- Usage: Errors, negative indicators

**`compliance_ok`:**

- Light green background (`#ECFDF5`)
- Green text (`#10B981`)
- Bold, centered
- Green border (thin)
- Usage: Compliance status OK

**`compliance_warning`:**

- Light yellow background (`#FFFBEB`)
- Orange text (`#F59E0B`)
- Bold, centered
- Orange border (thin)
- Usage: Compliance warnings

**`compliance_error`:**

- Light red background (`#FEF2F2`)
- Red text (`#EF4444`)
- Bold, centered
- Red border (thin)
- Usage: Compliance errors

### Other Styles

**`section_header`:**

- Subtle background (`#F9FAFB`)
- Dark text (`#374151`)
- Inter, 12pt, bold
- Bottom border (thin, gray)
- Usage: Section headers

**`section_divider`:**

- Subtle background (`#F9FAFB`)
- Secondary text (`#6B7280`)
- Inter, 11pt
- Top and bottom borders (thin, gray)
- Usage: Section dividers, separators

**`note_cell`:**

- White background
- Secondary text (`#6B7280`)
- Inter, 10pt, italic
- Left-aligned, top-aligned
- Usage: Notes, comments

**`note_cell_highlighted`:**

- Light yellow background (`#FFFBEB`)
- Dark text (`#374151`)
- Inter, 10pt, italic, bold
- Orange border (thin)
- Usage: Important notes, warnings

**`info_cell`:**

- Light blue background (`#F0F9FF`)
- Secondary text (`#6B7280`)
- Inter, 11pt
- Left border (medium, blue)
- Usage: Information boxes, tips

**`chart_title`:**

- White background
- Dark text (`#374151`)
- Gilroy-Bold, 14pt
- Left-aligned
- Usage: Chart titles

**`data_label`:**

- White background
- Secondary text (`#6B7280`)
- Inter, 10pt
- Centered
- Usage: Data labels, axis labels

**`footer_cell`:**

- Subtle background (`#F9FAFB`)
- Muted text (`#9CA3AF`)
- Inter, 9pt, italic
- Top border (thin, light gray)
- Usage: Footer information, metadata

## Chart Color Palettes

### Available Palettes

**`default`:**

- Ordio Blue, Success Green, Warning Orange, Error Red, Purple, Cyan, Orange, Lime
- Usage: General charts, most visualizations

**`professional`:**

- Blue gradient (5 shades of blue)
- Usage: Professional reports, corporate dashboards

**`status`:**

- Success Green, Warning Orange, Error Red, Neutral Gray
- Usage: Status indicators, compliance charts

**`monochrome`:**

- Gray scale (5 shades)
- Usage: Print-friendly charts, grayscale displays

**`categorical`:**

- 10 distinct colors for categories
- Usage: Multi-category charts, pie charts

**`gradient_blue`:**

- Blue gradient (7 shades)
- Usage: Single-color charts, heat maps

### Chart Color Usage Rules

1. **Use `professional` for business charts** - Most common choice
2. **Use `status` for compliance/status charts** - Clear visual meaning
3. **Use `monochrome` for print** - Better for black & white printing
4. **Use `categorical` for multi-series** - Distinct colors for clarity
5. **Never use custom colors** - Always use predefined palettes

## Number Formats

### Currency Formats

- **`currency`:** `#,##0.00 €` - Standard currency (e.g., 1.234,56 €)
- **`currency_int`:** `#,##0 €` - Integer currency (e.g., 1.234 €)
- **`currency_compact`:** `#,##0.0"k" €` - Compact currency (e.g., 1,2k €)

### Percentage Formats

- **`percentage`:** `0.00%` - Standard percentage (e.g., 12,34%)
- **`percentage_int`:** `0%` - Integer percentage (e.g., 12%)
- **`percentage_compact`:** `0.0%` - Compact percentage (e.g., 12,3%)

### Date Formats

- **`date`:** `TT.MM.JJJJ` - Standard date (e.g., 20.11.2025)
- **`date_short`:** `TT.MM.JJ` - Short date (e.g., 20.11.25)
- **`date_long`:** `TTTT, TT. MMMM JJJJ` - Long date (e.g., Donnerstag, 20. November 2025)

### Time Formats

- **`time`:** `HH:MM` - Standard time (e.g., 14:30)
- **`time_seconds`:** `HH:MM:SS` - Time with seconds (e.g., 14:30:45)

### DateTime Formats

- **`datetime`:** `TT.MM.JJJJ HH:MM` - Date and time (e.g., 20.11.2025 14:30)
- **`datetime_seconds`:** `TT.MM.JJJJ HH:MM:SS` - Date and time with seconds

### Number Formats

- **`number`:** `#,##0.00` - Standard number (e.g., 1.234,56)
- **`number_compact`:** `#,##0.0` - Compact number (e.g., 1.234,5)
- **`integer`:** `#,##0` - Integer (e.g., 1.234)

### Special Formats

- **`hours`:** `[h]:mm` - Hours format (e.g., 40:30)
- **`hours_decimal`:** `#,##0.00"h"` - Decimal hours (e.g., 40,50h)
- **`minutes`:** `mm` - Minutes only
- **`phone`:** `000 0000000` - Phone number format
- **`postal_code`:** `00000` - Postal code format

## Common Patterns

### Dashboard Layout

```json
{
  "cells": [
    {
      "address": "A1",
      "value": "Dashboard Titel",
      "style": { "preset": "dashboard_header" }
    },
    {
      "address": "B3",
      "value": "=SUMME(A:A)",
      "style": { "preset": "metric_cell_large" },
      "format": "currency"
    }
  ]
}
```

### Compliance Status

```json
{
  "cells": [
    {
      "address": "A2",
      "value": "Compliance Status",
      "style": { "preset": "header_light" }
    },
    {
      "address": "B2",
      "value": "=WENN(ComplianceCheck=\"OK\";\"OK\";\"Fehler\")",
      "style": { "preset": "compliance_ok" }
    }
  ]
}
```

### Section Divider

```json
{
  "cells": [
    {
      "address": "A5",
      "value": "",
      "style": { "preset": "section_divider" }
    }
  ]
}
```

### Chart with Title

```json
{
  "cells": [
    {
      "address": "D2",
      "value": "Umsatz pro Monat",
      "style": { "preset": "chart_title" }
    }
  ],
  "charts": [
    {
      "type": "bar",
      "title": "Umsatz pro Monat",
      "position": { "cell": "D3" },
      "color_palette": "professional"
    }
  ]
}
```

## Branding Violations to Avoid

### ❌ Don't Do This

1. **Custom Colors:**

   ```json
   // ❌ BAD
   {"fill": {"color": "#FF0000"}}  // Red not in palette

   // ✅ GOOD
   {"style": {"preset": "error_cell"}}  // Uses preset
   ```

2. **Wrong Fonts:**

   ```json
   // ❌ BAD
   {"font": {"name": "Arial"}}

   // ✅ GOOD
   {"font": {"name": "Inter"}}
   ```

3. **Non-Standard Sizes:**

   ```json
   // ❌ BAD
   {"font": {"size": 13}}  // Not in standard sizes

   // ✅ GOOD
   {"style": {"preset": "heading"}}  // Uses preset with standard size
   ```

4. **Custom Chart Colors:**

   ```json
   // ❌ BAD
   {"charts": [{"style": {"colors": ["#FF0000", "#00FF00"]}}]}

   // ✅ GOOD
   {"charts": [{"color_palette": "professional"}]}
   ```

5. **Inconsistent Styles:**

   ```json
   // ❌ BAD - Mixing custom styles
   {"font": {"color": "#000000"}, "fill": {"color": "#FFFFFF"}}

   // ✅ GOOD - Using presets
   {"style": {"preset": "data_cell"}}
   ```

## Validation

### Automatic Validation

The branding validator automatically checks:

1. **Color Usage:** Only Ordio brand colors allowed
2. **Font Usage:** Only Inter and Gilroy-Bold allowed
3. **Font Sizes:** Standard sizes recommended
4. **Style Presets:** Valid preset names only
5. **Chart Palettes:** Valid palette names only

### Validation Commands

**CLI Validation:**

```bash
php v2/systems/excel-template-generator/scripts/validate-branding.php template.json
php v2/systems/excel-template-generator/scripts/validate-branding.php template.json --json
php v2/systems/excel-template-generator/scripts/validate-branding.php template.json --verbose
```

**Integrated Validation:**

```bash
php v2/systems/excel-template-generator/scripts/template-validator.php template.json
```

### Validation Score

Branding compliance is scored 0-100:

- **100:** Perfect compliance
- **90-99:** Minor warnings
- **80-89:** Some warnings
- **<80:** Errors present

### Fixing Violations

1. **Replace custom colors with presets**
2. **Use standard fonts (Inter/Gilroy-Bold)**
3. **Use preset styles instead of custom styles**
4. **Use predefined chart palettes**
5. **Follow common patterns**

## Best Practices

1. **Always use presets** - Don't create custom styles
2. **Be consistent** - Use same presets for same purposes
3. **Follow patterns** - Use common patterns from examples
4. **Validate early** - Run validation during development
5. **Document exceptions** - If custom style needed, document why

## Reference

- **Branding Config:** `v2/systems/excel-template-generator/config/template-branding.php`
- **Validator:** `v2/systems/excel-template-generator/helpers/template-branding-validator.php`
- **CLI Tool:** `v2/systems/excel-template-generator/scripts/validate-branding.php`
- **Examples:** See `v2/systems/excel-template-generator/data/template-definitions/examples/`