Design Resources for Developers — Administrator & Developer Guide

For maintainers, forkers, and anyone responsible for keeping a curated link list useful over time. This guide documents the architecture, governance, and operations of bradtraversy/design-resources-for-developers — what it is, what it isn't, and the practical reality of running a high-traffic catalog with a minimal rule set.

1. Executive Summary

bradtraversy/design-resources-for-developers is a single-document curated link catalog maintained by Brad Traversy on GitHub. It contains 33 sections and approximately 1,088 entries linking to free design resources — icons, fonts, illustrations, CSS frameworks, component libraries, and design tools.

The repository is unusually minimalist for its visibility:

• One content file (readme.md)
• One contribution-rules file (contributing.md) of 480 bytes
• A pull-request template with a single self-review checkbox
• An MIT license
• A .prettierignore that excludes the README from formatter rewrites
• No CI, no build, no website, no API, no tests, no automation

Operationally, the entire repository is a review queue + a markdown file. The maintainer's job is reviewing pull requests against four contribution rules, occasionally curating dead links from issue reports, and ensuring the README stays renderable on github.com.

Important

This is not a software project; it is a content project. Standard sections on deployment, configuration, and security hardening do not apply in their conventional form. This guide reframes them around the operational reality: review governance, link-rot management, fork strategy, and submission throughput.

What the repository ships

What the repository does NOT have

Note

This negative-knowledge list is load-bearing for forkers and AI agents. Inferring missing infrastructure leads to fabricated guidance.

• No package manifest (package.json, pyproject.toml, Gemfile, etc.)
• No build scripts or Makefile
• No GitHub Actions workflows or other CI
• No tests
• No linter configuration (other than .prettierignore)
• No release tags or versioned snapshots
• No website beyond the rendered README on github.com
• No API, scraper, or data export
• No bot-based link checker
• No code of conduct file
• No security policy file
• No discussion board (issues only)

2. Architecture

The "architecture" of a curated link list is its content structure and its review workflow. There is no software architecture in the traditional sense.

Content architecture

