Armada Laravel Package

Technical Evaluation

Architecture fit

• Blade-native, anonymous components. The package sits entirely in the presentation layer: no migrations, no service providers that mutate application behaviour, no persistence or domain assumptions. Architectural intrusion is about as low as a UI package can get.
• The armada namespace avoids collision with in-house component libraries, and dual invocation syntax (<armada:name> / <x-armada::name>) means adoption does not require a naming-convention decision up front.
• The two deliberate design choices that matter most are the design-token layer (--arm-* custom properties) and cascade layers, explicitly ordered so application CSS always wins. This is a strong signal the package was designed for brownfield adoption rather than greenfield demos, and it materially lowers the risk of visual regressions in an existing product.
• Deepest coupling is Livewire: wire:model support and automatic validation-error rendering in the form family, plus a Livewire toaster API. That is the highest-value feature set and also the highest-blast-radius one.

Integration feasibility

• High. Composer install, publish assets, publish selected components. No infrastructure, no runtime services, no queue or scheduler impact. Reversible on an incremental-adoption basis.
• Per-component override via vendor:publish --tag=armada-components is the right primitive, but it creates a local fork by design (see Operational Impact).

Technical risk

• v1.0.0 is the first stable release with no operating history. No stated support window, backwards-compatibility policy, or LTS commitment in the notes.
• 100+ components shipped in a single first stable cut is a very large surface area. Coverage will be uneven, and the four genuinely hard components — rich text editor, date/time pickers, kanban with touch drag-and-drop, file upload — are each a project in their own right.
• The Livewire version dependency is unstated and is a critical pin. Form binding, validation-error rendering, and toaster behaviour all degrade differently across Livewire majors.
• Custom JavaScript footprint is unspecified (Alpine vs. vanilla vs. Livewire internals) across command palette, kanban, infinite scroll, drawers/sheets, and dropdowns. This determines CSP exposure and upgrade fragility more than anything else in the package.
• Server-rendered SVG charts are a defensible trade (no chart library, no client runtime, privacy-friendly video facade is a genuinely good call), but they forgo hover tooltips, zoom, brush, and streaming. Large datasets will inflate HTML payload and paint cost — this needs pagination or server-side aggregation discipline.
• Accessibility is unaddressed. Command palette, combobox, kanban, drawers, date pickers, and toasts are precisely where keyboard and screen-reader support fails in practice. No WCAG conformance claim is a gap for enterprise or public-sector use.
• i18n is EN/TR only, with no stated RTL or pluralisation strategy. A hard blocker for some locales.
• Security surfaces requiring verification before production use: rich text output sanitisation, file-upload validation and storage configuration, and the inline no-flash theme script against a strict CSP.

Key questions

1. What is the supported matrix for PHP, Laravel, and Livewire versions, and is that matrix enforced by CI?
2. Is semantic versioning committed to, and what is the deprecation policy between minors?
3. Does the package require Tailwind, and if so which major? How are tokens delivered — prebuilt CSS, or compiled by the host build?
4. What is the JS model per component (Alpine directives, Livewire hooks, standalone modules), and what is the total shipped JS/CSS weight?
5. Is the CSS monolithic or per-component/tree-shakeable? Same question for the 2,100 Lucide icons — sprite, on-demand, or inline?
6. What is the WCAG 2.2 AA position, and is there automated a11y testing (axe) in CI?
7. How is rich text editor output sanitised — client, server, or not at all?
8. What is the test strategy and coverage per component, and who maintains it (bus factor, funding model, licence)?
9. How does the no-flash theme script work, and can it accept a CSP nonce?
10. Are charts extensible — can we attach our own interaction layer without forking?

Integration Approach

Stack fit

• Strong fit for Laravel + Blade, strongest for Laravel + Livewire. Adequate for Blade-only apps if the Livewire-coupled components (forms, toaster) are excluded or wrapped.
• CSS strategy is compatible with either a Tailwind or a bespoke stylesheet, provided the host app adopts or at least respects cascade layers. The "application CSS always wins" ordering makes coexistence with an existing design system genuinely viable — this is the single biggest de-risking factor.

Migration path

