Lookbook

What you get

velvetkit:add copies each component's previews to test/components/previews/ui/, renamed into your namespace like everything else.

• A preview that shows components you haven't added is skipped, and add tells you which ones it needs.
• Leave them out with --skip-previews.
• The same templates are the examples on this site and in your agent's docs/velvetkit.md, so improving a preview improves all three.

Run it in your app

1. 1. Add the gem to the development group.

   Gemfile

   group :development do
     gem "lookbook"
   end

2. 2. Mount it for development only.

   config/routes.rb

   Rails.application.routes.draw do
     mount Lookbook::Engine, at: "/lookbook" if Rails.env.development?
     # …
   end

3. 3. Give previews your styles and scripts. Previews render inside a layout, so it needs your CSS, your JavaScript (for the Stimulus controllers) and the theme script.

   app/views/layouts/component_preview.html.erb

   <!DOCTYPE html>
   <html>
     <head>
       <%= render "layouts/theme_script" %>
       <%= stylesheet_link_tag "application" %>
       <%= javascript_include_tag "application", type: "module" %>
     </head>
     <body class="bg-background p-6 text-foreground">
       <%= yield %>
     </body>
   </html>
   config/environments/development.rb

   # config/environments/development.rb
   config.view_component.previews.default_layout = "component_preview"

4. 4. Open it at http://localhost:3000/lookbook.

Writing a preview

A preview is a class with one method per scenario. @param tags turn arguments into controls; render_with_template renders an ERB file named after the method.

class UI::BadgePreview < ViewComponent::Preview
  # @label Playground
  # @param text text
  # @param variant select { choices: [default, secondary, outline, success] }
  def playground(text: "New", variant: :default)
    render(UI::Badge.new(variant: variant.to_sym)) { text }
  end

  # @label Variants
  def variants
    render_with_template # renders badge_preview/variants.html.erb
  end
end