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