Lesson 8 — Module review and Lookbook documentation

The living style guide

By the end of this module /lookbook shows the complete Phlex::UI library with previews for every component. This is now the living reference for the design system — when a new developer joins the project, Lookbook is where they go to understand what components exist and how they behave.

Adding documentation to previews

Lookbook supports Markdown documentation alongside previews.

There are two styles of documentaion:

• notes attached to a particular preview
• doc pages which appear in a separate section.

For completeness we’ll cover examples of them both here:

Attached notes

This is the simplest approach. Take the button_preview and add a note above the preview as shown below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

class ButtonPreview < Lookbook::Preview
  layout "lookbook/preview"

  # @notes
  # Use **Button** for actions that trigger server-side behaviour.
  # Use **Link** for navigation.
  # Buttons always include **aria-disabled** for accessibility.
  def default
    render Components::Button.new(label: "Click me")
  end

  ... remaining previews

Check in lookbook now, you should see a note attached to the default component (in the section at the bottom)

Documentation pages

A way to add comprehensive documentation to assist in using complex components. There’s a bit of setup involved:

Firstly, update the config/initializer/lookbook.rb page to add a path to our docs

1
2
3
4
5
6
7
8

# config/initializers/lookbook.rb
if defined?(Lookbook)
  Lookbook.configure do |config|
    config.component_paths  << Rails.root.join("app/components")
    config.preview_layout   = "lookbook/preview"
    config.page_paths      << Rails.root.join("test/components/docs")
  end
end

Add a docs directory alongside previews:

test/components/
  previews/
    button_preview.rb
  docs/
    button.md.erb

Then create your document - here’s an example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
title: Button
---

# Button

The primary interactive element in Phlex::UI. Use `Button` for actions
that trigger server-side behaviour. Use `Link` for navigation.

## Variants

<lookbook-embed preview="ButtonPreview" scenario="primary"></lookbook-embed>
<lookbook-embed preview="ButtonPreview" scenario="secondary"></lookbook-embed>
<lookbook-embed preview="ButtonPreview" scenario="danger"></lookbook-embed>
<lookbook-embed preview="ButtonPreview" scenario="ghost"></lookbook-embed>

## Accessibility

Buttons always include `aria-disabled` to ensure assistive technology
correctly announces the disabled state even when the `disabled` attribute
is also present.

The lookbook-embed helper embeds live component previews inline in the documentation. Documentation stays accurate because it renders the real component, not a screenshot.

In most cases the additional documentation is not necessary since most components are pretty much self-explanatory.

Module summary

• Lookbook provides a proper component browser at /lookbook — previews for every Phlex::UI component, resizable viewport, live updates
• Preview files live in test/components/previews/ and extend Lookbook::Preview
• EmptyState handles the empty collection case throughout the app
• Breadcrumb uses the vanish + item pattern to collect navigation items before rendering
• Table now supports row actions via an actions block and empty state handling
• Component unit tests use the simple component_test_helper
• View tests use the view_test_helper
• The view_template / private render_ method pattern keeps views readable as complexity grows

Components built this module

• Components::EmptyState — title, message, optional CTA
• Components::Breadcrumb — navigation hierarchy via item slots
• Components::Table — expanded with actions block and empty state

Views built this module

• Views::Boards::Index — board grid with EmptyState
• Views::Boards::Show — column placeholder with Breadcrumb