# Contributing to theSVG

Thank you for your interest in contributing to theSVG! This guide will help you
get started.

## Ways to Contribute

### Submit a New Icon

You have two options:

**A. Via the submit form** (easiest):

1. Go to [thesvg.org/submit](https://thesvg.org/submit)
2. Upload the SVG, fill in the brand name, category, and website URL
3. Submit — this opens a triaged issue

**B. Via a direct PR** (faster if you're comfortable with git):

1. Fork the repo and branch off `main`: `git checkout -b feat/icon-{slug}`
2. Drop the SVG at `public/icons/{slug}/default.svg`
3. Add an entry to `src/data/icons.json` at the correct alphabetical position, following the schema:
   ```json
   {
     "slug": "your-brand",
     "title": "Your Brand",
     "aliases": [],
     "hex": "F97316",
     "categories": ["DevTool"],
     "variants": { "default": "/icons/your-brand/default.svg" },
     "license": "CC0-1.0",
     "url": "https://yourbrand.com",
     "collection": "brands",
     "dateAdded": "2026-05-16"
   }
   ```
4. Open a PR titled `feat: add {slug} icon`. The triage workflow will auto-label it; if everything passes (`Validate SVG`, `Lint & Build`), it'll auto-merge.

**Requirements for icon submissions (both paths):**

- SVG format only (no PNG, JPG, etc.)
- Must be an official brand logo or icon
- Must have a valid `viewBox` attribute
- File size under 50KB
- No embedded `<script>` tags, event handlers, or `javascript:` URIs
- No raster images embedded in the SVG
- Brand domain at least 30 days old (we reject fresh-spun-up sites)
- One valid category from the [issue template's dropdown](.github/ISSUE_TEMPLATE/icon_request.yml)
- Preferably optimized with [SVGO](https://github.com/svg/svgo)

### Report an Issue

- **Incorrect icon data** - wrong brand name, color, category, or URL
- **Missing variants** - brand has a dark/light/mono version we don't have
- **Broken icon** - SVG doesn't render correctly
- **Package bug** - import errors, TypeScript issues, build problems

Use the appropriate [issue template](https://github.com/glincker/thesvg/issues/new/choose).

### Improve the Code

1. Fork the repository
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Make your changes
4. Run the build: `cd packages/icons && npm run build`
5. Run audits: `npm run audit && npm run validate`
6. Commit with conventional commits: `feat: add new feature`
7. Open a pull request

## Development Setup

```bash
# Clone the repo
git clone https://github.com/glincker/thesvg.git
cd thesvg

# Install dependencies
pnpm install

# Run the website
pnpm dev

# Build the icon package
cd packages/icons
npm run build
npm run audit
npm run validate
```

## Commit Convention

We use [conventional commits](https://www.conventionalcommits.org/):

- `feat: add new feature` - triggers a minor release
- `fix: fix a bug` - triggers a patch release
- `feat!: breaking change` - triggers a major release
- `docs: update readme` - no release
- `chore: maintenance` - no release

## Collections

theSVG organizes icons into collections. Each icon belongs to exactly one collection:

| Collection | Slug prefix | Source | License |
|------------|------------|--------|---------|
| Brand Icons | *(none)* | Community submissions | Per-brand |
| AWS Architecture | `aws-` | Official AWS icon package | [CC BY-ND 2.0](https://creativecommons.org/licenses/by-nd/2.0/) |
| GCP *(planned)* | `gcp-` | Google Cloud icons | TBD |
| Azure *(planned)* | `azure-` | Microsoft Azure icons | TBD |

### Submitting brand icons

Use [thesvg.org/submit](https://thesvg.org/submit) or open a PR. Brand icons go in `public/icons/{slug}/` and get `"collection": "brands"` in icons.json.

### Architecture icon collections (AWS, GCP, Azure)

Architecture icons are imported in bulk from official icon packages using scripts in `scripts/`. These icons are **not modified** -- all SVG files (including size variants like 16/32/64px) are provided by the official package and copied verbatim to comply with their respective licenses. Do not submit individual architecture icons through the submit form.

To update an architecture collection (e.g., when AWS releases a new quarterly icon set):

1. Download the latest official icon package
2. Run the import script: `npx tsx scripts/import-aws-icons.ts`
3. Verify the import: check `src/data/icons.json` and `public/icons/aws-*/`
4. Open a PR with the updated icons

## Icon Data Structure

Icons are stored in `src/data/icons.json`. Each entry:

```json
{
  "slug": "github",
  "title": "GitHub",
  "aliases": ["gh"],
  "hex": "181717",
  "categories": ["DevTool", "VCS"],
  "variants": {
    "default": "/icons/github/default.svg",
    "mono": "/icons/github/mono.svg"
  },
  "license": "MIT",
  "url": "https://github.com",
  "collection": "brands",
  "dateAdded": "2026-03-07"
}
```

For architecture icons, additional fields:

```json
{
  "slug": "aws-amazon-s3",
  "title": "Amazon S3",
  "collection": "aws",
  "collectionVersion": "2026-Q1",
  "collectionMeta": {
    "type": "service",
    "parent": "Storage"
  }
}
```

SVG files live in `public/icons/{slug}/{variant}.svg`.

## Brand Icon Guidelines

- We only include official brand assets - no fan-made or modified logos
- Icons should represent the brand accurately as it appears in official materials
- Do not modify brand colors unless providing a mono variant
- Check the brand's public guidelines or press kit before submitting
- If a brand has explicit restrictions on third-party use, note it in the PR

### Brands that restrict distribution

Some companies actively enforce trademark restrictions on third-party icon
distribution. Before submitting, check whether the brand allows it. If you are
unsure, submit anyway and we will review.

If a brand owner requests removal, we comply within 24 hours. See our
[Trademark Policy](./TRADEMARK.md) for details.

## Legal

By contributing, you agree that your contributions will be licensed under the
project's [MIT License](./LICENSE).

All brand icons remain the property of their respective owners. Icons are
provided for identification and development purposes only, consistent with
nominative fair use of trademarks. thesvg is not affiliated with, endorsed by,
or sponsored by any of the brands whose icons appear in our library.

AWS Architecture Icons are distributed unmodified under [CC BY-ND 2.0](https://creativecommons.org/licenses/by-nd/2.0/). Amazon
Web Services and all related marks are trademarks of Amazon.com, Inc.

For trademark concerns, see [TRADEMARK.md](./TRADEMARK.md) or contact
[support@glincker.com](mailto:support@glincker.com).

## Questions?

- [Open a discussion](https://github.com/glincker/thesvg/discussions)
- [Browse existing issues](https://github.com/glincker/thesvg/issues)
- [Contact us](https://thesvg.org/contact)