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

Token	Light Mode	Dark Mode	Tailwind Class	Usage
Primary	`#1b7a95`	`#66c4e1`	`text-webcon-primary`	Links, primary buttons, active states
Primary Light	`#66c4e1`	`#9dd8eb`	`text-webcon-primary-light`	Hover states, accents
Primary 50	`#e8f4f8`	`#0f3d4a`	`bg-webcon-primary-50`	Light backgrounds
Primary 100	`#c5e4ed`	`#155d73`	`bg-webcon-primary-100`	Subtle backgrounds
Primary 200	`#9dd2e2`	`#1b7a95`	`bg-webcon-primary-200`	Borders, highlights
Primary 700	`#1b7a95`	`#66c4e1`	`text-webcon-primary-700`	Primary text
Primary 800	`#155d73`	`#9dd8eb`	`text-webcon-primary-800`	Strong emphasis
Primary 900	`#0f4555`	`#c5e8f2`	`text-webcon-primary-900`	Maximum contrast

Semantic State Colors

State	Color	Light BG	Border	Tailwind Prefix
Success	`#16a34a` / `#4ade80`	`#dcfce7` / `#14532d`	`#86efac` / `#22c55e`	`webcon-success`
Error	`#dc2626` / `#f87171`	`#fee2e2` / `#450a0a`	`#fca5a5` / `#ef4444`	`webcon-error`
Warning	`#d97706` / `#fbbf24`	`#fef3c7` / `#451a03`	`#fcd34d` / `#f59e0b`	`webcon-warning`
Info	`#1b7a95` / `#66c4e1`	`#e8f4f8` / `#0f3d4a`	`#66c4e1` / `#1b7a95`	`webcon-info`

Using Brand Colors

jsx

// 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

Element	Font Family	Weight	Usage
All Text	Hanken Grotesk	400-700	Body, headings, UI
Display	Hanken Grotesk (wide)	600, 700	Hero titles, emphasis
Code	System monospace	400	Code blocks, inline code

Font Configuration (Next.js):

typescript

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

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

CSS Variables:

css

--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):

jsx

<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:

jsx

<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

jsx

<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

jsx

<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

jsx

<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:

markdown

%%{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

Breakpoint	Width	Tailwind Prefix
Mobile	< 640px	(default)
Tablet	≥ 640px	`sm:`
Desktop	≥ 1024px	`lg:`
Wide	≥ 1280px	`xl:`

7. Component Spacing Scale

Use consistent spacing based on 4px grid:

Token	Value	Usage
`space-1`	4px	Icon gaps
`space-2`	8px	Inline elements
`space-4`	16px	Component padding
`space-6`	24px	Section gaps
`space-8`	32px	Major sections
`space-12`	48px	Page sections

8. Button Styles

Primary Button

html

<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

html

<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

html

<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:

Token	Light	Dark
`--webcon-primary`	`#1b7a95`	`#66c4e1`
`--webcon-success`	`#16a34a`	`#4ade80`
`--webcon-error`	`#dc2626`	`#f87171`
`--webcon-warning`	`#d97706`	`#fbbf24`

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:

shadcn Token	webconsulting Equivalent
`--background`	Light: white, Dark: neutral-950
`--foreground`	Light: neutral-950, Dark: white
`--primary`	`--webcon-primary`
`--destructive`	`--webcon-error`
`--muted`	Neutral grays
`--accent`	Light backgrounds
`--ring`	Focus ring color