### Generator Options for Installation

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Customize the installation process using generator flags. Options include skipping theme variables or the helper file.

```bash
# Default: adds everything
bin/rails generate maquina_components:install

# Skip theme variables (if you have your own)
bin/rails generate maquina_components:install --skip-theme

# Skip helper file
bin/rails generate maquina_components:install --skip-helper
```

--------------------------------

### Install Maquina Components

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Run the install generator to set up Maquina Components. This includes adding CSS imports, theme variables, and a helper file for icon customization.

```bash
bundle install
```

```bash
bin/rails generate maquina_components:install
```

--------------------------------

### Generator Options for Maquina Components Install

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

Customize the maquina_components installation by skipping theme variables or helper creation.

```bash
bin/rails generate maquina_components:install --skip-theme
```

```bash
bin/rails generate maquina_components:install --skip-helper
```

```bash
bin/rails generate maquina_components:install --skip-theme --skip-helper
```

--------------------------------

### Complete Input Examples with HTML5 Attributes

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/form-patterns.md

Provides examples of various input types with recommended HTML5 attributes for validation, accessibility, and mobile optimization. Uses ERB syntax.

```erb
<%# Name - text with sensible limits %>
<%= f.text_field :name,
    data: { component: "input" },
    required: true,
    minlength: 2,
    maxlength: 100,
    autocomplete: "name" %>

<%# Email - correct type, maxlength per RFC %>
<%= f.email_field :email,
    data: { component: "input" },
    required: true,
    maxlength: 254,
    autocomplete: "email" %>

<%# Phone - pattern for flexibility, tel keyboard %>
<%= f.phone_field :phone,
    data: { component: "input" },
    required: true,
    maxlength: 20,
    pattern: "[+]?[0-9\\s\\-]+",
    inputmode: "tel",
    autocomplete: "tel" %>

<%# Money - number with cents precision %>
<%= f.number_field :price,
    data: { component: "input" },
    required: true,
    min: 0,
    max: 999999.99,
    step: 0.01,
    inputmode: "decimal" %>

<%# URL - correct type, sensible max %>
<%= f.url_field :website,
    data: { component: "input" },
    maxlength: 2000,
    autocomplete: "url",
    placeholder: "https://" %>

<%# Postal code - pattern for format %>
<%= f.text_field :postal_code,
    data: { component: "input" },
    required: true,
    maxlength: 10,
    pattern: "[0-9]{5}",
    inputmode: "numeric",
    autocomplete: "postal-code" %>

<%# Date - with range limits %>
<%= f.date_field :birthdate,
    data: { component: "input" },
    required: true,
    min: 100.years.ago.to_date,
    max: Date.current %>

<%# Password - minimum length for security %>
<%= f.password_field :password,
    data: { component: "input" },
    required: true,
    minlength: 8,
    maxlength: 128,
    autocomplete: "new-password" %>
```

--------------------------------

### Drawer with Trigger Example

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/drawer.md

This example shows how to use the drawer's trigger component to toggle its visibility. It also includes the provider and the drawer itself.

```erb
<%%= render "components/drawer/trigger" %>

<%%= render "components/drawer/provider" do %>
  <%%= render "components/drawer" do %>
    <!-- content -->
  <%% end %>
<%% end %>
```

--------------------------------

### Toast Component Examples

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/toast.md

Examples of different toast variants: success, error, warning, and with an action.

```APIDOC
## Toast Component Examples

### Success Toast

#### Description
Displays a toast with a success variant, indicating a successful operation.

#### Method
`render`

#### Endpoint
`"components/toast"`

#### Parameters
- **variant** (Symbol) - Optional - `:success` for success messages.
- **title** (String) - Required - The main text content of the toast.
- **description** (String) - Required - The secondary text content of the toast.

#### Request Example
```erb
<%%= render "components/toast",
  variant: :success,
  title: "Success!",
  description: "Your changes have been saved."
%>```

### Error Toast

#### Description
Displays a toast with an error variant, indicating a problem.

#### Method
`render`

#### Endpoint
`"components/toast"`

#### Parameters
- **variant** (Symbol) - Optional - `:error` for error messages.
- **title** (String) - Required - The main text content of the toast.
- **description** (String) - Required - The secondary text content of the toast.

#### Request Example
```erb
<%%= render "components/toast",
  variant: :error,
  title: "Error",
  description: "There was a problem with your request."
%>```

### Warning Toast

#### Description
Displays a toast with a warning variant, alerting the user.

#### Method
`render`

#### Endpoint
`"components/toast"`

#### Parameters
- **variant** (Symbol) - Optional - `:warning` for warning messages.
- **title** (String) - Required - The main text content of the toast.
- **description** (String) - Required - The secondary text content of the toast.

#### Request Example
```erb
<%%= render "components/toast",
  variant: :warning,
  title: "Warning",
  description: "Your session is about to expire."
