prompts/docs/skills/zensical-docs/references/theme-customization-and-icons.md

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

• 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.

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: 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.