Phlex Development
Build Ruby view components using Phlex with Atomic Design methodology, Tailwind CSS, Stimulus, and Turbo.
When to Apply
Use this skill when:
- Creating new Phlex view components (any atomic level)
- Converting ERB templates to Phlex components
- Building a component library in Rails
- Adding Stimulus interactivity to Phlex components
- Integrating Turbo frames/streams with Phlex views
Workflow
8-Step Component Development
- Analyze requirements -- Understand what the component needs to do, its props, and behavior
- Determine atomic level -- Use the decision tree to classify as atom/molecule/organism/template/page
- Check existing components -- Search
backend/app/components/ and backend/app/views/ for reusable pieces
- Check theming tokens -- Verify design tokens exist for needed visual properties
- Create component class -- Inherit from
Components::Base or Views::Base, use view_template
- Apply Tailwind styling -- Use token-based utility classes,
class_variants for variants
- Add Stimulus controllers -- Wire up
data-controller, data-action, data-target attributes
- Test the component -- Unit test with
Phlex::Testing::ViewHelper
Component Class Reference
| Method |
Purpose |
view_template |
Main render method (replaces ERB) |
render ComponentClass.new(...) |
Compose child components |
yield / &block |
Accept content blocks |
html, head, body, div, span, ... |
HTML element methods |
data: { controller: "name" } |
Stimulus controller binding |
Key Conventions
- Props: keyword arguments in
initialize
- Composition:
render for child components
- Content:
yield or &block for content slots
- Styling: Tailwind utilities, design tokens,
class_variants
- Variants:
class_variants gem for multi-variant components
- File limit: 200 lines max per component
References
references/phlex-patterns.md -- Comprehensive Phlex patterns and APIreferences/component-examples.md -- Working examples at each atomic level
Owned by std-phlex-conventions (scoped to **/app/components/**/*.rb)
The two files above are worked patterns. These are decision-shaped, carry the bad/good pairs,
and are what the conventions actually mean — naming the skill is not the same as reading them:
- Atoms and molecules →
@skills/std-phlex-conventions/references/component-levels-primitives.md
- Organisms, templates, pages →
@skills/std-phlex-conventions/references/component-levels-composites.md
- Variants, tokens, class merging (
class_variants) → @skills/std-phlex-conventions/references/variants-and-styling.md
- Stimulus wiring →
@skills/std-phlex-conventions/references/stimulus-wiring.md
- Turbo Frames and Streams →
@skills/std-phlex-conventions/references/turbo-frames-and-streams.md
- Testing components →
@skills/std-phlex-conventions/references/testing.md
Rails backend conventions → the std-rails-conventions skill.
Two token facts before you style anything. destructive and neutral are variant keys,
not tokens — the registered tokens are error and muted, and a class naming an unregistered
token (bg-destructive) compiles to no CSS at all, silently: the button renders transparent
with inherited text and review cannot see it. And a -foreground token is contrast-verified
against its solid surface, so bg-success/10 text-success-foreground is near-white on
near-white; on a tint use text-foreground. The registry is
@skills/theming/references/platform-integration.md.
1---2name: phlex-dev3description: Build Phlex (Ruby) view components for Rails with Atomic Design methodology, Tailwind CSS styling, Stimulus controllers, and Turbo integration. Triggers on "Phlex component", "Phlex view", "Ruby view component", "build a Phlex", "Rails component", or "view_template".4---56# Phlex Development78Build Ruby view components using Phlex with Atomic Design methodology, Tailwind CSS, Stimulus, and Turbo.910## When to Apply1112Use this skill when:13- Creating new Phlex view components (any atomic level)14- Converting ERB templates to Phlex components15- Building a component library in Rails16- Adding Stimulus interactivity to Phlex components17- Integrating Turbo frames/streams with Phlex views1819## Workflow2021### 8-Step Component Development22231. **Analyze requirements** -- Understand what the component needs to do, its props, and behavior242. **Determine atomic level** -- Use the decision tree to classify as atom/molecule/organism/template/page253. **Check existing components** -- Search `backend/app/components/` and `backend/app/views/` for reusable pieces264. **Check theming tokens** -- Verify design tokens exist for needed visual properties275. **Create component class** -- Inherit from `Components::Base` or `Views::Base`, use `view_template`286. **Apply Tailwind styling** -- Use token-based utility classes, `class_variants` for variants297. **Add Stimulus controllers** -- Wire up `data-controller`, `data-action`, `data-target` attributes308. **Test the component** -- Unit test with `Phlex::Testing::ViewHelper`3132## Component Class Reference3334| Method | Purpose |35|--------|---------|36| `view_template` | Main render method (replaces ERB) |37| `render ComponentClass.new(...)` | Compose child components |38| `yield` / `&block` | Accept content blocks |39| `html`, `head`, `body`, `div`, `span`, ... | HTML element methods |40| `data: { controller: "name" }` | Stimulus controller binding |4142## Key Conventions4344- **Props**: keyword arguments in `initialize`45- **Composition**: `render` for child components46- **Content**: `yield` or `&block` for content slots47- **Styling**: Tailwind utilities, design tokens, `class_variants`48- **Variants**: `class_variants` gem for multi-variant components49- **File limit**: 200 lines max per component5051## References5253- `references/phlex-patterns.md` -- Comprehensive Phlex patterns and API54- `references/component-examples.md` -- Working examples at each atomic level5556### Owned by `std-phlex-conventions` (scoped to `**/app/components/**/*.rb`)5758The two files above are worked *patterns*. These are decision-shaped, carry the bad/good pairs,59and are what the conventions actually mean — naming the skill is not the same as reading them:6061- **Atoms and molecules** → `@skills/std-phlex-conventions/references/component-levels-primitives.md`62- **Organisms, templates, pages** → `@skills/std-phlex-conventions/references/component-levels-composites.md`63- **Variants, tokens, class merging (`class_variants`)** → `@skills/std-phlex-conventions/references/variants-and-styling.md`64- **Stimulus wiring** → `@skills/std-phlex-conventions/references/stimulus-wiring.md`65- **Turbo Frames and Streams** → `@skills/std-phlex-conventions/references/turbo-frames-and-streams.md`66- **Testing components** → `@skills/std-phlex-conventions/references/testing.md`6768Rails backend conventions → the `std-rails-conventions` skill.6970**Two token facts before you style anything.** `destructive` and `neutral` are variant **keys**,71not tokens — the registered tokens are `error` and `muted`, and a class naming an unregistered72token (`bg-destructive`) compiles to **no CSS at all**, silently: the button renders transparent73with inherited text and review cannot see it. And a `-foreground` token is contrast-verified74against its **solid** surface, so `bg-success/10 text-success-foreground` is near-white on75near-white; on a tint use `text-foreground`. The registry is76`@skills/theming/references/platform-integration.md`.
Kaakati