%>```

### Toast With Action

#### Description
Displays a toast that includes an action button, allowing user interaction.

#### Method
`render`

#### Endpoint
`"components/toast"`

#### Parameters
- **title** (String) - Required - The main text content of the toast.
- **description** (String) - Required - The secondary text content of the toast.
- **content** (String) - Required - HTML content for the action, typically using `capture`.

#### Request Example
```erb
<%%= render "components/toast",
  title: "Event Created",
  description: "Your event has been scheduled.",
  content: capture { %>
  <%%= render "components/toast/action", label: "Undo", href: "#" %>
<%% }
%>```
```

--------------------------------

### Run Dummy App Server

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Navigate to the dummy app directory and start the Rails server to test components.

```bash
cd test/dummy
bin/rails server
```

--------------------------------

### Render Empty Component With Action

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/empty.md

This example shows how to include an action button within the empty state, guiding the user on the next step.

```erb
<%%= render "components/empty" do %>
  <%%= render "components/empty/header" do %>
    <%%= render "components/empty/media", icon: :folder %>
    <%%= render "components/empty/title", text: "No projects yet" %>
    <%%= render "components/empty/description", text: "Get started by creating your first project."
  <%% end %>
  <%%= render "components/empty/content" do %>
    <button data-component="button" data-variant="primary">Create project</button>
  <%% end %>
<%% end %>
```

--------------------------------

### Render Calendar with Week Starting Monday

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/calendar.md

Customizes the calendar to start the week on Monday. Set the 'week_starts_on' parameter to :monday.

```erb
<%%= render "components/calendar",
      week_starts_on: :monday %>
```

--------------------------------

### Install Maquina UI Standards Skill

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/README.md

Steps to install the maquina UI standards skill in your Rails project. This involves creating a skills directory and adding the skill either by unzipping a release or copying the directory.

```bash
cd your-rails-app
mkdir -p .claude/skills
```

```bash
unzip maquina-ui-standards.zip -d .claude/skills/
```

```bash
cp -r /path/to/maquina-ui-standards .claude/skills/
```

--------------------------------

### Render Basic Components

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

Example of rendering a card component with header and content sections using ERB.

```erb
<%%= render "components/card" do %>
  <%%= render "components/card/header" do %>
    <%%= render "components/card/title", text: "Welcome" %>
  <%% end %>
  <%%= render "components/card/content" do %>
    <p>Your content here</p>
  <%% end %>
<%% end %>
```

--------------------------------

### Responsive Layouts (Mobile-First)

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/layout-patterns.md

Demonstrates responsive design patterns using a mobile-first approach. Includes examples for stacking elements, side-by-side layouts, and controlling visibility based on screen size.

```erb
<%# Mobile: stack, Tablet+: side by side %>
<div class="flex flex-col md:flex-row gap-4">
  <div class="md:w-1/3">Sidebar</div>
  <div class="md:w-2/3">Main</div>
</div>

<%# Mobile: full width, Desktop: max width %>
<div class="w-full max-w-2xl mx-auto">
  ...
</div>

<%# Hide on mobile, show on desktop %>
<div class="hidden lg:block">Desktop only</div>

<%# Show on mobile, hide on desktop %>
<div class="lg:hidden">Mobile only</div>
```

--------------------------------

### Card with Action Header Example

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/SKILL.md

Example of a card component featuring an action header. It includes a title, description, and a primary action button with an icon.

```erb
<%= render "components/card" do %>
  <%= render "components/card/header", layout: :row do %>
    <div>
      <%= render "components/card/title", text: t(".title") %>
      <%= render "components/card/description", text: t(".description") %>
    </div>
    <%= render "components/card/action" do %>
      <%= link_to new_resource_path, data: { component: "button", variant: "primary", size: "sm" } do %>
        <%= icon_for :plus, class: "size-4 mr-1" %><%= t(".add") %>
      <% end %>
    <% end %>
  <% end %>
  <%= render "components/card/content" do %>
    <!-- Content here -->
  <% end %>
<% end %>
```

--------------------------------

### Controller setup for pagination

Source: https://context7.com/maquina-app/maquina_components/llms.txt

This controller action sets up pagination for a User model using the `pagy` method. It defines the number of items per page.

```ruby
# app/controllers/users_controller.rb
def index
  @pagy, @users = pagy(User.all, items: 20)
end
```

--------------------------------

### Pagination Component Usage

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/pagination.md

Example of how to render the pagination component with various items like previous, next, links, and ellipsis.

```APIDOC
## Pagination Component Usage

This example demonstrates how to implement the pagination component in your project.

```erb
<%%= render "components/pagination" do %>
  <%%= render "components/pagination/content" do %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/previous", href: "/page/1" %>
    <%% end %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/link", href: "/page/1" do %>1<%% end %>
    <%% end %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/link", href: "/page/2", active: true do %>2<%% end %>
    <%% end %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/link", href: "/page/3" do %>3<%% end %>
    <%% end %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/ellipsis" %>
    <%% end %>
    <%%= render "components/pagination/item" do %>
      <%%= render "components/pagination/next", href: "/page/3" %>
    <%% end %>
  <%% end %>
