color-name-list 13.13.0 → 13.14.0

package/CONTRIBUTING.md

@@ -7,17 +7,26 @@ interactions with the project.
 
 ## Adding colors
 
-1. Only update the `src/colornames.csv` file and run `npm run test`
+1. Only update the `src/colornames.csv` file and run `npm test`.
 2. Make sure the names you commit are not racist or offensive or a protected
    brand name (No Facebook Blue, Coca Cola Red etc.., no nationality or tan etc..).
 3. Read the "Rules for new color names" directly below
 4. Make sure that neither name nor hex value of your added colors are already
-   in use. `npm run test` will test that for you.
-5. Update the `README.md` with the source of your colors, unless you invented
-   that color, in this case add yourself to the contributors in the `README.md`
+  in use. `npm test` will test that for you.
+5. Do not edit generated files. Do not commit changes to `README.md`,
+  `changes.svg` or anything in `dist/`.
+6. Add the source of your colors in the Pull Request description.
+  Maintainers will update documentation if needed.
 
 **We use automated semantic versioning** make sure to use git cz (or npm run commit).
 
+## Generated files and CI
+
+- PRs run `npm ci`, `npm run build`, and `npm test` in CI.
+- CI may update `README.md` and `changes.svg` automatically and push
+  to your PR branch.
+- Do not include generated files (`dist/`, `README.md`, `changes.svg`) in commits.
+
 ## Rules for new color names
 
 - No duplicate names or hex values.
@@ -41,6 +50,7 @@ interactions with the project.
   **feat(colors): Add fantastic new colors names.** rather then
   feat(colors): Added new names.
 - Make sure to run `npm run test` before committing.
+  For color name changes this is the only command you need locally.
 
 ### Attribution
 

package/README.md

@@ -27,7 +27,6 @@ A meticulously curated collection of __29985__ unique color names, sourced from
   | <a href="#usage-">Usage</a>
   | <a href="#cdn-">CDN</a>
   | <a href="#api-">Public Rest API</a>
-  | <a href="#usage-js-">Usage JS/Java/Kotlin/C#</a>
   | <a href="#sources-">Name Sources</a>
   | <a href="#latest-color-names-">Latest Color Names</a>
   | <a href="#costs--sponsors">Sponsors</a>
@@ -62,7 +61,18 @@ Please review the [naming rules](CONTRIBUTING.md) before contributing!
 ### Contributing via Git 🫱🏽‍🫲🏻
 
 To contribute via Git, edit the `src/colornames.csv` file
-and ensure it builds correctly (`npm run ci && npm run build`).
+and ensure tests pass locally (`npm test`).
+
+See the full guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+CI notes:
+
+- Pull Requests run `npm ci`, `npm run build`, and `npm test`.
+- CI auto-updates `README.md` and `changes.svg` if needed and pushes to your PR branch.
+- Do not commit generated files (`dist/`, `changes.svg`).
+- For color name changes, only submit updates to `src/colornames.csv`.
+- No need to run `npm run build` locally; CI generates outputs.
+- Optional locally: `npm run lint:markdown` to match CI markdown checks.
 
 ## Color Count: __29985__ 🎉
 
