Shape Laravel Package

Product Decisions This Supports

• Build vs. buy for the design system layer. Shape supplies 30 components across foundation, forms, data display, navigation, overlays and feedback. For a Livewire/Tailwind product, that is the majority of "we need a Button, a Modal, a Table" work that otherwise consumes one to two engineer-months before a single feature ships. The PM decision is whether that time goes into differentiated product surface or into re-implementing a select box.
• Committing to a Livewire + Tailwind stack. Adoption is effectively a statement that Blade components, Livewire and Tailwind are the rendering strategy for the forseeable roadmap. Worth making explicit rather than drifting into it.
• Theming and brand readiness. The theme layer is deliberately narrow — one neutral ramp with a temperature, brand, accent, four state colours, one radius decision, a per-surface foreground contract — with an optional seed stylesheet that derives brand and neutrals from a single colour in OKLCH, contrast verified across 96 seeds by measurement. That means a rebrand or a white-label tenant palette is a configuration exercise, not a redesign project.
• White-labelling / multi-tenant branding. If the roadmap includes per-customer theming, the seed-derivation approach is a direct enabler and worth prototyping before it becomes a committed feature.
• Risk posture on lock-in. shape:eject copies a component and its dependency graph into your codebase, records what the package held at copy time, and shape:eject:status distinguishes "you edited this" from "the package changed underneath you." The build-vs-buy decision is therefore reversible component-by-component, not all-or-nothing. This materially lowers the cost of saying yes now.
• Accessibility and browser-platform strategy. Modal and drawer are native <dialog>; dropdown, popover and tooltip use the popover attribute. Focus trapping, top layer, Escape, light dismiss and the scrim come from the browser. This is a defensible bet that reduces our own JS surface, but it is a bet with a browser-baseline requirement that should be checked against the support matrix we actually promise.
• JS dependency budget. The only script imports nothing and depends on nothing — not Alpine, not Livewire. For a PM tracking front-end risk and bundle size, this is a concrete, checkable claim rather than a marketing one.
• Notification/toast/confirm UX as a shared primitive. Shape::toast() and Shape::confirm() dispatch through Livewire when a request is available and flash to session otherwise, arriving as the same event so one code path builds the toast either way — Livewire is not a dependency. That means feedback UX is standardized early, before three teams each invent a flash-message pattern.
• Icon supply chain and brand consistency. shape:icon generates components from SVG sets (Heroicons, Lucide, Tabler, Phosphor, Bootstrap Icons, Remix Icon, Material Symbols, or any directory), writing the resolved upstream commit into every file, with shape:icon:status reporting what has been redrawn upstream. shape:icon:replace --set=lucide redraws the library in another set without touching a call site. That makes "switch icon family" a one-command decision instead of a refactor, and gives an auditable answer to "which upstream version are we shipping?"
• Component API stability as a roadmap input. This is 0.x and the component APIs may still change before 1.0. That is a scheduling fact: any feature work touching component props should budget for churn, or wait.
• Compile-time performance as a product concern. Annotations let Blaze fold components into the parent template at compile time. For a large Blade surface this is a render-cost lever, and it is opt-in — without Blaze the components render normally and annotations compile away.

When to Consider This Package

Consider it when most of the following hold:

• The application is Laravel 12 or 13 on PHP 8.3/8.4/8.5. Outside that matrix, stop here.
• The front end is Blade + Livewire + Tailwind. Shape is styled with Tailwind and ships no compiled CSS, so your build must scan the package's Blade files. A team on Vue/React/Inertia, or on a CSS-in-JS or non-Tailwind styling approach, gets little from this.
• You want a neutral, opinionated-but-themable baseline rather than a distinctive designed product. Shape provides hierarchy (variant) and semantics (tone) as separate props — so a destructive action can stay quiet until it matters — and every default carries zero specificity so application classes win without !important. That is a library designed to be overridden, which suits product teams and frustrates teams wanting a fully finished visual identity.
• You have, or want, a browser baseline that includes <dialog> and the popover attribute. Verify this against your real support commitments, including any enterprise or embedded-webview audience, before adoption — this is the single most consequential technical assumption in the package.
• You need an escape hatch from vendor dependence. shape:eject, shape:eject:all and shape:eject:status make partial or full in-housing a supported workflow with change tracking, not a fork.
• You want CI-enforceable safety around pre-rendered components. shape:doctor exits non-zero and checks ejected components for request-scoped state (auth(), session(), config(), translations) that a folded component resolves once and then serves to everybody — a failure with no stack trace and no symptom in development. If you plan to use Blaze, this check is close to mandatory and its existence is a genuine adoption argument.
• You want documentation that cannot silently rot. Docs are markdown committed next to the code, and a test asserts every single-file example still compiles, so a renamed prop cannot leave a page describing the old one.
• You are comfortable with 0.x churn on component APIs, and can absorb it.

