| name | github-pages-visual-system |
| description | Design or refine the visual system of a GitHub Pages documentation site, repository website, wiki, or project landing page. Use for Pages-specific CSS tokens, color and dark themes, typography, reading measure, spacing, grids, hierarchy, responsive behavior, and repository branding. Do not use for generic product design systems, native mobile UI, or non-Pages websites. |
GitHub Pages Visual System
Create a coherent, lightweight visual layer that supports repository content and survives static hosting constraints.
Stay inside the Pages boundary
- Inspect the existing site stack, theme, CSS, assets, screenshots, logos, and documented branding before changing visual direction.
- Preserve a healthy framework-native theme and its accessible behavior. Prefer small token and component overrides over a replacement design system.
- Design for documentation, project explanation, code, tables, and navigation—not for an imaginary application dashboard.
- Keep remote fonts, trackers, scripts, and asset hosts out unless explicitly authorized and reviewed for privacy, reliability, and integrity.
- Treat exact colors, typefaces, and breakpoints as repository decisions. Do not copy illustrative values as universal requirements.
- Leave route generation, base-path configuration, framework migration, and deployment ownership with
create-github-pages. If visual work exposes a defect in one of those areas, report and hand it off instead of silently changing it.
Read the contract
Read references/pages-visual-contract.md before creating or materially changing the Pages visual system.
Produce an implementable system
Define only the tokens and rules the site actually uses:
- semantic colors for background, surface, text, border, action, focus, code, and status;
- type roles for body, headings, labels, and code;
- spacing, content width, grid, and radius scales;
- light, dark, and high-contrast behavior when supported;
- responsive rules driven by real content failure points;
- hierarchy for home, documentation, navigation, cards, callouts, and CTAs;
- asset and branding reuse decisions.
Implement these through the selected framework's supported theme layer or maintainable CSS variables. Avoid unused token catalogs.
Verify the result
- Render representative home, documentation, reference, and not-found pages at desktop and narrow mobile widths.
- Run the production build and preview it under the expected Pages base path; confirm representative routes still resolve after theme changes.
- Check contrast, visible focus, keyboard states, zoom, reduced motion, overflow, code, tables, images, and navigation.
- Test real repository content rather than placeholder copy.
- Verify that light and dark variants preserve semantic roles instead of merely inverting colors.
- Report browser or accessibility checks that could not be performed; source inspection is not rendered verification.
