Statamic Image Colors Laravel Package

Product Decisions This Supports

• Feature: editor-driven accent colors without a design bottleneck. With pinning (:is_pinned) plus an auto-extracted palette, editors can accept the sampled color or override it. That is the difference between a feature that ships to non-designers and one that generates "can you set the color for me" tickets.
• Feature: contrast-aware UI branching. Conditions now actually evaluate (imagecolors:color:is_dark, color:contrast >= 4.5), so you can decide layout and text treatment at render time instead of hardcoding it per entry. This is the single most valuable item in the release — it turns a color picker into a theming primitive.
• Roadmap: accessibility guardrails. The corrected docs matter more than they look. :contrast measures against the solid color, not the photo, so it can support "put the title on a color band" but cannot back a "WCAG-safe text over image" claim. Scope the roadmap on what the data actually proves.
• Build vs buy: buy. Color extraction is a small, well-bounded capability. Rebuilding it means owning quantization, caching, invalidation on asset replace, and the storage collision problem below. Not a differentiator worth in-house time.
• Use cases: hero and card imagery on editorial sites, per-entry theming, headless delivery via the ImageColors GraphQL type, batch backfill on existing asset libraries.
• Operational readiness: the extraction action now fails loudly and reports partial success ("Colors extracted for 1 of 2 images"). That makes it trustworthy in a scheduled or bulk run, where the previous always-success message would have silently hidden broken images.

When to Consider This Package

Adopt when all of these hold:

• You are on Statamic and colors need to derive from assets that editors upload, not from a fixed palette.
• You want editors to pin a brand color and still get a fallback when they don't.
• You render in Antlers or consume GraphQL — both are covered by the ImageColors type.
• Your imagecolors key is free. The addon deliberately refuses to touch assets where that key already carries a value it did not write. Good citizenship, but it is a hard gate: audit existing blueprints and asset data before rollout or you will get a silent no-op with the reason buried in the log.

Look elsewhere, or defer, when:

• You need text-over-photo contrast guarantees. You don't have them. Only solid-color contrast.
• You need edge/CDN-time extraction or a service that scales independently of PHP request cycles.
• You already shipped {{ hero:color }} / {{ hero:colors }}. Those are removed in a patch release. If any template uses them, that is a silent empty render, not an error. Audit and migrate first.
• You require strict semver. A breaking template rename plus a storage-layout change in 1.0.1 signals the API surface is still settling. Pin the version and budget for churn.
• You are not on Statamic, or you need extraction from non-asset sources.

How to Pitch It (Stakeholders)

For executives: A small Statamic addon that pulls a usable color palette out of each uploaded image so editors can theme pages without a designer in the loop. Version 1.0.1 fixes a real defect (conditional color logic never fired), makes bulk extraction report failures honestly, and corrects documentation that overstated its accessibility guarantees. Cost is low; the value is removing a recurring design-request queue. Caveat worth stating plainly: it's still a young package — the 1.0.1 release renamed template tags — so treat it as pin-and-monitor, not load-bearing infrastructure.

For engineering:

• Storage is namespaced under a single imagecolors asset key holding colors, stamp, and pinned color. The addon refuses to sample or overwrite when that key is occupied by foreign data — collision-safe, but validate your existing blueprints and asset data before enabling.
• Template surface is now {{ hero:imagecolors }} with :color, :colors, :is_pinned. The standalone {{ hero:color }} and {{ hero:colors }} tags are gone; sweep templates for them. GraphQL mirrors this with an ImageColors type.
• :contrast is measured against the solid color, not the photograph. Don't build accessibility logic on the wrong assumption — this was previously mis-documented.
• Conditions work because color values expose properties rather than methods (Antlers won't call methods inside if). No action needed, but it's the reason dark-mode and contrast branching now behaves.
• The Extract colors action now fails when nothing was readable and reports partial counts otherwise, with reasons logged. Wire alerting to the action result if extraction runs on a schedule.
• No third-party artwork or attribution obligations.