• There is no data migration. This is purely additive: install, publish config and assets, adopt components page by page, and remove the package if the pilot fails.
• Brownfield coexistence is the intended mode: run the existing UI kit alongside Armada on new screens, then retrofit high-churn screens. Avoid a big-bang restyle.
• Prefer application-level CSS overrides over vendor:publish forks wherever possible — every published component becomes code you own.

Compatibility

• Verify: PHP/Laravel/Livewire matrix, Tailwind major if applicable, CSP nonce support for the theme bootstrap, and mobile browser support for touch drag-and-drop and bottom sheets.
• Confirm the compiled asset pipeline — whether host build steps are required or prebuilt CSS/JS is shipped — before estimating effort.

Sequencing

1. Spike (2–3 days, on a branch): install, publish tokens, rebuild one real production screen (list + form + modal) with the existing app stylesheet still loaded. Measure CSS/JS payload, run axe, test on a low-end phone. This single exercise answers most of the risk questions.
2. Go/no-go gate. Criteria: no visual regression on the host app, acceptable payload, no CSP violations, acceptable keyboard behaviour on the form and modal.
3. Foundation: tokens, theme switching, app shell, layout primitives (container, stack, grid, card, page header).
4. Forms: highest value, highest coupling. Do one representative form end-to-end, including validation errors, then codify the pattern before rolling out.
5. Data display and tables, including the table-to-card mobile behaviour.
6. Overlays and feedback (modal, drawer, toaster).
7. Charts last — adopt only where static SVG is sufficient; keep an escape hatch to a client chart library for interactive needs.

Operational Impact

Maintenance

• The recurring cost is upgrade cadence, not day-to-day operation. Assign a named frontend owner and pin to a minor version.
• vendor:publish overrides are the main long-term liability. Keep a manifest of every published component, and re-diff each against upstream on every upgrade. Without that discipline, published components silently freeze at the version they were copied from.

Support

• No stated SLA, commercial backing, or governance model. Assume community support and plan accordingly. A 100+ component library maintained by a small team is a real bus-factor exposure; for a business-critical surface, budget for the possibility of internal ownership or a fork.

Scaling

• Server-side cost is negligible: Blade components compile to PHP, and unused components cost nothing at runtime.
• Client-side cost is the risk. If CSS is monolithic, every page pays for 100+ components. Confirm tree-shaking or per-component stylesheets before adopting broadly across a large app. Same for icons — verify the 2,100-icon set is not inlined wholesale.
• Charts, kanban, infinite scroll, and the rich text editor are the payload outliers. Set page-weight budgets and keep those components off high-traffic pages until measured.
• Organisationally, a shared component vocabulary scales well across teams — but only with an internal review path for overrides, or teams will diverge into per-team forks.

Failure modes

• A Livewire major upgrade changes binding or error-bag behaviour and silently breaks forms and toasts.
• Unlayered or reordered application CSS overrides components in unexpected places, or a layer-order change upstream flips precedence.
• Published components drift from upstream and miss bug and security fixes.
• A strict CSP blocks the inline no-flash theme script, reintroducing the flash-of-wrong-theme it was designed to prevent.
• Rich text editor output is rendered without server-side sanitisation — stored XSS.
• Large datasets passed to SVG charts cause slow paint and memory pressure on mobile.
• Locale gaps (EN/TR only, no stated RTL) block non-English/Turkish rollouts; date/time components surface timezone bugs late.
• Touch drag-and-drop degrades on older mobile browsers, making the kanban unusable in the field.

Ramp-up

• Blade developers become productive with the basic component set in a couple of days.
• The genuine learning curve is threefold: the --arm-* token map, the override/vendor:publish decision, and knowing which components require a Livewire context versus plain Blade.
• Budget roughly a week of a frontend lead to do a deep pass and write internal usage guidelines, plus a designer session to map tokens into the design handoff.
• Bottom line: worth a scoped pilot. The architecture and the cascade-layer/override model are well matched to a brownfield Laravel estate, but v1.0.0 with 100+ components, an unstated Livewire matrix, no accessibility position, and no support commitment are real unknowns. Gate full adoption on the spike in step 1 and on written answers to questions 1–3 and 6.