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 topic tabs (e.g., “Public site” vs “Editor guide”); for TYPO3, this collection targets v14 only:

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

Data & Comparison Tables

Use ComparisonTable for feature matrices. Supports boolean checkmarks:

<ComparisonTable 
  headers={['Feature', 'TYPO3 v14']}
  rows={[
    { label: 'Content Blocks 2.x', values: [true] },
    { label: 'Symfony 7.2', values: [true] },
    { label: 'PHP 8.2+', values: [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

Source: https://github.com/dirnbauer/webconsulting-skills