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 relevant references

• Read references/pages-visual-contract.md before creating or materially changing the Pages visual system.
• Read references/design-direction-and-redesign.md before choosing a direction or extending or redesigning an existing visual layer.
• Read references/pages-design-directions.md when the brief needs direction exploration. Extract supplied branding first; do not impose a new style on a bounded extension.
• Read references/design-critique.md for a requested composition critique and before delivering material visual changes. Inspect only the patterns relevant to the site.

Establish the visual direction

Before defining tokens, state a compact design brief: audience and reader task, existing evidence, visual language, change mode, and concrete choices for compositional variation, motion, information density, asset dependence, and brand fidelity. Explain how these choices affect the site; avoid decorative scores.

Classify existing-site work as Extension, Preserve, or Overhaul and name the visual and behavioral contracts that survive. Choose the smallest mode that fulfills the request. Keep content hierarchy ownership with github-pages-content-architecture and full rendered auditing with audit-github-pages-ux.

When direction is unresolved, present only materially different, repository-grounded options and recommend one. Show how each differs in composition, typography, density, assets, and reader benefit; recoloring the same layout is not direction exploration. An established brand or explicit user choice can supply the direction directly.

For a material new direction, show a representative preview early using real headings, technical content, and available assets. Follow the preview and authorization rules in the direction reference. Do not add confirmation gates to already authorized work. Temporary asset slots belong only in a clearly labelled preview; resolve or remove them before delivery.

Produce an implementable system

Define only the tokens and rules the site actually uses:

1. semantic colors for background, surface, text, border, action, focus, code, and status;
2. type roles for body, headings, labels, and code;
3. spacing, content width, grid, and radius scales;
4. light, dark, and high-contrast behavior when supported;
5. responsive rules driven by real content failure points;
6. hierarchy for home, documentation, navigation, cards, callouts, and CTAs;
7. 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.
• Review composition and visual coherence against the stated direction; report what to preserve, consequential fixes, and any supported opportunities separately from functional or accessibility defects.
• Report browser or accessibility checks that could not be performed; source inspection is not rendered verification.