docs-design

name	docs-design
description	Improve the visual design and UX of the VitePress docs site — layout, colors, typography, components, and responsiveness
license	MIT
metadata	{"audience":"designers","workflow":"docs"}

What I do

Analyze and improve the visual design, user experience, and polish of the openclaw-go documentation site built with VitePress.

When to use me

Use this skill when the docs site needs visual improvements, when adding new UI components, or when the site feels rough or inconsistent.

Design system

Brand colors

• Primary (amber): #f5a623
• Primary hover: #d4891e
• Primary deep: #b8730f
• Primary soft: rgba(245, 166, 35, 0.12)

Dark mode surfaces

• Background: #0d0d0f
• Soft background: #1a1a1f
• Mute background: #141418
• Alt background: #101013
• Border/divider: #2a2a35

Mascot

• File: docs-site/public/mascot-gpt.png — a Go gopher with lobster claws
• Used as: navbar logo (64x64px) and favicon
• Style: playful but professional

Key files to edit

File	What it controls
docs-site/.vitepress/theme/custom.css	All custom styles — colors, component overrides, dark mode
docs-site/.vitepress/theme/index.ts	Theme setup, layout component registration
docs-site/.vitepress/config.mts	Nav, sidebar, logo, footer, head meta
docs-site/index.md	Home page hero, feature cards, install block

Design principles

1. Dark-first — the site is primarily viewed in dark mode. Light mode should work but dark mode is the priority.
2. Readable code — code blocks need high contrast, clear syntax highlighting, and generous padding.
3. Amber accents — use the brand amber sparingly for links, active states, and interactive elements. Don't overwhelm with color.
4. Whitespace — generous spacing between sections. Don't crowd content.
5. Mobile-friendly — test at 375px width. Navigation, code blocks, and tables should be usable on mobile.

Improvement areas to consider

Homepage

• Hero section: gradient, tagline sizing, CTA button styling
• Feature cards: hover effects, icon sizing, card grid layout
• Install/quickstart section: code block styling, spacing

Navigation

• Logo sizing and alignment in the navbar
• Active state styling for nav items
• Sidebar width and item spacing
• Mobile hamburger menu behavior

Content pages

• Heading hierarchy and spacing
• Table styling (borders, padding, zebra striping)
• Inline code vs code block contrast
• Tip/warning/info callout boxes
• "On this page" ToC sidebar styling

Typography

• Font stack for body, headings, and code
• Line height and paragraph spacing
• Heading sizes and weight progression

Interactions

• Link hover states
• Button focus rings
• Smooth scroll behavior
• Page transition effects

Workflow

1. Assess current state — take screenshots, identify issues
2. Prioritize — fix broken/ugly things first, polish second
3. Edit CSS — make changes in custom.css
4. Build and preview:

   cd docs-site && npm run build && npm run preview
   

5. Compare — screenshot before/after
6. Test responsiveness — check at 375px, 768px, and 1440px widths
7. Test both themes — verify changes work in dark and light mode

Rules

• Stay within VitePress's theming system — override CSS variables and class selectors, don't fight the framework
• Keep custom CSS maintainable — comment sections, use the existing color variables
• Don't add JavaScript for purely visual effects — CSS-only where possible
• Test in both dark and light mode even though dark is primary