<%% end %>
```
```

--------------------------------

### Install Maquina Components Gem

Source: https://context7.com/maquina-app/maquina_components/llms.txt

Add the gem to your Gemfile and run the install generator to integrate Maquina Components into your Rails application. The generator configures CSS and optionally creates a helper file.

```ruby
# Gemfile
gem "maquina-components"
```

```bash
bundle install
bin/rails generate maquina_components:install
# Skip options:
#   --skip-theme    (if you already have CSS variables)
#   --skip-helper   (skip creating maquina_components_helper.rb)
```

--------------------------------

### Install Tailwind CSS Rails

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

Ensure tailwindcss-rails is installed and configured before running the maquina_components generator.

```bash
bundle add tailwindcss-rails
```

```bash
bin/rails tailwindcss:install
```

--------------------------------

### File Structure After Setup

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

This shows the expected file structure after successfully setting up Maquina Components in your Rails application. Key files include the main CSS, helper, Stimulus initialization, and the layout file.

```text
app/
├── assets/tailwind/
│   └── application.css          # Theme + engine import
├── helpers/
│   └── maquina_components_helper.rb  # Icon override
├── javascript/
│   └── application.js           # Stimulus init
└── views/layouts/
    └── application.html.erb     # Layout with components

```

--------------------------------

### Complete Layout Example with Maquina Components

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

This ERB template demonstrates a full application layout using Maquina's sidebar and header components. Ensure Stimulus is initialized and the provider wraps both sidebar and content for proper functionality.

```erb
<!DOCTYPE html>
<html lang="en" class="h-full">
  <head>
    <title><%%= content_for(:title) || "My App" %></title>
    <%%= csrf_meta_tags %>
    <%%= csp_meta_tag %>
    <%%= stylesheet_link_tag "application", data_turbo_track: "reload" %>
    <%%= javascript_importmap_tags %>
  </head>

  <body class="h-full overflow-hidden bg-background font-sans antialiased">
    <%%= render "components/sidebar/provider",
      default_open: app_sidebar_open?,
      variant: :inset do %>
      
      <%%= render "components/sidebar", variant: :inset do %>
        <%%= render "components/sidebar/header" do %>
          <span class="font-semibold">My App</span>
        <%% end %>

        <%%= render "components/sidebar/content" do %>
          <%%= render "components/sidebar/group", title: "Menu" do %>
            <%%= render "components/sidebar/menu" do %>
              <%%= render "components/sidebar/menu_item" do %>
                <%%= render "components/sidebar/menu_button",
                  title: "Dashboard",
                  url: root_path,
                  icon_name: :home,
                  active: current_page?(root_path) %>
              <%% end %>
            <%% end %>
          <%% end %>
        <%% end %>

        <%%= render "components/sidebar/footer" do %>
          <!-- User menu -->
        <%% end %>
      <%% end %>

      <%%= render "components/sidebar/inset" do %>
        <%%= render "components/header" do %>
          <%%= render "components/sidebar/trigger", icon_name: :panel_left %>
        <%% end %>

        <main class="flex-1 overflow-y-auto p-6">
          <%%= yield %>
        </main>
      <%% end %>
    <%% end %>
  </body>
</html>

```

--------------------------------

### Render a Card with Footer Actions

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/card.md

This example shows a card with a header, content, and a footer containing two buttons. The footer content is right-aligned using `align: :end`.

```erb
<%%= render "components/card" do %>
  <%%= render "components/card/header" do %>
    <%%= render "components/card/title", text: "Settings" %>
  <%% end %>
  <%%= render "components/card/content" do %>
    <p>Configure your preferences.</p>
  <%% end %>
  <%%= render "components/card/footer", align: :end do %>
    <button data-component="button" data-variant="outline">Cancel</button>
    <button data-component="button" data-variant="primary">Save</button>
  <%% end %>
<%% end %>
```

--------------------------------

### Subscribe to Turbo Stream Broadcasts in View

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/turbo-integration.md

Set up a Turbo Stream subscription in your view to receive real-time updates. This example shows how to subscribe to a specific channel and define a container for incoming broadcasts.

```erb
<%# Subscribe to broadcasts %>
<%= turbo_stream_from current_account, :bookings %>

<%# Container for broadcasts %>
<div id="bookings">
  <%= render @bookings %>
</div>
```

--------------------------------

### Render Table with Footer

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/table.md

This example shows how to add a footer to the table, typically used for summaries or totals. It utilizes `colspan` for cells spanning multiple columns.

