feat: redesign shared documentation theme

[Marvelousmicheal]

Overview

This PR refreshes @xberg-io/docs-theme into a polished, reusable documentation system aligned with the Kreuzberg Cloud visual identity.

The redesign preserves the existing Astro Starlight architecture and public configuration API. It focuses on presentation, responsive behavior, accessibility, and consistency without introducing another framework or additional runtime dependencies.

What changed

Brand system

• Replaced the previous typography with Geist and Geist Mono.
• Introduced the shared cream, dark-purple, cyan, purple, red, yellow, and neutral color tokens.
• Standardized typography, spacing, borders, components, and semantic colors.
• Updated the navbar to use the shared xberg application icon and product title.
• Added subtle branded halftone textures to the landing page.
• Preserved support for both light and dark themes.

Landing page

• Rebuilt the landing page with a product-focused hero and clearer visual hierarchy.
• Added branded gradient text and background artwork.
• Added feature, workflow, proof-point, and call-to-action sections.
• Improved narrow-screen typography and prevented awkward word wrapping.
• Preserved the original navigation destinations and documentation structure.

Documentation pages

• Reduced and refined the left sidebar.
• Improved article width, spacing, typography, headings, lists, and inline code.
• Redesigned the desktop table of contents.
• Improved the responsive “On this page” dropdown.
• Removed redundant hover-only heading-link icons.
• Added compact, directionally aligned previous/next navigation.

Component styling

• Redesigned tables with full-width headers, clearer column hierarchy, and internal mobile scrolling.
• Redesigned code blocks with a branded language header and persistent copy action.
• Improved note and admonition components:
  • Tips use the brand cyan.
  • Cautions use the brand yellow.
  • Danger notices use the brand red.
  • Standard notes retain the purple accent.
• Kept component borders neutral for visual consistency.

Header and mobile navigation

• Added GitHub, Discord, and Reddit links to the default social navigation.
• Improved the search control and removed unnecessary theme-switcher hover effects.
• Fixed overlap between the mobile search and hamburger controls.
• Standardized both controls to matching 40×40px transparent bordered buttons.
• Matched and centered the search and hamburger icons.
• Fixed clipping of the search dialog’s Cancel button.

Documentation and API accuracy

• Updated the README to reflect the new design system and default social links.
• Corrected stale Exo 2 references.
• Updated TypeScript documentation for component override precedence.
• Preserved consumer precedence for custom CSS, components, and head entries.

Architecture and compatibility

This remains a lightweight Astro Starlight theme:

• Compatible with Astro 7 and Starlight 0.41+.
• Preserves the existing xbergStarlightConfig() API.
• Remains statically generated.
• Adds no runtime package dependencies.
• Ships Astro, CSS, JavaScript configuration, and type-definition source directly.
• Continues loading versioned brand assets from the shared xberg CDN.

The npm package remains small:

• Approximately 11.5 KB compressed.
• Approximately 43 KB unpacked.
• Seven published files.
• Zero bundled dependencies.

Responsive coverage

The landing page, Introduction page, and Components demo were audited at:

• 320px
• 390px
• 768px
• 1024px
• 1280px

Tables and code blocks scroll internally on narrow screens without creating page-level horizontal overflow.

Verification

The following checks pass:

• Production Astro build
• git diff --check
• Package configuration smoke test
• Public API and consumer-override regression test
• Light and dark theme audit
• Desktop, tablet, and mobile breakpoint audit
• Mobile menu open/close test
• Search dialog and Cancel-button test
• Theme-switcher test
• Code-copy control verification
• Browser console error audit
• Heading and image accessibility checks

Result

The theme now provides a cohesive documentation experience across xberg products while remaining static, lightweight, configurable, and fully aligned with Astro Starlight.