| 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
- Dark-first — the site is primarily viewed in dark mode. Light mode should work but dark mode is the priority.
- Readable code — code blocks need high contrast, clear syntax highlighting, and generous padding.
- Amber accents — use the brand amber sparingly for links, active states, and interactive elements. Don't overwhelm with color.
- Whitespace — generous spacing between sections. Don't crowd content.
- 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
- Assess current state — take screenshots, identify issues
- Prioritize — fix broken/ugly things first, polish second
- Edit CSS — make changes in
custom.css
- Build and preview:
cd docs-site && npm run build && npm run preview
- Compare — screenshot before/after
- Test responsiveness — check at 375px, 768px, and 1440px widths
- 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