```erb
<%%= render "components/table" do %>
  <%%= render "components/table/header" do %>
    <%# ... %>
  <%% end %>
  <%%= render "components/table/body" do %>
    <%# ... %>
  <%% end %>
  <%%= render "components/table/footer" do %>
    <%%= render "components/table/row" do %>
      <%%= render "components/table/cell", colspan: 2 do %>Total<%% end %>
      <%%= render "components/table/cell", css_classes: "text-right" do %>$750.00<%% end %>
    <%% end %>
  <%% end %>
<%% end %>
```

--------------------------------

### Empty State Component Examples

Source: https://context7.com/maquina-app/maquina_components/llms.txt

Displays a placeholder when content is absent. Supports various media, text, and action elements. Use when lists or sections have no data.

```erb
<%# Empty state with action %>
<% if @projects.empty? %>
  <%= render "components/empty" do %>
    <%= render "components/empty/header" do %>
      <%= render "components/empty/media", icon: :folder %>
      <%= render "components/empty/title", text: "No projects yet" %>
      <%= render "components/empty/description",
            text: "Get started by creating your first project."
      %>
    <% end %>
    <%= render "components/empty/content" do %>
      <%= link_to "New Project", new_project_path,
            data: { component: "button", variant: "primary" } %>
    <% end %>
  <% end %>
<% end %>
```

```erb
<%# Compact empty state inside a card %>
<%= render "components/empty", size: :compact do %>
  <%= render "components/empty/header" do %>
    <%= render "components/empty/media", icon: :search %>
    <%= render "components/empty/title", text: "No results for "#{params[:q]}"" %>
  <% end %>
<% end %>
```

```erb
<%# Outline variant (upload drop zone style) %>
<%= render "components/empty", variant: :outline do %>
  <%= render "components/empty/header" do %>
    <%= render "components/empty/media", icon: :upload %>
    <%= render "components/empty/title", text: "Drop files here" %>
    <%= render "components/empty/description", text: "or click to browse" %>
  <% end %>
<% end %>
```

--------------------------------

### Render Basic Calendar

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/calendar.md

Renders the default calendar component. No specific setup is required beyond including the component.

```erb
<%%= render "components/calendar" %>
```

--------------------------------

### Manually compose pagination controls

Source: https://context7.com/maquina-app/maquina_components/llms.txt

This example shows how to manually compose pagination controls using individual pagination components. It demonstrates creating previous, next, ellipsis, and page number links, handling disabled states and active page highlighting.

```erb
<%# Manual composable version %>
<%= render "components/pagination" do %>
  <%= render "components/pagination/content" do %>
    <%= render "components/pagination/item" do %>
      <%= render "components/pagination/previous",
            href: @pagy.prev ? paginated_path(:users_path, @pagy, @pagy.prev) : nil,
            disabled: @pagy.prev.nil? %>
    <% end %>
    <% @pagy.series.each do |item| %>
      <%= render "components/pagination/item" do %>
        <% if item == :gap %>
          <%= render "components/pagination/ellipsis" %>
        <% else %>
          <%= render "components/pagination/link",
                href: paginated_path(:users_path, @pagy, item.to_i),
                active: item.to_s == @pagy.page.to_s do %>
            <%= item %>
          <% end %>
        <% end %>
      <% end %>
    <% end %>
    <%= render "components/pagination/item" do %>
      <%= render "components/pagination/next",
            href: @pagy.next ? paginated_path(:users_path, @pagy, @pagy.next) : nil,
            disabled: @pagy.next.nil? %>
    <% end %>
  <% end %>
<% end %>
```

--------------------------------

### Setup and Use Toast Notifications

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Add a toaster to your layout and use `flash` or the JavaScript API to display toast notifications. Supports success and error variants.

```erb
<%# Add toaster to your layout %>
<%= render "components/toaster", position: :bottom_right do %>
  <%= toast_flash_messages %>
<% end %>
```

```ruby
flash[:success] = "Changes saved successfully!"
```

```javascript
Toast.success("Profile updated!")
Toast.error("Something went wrong", { description: "Please try again." })
```

--------------------------------

### Render Basic Badge Components

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/component-catalog.md

Use badges for compact status indicators and labels. This example shows a success badge for an 'Active' status.

```erb
<%# Basic %>
<%= render "components/badge", variant: :success do %>Active<% end %>
```

--------------------------------

### Handle Turbo Stream Response in Controller

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/turbo-integration.md

Respond to Turbo Stream requests in a controller action. This example shows how to render different Turbo Stream formats and fall back to HTML.

```ruby
def create
  @booking = current_account.bookings.build(booking_params)
  
  if @booking.save
    respond_to do |format|
      format.turbo_stream
      format.html { redirect_to bookings_path, notice: t(".created") }
    end
  else
    render :new, status: :unprocessable_entity
  end
end
```

--------------------------------

### Use Card Components in ERB

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Example of rendering nested card components using ERB syntax. Ensure the necessary partials are available in your views.

