README.md in lookbook-0.3.5 vs README.md in lookbook-0.4.0.beta.1

@@ -14,35 +14,31 @@
 
 **Lookbook gives [ViewComponent](http://viewcomponent.org/)-based projects a _ready-to-go_ development UI for navigating, inspecting and interacting with component previews.**
 
 It uses (and extends) the native [ViewComponent preview functionality](https://viewcomponent.org/guide/previews.html), so you don't need to learn a new DSL or create any extra files to get up and running.
 
-Lookbook uses [RDoc/Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code.
+Lookbook uses [RDoc/Yard-style comment tags](#annotating-preview-files) to extend the capabilities of ViewComponent's previews whilst maintaining compatability with the standard preview class format, so you can add or remove Lookbook at any time without having to rework your code.
 
 ![Lookbook UI](.github/assets/lookbook_screenshot.png)
 
 ### Features
 
-- Tree-style navigation menu
-- Live nav search/filter
+- Tree-style navigation menu with live search/filter
 - Resizable preview window for responsive testing
 - Highlighted preview source code and HTML output
-- Add notes via comments in the preview file (markdown supported)
 - Auto-updating UI when component or preview files are updated _(Rails v6.0+ only)_
-- Hide, group and rename preview examples using comment tags
+- Use comment tag annotations for granular customisation of the preview experience
 - Fully compatible with standard the ViewComponent preview system
 
 ## Lookbook demo
 
 If you want to have a quick play with Lookbook, the easiest way is to [give the demo app](https://github.com/allmarkedup/lookbook-demo) a spin. It's a basic Rails/ViewComponent app with a few test components included to tinker with.
 
 The [demo app repo](https://github.com/allmarkedup/lookbook-demo) contains instructions on how to get it up and running.
 
 ## Installing
 
-> ⚠️ **Please note:** Lookbook is still in the early stages of development and has not yet been well tested across a wide range of Rails/ViewComponent versions and setups. If you run into any problems please [open an issue](issues) with as much detail as possible. Thanks! ⚠️
-
 ### 1. Add as a dependency
 
 Add Lookbook to your `Gemfile` somewhere **after** the ViewComponent gem. For example:
 
 ```ruby
@@ -72,16 +68,17 @@
 
 You don't need to do anything special to see your ViewComponent previews and examples in Lookbook - just create them as normal and they'll automatically appear in the Lookbook UI. Preview templates, custom layouts and even bespoke [preview controllers](https://viewcomponent.org/guide/previews.html#configuring-preview-controller) should all work as you would expect.
 
 > If you are new to ViewComponent development, checkout the ViewComponent [documentation](https://viewcomponent.org/guide/) on how to get started developing your components and [creating previews](https://viewcomponent.org/guide/previews.html).
 
-### Annotating preview files
+## Annotating preview files
 
 Lookbook parses [Yard-style comment tags](https://rubydoc.info/gems/yard/file/docs/Tags.md) in your preview classes to customise and extend the standard ViewComponent preview experience:
 
 ```ruby
 # @label Basic Button
+# @display bg_color: "#fff"
 class ButtonComponentPreview < ViewComponent::Preview
 
   # Primary button
   # ---------------
   # This is the button style you should use for most things.
@@ -91,15 +88,17 @@
     render ButtonComponent.new do
       "Click me"
     end
   end
 
-  # Secondary button
+  # Inverted button
   # ---------------
-  # This should be used for less important actions.
+  # For light-on-dark screens
+  #
+  # @display bg_color: "#000"
   def secondary
-    render ButtonComponent.new(style: :secondary) do
+    render ButtonComponent.new(style: :inverted) do
       "Click me"
     end
   end
 
   # Unicorn button
@@ -140,12 +139,17 @@
 
 **Tags** are just strings identified by their `@` prefix - for example `@hidden`. Tags are always placed in a comment above the relevant preview class or example method.
 
 The following Lookbook-specific tags are available for use:
 
-#### `@label <text>`
+* `@label <label>` -[Customise navigation labels](#-label-text)
+* `@hidden` - [Prevent items displaying in the navigation](#-hidden)
+* `@display <key>:<value>` - [Specify params to pass into the preview template](#-display-key-value)
+* `@!group <name> ... @!endgroup` - [Render examples in a group on the same page](#-group-name--endgroup)
 
+### 🔖 `@label <text>`
+
 Used to replace the auto-generated navigation label for the item with `<text>`.
 
 > Available for preview classes & example methods.
 
 ```ruby
@@ -156,11 +160,11 @@
   def default
   end
 end
 ```
 
-#### `@hidden`
+### 🔖 `@hidden`
 
 Used to temporarily exclude an item from the Lookbook navigation. The item will still be accessible via it's URL.
 
 Can be useful when a component (or a variant of a component) is still in development and is not ready to be shared with the wider team.
 
@@ -174,12 +178,96 @@
   def default
   end
 end
 ```
 
-#### `@!group <name> ... @!endgroup`
+### 🔖 `@display <key>: <value>`
 
+The `@display` tag lets you pass custom parameters to your preview layout so that the component preview can be customised on a per-example basis.
+
+```ruby
+# @display bg_color: "#eee"
+class FooComponentPreview < ViewComponent::Preview
+
+  # @display max_width: "500px"
+  # @display wrapper: true
+  def default
+  end
+end
+```
+
+The `@display` tag can be applied at the preview (class) or at the example (method) level, and takes the following format:
+
+```ruby
+# @display <key>: <value>
+```
+
+- `<key>` must be a valid Ruby hash key name, without quotes or spaces
+- `<value>` must be a valid JSON-parsable value. It can be a string (surrounded by **double** quotes), a boolean or an integer.
+
+> [See below for some examples](#some-display-value-examples) of valid and invalid `@display` values.
+
+These display parameters can then be accessed via the `params` hash in your preview layout using `params[:lookbook][:display][<key>]`:
+
+```html
+<!DOCTYPE html>
+<html style="background-color: <%= params[:lookbook][:display][:bg_color] %>">
+  <head>
+    <title>Preview Layout</title>
+  </head>
+  <body>
+    <div style="max-width: <%= params[:lookbook][:display][:max_width] || '100%' %>">
+      <% if params[:lookbook][:display][:wrapper] == true %>
+        <div class="wrapper"><%= yield %></div>
+      <% else %>
+        <%= yield %>
+      <% end %>
+    </div>
+  </body>
+</html>
+```
+
+> By default ViewComponent will use your default application layout for displaying the rendered example. However it's often better to create a seperate layout that you can customise and use specifically for previewing your components. See the  ViewComponent [preview docs](https://viewcomponent.org/guide/previews.html) for instructions on how to set that up.
+
+Any `@display` params set at the preview (class) level with be merged with those set on individual example methods.
+
+#### Global display params
+
+Global (fallback) display params can be defined via a configuration option:
+
+```ruby
+# config/application.rb
+config.lookbook.preview_display_params = {
+  bg_color: "#fff",
+  max_width: "100%"
+}
+```
+
+Globally defined display params will be available to all previews. Any preview or example-level `@display` values with the same name will take precedence and override a globally-set one.
+
+#### Some `@display` value examples:
+
+Valid:
+
+```ruby
+# @display body_classes: "bg-red border border-4 border-green"
+# @display wrap_in_container: true
+# @display emojis_to_show: 4
+# @display page_title: "Special example title"
+```
+
+Invalid:
+
+```ruby
+# @display body_classes: 'bg-red border border-4 border-green' [❌ single quotes]
+# @display wrap_in_container: should_wrap [❌ unquoted string, perhaps trying to call a method]
+# @display page title: "Special example title" [❌ space in key]
+# @display bg_color: #fff [❌ colors need quotes around them, it's not CSS!]
+```
+
+### 🔖 `@!group <name> ... @!endgroup`
+
 For smaller components, it can often make sense to render a set of preview examples in a single window, rather than representing them as individual items in the navigation which can start to look a bit cluttered.
 
 You can group a set of examples by wrapping them in `@!group <name>` / `@!endgroup` tags within your preview file:
 
 ```ruby
@@ -220,10 +308,10 @@
 
 <img src=".github/assets/nav_group.png">
 
 You can have as many groups as you like within a single preview class, but each example can only belong to one group.
 
-#### Adding notes
+### Adding notes
 
 All comment text other than tags will be treated as markdown and rendered in the **Notes** panel for that example in the Lookbook UI.
 
 ```ruby
 # @hidden