Look elsewhere when:

• You are on Laravel 11 or earlier, or PHP below 8.3.
• You need a stable 1.0 API contract for a long-lived, low-maintenance product, or your governance process cannot accept 0.x versioning. Pinning is possible; the API moving under you is the stated risk.
• You need a designed, distinctive brand system delivered as-is, or a component library with a large third-party ecosystem, plugins and community themes.
• You need components outside the 30 shipped — there is no rich text editor, date picker, combobox/autocomplete, command palette, data grid with virtualisation, or charting. These are the predictable gaps and should be scoped explicitly rather than assumed to arrive.
• You need a documented, dated release cadence and security policy. A first public pre-release has no track record; treat support responsiveness as unproven.
• Your team is not on Tailwind, or the build pipeline cannot be extended to scan package templates.
• You require an accessible-by-audit component set with published per-component conformance evidence. Browser primitives are a strong starting position, but "the browser handles the focus trap" is a different claim from "we have tested this against our audit standard."

How to Pitch It (Stakeholders)

For executives — one paragraph. Shape is a free, open-source Blade component library that gives a Laravel/Livewire product its entire UI kit — buttons, forms, tables, modals, toasts and the rest of thirty components — in a single composer require. The commercial case is time-to-market: it removes the undifferentiated build-out of a design system that would otherwise sit in front of our first release, and it removes it reversibly. Any component can be copied into our codebase on demand, with tracking that tells us whether we or the upstream package changed a file, so adopting it does not lock us in. Theming is configuration, including derived brand palettes for white-label work. The costs are real but bounded: it is a 0.x pre-release, so component APIs may shift; it requires a modern stack (Laravel 12/13, PHP 8.3+) and a modern browser baseline; and it commits us to Tailwind and Livewire on the front end. Recommended posture: adopt behind the eject escape hatch in a contained area, pin the version, and treat "reach 1.0 or we take ownership of the components we use" as an explicit decision point rather than an open question.

For engineering — the honest summary. Anonymous Blade files, Tailwind-styled, annotated for Blaze compile-time folding; Blaze is optional and annotations compile away without it. No compiled CSS and no asset build step — the trade-off is that our Tailwind content configuration must include the package's templates, which needs verifying in our pipeline before we commit. Overlays sit on native <dialog> and popover, so focus trap, top layer, Escape, light dismiss and scrim are the browser's, not ours; the remaining script is one dependency-free file — no Alpine, no Livewire. Feedback dispatch rides a Livewire request when one exists and flashes to session otherwise, arriving as the same event with a single code path, and Livewire is not a dependency of the package. shape:install publishes tokens, the script and a chosen set. shape:doctor exits non-zero and catches request-scoped state in folded components — the silent, untraceable bug class — so it belongs in CI from day one if Blaze is on. Icon components are generated from named SVG sets with the resolved upstream commit written into every file, and shape:icon:replace --set=… swaps the whole family without a call site changing. The testing story is above average for a 0.x: Ubuntu and Windows across the PHP 8.3/8.4/8.5 and Laravel 12/13 matrix, on both prefer-stable and prefer-lowest, plus a test asserting every documentation example compiles. What we do not get: a 1.0 API guarantee, a published support policy, or component coverage for rich inputs and data grids — scope those separately.

The one-line version. Thirty Tailwind/Blade components, browser-native overlays, zero JS dependencies and a real exit door — at the price of 0.x API churn and a modern-browser, modern-Laravel baseline.