Skip to content

YuShenLiu06/PCHSystem / .claude/skills/beautify-github-readme

beautify-github-readme

Verified

Redesign GitHub README homepages or create project-native pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets. Use when a user asks to beautify, redesign, rebrand, visually upgrade, simplify, or audit a GitHub README; create only a hero, section headers, diagrams, badges, motion graphics, showcase modules, or other README assets; or turn a repository homepage into a cohesive visual story. If whole-README work versus asset-only work is unclear, ask which scope the user wants. For hero-like assets where pure SVG and generated raster material are both viable, explain the tradeoffs and confirm the implementation before creating the asset.

references/visual-direction.md

View on GitHub
# Theme-specific visual direction

## Derivation order

Choose the visual system in this order:

1. Real product semantics: what the repository actually helps people do.
2. Existing identity: logo, UI tokens, screenshots, diagrams, code style, or documentation tone.
3. Audience expectation: technical trust, creative energy, research clarity, or operational confidence.
4. Visual finish: palette, type scale, material, motif, and composition.

Do not start with a fashionable finish and force the project into it.

## Theme cues

| Repository type | Useful visual cues | Avoid |
| --- | --- | --- |
| CLI / developer tool | terminal rhythm, cursor, monospace accents, logs, precise grids | fake code, neon overload |
| AI product | relationships, transformations, evidence, input/output contrast | generic glowing brain imagery |
| Design resource | keylines, material samples, artboards, crop marks, specimen walls | portfolio decoration with no proof |
| Data / research | coordinates, annotations, charts, source labels, measured spacing | dashboard clichés unrelated to the data |
| Library / framework | modules, composition, API flow, dependency structure | pretending documentation is a marketing site |
| Creator project | voice, editorial imagery, sequences, human scale | generic SaaS landing-page sections |

## Monochrome technical direction

For infrastructure, security, research, systems, hardware, and other serious technical repositories, consider a black-and-white direction before adding brand color:

- Use black, warm white, and two neutral grays.
- Use a strict grid, thin rules, large numbers, mono metadata, and restrained diagrams.
- Mix sans-serif, monospace, or a sober serif only when the project supports it.
- Replace decorative cards with architecture, specifications, boundaries, results, or real interfaces.
- Avoid gradients, glossy materials, playful rounded tiles, and ornamental shadows.

Monochrome should still come from the project. A security repository may emphasize boundaries and permissions; hardware may emphasize dimensions, interfaces, and real objects; research may emphasize methods, results, and limits.

## Visual grammar

Freeze five decisions before producing assets:

- **Palette** — 3 to 5 colors with explicit hex values and clear roles.
- **Type** — system font stack; one large display scale, one section scale, one body scale.
- **Shape** — one radius family, one stroke weight, one spacing unit.
- **Motif** — one small recurring project-specific cue.
- **Density** — one deliberate rhythm: sparse editorial, compact technical, or expressive gallery.

The motif is the strongest anti-template device. Repeat it lightly in the hero, section transitions, and showcase, but never as wallpaper everywhere.

## Composition patterns

- **Artifact wall** — several screenshots or outputs, slightly rotated around a shared axis. Best when visual proof is the product.
- **Before / after** — show the transformation when the mechanism matters.
- **System map** — show one source feeding several components or outputs.
- **Annotated specimen** — enlarge one real artifact and label the decisions that matter.
- **Sequence strip** — show three to six dependent stages.

Prefer one strong composition over several small decorative graphics.

## Restraint rules

- Use shadow only to separate overlapping artifacts; keep it soft and low-opacity.
- Do not add top borders to every screenshot or card.
- Keep decorative dots, grids, and lines subordinate to content.
- If several modules compete for attention, remove one before reducing everything.
- A README should feel designed at GitHub's content width, not like a full-screen website squeezed into Markdown.
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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