```erb
<%= render "components/card" do %>
  <%= render "components/card/header" do %>
    <%= render "components/card/title", text: "Account Settings" %>
    <%= render "components/card/description", text: "Manage your preferences" %>
  <% end %>
  <%= render "components/card/content" do %>
    <!-- Your content -->
  <% end %>
<% end %>
```

--------------------------------

### Dashboard Layout Structure

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/SKILL.md

Example of planning a dashboard layout using a grid system and rendering nested components like stat cards and main content cards.

```erb
<%# Dashboard layout %>
<div class="space-y-6">
  <%# Stats row %>
  <div class="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
    <%= render "dashboard/stat_card", ... %>
  </div>
  
  <%# Main content %>
  <%= render "components/card" do %>
    ...
  <% end %>
</div>
```

--------------------------------

### Dropdown Menu Component Example

Source: https://context7.com/maquina-app/maquina_components/llms.txt

Use this component for user account menus or any context requiring a toggleable dropdown. Set `auto_close: true` for navigation menus to ensure proper behavior with Turbo caching.

```erb
<%# User account menu in a header %>
<%= render "components/dropdown_menu", auto_close: true do %>
  <%= render "components/dropdown_menu/trigger", as_child: true do %>
    <button type="button"
            data-component="button"
            data-variant="ghost"
            data-size="icon"
            data-dropdown-menu-target="trigger"
            data-action="dropdown-menu#toggle"
            aria-haspopup="menu"
            aria-expanded="false">
      <%= icon_for :more_horizontal, class: "size-4" %>
    </button>
  <% end %>

  <%= render "components/dropdown_menu/content", align: :end do %>
    <%= render "components/dropdown_menu/label", text: current_user.name %>
    <%= render "components/dropdown_menu/separator" %>
    <%= render "components/dropdown_menu/item", href: profile_path do %>
      <%= icon_for :user, class: "size-4" %>
      Profile
    <% end %>
    <%= render "components/dropdown_menu/item", href: settings_path do %>
      <%= icon_for :settings, class: "size-4" %>
      Settings
      <%= render "components/dropdown_menu/shortcut" do %>⌘,<% end %>
    <% end %>
    <%= render "components/dropdown_menu/separator" %>
    <%= render "components/dropdown_menu/item",
          href: logout_path,
          method: :delete,
          variant: :destructive do %>
      <%= icon_for :log_out, class: "size-4" %>
      Log out
    <% end %>
  <% end %>
<% end %>

<%# Dropdown Menu API
  dropdown_menu:         auto_close (false)
  dropdown_menu/trigger: variant, size, as_child (false)
  dropdown_menu/content: align (:start|:center|:end), side (:top|:bottom|:left|:right), width
  dropdown_menu/item:    href, method, variant (:default|:destructive), disabled
  dropdown_menu/label:   text, inset
%>
```

--------------------------------

### Badge Component Examples

Source: https://context7.com/maquina-app/maquina_components/llms.txt

Renders a small inline label for status indicators, tags, or counts. Requires no JavaScript and is fully styled through CSS custom properties.

```erb
<%# Status badges in a table cell %>
<% case @order.status %>
<% when "active"   %><%= render "components/badge", variant: :success do %>Active<% end %>
<% when "pending"  %><%= render "components/badge", variant: :warning do %>Pending<% end %>
<% when "failed"   %><%= render "components/badge", variant: :destructive do %>Failed<% end %>
<% when "archived" %><%= render "components/badge", variant: :outline do %>Archived<% end %>
<% end %>

<%# Badge with icon %>
<%= render "components/badge", variant: :success do %>
  <%= icon_for :check, class: "size-3" %>
  Verified
<% end %>

<%# Size variants %>
<%= render "components/badge", size: :sm do %>Small<% end %>
<%= render "components/badge", size: :md do %>Medium<% end %>  <%# default %>
<%= render "components/badge", size: :lg do %>Large<% end %>

<%# All variants: :default, :primary, :secondary, :destructive, :success, :warning, :outline %>

```

--------------------------------

### Alert Component Examples

Source: https://context7.com/maquina-app/maquina_components/llms.txt

Displays a callout box for important feedback messages. Supports four severity variants with optional icons. Both title and description accept either a `text:` string or a block for rich HTML content.

