ValentinNikolaev/agent-skills / agent-plugins/skills/github-pages-design
github-pages-design
VerifiedDesign or refine GitHub Pages direction, composition, tokens, themes, and responsive styling. Use for Pages visual work and critique, not generic product design or a full rendered UX audit.
| File | Kind | Size |
|---|---|---|
| LICENSE.avoid-ai-design | other | 1.0 KB |
| LICENSE.designer-skills | other | 1.0 KB |
| LICENSE.garden-skills | other | 1.0 KB |
| LICENSE.hallmark | other | 1.1 KB |
| LICENSE.impeccable | other | 10.5 KB |
| LICENSE.interface-design | other | 1.0 KB |
| LICENSE.taste-skill | other | 1.0 KB |
| NOTICE.impeccable | other | 503 B |
| SKILL.md | skill md | 5.6 KB |
| agents/openai.yaml | config | 227 B |
| references/design-critique.md | markdown | 5.7 KB |
| references/design-direction-and-redesign.md | markdown | 6.4 KB |
| references/pages-design-directions.md | markdown | 6.1 KB |
| references/pages-visual-contract.md | markdown | 4.8 KB |
references/pages-visual-contract.md
View on GitHub# GitHub Pages visual contract
Selected guidance is adapted and rewritten for Pages from Impeccable and other
design sources. See the bundled licenses/notices and repository third-party notices.
## Start from repository evidence
Record the existing framework/theme, CSS entrypoints, design tokens, brand assets, favicon, screenshots, supported browsers, content types, and user changes. Reuse viable choices. A redesign must have a repository-grounded benefit, not just novelty.
Read the accepted project style guide or configuration and neighboring components on continuation. Reuse their semantic roles and component patterns across pages. Extend the owning source only for a needed reusable decision or justified exception, not a second competing token catalog.
## Keep the token layer small
Prefer semantic CSS custom properties or the framework's native token mechanism:
- background and elevated surface;
- primary and muted text;
- border and divider;
- action, hover, active, and focus;
- code background and code text;
- success, warning, danger, and information when those states exist;
- spacing, content width, radius, typography, and optional motion.
Components should consume semantic roles rather than one-off values. Do not create global, alias, and component token tiers unless site complexity demonstrates the need.
## Color and themes
- Derive brand accents from repository assets or documented branding.
- Check every foreground/background pairing used in rendered pages.
- Do not communicate status or link identity through color alone.
- Keep focus indicators visible across themes.
- In dark mode, remap surface and text roles deliberately; avoid raw inversion and large areas of pure black or white when they impair reading.
- Respect `prefers-color-scheme` when appropriate and preserve an accessible manual control if the chosen theme provides one.
## Typography and reading measure
- Keep body text comfortably readable at default browser zoom; do not shrink it to fit more content.
- Use a restrained hierarchy with one H1 per page and visibly distinct H2/H3 levels.
- Give code a legible monospace face and sufficient line height.
- Constrain sustained prose to roughly 45–75 characters per line, with a narrower range often preferable for long technical reading.
- Test headings, navigation labels, long commands, URLs, translated strings, and real paragraphs rather than lorem ipsum.
- Prefer system or self-hosted fonts. Adding remote fonts requires explicit operational and privacy justification.
## Spacing, grid, and hierarchy
Use a small consistent spacing scale. Keep related items closer than separate sections, and make touch targets large enough without inflating the whole layout.
Choose the simplest grid that serves the content:
- single readable column for small sites;
- navigation plus content for multi-page docs;
- optional table of contents when page length warrants it;
- responsive card grid only for genuinely parallel destinations.
Make the page title or primary proposition the first visual entry point. For documentation, prominence belongs to the reader's main task or entry point, not a mandatory marketing CTA. An index or reference page may offer several equally useful destinations. Subordinate metadata and remove decoration that competes with comprehension.
Vary composition by page purpose within one system: a project home can foreground a real output sample, a quick start its first working command, an API reference signatures and tables, and a documentation index predictable groups of links. Do not invent dashboards, customer logos, testimonials, or numbers to fill a layout.
## Responsive behavior
Choose breakpoints where content, navigation, tables, or code stop working—not from a fixed device catalog. At each relevant width:
- reflow columns without changing reading order;
- keep essential navigation available through a labelled control;
- prevent page-level horizontal scrolling while preserving scrollable code and tables where necessary;
- scale headings without reducing body legibility;
- preserve touch targets, focus visibility, zoom, and image aspect ratios;
- avoid hover-only information or actions.
## Motion and media
Use motion only for orientation or feedback. Avoid autoplay, scroll hijacking, decorative parallax, and blocking transitions. Respect reduced-motion preferences. Give informative images meaningful alternatives, decorative images empty alternatives, and screenshots enough context to remain useful.
For existing or new assets, check relevance, provenance/rights, local path, dimensions, weight, aspect ratio, narrow-screen behavior, and alternatives or useful captions. Prefer suitable local materials. External services and image generation are optional capabilities subject to project permissions, not prerequisites. Never claim a file was created or optimized without inspecting the actual output.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |