Vellocs uses a flexible color system that lets you customize your site's appearance by editing simple color values in config.json.
How Colors Work
Instead of setting colors individually throughout your site, Vellocs uses color tokens (also called design tokens). Think of them like variables:
Change the value once in config.json, and it updates everywhere on your site automatically.
Quick Start
The fastest way to customize your site is to change the accent color:
This single color controls:
- Link colors
- Button backgrounds
- Active tab indicators
- Hover states
- Primary highlights
Start Simple
For most sites, just changing the accent color is enough! The other colors have sensible defaults.
Color Format
All colors must be in hex format:
All Color Tokens
Here are all the color tokens you can customize:
Background & Foreground
Main page background color. This is what users see behind all content.
Main text color. Used for paragraphs, headings, and most text content. Ensure good contrast with background for readability.
Cards & Popovers
Background color for card components and elevated surfaces. Should be slightly lighter/darker than background to create depth.
Text color on card backgrounds. Usually the same as foreground.
Brand Colors
Primary brand color. Used for primary buttons, active navigation items, and important highlights.
Text color on primary backgrounds (like button text). Must have good contrast with primary.
Accent color for links, hover states, and interactive elements. This is your brand color! Used for all links, code highlighting, interactive element highlights, and selected/active states.
Secondary & Muted
Background for muted/subtle elements like code block backgrounds, subtle backgrounds, and disabled states.
Text color for secondary/less important text like captions, helper text, timestamps, and labels.
Borders & Inputs
Color for borders, dividers, and separators. Should be subtle - not too dark, not too light.
Focus ring color (the outline that appears when you tab to an element). Should be visible against both light and dark backgrounds for accessibility.
Destructive/Error
Color for errors, warnings, and destructive actions. Use red tones to indicate danger/errors.
Example Color Schemes
Indigo/Purple (Default)
Green/Emerald
Blue/Cyan
Orange/Amber
Dark Mode
By default, Vellocs uses dark mode. The color values you set in config.json are for dark mode.
Theme Switching
Configure theme behavior in the appearance section:
Default theme when user first visits. Options: "dark", "light", or "system" (use system preference).
If true, disables theme switching - users are locked to the default theme.
Light Mode Colors
Currently, Vellocs is optimized for dark mode. Light mode uses automatic color inversion. Full light mode customization is coming in a future update.
Testing Your Colors
After changing colors in config.json:
- Save the file
- Check your browser - changes apply immediately in dev mode
- Test contrast - Make sure text is readable
- Check all components - Look at buttons, links, code blocks, alerts
- Test different pages - Colors should work everywhere
Troubleshooting
Best Practices
Just change accent first. See how it looks, then adjust others if needed.
Start Simple
Always check that text is readable against backgrounds. Use webaim.org/resources/contrastchecker
Test Contrast
Use colors from your brand guidelines. Don't pick random colors.
Stay Consistent
You don't need to customize every color. Defaults work great!
Less is More
Next Steps
Typography
Configure fonts for your documentation
Banner
Add announcement banners
Navigation
Set up your site navigation