Iris Laravel Package

Product Decisions This Supports

• Theme and design-token generation without a design-system dependency. Iris converts between Hex, Hexa, RGB, RGBA, HSL, HSLA, HSV, CMYK, and OKLCH, and manipulates them (lighten, darken, saturate, spin, mix, tint, shade, fade, fadeIn, fadeOut). This is exactly the server-side primitive needed for "derive a full palette from one brand color" features — a recurring request in white-label, multi-tenant, and theming roadmaps that is otherwise hand-rolled and reinvented per project.
• Brand-configurable UI as a product feature, not a config chore. Tenants/admins pick a brand color; the app deterministically generates hover states, borders, disabled variants, and chart series. isLight()/isDark() supports automatic foreground/text contrast selection, which removes a common class of "unreadable button" support tickets and QA cycles.
• Gradient and scale generation (->gradient($colorB, $steps), multi-pivot). Enables data-visualization palettes, heatmaps, progress/severity scales, and generated design tokens — all server-side, all reproducible in tests. This is a recent, actively added capability (2025-12-05 changelog), which is a positive signal on roadmap alignment.
• Robust input normalization via Factory::init(). User-supplied color strings (from forms, imports, or a mixed DB column) get resolved to the correct type rather than throwing. That is a validation/normalization concern PMs usually end up paying for twice — once in the form layer, once in the render layer.
• OKLCH support is a forward-looking roadmap bet. Perceptually uniform color is where CSS Color Level 4, modern design tooling, and accessible-palette work are heading. Having toOklch() on every class means a "generate perceptually even palettes" feature is a configuration change, not a project.
• Roadmap signal: "build vs. buy" resolves toward buy here. The conversion math (especially OKLCH and CMYK rounding — a bug fixed in the changelog) is low-value, high-fiddliness work. MIT license + small API surface means the buy decision is reversible; you can vendor or fork if needed.
• Explicitly out of scope, plan accordingly. No WCAG contrast-ratio method, no image/palette extraction, no Laravel service provider or facade, no persistence. Any accessibility-compliance feature must be built on top, not assumed.

When to Consider This Package

Adopt when:

• You have a PHP/Laravel app that must generate or transform colors server-side: theming, white-labeling, tenant branding, email/PDF templates, generated CSS variables, chart or badge palettes.
• You need multi-format interoperability (CSS strings in, Hex/RGB/OKLCH out) and want a tested, MIT-licensed conversion layer instead of in-house math.
• Your requirement is deterministic, unit-testable palette derivation — not color picking UI (this library is not a UI component).
• You're on PHP 8.1+ and are comfortable with a pure-computation dependency (no I/O, no network, negligible runtime and security surface).
• You need OKLCH now, or will within a year, and want to avoid a later migration.

Look elsewhere / build thin when:

• Accessibility compliance is a hard requirement. There is no contrast-ratio or APCA implementation; isLight()/isDark() is a heuristic, not a WCAG verdict. Expect to add a contrast utility on top (or pair with a dedicated accessibility library) and say so upfront.
• Ecosystem-proofing matters more than fit. 124 stars and 0 dependents is a weak adoption signal. Single-maintainer, no downstream users means bus-factor risk. Mitigate by pinning versions, vendoring/forking (small surface makes this cheap), or accepting the risk explicitly.
• You need OKLCH alpha or relative color syntax (oklch(from green l c h)) — documented as unsupported; alpha is silently ignored. Don't assume round-tripping preserves alpha through OKLCH.
• Client-side/DOM color work dominates. If colors are manipulated in the browser, a JS library plus CSS custom properties is the better architectural fit; use Iris only for the server-rendered/bootstrap portion.
• You need designer-grade palette generation (harmony rules, perceptual distance constraints, image extraction). Iris gives you the primitives; the palette policy is yours to build.
• You need a Laravel-idiomatic integration (config file, facade, validation rule, Blade helpers). None ship with the package — budget a thin wrapper (~a day) as part of adoption, and treat that wrapper as the stable internal interface so a future swap is contained.

Adoption checklist before committing: pin an exact version in composer.json; confirm the PHP 8.1 floor matches your platform roadmap; write characterization tests for the specific conversions you depend on (alpha handling especially, given the recent breaking changes); and record the fallback plan (fork-and-own) in the technical decision record.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT), low-risk library that unblocks a class of theming and branding features we'd otherwise build and maintain ourselves — per-customer color customization, automatically derived UI states, and chart palettes. It's a pure calculation library: no data storage, no external services, no security surface, so the compliance and privacy review is trivial. Total cost is roughly a day of integration plus a thin internal wrapper; the alternative is ad-hoc color math scattered across controllers and views, which is the more expensive option over time. The main caveat is maintenance depth (a single maintainer, limited adoption), which we mitigate by pinning the version and keeping our wrapper thin enough to fork if needed — a small, bounded risk for a dependency this narrow.

To engineering: Adopt ozdemirburak/iris behind a single internal service class rather than calling it directly from controllers or Blade. It gives us tested conversions across nine color spaces (including OKLCH, which we want for future palette work), a Factory that normalizes unpredictable user input, and the manipulation primitives (lighten, mix, gradient, fade) we keep reimplementing. Constraints to design around: PHP 8.1+ minimum, no Laravel service provider or validation rule (we write both), no WCAG contrast calculation (we add one if accessibility is in scope), and OKLCH ignores alpha. Recent releases were breaking (PHP 8.1 floor, PHPUnit 10/11, alpha-preservation fixes), so pin the version and cover our specific conversions with tests before upgrading.

Bottom line: buy the conversion math, build the design policy, and wrap the dependency so the decision stays reversible.