unoforge/flexiwind/flexiwind

Flexiwind Skill

Flexiwind is a Laravel-first UI component system built with Blade, Livewire, and Tailwind CSS v4. Think of it like shadcn/ui but for Laravel — it provides copy-paste components, blocks, and a semantic theming system, all installable via CLI.

Goal

Help users build accurate Flexiwind integrations without inventing components, props, CLI commands, or block names.

How Flexiwind Works

Flexiwind has three layers that work together:

1. Components (x-ui.*) — Reusable Blade primitives installed individually via CLI (php artisan flexi:add button). Each component is a Blade file you own and customize.

1. Blocks — Pre-built sections (login forms, sidebars, KPIs, hero sections, etc.) composed from components. Listed in config/blocks.php.

1. Theme — CSS variable tokens (--primary, --background, --foreground, --title-foreground, --border, etc.) consumed through Tailwind v4 @theme utilities (bg-primary, text-foreground, text-title-foreground, border-border).

Source of truth

Use the files in this skill first. The public docs site is also available at https://flexiwind.unoforge.com.

• references/best-practices.md — verified usage rules and source-of-truth guidance
• references/styling-principles.md — semantic tokens, dark mode, theming vocabulary
• references/things-to-avoid.md — common mistakes and invented APIs to avoid
• references/accessibility.md — accessible usage patterns
• references/performance.md — performance guidance
• references/theme.md — full CSS variable token reference and theme setup
• references/colors.md — color token setup for light/dark/both modes
• references/button-utilities.md — CSS utility definitions for button variants
• references/components.md — full component reference index
• references/interactions.md — Flexilla interaction setup, plugin imports, and livewire compatibility

Working Rules

1. Never invent x-ui.* components that are not present in resources/views/components/ui.
2. Never invent props, CLI commands, or block names.
3. Distinguish between docs page names and Blade component names when they differ:

1. Prefer documented composition patterns over custom abstractions.
2. When a component, prop, command, or block is not present in the skill files or the live docs, do not invent it.
3. Do not reference repository-local paths, examples, or source files in user-facing answers. Use Blade component syntax.
4. Components that require Flexilla JS must include the npm install and Alpine plugin import in any answer. For detailed Flexilla guidance (JS APIs, events, accessibility), suggest installing the Flexilla skill: php artisan boost:add-skill unoforge/flexilla.
5. The dissmissible component name is intentionally spelled with double-s in the codebase and CLI slug. Use that spelling exactly.

1. Follow component composition safety rules:

• Trigger components (x-ui.modal.trigger, x-ui.slideover.trigger, x-ui.dropdown.trigger, x-ui.popover.trigger, x-ui.tooltip.trigger) already render as <button> elements. Do not nest another <x-ui.button> or <button> inside them — they accept button props directly.
• Triggers must be placed outside their overlay wrapper (<x-ui.modal>, <x-ui.slideover>). These wrappers are invisible when closed — a trigger inside would be unclickable.
• Trigger attribute names: modal-id, slide-over-id (not slideover-id), dropdown-id, popover-id, tooltip-id.
• x-ui.modal.close and x-ui.slideover.close inherit x-ui.button props — do not nest a <button> or <x-ui.button> inside them. Passing text or an icon is fine.
• x-ui.dropdown.trigger accepts button props (variant, intent, size, etc.) — pass them directly to the trigger rather than wrapping in a button.
• Do not nest <x-ui.link> inside <x-ui.button> or vice versa. If you need a link that looks like a button, use x-ui.button href or x-ui.link asButton.
• x-ui.link renders an <a> tag by default — do not put interactive elements (buttons, links) inside it.

Answering Pattern

1. Identify the need: Is it a component, a block, theming, or CLI question?

1. Read the source: Open the relevant file from components/*.md or references/*.md.

1. Give the smallest working example:

• Install command: php artisan flexi:add <name>
• Minimal Blade usage with x-ui.* tags
• JS initialization if the component requires Flexilla/Alpine plugins

1. Call out important props — size, variant, intent, and any required attributes.

1. Add one short "avoid" note when there is a common Flexiwind mistake for that component.

Example Answer (good)

To add a button:

```bash

php artisan flexi:add button

```

```blade

<x-ui.button variant="solid" intent="primary" size="md">

Click me

</x-ui.button>

```

Key props: variant (solid|soft|outline|ghost|none), intent (one the variant supports, see components/button.md), size (xs|sm|md|lg|xl).

Avoid: Do not invent variant names outside the documented set.

Example Answer (bad)

Use flexi-ui-button with loading prop.

❌ "flexi-ui-button" doesn't exist. "loading" is not a documented prop.

Components Overview

Actions & Inputs

Layout & Structure

Navigation

Data & Feedback

Overlays & Disclosure

Typography

Key Composition Patterns

Button

<x-ui.button variant="solid" intent="primary" size="md">
    <x-ui.icon name="ph--atom" class="mr-1.5" />
    With Icon
</x-ui.button>

Input Group (CRITICAL — strict rules)

<x-ui.input.group>
    <x-ui.input variant="unstyled" type="email" placeholder="you@example.com" class="ps-9 px-3" />
    <x-ui.input.leading absolute class="text-foreground text-sm">
        <x-ui.icon name="ph--at" class="size-4" />
    </x-ui.input.leading>
</x-ui.input.group>

Rules: variant="unstyled" inside group, never pass label to grouped input.

Modal

<x-ui.modal.trigger modal-id="edit-profile" variant="solid" intent="primary">
    Open
</x-ui.modal.trigger>
 
<x-ui.modal id="edit-profile">
    <x-ui.modal.content size="md">
        <x-ui.modal.header title="Title" description="Optional description." />
        <x-ui.modal.body>Content</x-ui.modal.body>
        <x-ui.modal.footer>
            <x-ui.button>Save</x-ui.button>
        </x-ui.modal.footer>
    </x-ui.modal.content>
</x-ui.modal>

The trigger must be outside <x-ui.modal> — the dialog is hidden when closed. Requires Flexilla JS: npm i @flexilla/modal. Import plugin in Alpine.

Card

<x-ui.card>
    <x-ui.card.header>
        <x-ui.card.title>Title</x-ui.card.title>
        <x-ui.card.description>Description</x-ui.card.description>
    </x-ui.card.header>
    <x-ui.card.content>Content</x-ui.card.content>
    <x-ui.card.footer>
        <x-ui.button size="sm">Action</x-ui.button>
    </x-ui.card.footer>
</x-ui.card>

Table

<x-ui.table striped hoverable>
    <x-ui.table.columns>
        <x-ui.table.column>Name</x-ui.table.column>
        <x-ui.table.column>Email</x-ui.table.column>
    </x-ui.table.columns>
    <x-ui.table.rows>
        <x-ui.table.row>
            <x-ui.table.cell>John</x-ui.table.cell>
            <x-ui.table.cell>john@example.com</x-ui.table.cell>
        </x-ui.table.row>
    </x-ui.table.rows>
</x-ui.table>

Blocks (Pre-built Sections)

Blocks are full sections composed from components. Available block categories from config/blocks.php:

Application Blocks