Statamic Image Colors Laravel Package

Technical Evaluation

Architecture fit

• This is a Statamic addon on Laravel, not a framework-agnostic package. It attaches derived data to assets and exposes it through Antlers tags, an action, and a GraphQL type — which is the idiomatic shape for a Statamic addon and a good fit if the CMS layer is already Statamic.
• Storing everything under a single imagecolors key with colors, stamp and color is the right call: computed data is colocated with the asset, reads at render time are free (no per-request image processing), and the namespacing makes the addon's write surface auditable.
• The collision guard (back off if a blueprint field or an asset value named imagecolors already exists) is defensive and correct for a v1 addon, but it converts a potential data-clobbering bug into a silent no-op, which shifts the burden to operations.

Integration feasibility

• Installation is Composer-only, no schema migrations described. Integration cost is concentrated in template and GraphQL consumers, not infrastructure.
• Extraction appears to run via a command and an action — i.e., batch/off-request — which is the right model. Confirm whether it dispatches to a queue or runs synchronously in the request cycle before committing to large libraries.
• Requires an image-processing extension (GD or Imagick) and read access to the underlying asset bytes. If assets live on S3 or another remote disk, every extraction is a network fetch; verify throughput before a full-library backfill.

Technical risk

• Semver discipline is the headline risk. {{ hero:color }} and {{ hero:colors }} are removed in a 1.0.1 patch release. That is a breaking template change shipped under a patch version. Any consumer resolving ^1.0 gets hard render failures on upgrade. Pin the exact version and treat this as a major.
• Existing data may not carry over. Namespaced storage means colors previously written under old keys are likely orphaned, and assets that already carry an imagecolors value will now be skipped rather than sampled. Sites upgrading with real content need a backfill/repin plan, not just a deploy.
• Condition semantics flip silently. Conditions like {{ if hero:imagecolors:color:is_dark }} were always false and now evaluate correctly. That is a bug fix, but any template that shipped with a workaround — or that relied on the branch never rendering — will change output. This is a visual regression risk, not an error.
• Actions now fail loudly. Reporting "Colors extracted for 1 of 2 images" is better behavior, but partial failure will surface in editorial workflows that previously saw uniform success.
• Low-risk items: the README contrast correction and the removal of the Lucide credit are documentation/IP cleanups.

Key questions

1. Is there a documented migration or backfill command for assets whose colors were written under the pre-namespaced keys, or must editors re-pin manually?
2. Is 1.0.1 intentional for a breaking template-syntax change, and is a 2.0.0 planned or a compatibility alias for :color / :colors?
3. Where do skip and extraction-failure reasons get logged, and can that channel be routed to our monitoring rather than left in a file an operator has to grep?
4. What does stamp invalidate — does replacing an asset's file trigger re-extraction, or do pinned/stored colors go stale silently?
5. Is the pinned color permission-gated and revision-tracked, or can any editor with asset access overwrite a brand-critical color?
6. What is the render-time fallback when no color exists (skipped asset, extraction failure)? The docs' band-on-color example implies a dependency on a value that may legitimately be absent.
7. Does extraction run on a queue, and what is the expected wall-clock cost per image at typical asset sizes?

Integration Approach

Stack fit

• Laravel + Statamic, PHP 8.x, with GD or Imagick available in the runtime. The addon's surface is narrow and idiomatic: one Antlers tag, one action, one GraphQL type, one asset key. No service provider gymnastics, no custom fieldtype to register against existing blueprints.
• The GraphQL ImageColors type with the same three fields as the Antlers tag means headless and server-rendered consumers share one mental model — genuinely useful for teams running a hybrid front end.
• Main fit caveat: this only works if Statamic is the asset source of truth. If assets are brokered through a DAM or external CDN with its own metadata, the value lives in two places.

Migration path

• Pre-flight audit is mandatory and cheap:
  • Grep templates and partials for :color and :colors usage on asset URLs, including inside {{ if }} blocks.
  • Grep for imagecolors in blueprints, fieldsets, and existing asset meta to find collision candidates before they silently suppress extraction.
• Template rewrite is mechanical: {{ hero:color }} → {{ hero:imagecolors:color }}, {{ hero:colors }} → {{ hero:imagecolors:colors }}, and format variants via :color.
• Update any GraphQL queries and generated types to the ImageColors type.
• Plan the data step explicitly: run the extraction command, then reconcile the skip report. Assets reported as skipped for pre-existing imagecolors values need a decision — rename the conflicting field, or accept the asset as unmanaged.

