docs: add usage documentation and contributing guide

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to Platformicons
+
+## Development Setup
+
+```bash
+git clone https://github.com/getsentry/platformicons.git
+cd platformicons
+yarn install
+yarn build
+```
+
+Requirements: Node 20+ and Yarn 1.x (managed via [Volta](https://volta.sh/)).
+
+## Adding a New Icon
+
+1. **Add SVG files** to both directories:
+   - `svg/<icon-name>.svg` — small version (solid background for readability at small sizes)
+   - `svg_80x80/<icon-name>.svg` — large version (transparent background, 80x80px)
+
+   Both directories must have matching filenames — the build will fail if they don't.
+
+2. **Add the platform mapping** in `src/platformIcon.tsx` inside the `PLATFORM_TO_ICON` object. Keep entries in alphabetical order:
+
+   ```ts
+   export const PLATFORM_TO_ICON = {
+     // ...
+     "python-newframework": "newframework",
+     // ...
+   };
+   ```
+
+   The key is the platform identifier (e.g. `"python-newframework"`), and the value is the SVG filename without the extension (e.g. `"newframework"`).
+
+3. **Regenerate the icon imports:**
+
+   ```bash
+   yarn generate
+   ```
+
+   This runs `scripts/generate-icons.js`, which reads both SVG directories and writes `src/icons.generated.ts`. Do not edit that file by hand.
+
+4. **Verify the build:**
+
+   ```bash
+   yarn build
+   ```
+
+## Build Process
+
+`yarn build` does three things:
+
+1. Runs `scripts/generate-icons.js` to create static imports for all SVGs in `src/icons.generated.ts`
+2. Compiles TypeScript to CommonJS (`build/`)
+3. Compiles TypeScript to ESM (`esmbuild/`)
+
+## Submitting Changes
+
+1. Fork the repo and create a branch
+2. Make your changes
+3. Run `yarn build` to verify everything compiles
+4. Open a pull request — do **not** bump the version in `package.json`, that's handled automatically during release

README.md

@@ -2,12 +2,91 @@
 
 A set of platform and framework icons from the people behind https://sentry.io.
 
-## SVG Versions
+## Installation
 
-There are two kinds of icons in this collection:
+```bash
+# yarn
+yarn add platformicons
 
-- The icons in `/svg` are for smaller rendering sizes. They can have a solid background to achieve high contrast to make them easier to "read" in smaller sizes.
-- The icons in `/svg_80x80` are for bigger rendering sizes. They can have a transparent background.
+# npm
+npm install platformicons
+```
+
+React is a peer dependency, so make sure it’s installed in your project.
+
+The package ships both CommonJS and ESM builds:
+
+- `"main"` → `build/index.js` (CommonJS — works with webpack, Gatsby, etc.)
+- `"module"` → `esmbuild/index.js` (ESM — works with Vite, Astro, etc.)
+
+Most bundlers pick the right entry automatically. Static SVG imports ensure both module systems resolve icons correctly.
+
+## Usage
+
+```tsx
+import { PlatformIcon } from ‘platformicons’;
+
+function App() {
+  return <PlatformIcon platform="javascript-react" size={32} />;
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `platform` | `string` | — | Platform identifier (e.g. `"python-django"`, `"javascript-react"`) |
+| `size` | `string \| number` | `20` | Icon width and height in pixels |
+| `format` | `"sm" \| "lg"` | `"sm"` | `"sm"` uses compact icons from `/svg`, `"lg"` uses detailed icons from `/svg_80x80` |
+| `radius` | `number \| null` | `3` | Border radius in pixels |
+| `withLanguageIcon` | `boolean` | `false` | Show a small language badge in the bottom-right corner (e.g. the Python logo on a Django icon) |
+| `languageIconStyles` | `React.CSSProperties` | `{}` | Custom styles for the language badge |
+
+### Platform Names
+
+Platforms use a `language-framework` naming convention:
+
+```
+python-django
+javascript-react
+ruby-rails
+go-echo
+```
+
+Both dashes and dots are accepted (`python-django` and `python.django` are equivalent). If an exact match isn’t found, the library falls back to the language icon (the part before the first dash), then to a generic default icon.
+
+`node-*` is an alias for `javascript-*` for backwards compatibility.
+
+You can get the full list of supported platform keys at runtime:
+
+```tsx
+import { platforms } from ‘platformicons’;
+// platforms is a string[] of all valid platform keys
+```
+
+### Preloading
+
+To avoid render jank when icons appear on a new page, you can preload them:
+
+```tsx
+import { preloadIcons } from ‘platformicons’;
+
+// Preload all icons (both sizes)
+preloadIcons();
+
+// Preload only small or large icons
+preloadIcons(‘sm’);
+preloadIcons(‘lg’);
+```
+
+This inserts `<link rel="preload">` tags into the document head.
+
+## Using SVGs Directly
+
+If you aren’t using React, the raw SVG files are included in the package:
+
+- `platformicons/svg/` — small icons (solid backgrounds, optimized for small sizes)
+- `platformicons/svg_80x80/` — large icons (transparent backgrounds, 80x80px)
 
 ## Publishing Changes
 
@@ -18,3 +97,7 @@ Platformicons uses GitHub Actions to publish changes. You don’t need to update
 3. Head to the [Release workflow](https://github.com/getsentry/platformicons/actions/workflows/release.yml) and then run the workflow
 4. This will create an issue in [getsentry/publish](https://github.com/getsentry/publish/issues)
 5. Add the accepted label to publish
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add new icons.