Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/github-pages-design

github-pages-design

Verified

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

references/pages-design-directions.md

View on GitHub
# Visual directions for GitHub Pages

## Contents

- [Choose from evidence](#choose-from-evidence)
- [Direction library](#direction-library)
- [Translate a direction into a system](#translate-a-direction-into-a-system)

## Choose from evidence

Use this small library when visual direction is unresolved. It offers adaptable composition principles, not official brand specifications or mandatory palettes. Supplied brand rules, viable existing styling, and reader tasks take precedence.

Inspect only the relevant entries. For a real choice, compare a small set of substantially different directions and recommend the strongest fit. Do not force a fixed number of variants. Identify the project assets, vocabulary, or audience needs supporting each option and state what would make it unsuitable.

## Direction library

### Technical clarity

- **Fits:** installation guides, API references, configuration manuals, and mature multi-page documentation.
- **Composition:** stable navigation, a readable content column, optional contextual table of contents, and prominent code or tables where the task needs them.
- **Type and density:** restrained heading hierarchy, legible body and monospace roles, and dense but grouped reference material.
- **Color and assets:** semantic surfaces, a repository-derived accent, quiet borders, and explanatory diagrams. System fonts are a valid choice.
- **Distinctive move:** make the project's real syntax, architecture, or first successful command the visual entry point.
- **Avoid when:** the primary task is browsing imagery or a portfolio whose material demands a different composition.

### Editorial narrative

- **Fits:** conceptual projects, educational material, design rationale, research stories, and long-form project explanation.
- **Composition:** asymmetric introductions where useful, strong section rhythm, reading-led columns, and diagrams or captions placed at their explanatory moment.
- **Type and density:** an expressive but legible heading role paired with comfortable sustained reading; compact reference sections can coexist.
- **Color and assets:** restrained semantic palette and meaningful illustrations, archival material, or repository diagrams with verified rights.
- **Distinctive move:** use the project's own terminology or conceptual sequence to structure the page instead of repeating feature cards.
- **Avoid when:** ornamental introductions delay urgent lookup or every page must act as a terse operational reference.

### Developer-tool identity

- **Fits:** libraries, CLIs, infrastructure tools, and applications with real examples or screenshots worth foregrounding.
- **Composition:** a clear proposition, one primary action, and a genuine command, example, or interface as the main evidence; quieter documentation pages retain a stable grid.
- **Type and density:** precise heading hierarchy, useful monospace labels, and compact metadata only when it represents real version or compatibility information.
- **Color and assets:** deliberate light/dark surfaces, limited accent emphasis, authentic product captures, and reused icons. No brand's exact palette is required.
- **Distinctive move:** turn actual project behavior into an explanatory visual sequence or interactive example when static-hosting and maintenance constraints allow it.
- **Avoid when:** fictitious terminal output, status badges, or decorative interface panels would have to supply the identity.

### Visual showcase

- **Fits:** graphics libraries, creative tools, demos, portfolios, and projects whose visible output is their strongest evidence.
- **Composition:** genuine output samples dominate; scale, framing, and varied section rhythm distinguish key work from supporting detail. Captions and destinations remain discoverable.
- **Type and density:** strong display hierarchy on the landing page, with conventional legible documentation and modest motion for feedback.
- **Color and assets:** derive treatment from actual repository examples; retain useful image alternatives and avoid text over busy media.
- **Distinctive move:** one signature, content-backed visual moment, with a static or reduced-motion path conveying the same information.
- **Avoid when:** assets are unavailable, media would conceal limitations, or loading cost would obstruct the reader's task.

### Evidence-led research

- **Fits:** benchmark reports, datasets, scientific software, technical comparisons, and results-driven project explanations.
- **Composition:** question, method, evidence, limitations, and reproduction path; charts and tables carry the argument instead of decorative tiles.
- **Type and density:** scan-friendly headings, aligned quantitative labels, readable captions, and reference-dense supporting sections.
- **Color and assets:** semantic encodings with non-color cues, accessible chart alternatives, and links to actual source data or methods.
- **Distinctive move:** make a verified result or reproducible comparison the focal point and let annotations explain it.
- **Avoid when:** reliable results do not exist or the styling would imply evidence the repository cannot support.

## Translate a direction into a system

State how the selected direction changes composition, type roles, density, semantic colors, spacing, imagery, motion, and responsive behavior. Show representative uses rather than an unexplained palette. Define only tokens the site consumes and check actual foreground/background pairings.

External reference sites can inform a pattern. Cite the exact inspected source, explain its fit, and distinguish observed facts from interpretation. Do not label a recipe as a brand's official design system or copy its identity-bearing assets without permission. Check font rights and use suitable system or licensed self-hosted alternatives.

A bold direction must change a meaningful aspect of composition or project expression while preserving reader tasks. Concentrate experimentation where it helps; documentation, search, code, and tables should remain stable. If no library entry fits, articulate a custom evidence-backed direction instead of forcing a recipe. Coherent combinations are possible when their roles and reader benefits are explicit.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall