Pinion Ui Laravel Package

Getting Started

This release only changes rendering, not the public API — there is nothing new to wire up. If you are picking the package up fresh:

1. composer require sparrowhawk-labs/pinion-ui, publish the config/theme assets, and make sure your Tailwind entry includes the package preset so the ink-*, base-100 and <color> tokens resolve.
2. Read SEMVER.md before CHANGELOG.md. It records intentional default flips (this release logs the toggle counts), which is the fastest way to know whether an upgrade will move pixels in your app.
3. Skim scripts/compare-page/specs/ — the specs (e.g. signal-toggle.json) are executable expectations for what each component should look like per theme/color/variant. They double as documentation of the intended contrast story.
4. First use case: a boolean preference bound to state, e.g. <x-toggle wire:model="notifications" color="primary" variant="solid" />. Add stateLabel only if you want ON/OFF text; that text is now base-100 on every color.

Implementation Patterns

• Treat color as semantic, not literal. Pass primary / warning / neutral and let the package map it to an ink fill. Do not hand-roll bg-<color> on a toggle — that is exactly the pattern this release removed.
• Pick the variant by emphasis, not aesthetics. solid for the headline setting in a section, wire for dense lists, soft for inline/secondary toggles. All three now agree on the checked fill rule.
• Theme once, at the shell. The achromatic Tonal themes (signal, signal-dark) are where this fix matters most; saturated light themes will look nearly identical to before. Decide the theme per surface (app shell vs. marketing page) and stop overriding per component.
• Wire it to Livewire/Alpine state as a plain boolean. No prop changes were needed for this release, so existing wire:model bindings keep working; only the rendered classes shift.
• Keep a compare spec per component you rely on. When you bump the package, open the compare page, diff before/after, and update the JSON fixture in the same commit as the version bump. This is the package's own workflow and it transfers cleanly to app-level visual regression.
• Override by publishing views, not by patching classes in place. If you need a different checked fill, fork the Blade view and swap bg-ink-<color> deliberately — a CSS override layered on top will silently lose to whatever the component renders.

Gotchas and Tips

• This is a visual breaking change under a patch version. No props changed, so nothing will throw — but every snapshot, screenshot test, and design review of a checked toggle on an achromatic theme will now differ. Budget for it.
• Some colors visibly shift. Where ink ≠ color the ON state moves toward the theme's text color: ember/pop light warning yellow reads olive, pop light primary yellow reads dark. If brand yellow is load-bearing for you, verify it before shipping.
• neutral is the exception — it still uses base-content (carried over from v0.25.1). Don't "normalize" it yourself; you will diverge from the fixtures.
• stateLabel ON text is now base-100 for all colors, replacing <color>-content. Any custom selector you wrote against *-content on the label will stop matching.
• The contrast guarantee depends on base-100. Ink is ≥ 4.5:1 against base-100 by construction. If you restyle base-100 in your theme, that guarantee is void — re-check toggles on the achromatic themes first, since that is where the failure mode lives (previously 1.1–1.4:1 thumb-against-rail).
• Don't put a toggle on a surface of its own color. A toggle is a state lamp: its only signal is the fill under a base-100 thumb. Nesting it inside a same-colored card erases the state.
• Debugging order when a toggle looks wrong: inspect the rail/thumb classes for bg-ink-* vs. a stale bg-*, confirm the theme actually applied (Tonal vs. saturated), then check SEMVER.md for a flip you missed, then diff against the spec JSON.
• Pin exact versions pre-1.0. At v0.25.x, default flips like this one are permitted under the project's own semver policy, so ^0.25 will hand you visual changes. Read SEMVER.md on every bump.