Couleur Laravel Package

Technical Evaluation

Architecture fit. Couleur is a leaf dependency, not a framework citizen: no service provider, no facade, no config to publish, no migrations. That is the ideal shape for Laravel — zero boot cost, zero container coupling, and no deploy surface. It fits in an application-owned support/theming layer behind an adapter, and it fills a genuine gap: color logic for surfaces that never see a browser stylesheet (transactional email, PDF invoices, OG/social images, webhook card payloads, server-rendered theme variables, chart series). CSS Color 4 syntax support is the differentiator over the ad-hoc hex2rgb/lighten() helpers already in most codebases, but that claim is unverified against the spec and everything below depends on it being true.

Integration feasibility. composer require is the entire install. The only install-time gate is the PHP 8.2 floor — if any app or worker in the fleet runs 8.1, this is a hard stop, not a nuisance. MIT license clears legal. Because the package has 0 stars, 0 dependents, and one maintainer, feasibility includes a mandatory source read: the tree is small enough to audit end-to-end in under an hour, and you need to confirm the real FQCNs and method names rather than trusting documentation examples. Read the test suite too; if it does not exercise CSS Color 4 sample values, treat the library as untested code your team now owns.

Technical risk. The risks cluster in correctness, not performance:

• Gamut mapping. Out-of-sRGB OKLCH/Lab values need proper chroma reduction (CSS Color 4 §13 local-MINDE). Naive 0–255 clipping produces brand colors that visibly disagree with the browser. This is the go/no-go question and cannot be answered from the README.
• White point. D50 vs D65 in Lab/LCH conversions is a silent correctness bug — nothing errors, everything shifts subtly relative to design tooling or the spec.
• HSL lighten/darken is perceptually uneven. Replacing existing helpers will change output; that is a visual change requiring design sign-off, not a silent refactor.
• Parser coverage. Modern syntax (none channels, rgb(0 0 0 / 50%), deg/rad/turn) breaks regex-based parsers and will surface as confusing rejections in admin forms.
• Contrast semantics. Almost certainly WCAG 2.x ratios, not APCA, and unlikely to composite alpha correctly against an unknown background.
• Achromatic round-trip. Grays carry an arbitrary hue through HSL/OKLCH and can drift on serialize→parse.
• Supply chain and bus factor. One maintainer, no documented semver policy, no dependents to signal-test releases. The realistic failure mode is abandonment, not malice — but every upgrade must be treated as a reviewed change.

Key questions.

