Application Utils Core Laravel Package

Product Decisions This Supports

• Accessibility (WCAG) roadmap commitments. RGBAColor::setForceDark() / setForceLight() let us override the library's automatic luma-based contrast choice. This is the escape hatch we need for brand colors that sit near the mid-luma threshold where automated contrast picking is unreliable — the exact cases that fail AA contrast audits and generate accessibility tickets.
• Dark mode / theming strategy. Deciding between (a) maintaining hand-curated per-color text mappings, (b) shipping a design-token contrast table, or (c) computing contrast at runtime. This release makes (c) defensible in production: we get automation for the 90% case and a deterministic override for the 10% that designers or QA flag, without forking the library.
• Build vs. buy for color primitives. A "force dark/light text on this swatch" API is small but fiddly (luma coefficients, gamma, edge cases). Adopting an existing, actively maintained implementation is cheaper than owning it — this patch confirms the maintainer is still iterating on the contrast logic, which is the part we'd least want to own.
• Where the logic lives. Because overrides are per-RGBAColor instance and the companion methods let you remove/reset them, we can apply them at the point of rendering (badge/chip/status component, generated email, PDF template) rather than baking exceptions into a global theme config. That supports a per-surface decision: the same brand color can render differently in an email client than in the admin UI.
• Low-risk consumption of a patch release. Purely additive API in a 2.5.1 patch — no breaking changes, no deprecations, no migration work. Safe to adopt mid-sprint; can be evaluated in a spike branch without a version-bump negotiation.

When to Consider This Package

Adopt when several of these are true:

• You render text over user-, tenant-, or CMS-supplied colors (status badges, tags, category chips, avatars, chart legends, invoice/PDF line items) and contrast is currently guessed or hardcoded.
• You have an accessibility audit, VPAT, or procurement questionnaire that requires demonstrable contrast handling rather than "the designer picked white."
• You need deterministic output — the same color must always yield the same text color across web, email, and PDF surfaces, and you need an explicit override when it doesn't.
• You are willing to take a general-purpose utility dependency (application-utils-core) rather than a narrow color library; the contrast class is one of many concerns bundled in it.
• Your stack is PHP 8+ and you want framework-agnostic behavior — this is not Laravel-specific, so the same code works in queue workers, CLI generators, and non-Laravel services.

Look elsewhere or defer when:

• You only need hex↔RGB conversion or a one-off isLight() check — a handful of lines beats a broad dependency.
• You want Laravel-native ergonomics (config file, Blade directives, validation rules, facades). This gives you a plain PHP class; you'll write the wrapper.
• You are standardizing on design tokens with pre-computed contrast pairs (e.g., a token pipeline emitting --on-primary). Runtime luma detection is then redundant, and a single source of truth in the design system is preferable.
• Dependency-surface area is a hard constraint (strict SBOM/licensing review): confirm the full transitive footprint and license before committing.
• You need perceptual color spaces (OKLCH/CIELAB, APCA contrast) — luma-threshold heuristics, even with overrides, are not a substitute.

Watch item: the override API is new in this patch. Validate behavior in a spike against our actual brand palette and against edge cases (very saturated blues/reds, 50% gray) before removing any existing hand-tuned mappings.

How to Pitch It (Stakeholders)

To executives: This is a small, zero-risk upgrade to a utility library we use for color handling. It closes a known gap in our accessibility story: when the software automatically picks black or white text on a colored background, it can now be explicitly overridden for brand colors where the automatic choice is wrong. That converts contrast from a recurring QA-and-redesign loop into a one-line fix, which directly reduces accessibility remediation cost and supports the compliance commitments on the roadmap. The change is additive, has no breaking changes, and requires no migration.

To engineering: Patch release 2.5.1 on application-utils-core adds setForceDark() / setForceLight() to RGBAColor, plus companions to remove and reset luma overrides. This gives us an opt-out from automatic luma detection without forking or subclassing. Proposal: spike an onColor() helper on our badge/chip component that uses the override where design has flagged failures, keep the existing mappings until the spike clears our palette and edge cases, then retire them. No config or migration changes; the risk is a new-API surface (validate it) and the existing dependency footprint (unchanged).