```erb
<%# Default informational alert %>
<%= render "components/alert", icon: :info do %>
  <%= render "components/alert/title", text: "Heads up!" %>
  <%= render "components/alert/description", text: "Your trial expires in 3 days." %>
<% end %>

<%# Destructive alert (errors) %>
<%= render "components/alert", variant: :destructive, icon: :triangle_alert do %>
  <%= render "components/alert/title", text: "Payment failed" %>
  <%= render "components/alert/description" do %>
    Your card ending in <strong>4242</strong> was declined.
    <%= link_to "Update billing", billing_path, class: "underline" %>.
  <% end %>
<% end %>

<%# Success alert %>
<%= render "components/alert", variant: :success, icon: :check_circle do %>
  <%= render "components/alert/title", text: "Import complete" %>
  <%= render "components/alert/description", text: "1,234 records imported successfully." %>
<% end %>

<%# Warning alert %>
<%= render "components/alert", variant: :warning, icon: :triangle_alert do %>
  <%= render "components/alert/title", text: "Approaching limit" %>
  <%= render "components/alert/description", text: "You've used 90% of your storage quota." %>
<% end %>

<%# Alert API
  variant: :default | :destructive | :success | :warning
  icon:    Symbol (any icon_for name), nil
%>
```

--------------------------------

### Create Maquina Components Helper File

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/getting-started.md

Create the `app/helpers/maquina_components_helper.rb` file to define helper methods for Maquina Components. This includes overriding the default icon system and re-exporting sidebar state helpers for convenience.

```ruby
# frozen_string_literal: true

module MaquinaComponentsHelper
  # Override to use your own icon system
  def main_icon_svg_for(name)
    # Return nil to use engine's built-in icons
    # Or return SVG string for custom icons
    nil
  end

  # Sidebar state helpers (re-exported for convenience)
  def app_sidebar_state(cookie_name = "sidebar_state")
    sidebar_state(cookie_name)
  end

  def app_sidebar_open?(cookie_name = "sidebar_state")
    sidebar_open?(cookie_name)
  end

  def app_sidebar_closed?(cookie_name = "sidebar_state")
    sidebar_closed?(cookie_name)
  end
end

```

--------------------------------

### Direct vs. Wrapped Component Usage

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/component-catalog.md

Demonstrates two approaches to using maquina_components: direct composition of partials and using a pre-wrapped application component.

```erb
<%# Direct usage - explicit composition %>
<%= render "components/card" do %>
  <%= render "components/card/header" do %>
    <%= render "components/card/title", text: @booking.service.name %>
  <% end %>
<% end %>

<%# Application wrapper - compressed complexity %>
<%= render "bookings/card", booking: @booking %>
<%# Your partial handles the component composition internally %>
```

--------------------------------

### Drawer Provider with Panel and Content

Source: https://context7.com/maquina-app/maquina_components/llms.txt

This snippet sets up the Drawer provider and its content panel. It allows configuring the default open state, a cookie name for persistence, and a keyboard shortcut. The `side` option controls whether the drawer opens from the right or left.

```erb
<%# Drawer provider + panel (e.g. as a detail panel alongside a table) %>
<%= render "components/drawer/provider",
      default_open: drawer_open?,
      cookie_name: "detail_drawer",
      keyboard_shortcut: "d" do %>
  <%= render "components/drawer", state: drawer_state("detail_drawer"), side: :right do %>
    <%= render "components/drawer/header" do %>
      <h2 class="text-lg font-semibold">Order Details</h2>
      <%= render "components/drawer/close" %>
    <% end %>

    <%= render "components/drawer/content" do %>
      <%= render "components/card" do %>
        <%= render "components/card/content" do %>
          <p>Order #<%= @order.number %></p>
        <% end %>
      <% end %>
    <% end %>

    <%= render "components/drawer/footer" do %>
      <button data-component="button" data-variant="primary">Approve</button>
      <button data-component="button" data-variant="outline">Reject</button>
    <% end %>
  <% end %>
<% end %>
```

--------------------------------

### Calendar Range Selection

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/component-catalog.md

Configures the calendar for selecting a date range. Use `selected` for the start date and `selected_end` for the end date. Hidden input names are provided for both start and end dates.

```erb
<%= render "components/calendar",
  mode: :range,
  selected: @report.start_date,
  selected_end: @report.end_date,
  input_name: "report[start_date]",
  input_name_end: "report[end_date]" %>
```

--------------------------------

### Success Alert

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/alert.md

Example of a success alert, used to confirm successful operations.

```APIDOC
## Success Alert

### Description
Displays a success alert, used to confirm successful operations.

### Parameters
#### Component Parameters
- **icon** (Symbol, optional) - Icon name to display. Defaults to `:check_circle` for success variant.
- **variant** (Symbol, optional) - Set to `:success`.
- **css_classes** (String, optional) - Additional CSS classes to apply.
- **html_options** (Hash, optional) - Additional HTML attributes.

### Example Usage
```erb
<%%= render "components/alert", variant: :success, icon: :check_circle do %>
  <%%= render "components/alert/title", text: "Success" %>
  <%%= render "components/alert/description", text: "Your changes have been saved." %>
<%% end %>
```
```

--------------------------------

### Drawer Provider and Component Usage

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/drawer.md

This snippet demonstrates the basic usage of the Drawer component, including its provider and the main drawer structure with header, content, and footer.

