better

2026-06-18 22:34:31 -05:00
parent a4db33531e
commit 1254cc5432
5 changed files with 149 additions and 1 deletions
@@ -0,0 +1,60 @@
+# 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.