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/design-critique.md
View on GitHub# Composition critique and recurring failure patterns
## Contents
- [Critique from evidence](#critique-from-evidence)
- [Contextual failure patterns](#contextual-failure-patterns)
- [Report and boundaries](#report-and-boundaries)
## Critique from evidence
Use a rendered page or supplied screenshot for composition judgments. Record route, viewport, theme, and relevant state when available. A screenshot supports static visual observations only; source-only concerns remain hypotheses until rendered. Inspect these dimensions against the actual brief:
| Dimension | Check |
| --- | --- |
| Coherence | Type, colors, shapes, assets, density, and motion support the stated direction and project identity |
| Hierarchy | The first visual entry point and reading order support the reader's task; metadata and decoration do not compete |
| Craft | Alignment, grouping, spacing, image crop, and responsive reflow are deliberate across real content |
| Purpose | Each element explains, navigates, provides feedback, or identifies something; removing decoration does not impair the task |
| Expression | Project-specific evidence gives the site character without weakening familiar navigation or readability |
On documentation pages prioritize finding and understanding information. On a project landing page, identity and expression can take a larger role. Do not impose aesthetic scores, headline/body ratios, a fixed whitespace percentage, a maximum font count, or a mandatory number of fixes.
## Contextual failure patterns
These are diagnostic prompts, not prohibitions. An established brand pattern or a reader-task benefit can justify an apparent exception. Report only consequential examples.
| Pattern | Observable evidence | Smallest useful correction |
| --- | --- | --- |
| Mechanical section rhythm | Most sections repeat the same low-information label, heading, paragraph, or mirrored split | Remove redundant labels and vary composition according to content roles |
| Excessive card containers | Unrelated cards surround every paragraph or item without a grouping or interaction reason | Use alignment, spacing, dividers, or a shared surface where they convey the relationships better |
| Empty geometric layout | Bento cells or arbitrary spans exist only to complete a shape | Let meaningful content determine cells and prominence; remove filler |
| Unsupported hero formula | A large centered slogan, gradient, and competing CTAs obscure the actual project and next task | Bring real examples, screenshots, or a concrete proposition forward; distinguish actions |
| Decorative metadata | Fake status dots, coordinates, counters, version labels, or badges imply state or credibility without evidence | Remove them or connect them to verified information |
| Shape or token drift | Similar components use incompatible radii, borders, spacing, or unrelated colors without a semantic reason | Consolidate through the existing token and component roles |
| Counterfeit assets | CSS shapes or invented captures stand in for a recognizable real logo or product interface | Use verified assets, an honest preview slot, or an appropriate text identity |
| Media or decoration overwhelms reading | Labels cover meaningful imagery, display text clips, or textures hide content | Simplify treatment, adjust hierarchy and crop, and preserve readable captions |
| Spectacle without purpose | Multiple loops, reveals, or pinned sections delay reading without adding explanation or feedback | Remove or reduce motion and provide an equivalent reduced-motion path |
| Marketing treatment on reference pages | Giant headings and excessive spacing hinder lookup, comparison, or scanning | Restore task-appropriate density and a stable navigation/content structure |
| Happy-path-only styling | Search, menu, theme, or copy controls look complete only in one success state | Inspect applicable focus, active, disabled, empty, error, and narrow-layout states |
Do not ban gradients, system fonts, accent-bordered callouts, emoji, or repeated components categorically. Evaluate whether they suit existing branding, communicate real information, and remain readable. Consistency across documentation pages is often a strength.
Check whether a correction merely exchanges one generic cluster for another. Cream/terracotta, black/lime, mono capitals, and decorative numbering can be contextual prompts, never banned palettes or labels. Judge combinations by the page's purpose and accepted identity. A user-selected font, including Inter, a card, or a gradient is not itself a defect.
Keep source facts, rendered observations, tested interactions, assumptions, and design judgments distinct. A class name proves a class exists. Pixels support a visual observation. Neither proves keyboard operation or a successful link action. Scanners cannot establish authorship or assign severity by how recognizably “AI” something looks.
## Report and boundaries
Return a concise **Keep / Fix / Opportunity** assessment. For each actionable item state observed evidence, the affected reader task or visual intent, a concrete correction, and a verification method. Separate functional/accessibility defects from supported design opportunities and subjective preferences. Do not infer a verified interaction or contrast result from how a screenshot looks.
If no useful change survives these checks, say so and stop. Do not manufacture findings or variants to fill a quota.
This composition pass does not replace the production-build, keyboard, responsive, contrast, or route checks owned by `github-pages-audit`. In a read-only audit, advise without editing. In `github-pages-improve`, attach supported opportunities to the shared proposal IDs and approval state. During implementation, correct in-scope problems and disclose a material scope expansion before pursuing it.
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 |