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

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

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

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

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

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