@@ -80,23 +90,19 @@ color space: [Visualization](https://codepen.io/meodai/full/zdgXJj/)
 
 ## Usage 📖
 
+### Docs
+
+- JS/TS: [docs/usage-js.md](docs/usage-js.md)
+- Java/Kotlin: [docs/usage-java-kotlin.md](docs/usage-java-kotlin.md)
+- C#: [docs/usage-csharp.md](docs/usage-csharp.md)
+- Rust: [docs/usage-rust.md](docs/usage-rust.md)
+
 ### Consuming the list
 
 The list is available in [multiple formats](https://app.unpkg.com/color-name-list/files/dist),
 or you can use the [public REST API](#api-), making it easy to integrate into
 your project.
 
-### Node.js Installation 📦
-
-__Size Warning (1.14 MB)__: For browser usage,
-consider the [public rest API](#api-)
-
-```shell
-npm install color-name-list --save
-```
-
-or `yarn add color-name-list`
-
 ### CDN 🌍
 
 #### All Names 📚
@@ -122,6 +128,22 @@ or `yarn add color-name-list`
 / [SCSS](https://unpkg.com/color-name-list/dist/colornames.bestof.scss)
 / [CSS](https://unpkg.com/color-name-list/dist/colornames.bestof.css)
 
+### Usage JS 📦
+
+__Size Warning (1.14 MB)__: For browser usage,
+consider the [public rest API](#api-).
+
+Minimal example:
+
+```javascript
+import { colornames } from 'color-name-list';
+
+const white = colornames.find((c) => c.hex === '#ffffff');
+console.log(white?.name); // => white
+```
+
+More examples: see `docs/usage-js.md`.
+
 ### API 🃏
 
 To simplify access, we provide a free and public REST API for all color names
@@ -142,47 +164,6 @@ generates excessive traffic, you may be asked to become a sponsor.
 You are welcome to self-host the API—it's easy to deploy on Heroku and relies
 only on a few dependencies: [Color-Name-API](https://github.com/meodai/color-name-api)
 
-### Usage JS ⌨
-
-__Size Warning (1.16 MB)__: For browser usage,
-consider the [public rest API](#api-)
-
-#### Exact Color
-
-```javascript
-import { colornames } from 'color-name-list';
-
-let someColor = colornames.find((color) => color.hex === '#ffffff');
-console.log(someColor.name); // => white
-
-let someNamedColor = colornames.find((color) => color.name === 'Eigengrau');
-console.log(someColor.hex); // => #16161d
-```
-
-#### Closest Named Color
-
-With 16,777,216 possible RGB colors, you may want to use a library such as
-[nearest-color] or [ClosestVector] to find the closest named color.
-
-```js
-import nearestColor from 'nearest-color';
-import { colornames } from 'color-name-list';
-
-// nearestColor expects an object {name => hex}
-const colors = colornames.reduce((o, { name, hex }) => Object.assign(o, { [name]: hex }), {});
-
-const nearest = nearestColor.from(colors);
-
-// get closest named color
-nearest('#f1c1d1'); // => Fairy Tale
-```
-
-__Note__: For greater visual accuracy, consider using [DeltaE] or the above
-approach with [ciecam02] instead of RGB.
-
-[DeltaE]: https://github.com/zschuessler/DeltaE
-[ciecam02]: https://github.com/baskerville/ciecam02
-
 ### Building 🔨
 
 ```shell
@@ -191,145 +172,17 @@ npm install && npm run build
 
 See [package.json](package.json#L6) for details.
 
-### Usage Java/Kotlin ⌨
+### Java/Kotlin, C#, Rust
 
-Java/Kotlin support is provided by:
-[UwUAroze/Color-Names](https://github.com/UwUAroze/Color-Names).
-See the repository for more, or use the basics below:
+Moved to docs:
 
-#### Importing - Gradle.kts
-
-```kts
-repositories {
-      maven("https://jitpack.io")
-}
-
-dependencies {
-      implementation("me.aroze:color-names:1.0.4")
-}
-```
-
-#### Importing - Maven
-
-```xml
-<repository>
-  <id>jitpack.io</id>
-  <url>https://jitpack.io</url>
-</repository>
-
-<dependency>
-  <groupId>me.aroze</groupId>
-  <artifactId>color-names</artifactId>
-  <version>1.0.4</version>
-</dependency>
-```
-
-#### Closest named color - Java
-
-```java
-public ColorNames colorNames = new ColorNameBuilder()
-  .loadDefaults()
-  .build();
-
-String fromHex = colorNames.getName("#facfea"); // "Classic Rose"
-String fromRGB = colorNames.getName(224, 224, 255); // "Stoic White"
-String fromColor = colorNames.getName(new Color(255, 219, 240)); // "Silky Pink"
-```
-
-#### Closest named color - Kotlin
-
-```kt
-val colorNames = ColorNameBuilder()
-  .loadDefaults()
-  .build()
-
-val fromHex = colorNames.getName("#facfea") // "Classic Rose"
-val fromRGB = colorNames.getName(224, 224, 255) // "Stoic White"
-val fromColor = colorNames.getName(Color(255, 219, 240)) // "Silky Pink"
-```
-
-### Usage C# ⌨
-
-C# support is provided by:
-[vycdev/ColorNamesSharp](https://github.com/vycdev/ColorNamesSharp)
-See the repository for more details; basic usage is below:
-
-The library is available as a [nuget package](https://www.nuget.org/packages/ColorNamesSharp)
-
-#### Creating the instance
-
-```csharp
-ColorNames colorNames = new ColorNamesBuilder()
-  .Add("Best Blue", "#3299fe") // Add your own custom colors
-  .LoadDefault() // Load the default color list
-  .AddFromCsv("path/to/your/colorlist.csv") // Add a custom color list from a csv file
-  .Build(); // Get a new ColorNames instance that includes all the colors you've added
-```
-
-#### Getting a fitting color name
-
-```csharp
-NamedColor customNamedColor = new("Custom Named Color", 50, 153, 254);
-
-// You can directly get the name of the color as a string
-string colorNameFromHex = colorNames.FindClosestColorName("#facfea"); // Classic Rose
-string colorNameFromRgb = colorNames.FindClosestColorName(224, 224, 255); // Stoic White
-string colorNameFromNamedColor = colorNames.FindClosestColorName(customNamedColor); // Best Blue
-
-// Or similarly you can get the NamedColor object
-NamedColor namedColorFromHex = colorNames.FindClosestColorName("#facfea"); // Classic Rose
-NamedColor namedColorFromRgb = colorNames.FindClosestColorName(224, 224, 255); // Stoic White
-NamedColor namedColorFromNamedColor = colorNames.FindClosestColorName(customNamedColor); // Best Blue
-
-// Or a random color
-NamedColor randomColor = colorNames.GetRandomNamedColor();
-```
+- [docs/usage-java-kotlin.md](docs/usage-java-kotlin.md)
+- [docs/usage-csharp.md](docs/usage-csharp.md)
+- [docs/usage-rust.md](docs/usage-rust.md)
 
 ### Usage Rust
 
-Rust support is provided by
-[philocalyst/color-names](https://github.com/philocalyst/color-names).
-You can add it to your rust project with `cargo add colorsnamed`. See the
-repository for more details. Basic usage is below.
-
-#### Choosing colors
-
-```rust
-use colorsnamed;
-
-let black = colorsnamed::Basic::Black;
-let teal = colorsnamed::Basic::Teal;
-let another = colorsnamed::Xkcd::Tea;
-```
-
-#### Getting colors
-
-```rust
-use colorsnamed;
-
-// Get the relevant hex code
-let red = colorsnamed::Basic::Red;
-let hex = red.hex();
-
-// Figure out if there is a matching color for a hex code!
-let ex: colorsnamed::Basic = hex.try_into().unwrap();
-```
-
-#### Converting colors
-
-```rust
-use colorsnamed;
-use colors;
-use rgb::Rgb;
-
-// Convert to the represention of your colorspace of choice.
-let correct_color = red.color::<colors::Srgb>();
-
-let red = colorsnamed::Basic::Red;
-
-// Get the RGB representation
-let rgb: Rgb = red.rgb();
-```
+See [docs/usage-rust.md](docs/usage-rust.md).
 
 ## Sources 🗒
 
@@ -466,11 +319,6 @@ so we can address them promptly.
 [Color Distribution]: https://codepen.io/meodai/full/zdgXJj/
 [Twitter Bot]: https://twitter.com/color_parrot
 
-<!-- 3r party libraries & tools -->
-
-[ClosestVector]: https://github.com/meodai/ClosestVector
-[nearest-color]: https://github.com/dtao/nearest-color
-
 <!-- people -->
 
 [Ichatdelune]: https://www.reddit.com/user/Ichatdelune

package/docs/usage-csharp.md

@@ -0,0 +1,38 @@
+# C# Usage
+
+C# support is provided by
+[vycdev/ColorNamesSharp](https://github.com/vycdev/ColorNamesSharp).
+The library is available as a
+[NuGet package](https://www.nuget.org/packages/ColorNamesSharp).
+
+## Creating the instance
+
+```csharp
+ColorNames colorNames = new ColorNamesBuilder()
+  .Add("Best Blue", "#3299fe") // Add your own custom colors
+  .LoadDefault() // Load the default color list
+  .AddFromCsv("path/to/your/colorlist.csv") // Add a custom color list from a csv file
+  .Build(); // Get a new ColorNames instance that includes all the colors you've added
+```
+
+## Getting a fitting color name
+
+```csharp
+NamedColor customNamedColor = new("Custom Named Color", 50, 153, 254);
+
+// You can directly get the name of the color as a string
+string colorNameFromHex = colorNames.FindClosestColorName("#facfea"); // Classic Rose
+string colorNameFromRgb = colorNames.FindClosestColorName(224, 224, 255); // Stoic White
+string colorNameFromNamedColor = colorNames.FindClosestColorName(customNamedColor); // Best Blue
+
+// Or similarly you can get the NamedColor object
+NamedColor namedColorFromHex = colorNames.FindClosestColorName("#facfea"); // Classic Rose
+NamedColor namedColorFromRgb = colorNames.FindClosestColorName(224, 224, 255); // Stoic White
+NamedColor namedColorFromNamedColor = colorNames.FindClosestColorName(customNamedColor); // Best Blue
+
+// Or a random color
+NamedColor randomColor = colorNames.GetRandomNamedColor();
+```
+
+See the upstream project for more details and updates:
+[vycdev/ColorNamesSharp](https://github.com/vycdev/ColorNamesSharp)

package/docs/usage-java-kotlin.md

@@ -0,0 +1,58 @@
+# Java / Kotlin Usage
+
+Java/Kotlin support is provided by
+[UwUAroze/Color-Names](https://github.com/UwUAroze/Color-Names).
+
+## Gradle (Kotlin DSL)
+
+```kts
+repositories {
+  maven("https://jitpack.io")
+}
+
+dependencies {
+  implementation("me.aroze:color-names:1.0.4")
+}
+```
+
+## Maven
+
+```xml
+<repository>
+  <id>jitpack.io</id>
+  <url>https://jitpack.io</url>
+</repository>
+
+<dependency>
+  <groupId>me.aroze</groupId>
+  <artifactId>color-names</artifactId>
+  <version>1.0.4</version>
+</dependency>
+```
+
+## Closest Named Color (Java)
+
+```java
+public ColorNames colorNames = new ColorNameBuilder()
+  .loadDefaults()
+  .build();
+
+String fromHex = colorNames.getName("#facfea"); // "Classic Rose"
+String fromRGB = colorNames.getName(224, 224, 255); // "Stoic White"
+String fromColor = colorNames.getName(new Color(255, 219, 240)); // "Silky Pink"
+```
+
+## Closest Named Color (Kotlin)
+
+```kt
+val colorNames = ColorNameBuilder()
+  .loadDefaults()
+  .build()
+
+val fromHex = colorNames.getName("#facfea") // "Classic Rose"
+val fromRGB = colorNames.getName(224, 224, 255) // "Stoic White"
+val fromColor = colorNames.getName(Color(255, 219, 240)) // "Silky Pink"
+```
+
+See the upstream project for more details and updates:
+[UwUAroze/Color-Names](https://github.com/UwUAroze/Color-Names)

package/docs/usage-js.md

@@ -0,0 +1,81 @@
+# JavaScript / TypeScript Usage
+
+This guide shows how to use the color list from JavaScript and
+TypeScript projects. It covers ESM and CommonJS usage and finding the
+closest named color.
+
+## Install
+
+```sh
+npm install color-name-list
+```
+
+## Data Shape
+
+```ts
+type ColorName = { name: string; hex: string };
+```
+
+## ESM (Node/Browser Bundlers)
+
+```js
+import { colornames } from 'color-name-list';
+
+const white = colornames.find((c) => c.hex === '#ffffff');
+console.log(white.name); // => white
+
+const eigengrau = colornames.find((c) => c.name === 'Eigengrau');
+console.log(eigengrau?.hex); // => #16161d
+```
+
+## CommonJS (require)
+
+```js
+// When required, the package returns the array of color objects directly
+const colornames = require('color-name-list');
+
+const white = colornames.find((c) => c.hex === '#ffffff');
+console.log(white.name); // => white
+```
+
+## Find the Closest Named Color
+
+With 16,777,216 possible RGB colors, you may want to use a helper like
+`nearest-color` or `ClosestVector`.
+
+```js
+import nearestColor from 'nearest-color';
+import { colornames } from 'color-name-list';
+
+// nearestColor expects an object { name => hex }
+const colors = colornames.reduce((o, { name, hex }) => Object.assign(o, { [name]: hex }), {});
+const nearest = nearestColor.from(colors);
+
+// Get closest named color
+nearest('#f1c1d1'); // => Fairy Tale
+```
+
+Note: For better visual accuracy, consider DeltaE or using CIECAM02
+instead of raw RGB distance:
+
+- [DeltaE](https://github.com/zschuessler/DeltaE)
+- [CIECAM02](https://github.com/baskerville/ciecam02)
+
+## Subsets and Performance Tips
+
+- Best-of subset (smaller list):
+  - ESM: `import { colornames as bestof } from 'color-name-list/bestof'`
+  - UMD: `https://unpkg.com/color-name-list/dist/colornames.bestof.umd.js`
+- Short subset (< 13 characters, best-of filtered): `dist/colornames.short.*`
+- For browsers, prefer the public API for payload-sensitive scenarios:
+  [Color Name API](https://github.com/meodai/color-name-api)
+
+## CDN (Reproducible)
+
+- Latest: `https://unpkg.com/color-name-list/dist/colornames.min.json`
+- Pinned: `https://unpkg.com/color-name-list@<version>/dist/colornames.min.json`
+
+## Types
+
+The package ships ESM. For TypeScript projects, you can declare the data
+shape as shown above or infer it directly from usage.

package/docs/usage-rust.md

@@ -0,0 +1,51 @@
+# Rust Usage
+
+Rust support is provided by
+[philocalyst/color-names](https://github.com/philocalyst/color-names).
+Add it with:
+
+```sh
+cargo add colorsnamed
+```
+
+## Choosing colors
+
+```rust
+use colorsnamed;
+
+let black = colorsnamed::Basic::Black;
+let teal = colorsnamed::Basic::Teal;
+let another = colorsnamed::Xkcd::Tea;
+```
+
+## Getting colors
+
+```rust
+use colorsnamed;
+
+// Get the relevant hex code
+let red = colorsnamed::Basic::Red;
+let hex = red.hex();
+
+// Figure out if there is a matching color for a hex code!
+let ex: colorsnamed::Basic = hex.try_into().unwrap();
+```
+
+## Converting colors
+
+```rust
+use colorsnamed;
+use colors;
+use rgb::Rgb;
+
+// Convert to the representation of your colorspace of choice.
+let correct_color = red.color::<colors::Srgb>();
+
+let red = colorsnamed::Basic::Red;
+
+// Get the RGB representation
+let rgb: Rgb = red.rgb();
+```
+
+See the upstream project for more details and updates:
+[philocalyst/color-names](https://github.com/philocalyst/color-names)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "color-name-list",
-  "version": "13.13.0",
+  "version": "13.14.0",
   "description": "long list of color names",
   "main": "dist/colornames.json",
   "browser": "dist/colornames.umd.js",

package/scripts/build.js

@@ -288,8 +288,8 @@ fs.writeFileSync(
       `__${((colorsSrc.entries.length / (256 * 256 * 256)) * 100).toFixed(2)}%__`
     )
     .replace(
-      // update file size
-      /\d+(\.\d+)? MB\)__/, // no global to only hit first occurrence
+      // update file size (update all occurrences)
+      /\d+(\.\d+)? MB\)__+/g,
       `${(
         fs.statSync(path.normalize(`${baseFolder}${folderDist}${fileNameSrc}.json`)).size /
         1024 /