1. Does the parser accept real CSS Color 4 examples, including none, percentage alpha, and angle units — and fail cleanly on malformed input?
2. Does conversion implement proper gamut mapping, or clip? Which white point is assumed, and is chromatic adaptation exposed?
3. Do serialize→parse round-trips preserve value for achromatic colors and alpha-bearing colors?
4. What exactly do the "Laravel helpers" do — real Blade/helper integration, or documentation shorthand? (Planning assumption: none; pass prepared strings into views.)
5. Is there a release history, tag scheme, and responsive maintainer? Any real-world usage anywhere?
6. Does the contrast helper handle alpha compositing, or assume opaque inputs?
7. Which API calls return immutable value objects versus strings, and is the object safe to pass across layers? (Policy answer regardless: it isn't — the adapter owns it.)

Integration Approach

Stack fit. Compatible with any Laravel version on PHP 8.2+; no framework-version coupling exists to break. It belongs in console commands, queued jobs, mail builders, and theme-compilation listeners — not in request-path rendering. It complements, rather than replaces, Tailwind/CSS variables: PHP compiles tokens, the browser consumes them. Email and PDF clients are the surfaces where a PHP engine is not optional, so they set the compatibility bar, and that bar is plain hex/rgb, not oklch().

Migration path. Move from scattered helpers to a single app/Support/Color adapter with a deliberately tiny surface (parse, toHex, toCss, lighten, darken, contrast). Existing helper call sites delegate to the adapter, so signatures do not change and the vendor class never appears in models, API resources, Blade templates, or event payloads. Run a shadow phase: compute new tokens alongside old ones, log diffs, screenshot-diff generated themes per tenant behind a flag. Cut over when diffs are explained and signed off. The adapter is what makes this a one-afternoon reversal rather than a rewrite if the bet fails.

Compatibility. Three distinct boundaries, and only one is the framework:

• Runtime: PHP 8.2 floor; verify with composer why-not php 8.1 before committing.
• Browser: emit sRGB fallbacks first and gate oklch()/display-p3 behind @supports, since broad is not universal.
• Email/PDF clients: hex-only output; no L4 syntax leaves PHP for these surfaces.

Persist only strings (hex/CSS) and JSON token artifacts — never vendor objects.

Sequencing.

1. Audit gate (½ day). Read source and tests; build ~20 golden fixtures (achromatic gray, near-gamut-edge saturated, translucent, malformed, 3-digit, 8-digit alpha) and check parser behavior, gamut mapping, and contrast math against browser-computed values.
2. Pilot (1 day). One admin color input with a validation rule that normalizes input and rejects colors below the contrast policy. Blast radius: one form field. This is the cheapest possible signal on API ergonomics and correctness.
3. Theme compiler. Derive the token set at write time on tenant save, persist the artifact, and cache-key on theme:{tenant}:{sha1(hex)}:{schema_version}.
4. Server-rendered surfaces. Branded transactional email and PDF accents computed at send time with inline styles — the highest-value, lowest-risk proof point.
5. Design-system cutover. Only after golden files pass and design signs off on visual diffs.
6. Decision review. If step 1 fails on gamut mapping or round-trip fidelity, stop and either fork or reimplement ~200 lines behind the unchanged adapter.

Operational Impact

Maintenance. Budget this as an owned dependency from day one: pin the exact version (0.3.1, never ^ or *), mirror it privately with your conformance suite as the compatibility contract, and assign a named code owner. The adapter plus golden files are the entire mitigation budget; without them the cost of upstream abandonment or a subtly wrong release is a rewrite of every surface that touched color.

Support. There is no community corpus — no Stack Overflow answers, no issue history, no dependents to learn from. Any bug in color behavior is your team's to diagnose, and color bugs are expensive because they surface as customer complaints about brand drift rather than as exceptions. Document the adapter's contract and the golden-file update procedure before the second developer touches it.

Scaling. Compute cost is negligible provided tokens are compiled at write time and cached; the moment color math moves into a Blade template or a resource, it becomes per-render work with no upside. Real scaling concerns are artifact cardinality (tenants × token sets), cache invalidation keyed on the color value itself plus a schema version, and CDN caching of emitted theme CSS. Queue the compilation on tenant save rather than blocking the request.

Failure modes.

• Stale theme CSS after a brand-color change (cache key not derived from the value) — the class of bug that reproduces for exactly one customer.
• Brand-color drift where PHP gamut mapping disagrees with the browser.
• Gray round-trip drift in generated HSL/OKLCH tokens.
• Accessibility false negatives: a contrast helper that ignores alpha compositing lets an inaccessible color pass the save-time gate, which is worse than no gate because it creates false confidence.
• Uncaught parse exceptions in a request path — always try/catch, and treat parse failure as a validation error.
• Silent white-point or hue shifts after an unpinned upgrade.
• Abandonment, or a breaking release under a permissive constraint.

Ramp-up. The API is small; a mid-level developer is productive in a few hours. The real ramp-up is color-science literacy — gamut mapping, white points, WCAG ratio math, alpha compositing — which the package does not teach and cannot be assumed. Plan roughly one developer-day for the adapter plus validation pilot, one to two weeks for the theme compiler, email surfaces, and golden-file harness, and schedule design review explicitly: replacing hand-rolled lighten() helpers will change how existing themes look, and that conversation must happen before cutover, not after a customer notices.