webconsulting Design System

1. Brand Identity & Voice

Persona: Innovative, Technical, Professional ("Senior Solutions Architect")

Tone: Clear, concise, authoritative. Avoid marketing fluff.

Language: German (Primary) / English (Technical documentation)

2. Visual Design Tokens (Strict Adherence)

Brand Color Palette

Semantic State Colors

Using Brand Colors

// Primary button
<button className="bg-webcon-primary text-white hover:bg-webcon-primary-800">
  Action
</button>

// Info callout
<div className="bg-webcon-info-light border border-webcon-info-border text-webcon-info">
  Information message
</div>

// Success state
<div className="bg-webcon-success-light border border-webcon-success-border">
  <CheckIcon className="text-webcon-success" />
</div>

Typography

Font Configuration (Next.js):

import { Hanken_Grotesk } from 'next/font/google'

const hankenGrotesk = Hanken_Grotesk({
  subsets: ['latin'],
  variable: '--font-hanken-grotesk',
  display: 'swap',
})

CSS Variables:

--font-sans: var(--font-hanken-grotesk), ui-sans-serif, system-ui, sans-serif;
--font-display: var(--font-hanken-grotesk), ui-sans-serif, system-ui, sans-serif;
--font-display--font-variation-settings: 'wdth' 125;

3. MDX Component Architecture

When generating content or frontend components, use the following structure. Do NOT use raw HTML.

Interactive Tabs

Use for version comparisons (e.g., TYPO3 v11 vs v12 vs v13 vs v14):

<Tabs defaultValue="v14">
  <TabsList>
    <TabsTrigger value="v13">TYPO3 v13</TabsTrigger>
    <TabsTrigger value="v14">TYPO3 v14</TabsTrigger>
  </TabsList>
  <TabsContent value="v13">
    Content for v13...
  </TabsContent>
  <TabsContent value="v14">
    Content for v14 (preferred)...
  </TabsContent>
</Tabs>

Data & Comparison Tables

Use ComparisonTable for feature matrices. Supports boolean checkmarks:

<ComparisonTable 
  headers={['Feature', 'v13', 'v14']}
  rows={[
    { label: 'Content Blocks', values: [true, true] },
    { label: 'Symfony 7', values: [false, true] },
    { label: 'PHP 8.2+', values: [true, true] }
  ]} 
/>

Code Blocks with Syntax Highlighting

<CodeBlock 
  language="php" 
  filename="Classes/Controller/PageController.php"
  highlightLines={[3, 7]}
>
{`<?php
declare(strict_types=1);

namespace Vendor\\Extension\\Controller;

use Psr\\Http\\Message\\ResponseInterface;
use TYPO3\\CMS\\Extbase\\Mvc\\Controller\\ActionController;

final class PageController extends ActionController
{
    public function indexAction(): ResponseInterface
    {
        return $this->htmlResponse();
    }
}`}
</CodeBlock>

Callout Boxes

<Callout type="info" title="Best Practice">
  Always use `declare(strict_types=1);` in PHP files.
</Callout>

<Callout type="warning" title="Breaking Change">
  This API changed in TYPO3 v14.
</Callout>

<Callout type="danger" title="Security">
  Never expose sensitive configuration files.
</Callout>

MDX Images

<MDXImage 
  src="/images/architecture-diagram.png" 
  alt="TYPO3 Extension Architecture"
  caption="Figure 1: Domain-Driven Design in TYPO3 Extensions"
/>

4. Mermaid Diagrams (Theming)

All diagrams must explicitly override the theme to match the webconsulting palette:

%%{init: {'theme': 'base', 'themeVariables': { 
  'primaryColor': '#1b7a95', 
  'primaryTextColor': '#ffffff',
  'primaryBorderColor': '#155d73',
  'lineColor': '#404040',
  'secondaryColor': '#d97706',
  'tertiaryColor': '#fef3c7',
  'edgeLabelBackground': '#ffffff'
}}}%%
graph TD
    A[Client Request] -->|HTTP| B(Load Balancer)
    B --> C{TYPO3 Backend}
    C -->|Cache Hit| D[Response]
    C -->|Cache Miss| E[Database]
    E --> D

CSS enhancements (automatically applied via base.css):

• Nodes have 10px border-radius for modern look
• 2px stroke width for better definition
• White text with shadow on mindmap nodes
• Cluster/subgraph backgrounds use light gray (#f0f0f0)

5. Accessibility Guidelines (WCAG 2.1 AA)

Contrast Requirements

• Ensure 4.5:1 contrast ratio for all text
• Large text (18px+ bold, 24px+ regular): 3:1 minimum

Interactive Elements

• All interactive elements must have visible focus states
• Use ring: focus:ring-2 focus:ring-webcon-primary focus:ring-offset-2
• Outline for scrollable regions: outline: 2px solid #1B7A95

Images and Media

• All images MUST include alt text
• Use caption prop in MDXImage component
• Decorative images: use alt=""

Keyboard Navigation

• All interactive elements must be keyboard accessible
• Logical tab order (no positive tabindex)
• Skip links for main content (styled with dark background, white text)

6. Responsive Breakpoints

7. Component Spacing Scale

Use consistent spacing based on 4px grid:

8. Button Styles

Primary Button

<button class="bg-webcon-primary hover:bg-webcon-primary-800 text-white font-medium px-6 py-3 rounded-lg transition-colors focus:ring-2 focus:ring-webcon-primary focus:ring-offset-2">
  Primary Action
</button>

Secondary Button

<button class="border-2 border-webcon-primary text-webcon-primary hover:bg-webcon-primary-50 font-medium px-6 py-3 rounded-lg transition-colors">
  Secondary Action
</button>

Ghost Button

<button class="text-muted-foreground hover:text-webcon-primary hover:bg-muted px-4 py-2 rounded transition-colors">
  Ghost Action
</button>

9. Dark Mode Support

The design system supports automatic dark mode via the .dark class. All webcon-* colors automatically invert:

Usage: Apply dark class to a parent element (usually <html>) to enable dark mode.

10. shadcn/ui Integration

The design system is compatible with shadcn/ui components. Semantic tokens map to shadcn conventions: