Skip to content

Module 03 - Component Architecture

7 lessons ·Simple components · composition · testing
We build up our library of components. At this stage we’re using pico.css to keep the styling simple.
Every lesson adds to our demo_page so we can see our component library grow. We round out the module with some minitest samples to demonstrate how easy testing can be.

Before we start

This module introduces the patterns that make Phlex genuinely powerful — base classes, Kits, yielding, named slots, and composition. Some of these will feel unfamiliar at first. We follow the same approach throughout: show the naive solution first, demonstrate the problem it creates, then introduce the correct pattern and explain why it works.

From Lesson 1 onwards we maintain a demo.rb file — a living page that grows as new components are added. After each lesson the pattern is:

  1. Create the new component
  2. Add require_relative for it in demo.rb
  3. Add a show_ method to DemoPage
  4. Call that method from view_template
  5. Run ruby demo.rb and see the result in a browser

By the end of the module demo.rb is a complete, working component showcase.

Why Pico CSS in this module?

You will notice we use Pico CSS rather than Tailwind in this module. This is a deliberate choice.

In Module 3 the important things to understand are component structure — props, variants, slots, composition, and testing. Tailwind class strings are noise at this stage. A component like Button with four variants is much easier to understand when the variant logic looks like this:

1
2
3
4
5
6

VARIANTS = {
  primary:   nil,
  secondary: "secondary",
  danger:    "contrast",
  ghost:     "outline",
}.freeze

Rather than this:

1
2
3
4
5
6

VARIANTS = {
  primary:   "bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500",
  secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-500",
  danger:    "bg-red-600 text-white hover:bg-red-700 focus:ring-red-500",
  ghost:     "bg-transparent text-gray-700 hover:bg-gray-100 focus:ring-gray-500",
}.freeze

Pico CSS styles semantic HTML automatically — <button> looks like a button, <article> looks like a card, <table> looks like a table — with zero configuration and no class noise. This means our demo page looks clean and readable, and the component code stays focused on structure and behaviour.

Module 4 introduces Tailwind properly inside a real Rails app with a proper build step. At that point we restyle all Phlex::UI components with Tailwind utility classes — the component structure we build here stays identical, only the class strings change. A downloadable zip of the Tailwind-styled components is provided at the start of Module 4.

Setup

Add three gems to your Gemfile:

1
2
3
4
5

source "https://rubygems.org"

gem "phlex"
gem "literal"
gem "nokogiri"

Run bundle install. Create the directory structure:

phlex-sandbox/
  app/
    components/
      base.rb
      heading.rb
      button.rb
      badge.rb
      avatar.rb
      link.rb
      panel.rb
      card.rb
      section.rb
      table.rb
   test/
    test_helper.rb
    components/
      button_test.rb
      card_test.rb
  demo.rb
  demo.css

Note: The directory structure will be empty at first, but by the end of this module we will have created all of the simple components together with some sample tests.

You will need to download the demo CSS file to follow along with this lesson.