John Lancaster
63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# Theme Customization, Colors, and Icons
|
|
|
|
Use this reference when you want documentation that feels intentional and brand-aligned while preserving readability and accessibility.
|
|
|
|
## Start from the Scaffold
|
|
|
|
Always start new projects with `uv run zensical new` so the baseline theme/config scaffolding is in place before customization.
|
|
|
|
## Customization Strategy
|
|
|
|
1. Configure theme and feature flags in the project config first.
|
|
2. Apply visual tokens (colors, spacing, typography) in a shared CSS layer.
|
|
3. Add icons and logo assets with consistent naming.
|
|
4. Use template overrides only when config/CSS cannot solve the requirement.
|
|
|
|
## Key Zensical Customization Surfaces
|
|
|
|
!!! info "Zensical sources"
|
|
- [Customization overview](https://zensical.org/docs/customization/)
|
|
- [Additional CSS](https://zensical.org/docs/customization/#additional-css)
|
|
- [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
|
|
- [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
|
|
- [Logo and icons setup](https://zensical.org/docs/setup/logo-and-icons/)
|
|
|
|
## Colors and Accessibility
|
|
|
|
- Define color variables once and reuse them for semantic roles (primary, surface, muted, success, warning).
|
|
- Keep contrast high for body text, code blocks, and nav labels.
|
|
- Test color changes on mobile and desktop, including search highlights and active nav states.
|
|
|
|
!!! info "General references"
|
|
- [Material Design color guidance](https://m3.material.io/styles/color)
|
|
- [WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/)
|
|
|
|
## Icons: Selection and Search Landing Pages
|
|
|
|
If your theme supports icon sets through your docs stack, these search portals are useful:
|
|
|
|
- [Material Symbols search](https://fonts.google.com/icons)
|
|
- [Font Awesome icons search](https://fontawesome.com/search)
|
|
- [Simple Icons search](https://simpleicons.org/)
|
|
- [Iconify icon set search](https://icon-sets.iconify.design/)
|
|
- [Lucide icons](https://lucide.dev/icons/)
|
|
|
|
!!! tip "Icon family consistency"
|
|
Pick one primary icon family for navigation and status icons, then document naming conventions.
|
|
|
|
## Extending the Theme Safely
|
|
|
|
Use overrides as a last step, not the first.
|
|
|
|
1. Confirm the requirement cannot be solved by config and CSS.
|
|
2. Keep override templates minimal and focused.
|
|
3. Track upstream changes if you override partials.
|
|
4. Add a visual regression checklist for common pages.
|
|
|
|
## Review Checklist
|
|
|
|
- Theme changes preserve readability for long-form docs.
|
|
- Icons are consistent in weight/style and meaningful in context.
|
|
- Color changes do not break code-block syntax highlighting or search visibility.
|
|
- Overrides are documented with rationale and owner.
|