readme.md
│
├── Banner image                    ← headerimage.png
├── Sponsor block                   ← Warp banner (HTML <div align="center">)
│
├── Pointer to contributing.md      ← One-line callout
│
├── ## Table of Contents            ← Bulleted list of 33 anchor links
│   ├── - [UI Graphics](#ui-graphics)
│   ├── - [Fonts](#fonts)
│   └── ... (33 entries)
│
└── 33 sections, each shaped:
    │
    ├── ## Section Name             ← H2; GitHub auto-slugs to anchor
    ├── > One-line description      ← Blockquote
    ├── | Website | Description |   ← Two-column markdown table
    ├── | -------- | ------------- |
    ├── | [Name](url) | desc       |
    └── <div align="right">         ← Back-to-top link, raw HTML
            <b><a href="#table-of-contents">↥ Back To Top</a></b>
        </div>

Tip

The catalog uses raw HTML (<div>, <a>) where markdown can't express alignment — banner blocks, "Back to Top" links, the sponsor block. The mix is deliberate: GitHub renders both; plain markdown viewers fall back gracefully.

Slug convention (anchor links)

GitHub renders H2 headers into anchor slugs by lowercasing, replacing spaces with dashes, removing characters outside [a-z0-9-], and preserving consecutive dashes that come from removed punctuation. This produces the slugs in the Table of Contents:

Caution

The double-dash slugs from sections containing & are not a typo. Forkers running their own renderers (MkDocs, Hugo, Jekyll) will produce different slugs and the Table of Contents links will break. Test anchor links after any renderer change.

Review architecture

Contributor
   │
   │ 1. Forks repo
   │ 2. Edits readme.md (one entry, one section)
   │ 3. Opens PR titled `[Resource Name] -> [Section Name]`
   │ 4. Provides Link: <url> in PR body
   │
   ▼
Pull Request Queue
   │
   │ Maintainer reviews:
   │   - Is the link "truly free"?
   │   - Is the section right?
   │   - Is the formatting consistent with adjacent rows?
   │   - Are there duplicates?
   │
   ▼
Merge to master
   │
   ▼
Live on github.com

There is no automated review step. Every PR is human-reviewed by the maintainer.

3. System Requirements

For a reader, contributor, or forker, the entire list of requirements is short.

Note

No language runtime, no package manager, no build tooling, and no LLM is required to consume or contribute to this catalog. The bar is intentionally low.

4. Configuration & Curation Policy

There are no configuration files in the repository. What appears at first glance as configuration is actually curation policy — the rules that govern what enters the README and how.

The four contribution rules (verbatim from contributing.md)

- Add single resource in one pull request as it will allow for easier review.

- Pull request title should include resource name and resource section.
  - Example: `[Tailwind CSS] -> [CSS Frameworks]`

- Provide a link to submitted resource in pull request comment section for easier
  access without copy paste.
  - Example: `Link: https://tailwindcss.com/`

- Double check if the resource is truly free without any kind of hidden surprises.

That is the entire policy. It fits in 480 bytes.

Implicit policy revealed by the README

Beyond the written rules, the README structure encodes additional conventions enforced through review:

These conventions are enforced by review, not by lint. A new maintainer should walk through 5–10 merged PRs to internalize them.

Pull request template

.github/pull_request_template.md pre-fills the PR description box. The current template reads:

# Readme - header image

Updated header image to Warp sponsor

Link: www.linkToResource

#### Checklist:

- [ x] I have performed a self-review of submitted resource and its follows the guidelines of the project.

Note

The template appears to have been edited for a specific header-image update and was not reverted to a generic form. Contributors overwrite the body to describe their actual change. The single checkbox is the only enforcement mechanism — it is a self-review, not a maintainer-run check. Replacing this template with a generic one is listed as Improvement #2 in the backlog.

.prettierignore

readme.md

That single line excludes the catalog from any Prettier-driven formatting. The README uses author-controlled column padding and   tricks in column headers to keep mobile rendering tidy. A formatter would rewrite all that and silently corrupt the layout.

Warning

If you fork this repository and add Prettier or any other markdown formatter, keep the .prettierignore rule in place or your first formatter run will rewrite every section header and break visual alignment.

5. Operations

The day-to-day work of running this repository.

Triaging incoming pull requests

A typical PR session walks through queued PRs and applies the four rules. Maintainer checklist:

• [ ] Free? — Open the linked site, look for "Pricing" or "Get Started," verify there is a permanently usable free tier (not a 14-day trial or credit-card-required signup).
• [ ] Section fit? — If the PR adds a React-only library to "UI Components & Kits," ask the contributor to move it to "React UI Libraries."
• [ ] Duplicate? — Ctrl+F for the resource URL in readme.md. If it's already there, close politely.
• [ ] Description quality? — One factual sentence, no marketing language. Edit before merging if needed.
• [ ] PR title format? — [Resource] -> [Section]. Edit if the contributor used a different format.
• [ ] Single resource? — Multi-resource PRs get asked to split.

Closing dead-link issues

Contributors periodically open issues like:

• #1590 Linked site https://www.palettelist.com appears to be dead
• #1598 Removed expired and broken links from resources

A typical batch-cleanup pass:

git checkout -b cleanup-broken-links-YYYY-MM-DD
# Edit readme.md: remove dead entries, replace with successors where obvious
git add readme.md
git commit -m "Remove dead links (closes #1590, partial #1598)"
git push origin cleanup-broken-links-YYYY-MM-DD
# Open a PR linking the issues

Tip

Batching is the right strategy. Single-link removal PRs flood the activity stream and bury substantive contributions. A monthly or quarterly cleanup pass keeps signal-to-noise high.

Updating the sponsor banner

The Warp sponsor block at the top of the README is raw HTML wrapped in a <div align="center" markdown="1">. To swap it:

1. Replace the <a href="https://www.warp.dev/..."> with the new sponsor's URL.
2. Replace the <img alt="..." src="..."> with the new sponsor's image (typically hosted on GitHub user-attachments).
3. Update the explanatory line of text.
4. Commit with a message like Update sponsor banner and merge directly.

Caution

Sponsor banners are not curated entries. They are paid placements. A sponsor link goes above the Table of Contents in the dedicated <div>. It does not get added to a category section.

Verifying renderability after a large PR

After merging a substantial change (a new section, table-format edits), spot-check the rendered README on github.com:

• [ ] Scroll the page — does any table overflow past where it should?
• [ ] Click 3–5 random TOC entries — do they jump to the right section?
• [ ] Click "↥ Back To Top" at the end of several sections — does it return to the TOC?
• [ ] Click 3–5 newly added resource links — do they load?
• [ ] Resize browser narrow — do tables degrade gracefully?

Bulk dead-link audit (manual)

The repository has no automated link checker. A periodic manual pass:

# Extract every URL from the README
grep -oE 'https?://[^)\s]+' readme.md | sort -u > /tmp/all_urls.txt
wc -l /tmp/all_urls.txt

1100 /tmp/all_urls.txt

Feed the URL list to any link checker (linkchecker, lychee, or a custom curl loop). Investigate non-200 responses, but expect false positives — many sites block automated probes. Cross-check with a real browser before removing.

6. Security

A curated link list has a small but non-zero security surface. The threat model is third-party services that the catalog endorses by listing.

Threat model

Reviewer security checklist

When approving a PR, a security-minded reviewer asks:

• [ ] Does the linked URL resolve to HTTPS? Demote HTTP-only links.
• [ ] Is the domain a typosquat? (e.g., tail-windcss.com is not Tailwind.)
• [ ] Does the linked site demand signup before showing any value? Violates "truly free without hidden surprises."
• [ ] Does the page run wallet-connect, NFT, or crypto-payment flows? Out of scope, frequently covers scams.
• [ ] Is the link a redirect chain through an affiliate or analytics network? Direct links preferred.

Warning

The catalog is not a security endorsement of any listed tool. Listing means "free and design-relevant" — nothing about a tool's own security posture, vulnerability status, or supply chain.

What this catalog is NOT a security source for

• Library vulnerabilities — the catalog has no version data or security metadata
• Build supply-chain attacks — it doesn't ship code
• Endorsement of a tool's security posture — listing means "free and design-relevant," nothing more

7. Forking & Derivative Catalogs

The MIT license permits unrestricted forking. Common reasons: curate a niche subset, translate descriptions, or mirror on a non-GitHub platform.

Fork checklist

• [ ] Update LICENSE to reflect your own copyright while keeping Brad Traversy's original notice intact (MIT requires preserving the copyright notice).
• [ ] Edit the README to clearly state your fork is derived from Brad Traversy's catalog and link back.
• [ ] Decide on your contribution policy. Brad's four-rule policy is a good starting point — copy it, don't reinvent it.
• [ ] Update headerimage.png (or remove it) — don't keep the original banner if your scope diverges.
• [ ] Update or remove the Warp sponsor block — sponsorships do not transfer to forks.
• [ ] Re-test all anchor links if you renamed sections — every renamed ## Header produces a new slug and breaks the TOC.

Migrating to a different renderer (MkDocs, Hugo, Jekyll, Docusaurus)

8. Performance & Scaling

Performance for a single markdown file is bounded by how big the file gets and how slowly it renders.

Current scale

Soft limits to watch

• Above ~512 KB, github.com may show a "this file has been truncated" warning. The current README is well below this.
• Above ~5 MB, github.com refuses to render inline and shows only a download prompt.

If the catalog continues to grow, it will need to split before either threshold matters. Possible strategies:

Note

The single-file model is part of the catalog's identity. Don't split prematurely. Re-evaluate when the README approaches 250 KB.

9. Common Maintenance Tasks

Add a new section

1. Add a TOC entry near a related section (alphabetical or thematic — follow neighbor convention).

2. Below the last existing section, paste the section template:

   ## Section Name
   
   >One-line description of what this section is for
   
   | Website              | Description |
   | ----------------------- | ------------------ |
   | [First Resource](https://example.com/) | Short description |
   
   <div align="right">
       <b><a href="#table-of-contents">↥ Back To Top</a></b>
   </div>
   

3. New sections are heavyweight changes. Most submissions fit existing categories.

Rename a section

1. Edit the section header (## Old Name → ## New Name).
2. Edit the matching TOC entry with the new slug.
3. Note: external links to the old anchor (blog posts, bookmarks) will break. Weigh the friction.

Remove a dead resource

1. Verify the link is dead from multiple networks and Wayback Machine.
2. Delete the entire row (including leading and trailing |).
3. Commit message: Remove dead link: [Resource Name] (closes #issue).

Move an entry to a different section

Find the row, cut it from the source section's table, paste it into the destination section's table. Preserve the link and description verbatim. Mention the move in the commit message.

10. Troubleshooting (For Maintainers)

Issue: PR keeps adding entries with marketing-style descriptions

The contributing guidelines don't explicitly forbid this. Comment on the PR with a suggested rewrite, push the edit yourself if the contributor doesn't respond, and merge.

Issue: Section is becoming unreadable due to length

When a section crosses ~75 entries (the current "Others" section is the canonical case), readers scan less and miss good entries. Options: subdivide into two narrower sections; re-order rows alphabetically; add a "Sub-categories within this section" callout above the table.

Issue: Anchor link works on github.com but not on a fork's renderer

GitHub's slug algorithm differs from Python-Markdown, kramdown, and others. Symptoms include doubled dashes (from &) being collapsed or expanded differently. Test the specific renderer's output and adjust TOC links accordingly.

Issue: PR title doesn't match [Name] -> [Section] format

Edit the title yourself when merging. Most contributors don't read contributing.md before opening a PR. Don't bounce the PR; fix the title and merge.

Issue: Submitter says their tool is "free" but signup requires a credit card

Reject. This is the canonical "hidden surprise" the contributing rule filters out. Suggested close: "Thanks for the suggestion. The catalog requires resources to be usable without a credit card or paid trial. If your tool ever offers a no-card free tier, please re-submit then."

Issue: Same resource keeps getting re-submitted

Some tools attract repeated PR submissions because contributors don't search first. Close with a link to the existing entry. If volume is high, consider pinning a "Most-frequently-submitted-already-in-list" issue at the top of the issue tracker.

Issue: headerimage.png rendering is huge or blurry

# Replace headerimage.png with the new asset
mv ~/Downloads/new-banner.png headerimage.png
git add headerimage.png
git commit -m "Update header image"

Recommended dimensions: similar to the existing image (~1280×400). Optimize the PNG before committing — TinyPNG or Squoosh (both listed in the catalog's Image Compression section).

11. Improvements Backlog

Grounded list of improvements for incoming maintainers or AI-assisted maintainers, ranked by leverage.

Note

None of these is critical. The repository works as-is. Each improvement adds maintainer overhead — and simplicity is itself part of the product's identity.

12. Quick Reference for Maintainers

Repository at a glance

bradtraversy/design-resources-for-developers
├── readme.md                            ← THE catalog (only file you edit often)
├── contributing.md                      ← 4 rules, effectively never changes
├── LICENSE                              ← MIT, Copyright 2020 Brad Traversy
├── headerimage.png                      ← Banner; swap when sponsor changes
├── .prettierignore                      ← Keep `readme.md` line in place
└── .github/
    └── pull_request_template.md         ← Replace stale template (Improvement #2)

Maintainer commands

# Clone for editing
git clone git@github.com:bradtraversy/design-resources-for-developers.git
cd design-resources-for-developers

# Find a duplicate URL before merging a PR
grep -F 'https://example.com' readme.md

# Count entries (rows starting with `| [`)
grep -cE '^\| \[' readme.md

1088

# Quick audit: find sections with very few entries (candidates for merging)
awk '/^## /{section=$0; count=0; next} /^\| \[/{count++} /^---$/{print count, section}' readme.md | sort -n | head

# Spot-check anchor slug for a section
echo "## Stock Music & Sound Effects" | tr 'A-Z' 'a-z' | sed 's/[^a-z0-9 ]//g' | tr ' ' '-'

stock-music--sound-effects

Repository status (as of source commit 6d9884e, 2026-04-13)

URLs