flux-ui

Files (3)

• SKILL.md
• design-taste.md
• heroicon-list.txt

SKILL.md (first lines)

# Flux UI v2 Quick Reference

> Flux is a component library for Livewire built with Tailwind CSS v4.

**Building a full page or layout?** Read [design-taste.md](design-taste.md) first - it
covers page archetypes (settings, dashboards, tables, feeds, auth) and the judgement
calls this reference can't: when cards earn their place, vertical rhythm, restraint.

## Core Principles

### We Style, You Space
Flux provides **styling** (padding, colors). You provide **spacing** (margins, gaps, layout):

```blade
<form class="space-y-6">
    <flux:input label="Email" wire:model="email" />
    <flux:input label="Password" wire:model="password" />
    <flux:button type="submit" variant="primary">Submit</flux:button>
</form>
```

### Composition Over Configuration
Components mix and match. A `<flux:button>` works standalone OR inside other components.

---

## Common Mistakes to Avoid

### Use Flux Typography Components
```blade
{{-- WRONG: raw HTML with custom Tailwind --}}
<p class="text-sm text-zinc-500">Some help text</p>
<a href="/profile" class="text-blue-600 hover:underline">Profile</a>

{{-- CORRECT: Flux components --}}
<flux:text>Some help text</flux:text>
<flux:link href="/profile">Profile</flux:link>
```

For a title with a subtitle, use `flux:heading` + `flux:text class="mt-2"`. Avoid
`flux:subheading` - the Flux v2 docs and demo pages never use it.

### Button Variants - Less is More
Most buttons should be unstyled. Only the primary action gets `variant="primary"`:

```blade
{{-- WRONG: rainbow of variants --}}
<div class="flex gap-2">
    <flux:button variant="subtle">Cancel</flux:button>
    <flux:button variant="outline">Preview</flux:button>
    <flux:button variant="filled">Draft</flux:button>
    <flux:button variant="primary">Save</flux:button>
</div>

{{-- CORRECT: simple and clear --}}
<div class="flex gap-2">
    <flux:button>Cancel</flux:button>
    <flux:button>Preview</flux:button>
    <flux:button variant="primary">Save</flux:button>
</div>
```

Only use `variant="danger"` for genuinely destructive actions (delete, remove).

### Modals - Default to Flyout
```blade
{{-- Prefer flyout variant --}}
<flux:modal name="filters" variant="flyout">
    ...
</flux:modal>
```

### Modals - Trigger Behaviour
In Flux v2, modals can be triggered by a `<flux:modal.trigger>` component with the name prop matcher rather than toggling component state or events.

```blade
<flux:modal.trigger name="edit-profile">
    <flux:button>Edit</flux:button>
</flux:modal.trigger>

<flux:modal name="edit-profile" class="md:w-96">
    <div class="space-y-6">
       ....
    </div>
</flux:modal>
```

**Carve-out**: `flux:modal.trigger` is for modals whose content is already present. When
the server must load data before the modal opens (e.g. an edit flyout that hydrates a
model), `wire:click="editUser(...)"` + `Flux::modal('edit-user')->show()` in the action
is the correct pattern - do not "fix" it into a trigger, you'll break the data loading.

### Colours - Use Sparingly
Badges, callouts etc have colour options - but only use them when genuinely needed to draw attention. Default/neutral is usually fine.

### Sizing Inputs - max-w-*, not w-*
`flux:input`'s wrapper carries its own `w-full`; an added `w-72` lands beside it and can
lose the stylesheet-order tie - silently full width, no error. Use `max-w-72` / `max-w-96`
(this is what the official docs do). For a search box that shares a row on mobile but sits
at a fixed width on desktop: `class="flex-1 md:flex-none max-w-96"`.

### Alpine Bindings - Spell Out x-bind
On a Blade component tag, `:class` (or any `:attr`) is Blade prop-binding - the value is
evaluated as **PHP** and crashes on Alpine expressions. Always write the long form:

```blade
{{-- WRONG: Blade evaluates this as PHP --}}
<flux:select :class="showFilters ? '' : 'max-md:hidden'">

{{-- CORRECT --}}
<flux:select x-bind:class="showFilters ? '' : 'max-md:hidden'">
```

### Headings Need level to Be Headings
`flux:heading` without a `level` prop renders a styled **div**, not a heading element. A
page can look perfectly structured and still have no document outline at all (invisible
to screen readers). Give the page title `level="1"` and section headings `level="2"` -
`size` controls the look, `level` the semantics, independently.

From ohnotnow/agentic-stuff, MIT.

More from ohnotnow/agentic-stuff