Compatibility

• The collision guard is the compatibility story and the trap. An asset carrying an imagecolors value from a prior install will be treated as foreign and excluded — so the upgrade path is not "install and run," it's "audit, then install."
• Confirm the Statamic version floor before scheduling. Addon majors track Statamic majors, and this release gives no explicit statement.
• Antlers condition behavior now depends on properties rather than method calls. Any custom templates that wrapped these in workarounds should be re-tested rather than assumed improved.

Sequencing

1. Audit templates, blueprints and asset meta for :color / :colors usage and imagecolors collisions.
2. Pin the addon to an exact version in composer.json — do not float on ^1.0.
3. Upgrade in staging against a representative asset subset (mixed formats, mixed storage disks).
4. Run extraction; capture and review the skip/failure log before proceeding.
5. Rewrite templates and GraphQL queries; diff rendered output against staging baseline, paying particular attention to blocks whose conditions were previously always false.
6. Deploy, then backfill or hand-repin the assets that were skipped.
7. Only then open the action to editors, with a short note on what partial-failure messages mean.

Operational Impact

Maintenance

• Low steady-state cost: one asset key, one command, one action. The namespaced key means a future uninstall or migration has a single, well-defined thing to clean up — a real advantage over addons that scatter meta keys.
• The offsetting cost is version pinning. A breaking template change in a patch release means this addon cannot be safely auto-updated; it joins the small set of dependencies that need a human read of the changelog each release. Budget for that review cadence.

Support

• Support load shifts from developers to editors. The action now distinguishes total failure from partial success, which is correct but generates tickets phrased as "it says 1 of 2" from people who don't know why the second image failed. Publish a short runbook mapping the common causes (unreadable or unsupported format, oversized image, unreachable remote disk, collision with an existing key) to a resolution.
• The README correction on :contrast matters operationally: it measures against the solid color, not against text over the photograph. Anyone who built a hero on the old example has an accessibility problem, not just a cosmetic one. Treat the doc fix as a trigger to re-audit any shipped text-over-image component and check contrast properly against the actual backdrop.
• Skipped assets fail open — the page renders, the color is simply absent. That is the right default but it means nobody notices until someone sees a broken band. Add a periodic report of unmanaged assets rather than relying on log archaeology.

Scaling

• Color extraction is CPU-bound image decoding. Stored results make render scaling trivial; the batch is the only expensive operation. For libraries in the thousands, run the command off-peak, on a queue worker, with concurrency capped so it doesn't starve web workers.
• Remote disks turn extraction into a network-bound job. At scale that dominates; consider warming the cache for recently used assets first and letting the long tail run overnight.
• Because results are persisted with a stamp, repeat extraction should be incremental rather than a full re-scan — confirm that before scheduling a nightly job.

Failure modes

• Silent skip on collision. The most dangerous mode. Extraction is refused, only the log records why, and content ships with no color and no error. Requires active monitoring, not passive acceptance.
• Hard template errors. Removed :color / :colors syntax fails loudly at render. Painful but safe — this will be caught in staging, not production.
• Silent visual regressions from conditions. Previously-dead branches now render. Nothing errors; output simply changes. Only a visual diff catches this.
• Stale pinned colors. If an asset's image is replaced but stamp doesn't invalidate, the site keeps rendering the old color — potentially a brand color from a photo that no longer exists. Verify the invalidation path explicitly.
• Partial extraction. With the new partial-success behavior, a page can mix extracted and absent colors. Every consumer template needs a defined fallback rather than assuming the value exists.
• Missing color at render. Any band/overlay component keyed to the image color needs a neutral default; don't let the absence of the key degrade layout.

Ramp-up

• Editors: under 15 minutes. One action to run, one toggle to pin, and a new vocabulary around extraction failures. The pinned-color concept is intuitive and matches how editors already think about hero imagery.
• Developers: a couple of hours for anyone fluent in Statamic. The new tag shape, the :color format modifiers, the is_pinned / is_dark / contrast accessors, and the GraphQL type are all straightforward — the real time sink is the audit and the template rewrite, not learning the API.
• Plan one joint session where an editor and a developer walk the skip report together. That single conversation prevents most of the support tickets this release will otherwise generate.