```erb
<%%= render "components/drawer/provider", default_open: drawer_open? do %>
  <%%= render "components/drawer", state: drawer_state do %>
    <%%= render "components/drawer/header" do %>
      <h2 class="text-lg font-semibold">Drawer Title</h2>
      <%%= render "components/drawer/close" %>
    <%% end %>

    <%%= render "components/drawer/content" do %>
      <!-- Drawer content -->
    <%% end %>

    <%%= render "components/drawer/footer" do %>
      <!-- Footer actions -->
    <%% end %>
  <%% end %>
<%% end %>
```

--------------------------------

### Textarea Field

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/form.md

Example of a textarea component. Specify the number of rows using the `rows` attribute.

```erb
<%%= f.text_area :bio, data: { component: "textarea" }, rows: 4 %>
```

--------------------------------

### Responsive Column Grid Layouts

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/layout-patterns.md

Demonstrates responsive grid layouts for different column configurations across various screen sizes.

```erb
<%# 2 columns on tablet, 4 on desktop %>
<div class="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
  ...
</div>
```

```erb
<%# 2 columns, main + sidebar %>
<div class="grid gap-6 lg:grid-cols-3">
  <div class="lg:col-span-2">Main content</div>
  <div>Sidebar</div>
</div>
```

```erb
<%# Equal columns %>
<div class="grid gap-4 md:grid-cols-2">
  <div>Left</div>
  <div>Right</div>
</div>
```

```erb
<%# Three equal columns %>
<div class="grid gap-4 md:grid-cols-2 lg:grid-cols-3">
  ...
</div>
```

--------------------------------

### Helper Methods

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/toast.md

Documentation for helper methods used to generate and display toasts.

```APIDOC
## Helper Methods

### Description
These helper methods simplify the process of generating and displaying toast notifications.

### Methods

- **`toast_flash_messages(exclude: [])`**
  - **Description**: Renders all available flash messages as toast notifications. The `exclude` option can be used to omit specific flash message types.

- **`toast(variant, title, **options)`**
  - **Description**: A general method to render a single toast notification. Requires a `variant` and `title`, and accepts additional `options` for customization.

- **`toast_success(title, **options)`**
  - **Description**: A shorthand method for rendering a toast with the `:success` variant. Requires a `title` and accepts additional `options`.

- **`toast_error(title, **options)`**
  - **Description**: A shorthand method for rendering a toast with the `:error` variant. Requires a `title` and accepts additional `options`.

- **`toast_warning(title, **options)`**
  - **Description**: A shorthand method for rendering a toast with the `:warning` variant. Requires a `title` and accepts additional `options`.

- **`toast_info(title, **options)`**
  - **Description**: A shorthand method for rendering a toast with the `:info` variant. Requires a `title` and accepts additional `options`.
```

--------------------------------

### Warning Alert

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/alert.md

Example of a warning alert, used to caution users about potential issues or irreversible actions.

```APIDOC
## Warning Alert

### Description
Displays a warning alert, used to caution users about potential issues or irreversible actions.

### Parameters
#### Component Parameters
- **icon** (Symbol, optional) - Icon name to display. Defaults to `:triangle_alert` for warning variant.
- **variant** (Symbol, optional) - Set to `:warning`.
- **css_classes** (String, optional) - Additional CSS classes to apply.
- **html_options** (Hash, optional) - Additional HTML attributes.

### Example Usage
```erb
<%%= render "components/alert", variant: :warning, icon: :triangle_alert do %>
  <%%= render "components/alert/title", text: "Warning" %>
  <%%= render "components/alert/description", text: "This action cannot be undone." %>
<%% end %>
```
```

--------------------------------

### Destructive Alert

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/alert.md

Example of a destructive alert, typically used for error messages or warnings about irreversible actions.

```APIDOC
## Destructive Alert

### Description
Displays a destructive alert, often used for errors or critical warnings.

### Parameters
#### Component Parameters
- **icon** (Symbol, optional) - Icon name to display. Defaults to `:triangle_alert` for destructive variant.
- **variant** (Symbol, optional) - Set to `:destructive`.
- **css_classes** (String, optional) - Additional CSS classes to apply.
- **html_options** (Hash, optional) - Additional HTML attributes.

### Example Usage
```erb
<%%= render "components/alert", variant: :destructive, icon: :triangle_alert do %>
  <%%= render "components/alert/title", text: "Error" %>
  <%%= render "components/alert/description", text: "Your session has expired." %>
<%% end %>
```
```

--------------------------------

### Responsive Breadcrumbs

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/breadcrumbs.md

Demonstrates how to use `responsive_breadcrumbs` for adaptive breadcrumb display.

```APIDOC
### Responsive

```erb
<%%= responsive_breadcrumbs(
  {"Home" => "/", "Docs" => "/docs", "Components" => "/components"},
  "Breadcrumbs"
) %>
```
```

--------------------------------

### Checkbox Field

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/form.md

