@campo-design/icons 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Litchfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @campo-design/icons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Campo's icons are [Phosphor](https://phosphoricons.com) (MIT licensed). This
+package pins one Phosphor version, sets Campo's default weights, and gives every
+icon name a TypeScript type. It doesn't depend on any component library.
+`@campo-design/webawesome/icons` uses it to make Phosphor Web Awesome's icon set.
+
+## Weights
+
+Phosphor draws every icon in six weights: `thin`, `light`, `regular`, `bold`,
+`fill` and `duotone`.
+
+| Use | Weight | Why |
+| --- | --- | --- |
+| Content icons (`defaultWeight`) | `regular` | Its stroke matches body text at 16-24px |
+| Icons inside components (`uiWeight`) | `bold` | Components draw these small (often 12-14px), where regular's strokes get faint |
+
+Pick another weight per icon when the design calls for it, for example `fill`
+for a selected state.
+
+## How icons load
+
+Phosphor is 1,500+ icons × 6 weights, about 36 MB of SVG files, so nothing
+bundles all of it.
+
+- **Any icon:** `iconUrl(name, { weight })` returns the URL of its SVG file. By
+  default that's the exact Phosphor version installed here on the jsDelivr CDN,
+  so the icons always match the names in the types. Only the icons a page
+  actually shows get downloaded, and browsers cache them.
+- **Interface icons** (chevrons, close, check, eye…): `uiIcons` holds about 60
+  of them as SVG strings, built into the package. Components need these
+  instantly, and they still work offline or when a CDN is blocked.
+
+### Self-hosting
+
+A CDN can be blocked by a strict network or a page's Content Security Policy.
+To serve the icons yourself, copy Phosphor's `assets` folder into your site and
+point `base` at it:
+
+```sh
+cp -R node_modules/@phosphor-icons/core/assets public/phosphor
+```
+
+```js
+iconUrl('house', { base: '/phosphor/' }); // → /phosphor/regular/house.svg
+registerCampoIcons({ base: '/phosphor/' }); // the Web Awesome version
+```
+
+## API
+
+```js
+import { iconUrl, uiIcons, weights, defaultWeight, uiWeight } from '@campo-design/icons';
+
+iconUrl('house');                     // regular weight, from the CDN
+iconUrl('house', { weight: 'bold' }); // …/bold/house-bold.svg
+uiIcons['caret-down-bold'];           // '<svg …>…</svg>'
+```
+
+| Export | What it is |
+| --- | --- |
+| `iconUrl(name, { weight?, base? })` | URL of one icon's SVG |
+| `fileStem(name, weight?)` | Phosphor's file name: `house`, `house-bold` |
+| `uiIcons` | Inlined interface icons, keyed by file name |
+| `weights`, `defaultWeight`, `uiWeight` | The six weights, and Campo's two defaults |
+| `cdnBase`, `phosphorVersion` | Where icons load from, and which Phosphor version |
+| `IconName`, `IconWeight` (types) | Every icon name and weight, for autocomplete |
+| `@campo-design/icons/names.json` | Every icon name, as JSON |
+
+Icon SVGs use `fill="currentColor"` and a square viewBox, so they take the
+color of their text. Size them with font size (`1em`), not with icon-specific
+values.
+
+## Adding an interface icon
+
+When a component needs an icon that isn't inlined, add its Phosphor file name to
+`UI_ICONS` in `scripts/build.js` and run `pnpm build`. The build fails if the
+name doesn't exist in Phosphor.
+
+## Updating Phosphor
+
+Phosphor is pinned to an exact version in `package.json`. Bumping it updates
+the CDN URLs, the inlined icons and the name types together. Renamed or removed
+icons then show up as type errors and build failures, not as blank icons.