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: |4 Build Phlex (Ruby) view components for Rails with Atomic Design methodology,5 Tailwind CSS styling, Stimulus controllers, and Turbo integration.6 Triggers on "Phlex component", "Phlex view", "Ruby view component",7 "build a Phlex", "Rails component", or "view_template".8model: sonnet9agent: phlex-developer10context: fork11---1213# Phlex Development1415Build Ruby view components using Phlex with Atomic Design methodology, Tailwind CSS, Stimulus, and Turbo.1617## When to Apply1819Use this skill when:20- Creating new Phlex view components (any atomic level)21- Converting ERB templates to Phlex components22- Building a component library in Rails23- Adding Stimulus interactivity to Phlex components24- Integrating Turbo frames/streams with Phlex views2526## Workflow2728### 8-Step Component Development29301. **Analyze requirements** -- Understand what the component needs to do, its props, and behavior312. **Determine atomic level** -- Use the decision tree to classify as atom/molecule/organism/template/page323. **Check existing components** -- Search `backend/app/components/` and `backend/app/views/` for reusable pieces334. **Check theming tokens** -- Verify design tokens exist for needed visual properties345. **Create component class** -- Inherit from `Components::Base` or `Views::Base`, use `view_template`356. **Apply Tailwind styling** -- Use token-based utility classes, `class_variants` for variants367. **Add Stimulus controllers** -- Wire up `data-controller`, `data-action`, `data-target` attributes378. **Test the component** -- Unit test with `Phlex::Testing::ViewHelper`3839## Component Class Reference4041| Method | Purpose |42|--------|---------|43| `view_template` | Main render method (replaces ERB) |44| `render ComponentClass.new(...)` | Compose child components |45| `yield` / `&block` | Accept content blocks |46| `html`, `head`, `body`, `div`, `span`, ... | HTML element methods |47| `data: { controller: "name" }` | Stimulus controller binding |4849## Key Conventions5051- **Props**: keyword arguments in `initialize`52- **Composition**: `render` for child components53- **Content**: `yield` or `&block` for content slots54- **Styling**: Tailwind utilities, design tokens, `class_variants`55- **Variants**: `class_variants` gem for multi-variant components56- **File limit**: 200 lines max per component5758## References5960- `references/phlex-patterns.md` -- Comprehensive Phlex patterns and API61- `references/component-examples.md` -- Working examples at each atomic level6263### Owned by `std-phlex-conventions` (scoped to `**/app/components/**/*.rb`)6465The two files above are worked *patterns*. These are decision-shaped, carry the bad/good pairs,66and are what the conventions actually mean — naming the skill is not the same as reading them:6768- **Atoms and molecules** → `@skills/std-phlex-conventions/references/component-levels-primitives.md`69- **Organisms, templates, pages** → `@skills/std-phlex-conventions/references/component-levels-composites.md`70- **Variants, tokens, class merging (`class_variants`)** → `@skills/std-phlex-conventions/references/variants-and-styling.md`71- **Stimulus wiring** → `@skills/std-phlex-conventions/references/stimulus-wiring.md`72- **Turbo Frames and Streams** → `@skills/std-phlex-conventions/references/turbo-frames-and-streams.md`73- **Testing components** → `@skills/std-phlex-conventions/references/testing.md`7475Rails backend conventions → the `std-rails-conventions` skill.7677**Two token facts before you style anything.** `destructive` and `neutral` are variant **keys**,78not tokens — the registered tokens are `error` and `muted`, and a class naming an unregistered79token (`bg-destructive`) compiles to **no CSS at all**, silently: the button renders transparent80with inherited text and review cannot see it. And a `-foreground` token is contrast-verified81against its **solid** surface, so `bg-success/10 text-success-foreground` is near-white on82near-white; on a tint use `text-foreground`. The registry is83`@skills/theming/references/platform-integration.md`.
Kaakati