# Perler Color Palette Sources

## Summary

- Total colors: 103
- Confidence counts: 95 high, 8 medium, 0 low
- Main RGB/HEX source: `maxcleme/beadcolors` Perler CSV
- Main official verification source: Perler `Shop by Color` collection and individual Perler product pages
- Structured SKU field: 103 unique values copied from the existing source-backed `notes` entries
- Direct RGB source type in `src/data/perlerColors.json`: `open_source`
- Runtime use: the homepage loads all 103 records before its first demo, upload, or starter-pattern generation
- Known limitations: Perler official pages verify color names, SKU-style product codes, brand, and availability, but they do not publish an official machine-readable RGB/HEX standard. The RGB values are practical digital approximations from the open-source beadcolors palette. Real bead color can vary by lighting, batch, and display.

## Sources

### Perler Shop by Color

- URL: https://perler.com/collections/shop-by-color
- Product JSON checked: https://perler.com/collections/shop-by-color/products.json?limit=250
- Type: official
- Notes: Used on 2026-07-07 to confirm current Perler color names, product handles, vendor, and SKU-style codes where available. This source was not used for RGB sampling because product photos and swatches are affected by lighting, packaging, and image processing.

### Perler Individual Product Pages

- Example URL: https://perler.com/products/1-000-perler-beads-red
- Type: official
- Notes: Used as per-color official corroboration in each JSON object's `source` field when the open-source CSV SKU matched a current Perler product. Product pages link to Perler's downloadable color reference guide, but the guide was not directly harvested for RGB values.

### maxcleme/beadcolors Perler CSV

- URL: https://raw.githubusercontent.com/maxcleme/beadcolors/master/raw/perler.csv
- Repository: https://github.com/maxcleme/beadcolors
- Type: open_source
- Notes: Main RGB/HEX source. The CSV contains Perler SKU-style codes, names, RGB triplets, and contributor labels. These values were converted to uppercase HEX and kept only for Perler rows.

### Reddit r/beadsprites Community Thread

- URL: https://www.reddit.com/r/beadsprites/comments/csrppb/scientific_artkal_perler_rgb_colors_the_bead/
- Type: community
- Notes: Reviewed as a community reference for the older "scientific" RGB spreadsheet. It is useful context, but it covers a smaller legacy palette and was not used as the main source for the final JSON.

### Pixel Pattern Perler Reference

- URL: https://www.pixel-pattern.net/perler-bead-colors/
- Type: community
- Notes: Reviewed as a public converter/reference that points users toward the beadcolors community reference. It was treated as supporting context, not as an independent authority.

## Source Decisions

- Official Perler sources were preferred for brand, color names, product handles, and SKU-style codes.
- RGB/HEX values came from `maxcleme/beadcolors` because no official Perler RGB/HEX table was found.
- The structured `sku` field was copied from each record's existing `SKU 80-#####` note. No SKU was inferred from a color name or generated to fill a gap.
- `sourceType` is `open_source` for all entries because it describes the direct source of the RGB/HEX value.
- `confidence` is `high` when the CSV SKU matched a current Perler Shop by Color product on 2026-07-07.
- `confidence` is `medium` when the color appears in the open-source Perler CSV but did not match the current Perler Shop by Color product JSON by SKU on 2026-07-07.
- No `low` confidence colors are included because no values were inferred from product photos or color-card images.

## Data Contract And Runtime Use

- Every record keeps `id`, `brand`, `name`, `sku`, `hex`, `rgb`, `source`, `sourceType`, `confidence`, and `notes`.
- `sku` is required, must match `80-#####`, must be unique, and must match the SKU already recorded in `notes`.
- The runtime maps records in stable JSON order to `{ name, code: sku, hex, rgb, n: index + 1 }` and assigns the result to `BRAND_PALETTES.perler`.
- Normal demo, upload, and manual generation use a maximum of 24 colors. Starter patterns keep their configured 6-8 color limits, with candidates selected from the full 103-record palette before the existing second matching pass.
- If the JSON request, parse, record-count check, or runtime field validation fails, the generator uses the explicit nine-color fallback and shows a persistent limited-palette notice. Generation, PNG export, and the browser Print Guide remain available in that state.

## Name Normalization

| CSV Name | Final Name | Reason | Confidence |
|---|---|---|---|
| Blueberry Creme | Blueberry Cream | Perler current product name uses "Cream". | high |
| Carnation Pink | Carnation | Perler current product name uses "Carnation". | high |
| Green | Bright Green | Perler current product SKU `80-19080` uses "Bright Green". | high |
| Grey | Gray | Perler current product name uses "Gray". | high |

## Conflicts / Uncertain Colors

| Color Name | Issue | Final Decision | Confidence |
|---|---|---|---|
| Celery | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Lemon | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Mocha | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Neon Blue | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; likely special/neon or discontinued; review before enabling in a default solid palette. | medium |
| Periwinkle Blue | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Slime | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Spice | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |
| Sunflower | Not found in current Perler Shop by Color JSON by SKU. | Kept from beadcolors; needs availability review before treating as current. | medium |

## Omitted Official Special / Non-Solid Entries

These Perler official entries were found in current Shop by Color data but were not included because they are transparent, mixed, striped, glow, glitter, pearl, or metallic materials and no stable solid RGB value was available from the selected source:

- Clear
- Clear Blue
- Glitter Mix
- Glow in the Dark Green
- Glow in the Dark Mix
- Gold Metallic
- Metallic Mix
- Multi Mix
- Neon Mix
- Pearl Silver
- Zebra Stripe