Pinion Ui Laravel Package

Product Decisions This Supports

• Accessibility as a shipped, measurable guarantee — not a backlog item. v0.25.2 fixes a checked <x-toggle> that failed contrast on the achromatic Tonal theme (signal / signal-dark): the primary/secondary rail sat at 1.3:1 against the unchecked rail, the thumb at 1.1–1.4:1. The fix routes toggle fill through the same ink rule already used by progress/upload (v0.23.2), producing ≥4.5:1 by construction. For a PM this converts "WCAG compliance" from a per-sprint negotiation into a property of the design system — useful when scoping an enterprise/RFP accessibility requirement or a VPAT.
• Build vs. buy for the component layer. The package is opinionated about semantics (a toggle is "a state lamp, not a surface"; neutral deliberately keeps base-content), ships before/after comparison pages and fixtures (scripts/compare-page/specs/signal-toggle.json), and records rejected alternatives. That is the artifact set you'd otherwise have to fund internally over several quarters.
• Roadmap input: theme coverage is the real product surface. The defect only appeared on one theme family (Tonal, achromatic) in two modes. Any roadmap item that adds a theme, a brand palette, or a white-label offering must budget for this class of regression — the release is direct evidence that theme count is a multiplicative QA cost.
• Version-pinning and upgrade policy. This is a patch release that changes rendered defaults ("Default flip"). A PM decision follows immediately: do product teams take patch upgrades automatically, or is there a visual-regression gate? The existence of SEMVER.md with recorded change counts is what makes the "auto-update patches" policy defensible — and what you should cite when security/legal asks how visual drift is governed.
• Use cases this unblocks. Data-dense admin surfaces with many boolean settings, settings/preferences screens, permissions matrices, feature-flag consoles — anywhere a checked control must be unambiguous at a glance and in both light and dark mode. The failure mode fixed here (an ON switch that reads as OFF) is precisely the one that generates support tickets and mis-set configurations.

When to Consider This Package

Adopt when:

• You are on Laravel + Blade + Tailwind and want server-rendered components without adopting a JS SPA component library.
• You need theming/multi-brand (the package treats themes as first-class, including achromatic/tonal variants) and want the contrast math already reasoned about rather than re-derived per project.
• Accessibility is a contractual or procurement requirement and you need documented, reproducible evidence — before/after pages and fixtures are audit-friendly artifacts.
• You value maintainers who publish their reasoning: SEMVER.md change accounting, linked rejected alternatives, and a fill-rule precedent (v0.23.2) applied consistently. That is a strong signal for long-term maintainability.
• Your team can absorb occasional default shifts in patch releases behind visual regression tests or a manual review step.

Look elsewhere when:

• You need stability guarantees against any visual change on minor/patch upgrades — this release shows the project will trade visual continuity for correctness. That is the right call, but it is a policy mismatch if you cannot test rendering.
• You are not on Tailwind, or you need React/Vue-native components rather than Blade markup.
• You need enterprise support contracts, SLAs, or a formal deprecation calendar — nothing here indicates those exist; adoption is community-grade.
• You want a minimal, unstyled primitive set. This package encodes strong opinions (ink fill rules, base-content exceptions for neutral) that you would be fighting rather than inheriting.
• Your design system is already canonical — importing a second set of color semantics creates a two-sources-of-truth problem worse than the contrast bug it solves.

How to Pitch It (Stakeholders)

To executives: We evaluated a Laravel UI component library and its latest release. The headline is governance, not features: when the maintainers found that a checked toggle was effectively invisible on one theme (contrast as low as 1.1:1, far below the 4.5:1 accessibility floor), they fixed it, published before/after evidence, recorded the behavior change and its blast radius in a semver log, and documented the alternatives they rejected. That is the discipline we would otherwise have to build and staff internally. The trade-off to accept knowingly: this was a patch release that changed on-screen defaults, so adopting it means committing to render-level regression testing on upgrade.

To engineering: This is a Blade/Tailwind component set with a consistent fill rule — state indicators (toggle, progress, upload) paint bg-ink-<color> under a base-100 thumb so contrast holds by construction across themes and both modes. v0.25.2 applied that rule to <x-toggle>, with one deliberate carve-out (neutral retains base-content). Expect visual diffs on primary/secondary toggles in Tonal themes and on warm hues (ember/pop yellow → olive); where ink equals color — most saturated primaries on light themes — nothing moves. Fixtures and the comparison spec are in scripts/compare-page/specs/signal-toggle.json, so we can wire this into our existing visual-diff job rather than eyeballing it. Recommendation: adopt behind a pinned version, add a snapshot test for every theme we ship, and treat theme additions as QA-scoped work.