Example of a checkbox component. It's typically used within a label for better accessibility.

```erb
<label class="flex items-center gap-2">
  <%%= f.check_box :terms, data: { component: "checkbox" } %> 
  <span class="text-sm">Accept terms</span>
</label>
```

--------------------------------

### Header with Breadcrumbs

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/header.md

Example of rendering the Header component with nested breadcrumbs. Ensure breadcrumb components are correctly structured.

```erb
<%%= render "components/header" do %>
  <%%= render "components/breadcrumbs" do %>
    <%%= render "components/breadcrumbs/list" do %>
      <%%= render "components/breadcrumbs/item" do %>
        <%%= render "components/breadcrumbs/link", href: "#" do %>Dashboard<%% end %>
      <%% end %>
      <%%= render "components/breadcrumbs/separator" %>
      <%%= render "components/breadcrumbs/item" do %>
        <%%= render "components/breadcrumbs/page" do %>Settings<%% end %>
      <%% end %>
    <%% end %>
  <%% end %>
<%% end %>
```

--------------------------------

### Using Helper

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/breadcrumbs.md

Shows how to use the `breadcrumbs` helper function for simpler breadcrumb generation.

```APIDOC
## Using Helper

```erb
<%%= breadcrumbs({"Home" => root_path, "Users" => users_path}, "John Doe") %>
```
```

--------------------------------

### Text Field with Placeholder

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/form-patterns.md

Use for text input that requires a placeholder to guide the user. The placeholder text is localized.

```erb
<%# With placeholder %>
<%= f.text_field :name, data: { component: "input" }, placeholder: t(".placeholder") %>
```

--------------------------------

### Render Default Badge

Source: https://github.com/maquina-app/maquina_components/blob/main/docs/badge.md

Basic usage of the Badge component. No specific setup is required beyond including the component.

```erb
<%%= render "components/badge" do %>
  Badge
<%% end %>
```

--------------------------------

### Using the Combobox Helper

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/component-catalog.md

Use the helper method for a structured way to build a combobox with custom content, including triggers, inputs, lists, and options.

```erb
<%= combobox placeholder: "Select framework..." do |cb| %>
  <% cb.trigger %>
  <% cb.content do %>
    <% cb.input placeholder: "Search frameworks..." %>
    <% cb.list do %>
      <% cb.option value: "rails" do %>Ruby on Rails<% end %>
      <% cb.option value: "django" do %>Django<% end %>
      <% cb.option value: "phoenix" do %>Phoenix<% end %>
    <% end %>
    <% cb.empty %>
  <% end %>
<% end %>
```

--------------------------------

### Install Claude Code Skill

Source: https://github.com/maquina-app/maquina_components/blob/main/README.md

Copy the Claude Code skill directory into your Rails project for UI development standards.

```bash
cp -r /path/to/maquina_components/skill .claude/skills/maquina-ui-standards
```

--------------------------------

### Range Date Selection

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/component-catalog.md

Configure the Date Picker for selecting a date range, specifying start and end date inputs.

```erb
<%= render "components/date_picker",
  mode: :range,
  placeholder: "Select date range",
  selected: @report.start_date,
  selected_end: @report.end_date,
  input_name: "report[start_date]",
  input_name_end: "report[end_date]" %>
```

--------------------------------

### YAML for UI Implementation Sign-off

Source: https://github.com/maquina-app/maquina_components/blob/main/skill/references/spec-checklist.md

Use this YAML template to document the completion of UI implementation, including dates, components used, and verification status of various checklist items.

```yaml
ui_implementation:
  completed_at: YYYY-MM-DD
  components_used:
    - Card (main container)
    - Table (data display)
    - Badge (status)
    - Button (actions)
    - Form (create/edit)
    - Empty (no data state)
    - Dropdown Menu (row actions)
  
  checklist_verified:
    - accessibility: true
    - responsive: true
    - i18n: true
    - turbo: true
    - empty_states: true
    - loading_states: true
    - error_states: true
  
  notes: |
    Any implementation notes or deviations from spec
```

--------------------------------

### Header Component Example

Source: https://context7.com/maquina-app/maquina_components/llms.txt

A fixed-height top navigation bar. Uses `data-header-part` attributes for element positioning. Pairs with Sidebar layout.

```erb
<%# Header with sidebar trigger, breadcrumbs, and action buttons %>
<%= render "components/header" do %>
  <%= render "components/sidebar/trigger", icon_name: :left_panel %>

  <%= responsive_breadcrumbs(
    {"Dashboard" => root_path, "Users" => users_path},
    @user.name
  ) %>

  <div data-header-part="actions">
    <%= link_to "Export", export_users_path, format: :csv,
          data: { component: "button", variant: "outline", size: "sm" } %>
    <%= link_to "New User", new_user_path,
          data: { component: "button", variant: "primary", size: "sm" } %>
  </div>
<% end %>
```