bikeindex/bike_index / .claude/skills/frontend-conventions
frontend-conventions
VerifiedBike Index's frontend conventions — Tailwind class prefixing (`tw:`), the standard `twinput`/`twlabel`/`twlink` form/link classes, the `number_display` helper for numbers, `Counts` for site-wide figures (bikes registered, recoveries, organizations), the UI component library rule (every button is `UI::Button`/`UI::ButtonLink`, every typeahead/autocomplete is `UI::Forms::Combobox`, every FAQ is `UI::Accordion`, never hand-rolled markup; existing components before new ones — never a wrapper around one to dodge asking for a new `UI::*` argument, which needs the user's permission), that **helpers are deprecated — render a view component taking full keyword arguments instead of adding or extending one**, ViewComponent rules (when to write a partial instead, keyword arguments, instance variables, `helpers.` prefix in templates), and `UI::Time::Component` for every date/time, and that a new marketing page's URL is spelled with dashes. Trigger when adding or modifying views (`.html.erb`), view components, Stimulus controllers, Tailwind classes, image or icon files under `app/assets/images` (which usually already exist), a page's route or a link's path, or any frontend code that touches styling or interactivity. Stimulus.js is the JavaScript framework; SCSS and CoffeeScript files exist but are deprecated.
Frontend conventions
SCSS and CoffeeScript files are deprecated — don't add to them.
Format ERB before committing. After editing any .html.erb, run bin/lint on the files or directories you changed — bin/lint app/components/ui/table. It runs herb-lint and herb-format, which sort tw: classes, reflow long class attributes onto multiple lines, and flag things like an <input> missing autocomplete. CI's lint_and_scan job runs both as steps separate from standardrb/rubocop, so hand-edited ERB that skips formatting fails CI even when the Ruby is clean.
Scope it: every file a bare run rewrites that you've already read is re-injected into context in full.
Tailwind classes and helpers
-
Tailwind classes have the prefix
tw:(e.g.tw:text-blue,tw:flex,tw:gap-4).- The
tw:prefix comes before variant modifiers, not after. Usetw:dark:bg-gray-800,tw:hover:bg-blue-600,tw:sm:flex,tw:focus-visible:ring-2. Neverdark:tw:bg-gray-800— variant prefixes layer on top oftw:. darkis a custom variant keyed to a.darkancestor (app/assets/tailwind/application.css), and the page layouts set that class on<body>fromUser#color_scheme— it defaults tosystem, whichSharedBlocks::SystemColorSchemeresolves in the browser, and a signed-out page stays light whateverprefers-color-schemesays, so a dark-mode check means turning that on or adding.darkto<body>by hand (combobox.csskeys onbody.dark, so on<html>the comboboxes stay light). A preview takes it as?lookbook%5Bdisplay%5D%5Btheme%5D=darkon the bare/rails/view_components/route, which/lookbook/preview/ignores. Keep writing the variants; just don't read a light screenshot as a missing one. Legacy markup's dark colors are inapp/assets/tailwind/legacy_dark.css, not the SCSS;kelsey_styles.cssis unlayered, so its pages stay light unless their wrapper addskelsey_styles_dark, which re-points its--redesign-*colors, and a section inside it addskelsey_styles_lightto keep the light ones (Pages::LandingPages::ForSchools); a color it doesn't cover takes a!utility. Black-ink art on a transparent background istw:dark:invert tw:dark:hue-rotate-180.
- The
-
Yellow is the theme's
yellow-*, Bike Index's own ramp —yellow-300is the brand yellow, never its hex oramber-*. A status surface in dark mode is a translucent tint, not a solid-950:tw:dark:bg-yellow-300/25 tw:dark:border-yellow-300/50, and the-500of the other status colors.UI::Alerts::Baseis the pattern. -
Form fields should use the
twinputclass. -
Labels should use the
twlabelclass. -
Basic links should use the
twlinkclass. -
A link that should take the color of the text around it — inside an alert, a colored
<small>, the review-app banner — usestwlink-underlinedinstead. Never hand-rolltw:text-inherit tw:underline. Its color must come from an ancestor, not atw:text-*on the link itself, which would outrank the class at every state. -
A row of two or three things side by side uses
twfieldrowortwwiderow, nottw:md:grid-cols-2.twfieldrowis for fields that read as one control (a city and its state);twwiderowis for cards and sections, andtwwiderow twwiderow-3for three of them. Both break on the row's own width rather than a viewport breakpoint, so a row nested in a narrow card breaks where it should.UI::Card'sfull_bleed:is keyed totwwiderowby a container query, so it only bleeds inside one, and only once that row is single-column. All three are inapp/assets/tailwind/bike_index_components.css. -
A small purple section label (the registration page's and Bike Book's) is
tw:tweyebrow. -
The default text color is
tw:twtext-color(tw:twtext-color!to force it). It's an@utility, hence thetw:prefix — any Bike Index class that something@applys has to be an@utility; v4's@applyrejects a@layer componentsclass with "Cannot apply unknown utility class". -
A horizontal scroller runs out to its container's edges, the container's padding inside it —
twgutter-bleed tw:overflow-x-auto, with--gutterset to that padding wherever it isn't the page's (tw:[--gutter:--spacing(2.5)]in apx-2.5table cell). One out to the window's edges istwpagebleed, paddedtw:px-(--gutter).UI::Table::Base,UI::TabsandSharedBlocks::Marketing::RecoveryStoriesare the pattern; atw:m-0ortw:p-0besidetwgutter-bleedundoes it. A scroller that is its own bordered box — a code block,Atoms::CopyableCode— scrolls inside its border instead. -
A custom
@utilityhas no fixed rank against a core one it collides with — Tailwind sorts custom and core utilities together, sotw:twfullbleedemits aftertw:borderwhile another pairing may go the other way. A hand-written@layer utilities { }block inbike_index_components.cssdoes have a fixed rank: it emits after everything Tailwind generates, so it takes ties and needs no@variantor!. That's also how to define an unprefixed class name —@utilitywould force thetw:prefix..only-dev-visibleis the pattern for both. Grepapp/assets/builds/tailwind.cssfor the two selectors when a collision matters. -
A
@layer componentsrule loses to a utility class on the same element, whatever the specificity — so a hand-written rule that setsdisplayis inert against an element carryingtw:gridortw:flex, silently. A variant utility has no such problem, and reaches further than it looks:SharedBlocks::SearchResults::Framedrives its whole loading swap offtw:group,tw:peerand an arbitrarytw:peer-[[busy]:not(:has(>.search-results-card))]:block, with no rule at all.@custom-variantwhen the state is worth naming for templates to use inline (search-all-checkedis the pattern), and a long selector written out per utility in a component constant, since tailwind scans for whole class names. -
A Tailwind class a Stimulus controller toggles is a literal in that controller, not a
static classesvalue the template has to carry —ui/table_controller.jstogglingtw:overflow-x-scrollis the pattern, and there are ~40 of those against onestatic classes. Tailwind scansapp/javascript, so the utility is generated either way; reach forstatic classesonly when call sites need different classes. -
Every number renders with
number_display(number)— including one composed into a string:[number_display(bike_count), organization.short_name].join(" ")wraps the number, not the string.- "Number" includes counts, distances and quantities — anything whose magnitude is the point.
- Not a year.
number_displayisnumber_with_delimiter, so it renders 2015 as "2,015". Emit a year bare, the waybike_title_htmland the search result cards do — nothing inapp/wraps one. The same delimiter argument applies to any identifier that only looks numeric.
-
A site-wide figure comes from
Counts(app/services/counts.rb) — bikes registered (total_bikes), stolen (stolen_bikes), recoveries, the recovered value, organizations. Read several in one round trip withCounts.retrieve_many("total_bikes", "recoveries"). Never a liveBike.count/Organization.counton a public page, which counts the whole table on every render, and never a number typed into copy, which goes stale.UpdateCountsJobrefreshes them hourly, so a new figure is a newCOUNT_KEYSentry with anassign_*, not a query in the view. Admin screens that want the exact live number are the exception. A dev server shows whatever its Redis holds, not this workspace's database —bin/rails setup:load_countsrecomputes them. -
Currency amounts use
amount_display(obj)instead ofnumber_displaydirectly. It takes an object that responds toamount_cents,amount,currency_symbol, andcurrency_name(e.g. aMarketplaceListing), and renders the symbol +number_display(amount)together. Don't reach fornumber_to_currencyor roll your own. -
Every phone number renders through
Atoms::Phone::Component— never a hand-rolledtel:link ornumber_to_phone. It links by default; passskip_link: truefor plain text. Seeapp/components/atoms/phone/. Non-markup callers that need the formatted string (a form field value, a translation interpolation) usePhonifyer.display. -
Every date/time renders through
UI::Time::Component—render(UI::Time::Component.new(time: some_time)). It emits the client-localizedlocalizeTimespan the frontend JS converts to the viewer's timezone. This is the only way to show a time: neverl(time, ...),strftime,time_ago_in_words, or a hand-writtenlocalizeTimespan. Passformat: :localize_time_precisewhen you need seconds precision (default is:localize_time). It self-hides whentimeis nil, so no surroundingifguard is needed.- Legacy
l(time, format: :convert_time)inside alocalizeTimespan predates the component and is still all over the admin tables. Convert one toUI::Time::Componentwhenever you touch the line it's on — including when it's the body of alink_to.
- Legacy
-
An image from a design handoff is already in the repo — use the original, never a renamed or resized copy.
kelsey_redesign/holds the drawn originals; a served one is a byte-identical copy under its original name inapp/assets/images/kelsey/illustrations/, ascomic-assets_bike-love-*.pngare. Before adding any PNG/JPG,git ls-filesthe distinctive words of its name across the whole repo — a hash search misses a resized copy. -
Look for an existing icon before adding an SVG — all of
app/assets/images/(not justicons/),app/javascript/bikebook/templates/icons.js, and text glyphs in templates. A mark that's a plain character is text, not an icon: a link's trailing arrow is<span aria-hidden="true">→</span>(SharedBlocks::MainContent::OrganizedShopIntegrationAlert), and a?,!oriin a disc is the character (UI::Tooltip,Pages::EbikeRules::StatusIcon). A check or a cross stays an icon. -
A decorative icon is
inline_svg_tag(..., aria_hidden: true)—aria: {hidden: true}is a hashinline_svgdrops, leaving ansvg[role=img]with no accessible name, which only an axe audit in a:jsspec catches.
Building markup to pass into a component argument uses capture — a component keyword like UI::Alerts::Base's header: or UI::Header's text: takes a string, so a heading that wraps a link or an <em> has to be captured first.
A component dropped into legacy markup is styled on the component
Every legacy stylesheet wraps itself in @layer legacy (see app/assets/stylesheets/legacy_includes/_css_layers.scss), which sorts below tailwind's components and utilities. So a UI::* component rendered inside legacy-styled markup wins over the surrounding stylesheet's rules for every property its own classes set — UI::Button's tw:inline-flex, tw:p-0 and twlink beat .primary-header-nav's display, padding and color no matter how specific those selectors are.
!important reverses layer order, so a legacy-layer !important beats a tailwind utility that isn't. A rule kept "just in case" in revised.scss is not inert — it is what paints. Delete the legacy rule rather than leaving it alongside; revised.scss is fully inside the layer, so the utility already wins without it.
Tailwind v4 traps
- A build that was right can go wrong under you. Each workspace runs its own
tailwindcss:watch, and one can overwriteapp/assets/builds/tailwind.csswith a scan from before your edit — so a rule you just wrote is served, then isn't. Before believing a CSS change doesn't work, count it in the build (grep -o '<class>' app/assets/builds/tailwind.css | wc -l, since the file is minified onto few lines) and check the built file's mtime against the source's.bin/rails tailwindcss:buildrestores it. - An
_inside an arbitrary value compiles to a space.tw:group-has-[#donate_cadence:checked]:flexbuilds#donate cadence:checked, a descendant selector that never matches, so the class is emitted and inert. Give an id an arbitrary variant keys on dashes (Pages::Donate::Form'sdonate-cadence-one-time), or escape it as\_. - A grid item stretches to its row. For a
<div>that's invisible, but a bare<table>grid item spreads the extra height across its own rows, so twoUI::Table::Listpanels side by side pull each other's rows tall.tw:items-starton the grid, or wrap the table in a<div>.
Buttons: always UI::Button (and the UI component library generally)
Every button goes through UI::Button::Component — never a hand-rolled <button>, button_to, or submit input with ad-hoc Tailwind classes. The component centralizes colors (its COLORS is the list of record), sizes (:sm/:md/:lg), and the focus/active/dark-mode states; a hand-styled button silently drifts from all of that the next time the design changes.
An in-page action trigger that doesn't navigate is a UI::Button, not link_to "#" — .herb.yml runs html-anchor-require-href over app/components only, so a component is caught and an app/views template isn't. UI::Forms::NestedFields::Component's add trigger is the worked example.
-
Plain button or form submit — a form submits with
color: :primary:render UI::Button::Component.new(text: "Save", color: :primary, type: "submit"). Pass a class ashtml_class:— the component builds its own, so aclass:raises. -
A link styled as a button:
UI::ButtonLink::Component.new(href:, text:, color:, size:)— same palette, renders an<a>. -
A standalone action button (POST/DELETE/etc. to a URL) — a link that performs an action: pass
method:toButtonLinkand it rendersbutton_tofor you (render UI::ButtonLink::Component.new(text: "Delete", color: :error, href: bike_path(@bike), method: :delete)), so don't hand-roll abutton_toor wrap a submit button in a bare form. Extrahtml_optionsflow through: passparams:for a POST that carries params (they render as hidden fields — no manualform_with/hidden_field_tagneeded).- Not inside another form —
button_torenders a<form>, and the parser drops a nested one, hoisting its button into the outer form, which that button then submits. Nothing errors; it just does the wrong thing when clicked. Either passconfirm:(which switches the component to a Turbo link — see below), or, for an action with no prompt, carry the verb yourself withdata: {turbo: true, turbo_method: :put}on a link.
- Not inside another form —
-
An action that needs confirming passes
confirm:alongsidemethod:, and the component renders a Turbo link rather than abutton_to— an<a>carrying the method plus anonclickthat Turbo's click handler honours. So a confirming action nests anywhere a link does, and no call site spells the mechanism out.Pages::MyAccount::OrganizationRolesis the worked example.
The same instinct applies beyond buttons: check app/components/ui/ and app/components/atoms/ before hand-rolling any UI primitive (dropdowns → UI::Dropdown, tooltips → UI::Tooltip, form fields → UI::Forms::*, label-beside-value tables → UI::Table::List — only email CSS still styles .table-list, so the legacy class renders bare on a page — inline code → UI::Code::Inline, a block of JSON → UI::Code::Json, badges, modals, pagination, tables…). If a component exists for the pattern, use it. Never add an argument to a UI::* component without the user's explicit permission — its arguments are the design system's surface, and one added for a single caller stays for every caller. If it almost fits, ask, and don't fork its markup inline meanwhile.
A marketing page — a for_* landing page, donate, a how-it-works — builds on SharedBlocks::Marketing; the use-existing-markup skill maps each hand-drawn block to its component.
Four of those carry a rule beyond "use the component":
UI::Tooltipkeeps its default?button trigger unless the user explicitly says otherwise — never pass a label as the trigger content.- A
UI::Forms::*field gets its label fromUI::Forms::Group— render it inside aGroupblock, passingform_builder:when there is one. Holds forCombobox,Select,TextEditor, andFiles::Upload, whose ownUploadbutton is a second label for the same input and audits clean besideGroup's (spec/components/ui/forms/group/component_system_spec.rb) — never dropGroupfor a bare<label>to avoid it. A visually hidden label is the exception:Group's label always carries a required/optional suffix, so use a barelabel_tagwithtwlabel tw:sr-only, the wayPages::Search::Formdoes. - Every typeahead / autocomplete goes through
UI::Forms::Combobox::Component— never a new Stimulus controller that fetches matches and renders its own menu.spec/components/ui/forms/comboboxshows how to invoke it. - Every FAQ / list of questions is
UI::Accordion::Component—items:as[question, answer]pairs. Never hand-rolled<details>or per-itemUI::Collapsemarkup. - Every chart goes through
UI::Chart::Component— chartkick'scolumn_chart/line_chart/pie_charthelpers are pinnedpreload: falseand fetched by the component'sui--chartcontroller, so a bare helper call renders the placeholder and nothing else. Passkind:for a line or pie. A page with no Stimulus (layout: false) loads them itself:app/views/welcome/bike_creation_graph.html.erb.
Atoms::* (app/components/atoms/) holds the small value-rendering components — Atoms::Serial, Atoms::Sticker, Atoms::ShortId, Atoms::Phone. Everything else is UI::*; older value renderers like UI::AddressDisplay predate the split and stay put. Render a serial with Atoms::Serial::Component.
URLs: dashes for a new marketing page
Spell a new marketing or landing page's path with dashes — /donate/year-end-2026, /ebike-rules, /marketplace/how-it-works — since Google reads a hyphen as a word break and an underscore as joining two words. Give its route an underscored as: so the helper still reads like the rest (get "ebike-rules", to: "ebike_rules#show", as: :ebike_rules). Everything else, and the marketing pages that are already underscored (/for_bike_shops), stays as it is.
Don't add a route for the other spelling. PathSpellingRedirect, the *path route at the end of config/routes.rb, 301s an unmatched path to whichever spelling is routed, keeping the query. Link with the path helper; where a literal has to stand (a JS template, an emailed link, a spec's have_current_path), write the routed spelling, since the other costs a redirect.
Form drafts: always form-persist
A form worth not retyping mirrors itself to localStorage through the form-persist controller — never one of your own. It takes a data-form-persist-key-value when the derived key — the pathname plus the form's action — isn't unique per form. See app/components/pages/register/views/step1/component.rb and app/components/pages/register/views/step2/component.html.erb.
A controller whose UI hangs off a restored field reconciles in two places — a form-persist:restored@window->… entry in the element's data-action, and the same call in its own connect. A hand-rolled window.addEventListener is the older idiom; don't add more. See app/components/pages/register/views/step1/component.html.erb with app/javascript/controllers/register/heading_controller.js.
Current-page links: always UI::ActiveLink
Every link that goes aria-current on the page it points at goes through UI::ActiveLink::Component — never current_page? in a template, and never a Stimulus controller of your own comparing window.location. It always derives the state in the browser (app/javascript/controllers/ui/active_link_controller.js), so there's no way to pass the answer in: match_paths: is the only control over what counts as the page it points at. Any layout rendering one opens its <body> with body_tag. See app/components/ui/active_link/.
match_params: is the params the entry stands for, not the ones its path: sets — a filter entry that toggles links away from itself to clear the filter, so the two differ. Passing path:'s value to both fails silently, and only on the entry that is currently applied.
Showing and hiding elements: always use the collapse helpers
Any time you show, hide, or toggle an element in response to interaction, go through the shared collapse helpers. Never hand-roll it with the hidden attribute, element.style.display, element.hidden = true, or ad-hoc classList.add('tw:hidden') — those skip the shared show/hide animation and the tw:hidden!/tw:hidden class contract the rest of the app depends on.
-
Markup-only toggle (a trigger reveals/collapses a panel, no other logic): add
data-controller="ui--collapse", mark the collapsible elementdata-ui--collapse-target="content", and render the trigger withUI::Collapse::Component(chevron: truefor the rotating chevron) — never a hand-wired button (app/javascript/controllers/ui/collapse_controller.js). -
Inside your own Stimulus controller (you have extra logic — a redirect branch, a query-param check, etc.): import
collapse_utilsand call it directly:import { collapse } from 'utils/collapse_utils' // ... collapse('show', this.formTarget) // 'show' | 'hide' | 'toggle'; optional duration (default 200)
The collapsible element starts hidden with the tw:hidden class (not the hidden attribute) — collapse toggles tw:hidden/tw:hidden! and runs the height/scale transition for you. Use tw:hidden! when the element also carries a display utility that sorts after hidden — any inline-*, which every UI::Button has. A plain tw:hidden renders that panel open, and no component spec can see it: the class is in the attribute, it just loses the cascade. Because the initial hidden state is a class, component specs assert it by class (have_css("[…].tw\\:hidden")), not Capybara visibility — the rack_test driver doesn't evaluate CSS, so it can't tell a class-hidden element is hidden.
No dead hooks in markup
Only add an id or non-utility class when something concrete consumes it — a CSS rule, a JS/Stimulus selector, a test fixture, an accessibility attribute. Don't keep or invent "structural identifier" hooks "in case something needs them later."
When deleting an id/class, grep the repo for the name before deciding what to do with it:
On a page that loads a vendored bundle, grep public/vendored_assets/*.js as well as app/. The
Doorkeeper layout loads application_standalone.js and the bike versions index bikes_search1.js; they bind
behaviour by id and class, and their source left the repo with the webpack config, so they can't be rebuilt —
a hook with no consumer in app/ is routinely live. Each .js.map still carries the original source in
sourcesContent, which reads far better than the minified bundle. Handlers are guarded on a hook being present, and the guard is often a different id than the one bound: #blog-image-form gates the module
that binds #infoCheck. So removing an id silently disables behaviour, sometimes behaviour attached
to another id entirely.
Grep for what a module assigns, not only the hooks it binds — a guarded init publishes globals and
its callers don't re-check the guard. No spec catches it; a converted page's browser_console_messages does.
- Zero consumers: delete it, don't rename it.
- Consumers exist: either update them, or leave the hook in place — the consumers are the reason it earns its spot in the markup.
Helpers are deprecated — render a view component instead
Never add a helper method, and don't extend an existing one. Anything a helper would render belongs in a view component that takes what it needs as explicit keyword arguments. app/helpers/ is legacy: leave what's there, but move a helper into a component when you touch the line that calls it.
- A view helper that only gathers a component's arguments out of controller assigns is still a helper — pass those arguments from the view.
ApplicationComponentHelperis the exception (number_display,amount_display,check_mark,search_emoji) — value formattersApplicationComponentalready includes, so components call them bare.
What's banned is the component reaching out, not the number of arguments. State the controller already owns can be named and passed as one value object — ComponentStructs::IndexState (built in ControllerHelpers#admin_index_state) and ComponentStructs::SortState (ControllerHelpers#sort_state) are the pattern — value objects live in app/services/component_structs/.
Bundle only what's cohesive — one subject, assembled in one place. IndexState is "this admin index request"; ComponentStructs::SortState is "how this table is sorted and what its links carry". A grab-bag of unrelated request facts (display_dev_info, current_user, current_country_id) is not a value object, it's helpers renamed — those stay individual arguments. Data.define for one that only carries its arguments; a plain class when it memoizes derivations, since Data instances are frozen and @x ||= raises on one (ComponentStructs::OrgSearchSettings).
ViewComponent rules
This project uses the ViewComponent gem to render components.
- Prefer an existing component to a new one, extended if needed. Before creating one, look for a component that already renders the pattern or its core — in
ui/,atoms/and the siblingpages/namespaces. A new component whose template is mostly one existingUI::*component plus chrome is that component with an argument: ask to extend it (the no-new-argument rule above) rather than wrapping it to avoid asking.UI::BulkTableCard, folded intoUI::Table::InCard'scolumn_settings:, is the pattern. - Before creating a component, check it earns its class. If its
component.rbwould hold nothing butinitializeassigning arguments to ivars, and fewer than 3 callers render it, write a partial instead, with<%# locals: (…) %>at the top. An admin index table onUI::Table::Baseis the usual case:admin/strava_gears/_table.html.erbis the pattern, andPages::Admin::IndexSkeletonrenders the_tablepartial without atable_view:. A component earns its class with logic to name, a cache key to build, or a third caller; past that bar, prefer components to partials. - If a view file only renders a single component, consider rendering it from the controller instead (
render Foo::Component.new(...)) and deleting the view file — the layout still wraps it. - Generate a new view component with
rails generate component ComponentName argument1 argument2. - View components must initialize with keyword arguments. Everything the component needs must be passed in explicitly by the caller — never reach into controller state from inside a component (e.g.
controller.instance_variable_get(:@bike)). If the component needs@bike, the caller rendersComponent.new(bike: @bike). - In view components, use instance variables directly — don't add
attr_reader/attr_accessor. Reference@fooeverywhere, including in the template (@current_user, notcurrent_user). - In ViewComponent templates, use the
helpers.prefix for view helpers (e.g.helpers.time_ago_in_words) — a legacy bridge, and a sign the helper wants to be a component.- Rule of thumb: try the bare call first. Only add
helpers.if it fails withNoMethodError— route helpers (new_bike_path) and ActionView tag/url builders (tag.span,content_tag,link_to) are mixed intoViewComponent::Basedirectly, so they don't need it.
- Rule of thumb: try the bare call first. Only add
- Never nest a component inside a folder that already holds a
component.rb. Each component lives inapp/components/<path>/component.rb(andspec/components/<path>/component_spec.rb); siblings go in sibling folders, not subfolders. If you havepages/search/everything_combobox/component.rband need a related component, place it atpages/search/everything_combobox_options/component.rb(modulePages::Search::EverythingComboboxOptions), notpages/search/everything_combobox/options/component.rb. - Cached markup has no digest to maintain.
ApplicationComponentincludesViewComponent::ExperimentallyCacheable, so acacheblock moves when anything it renders changes. - A component that builds its own
cache_keyincludesself.class.cache_digest—SharedBlocks::Footeris the pattern. - A component not rendered as a literal constant after
renderneeds a# Template Dependency: Full::Class::Componentline in the component that uses it —render(inner_component), a collection, or a constant read all count.SharedBlocks::Navbar::Wrapperis the pattern;spec/components/application_component_spec.rbfails on a missing or stale one. skip_digest: trueand components outsideApplicationComponentbypass the digest. Askip_digestkey carries the component'scache_digestitself —welcome/index.html.erbis the pattern.- Change a component's signature, then open its
component_preview.rb— nothing renders previews in the suite, so a stale one raisesArgumentError: unknown keywordon its Lookbook page with the whole suite green.curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/rails/view_components/<path>/component/<scenario>"is the check. - A
UI::Table::Basecell block isinstance_exec'd against the component. Insidetable.column ... do, bare calls and@ivars resolve onUI::Table::Base::Component, not the view. A bare call raises, but an@ivarfails silently — it readsnil, or worse, an identically-named ivar the table happens to hold. Reach state through the readers the table exposes (sort_state.search_params, notsortable_search_params), and for anything else assign a local above the block, the wayPages::Org::SearchResults::BikesTablecarriesorganization. Above theUI::Table::Base::Component.newblock the view's own helpers work; rewriting those too is churn. - Dev-only admin markup renders unconditionally, classed
only-dev-visible—SharedBlocks::HeaderTagshides that class in the page head per request, which is what lets one fragment-cached row serve dev and non-dev viewers both. Never putdisplay_dev_info?in a cache key, and never inject a second, local<style>to hide it;admin/notifications/_table.html.erbis the pattern. The class hides, it does not omit, so three things keep adisplay_dev_info?gate: a payload a non-dev should not hold in page source at all (Pages::Org::BulkImportError's rawimport_errors), a form input, whose params would otherwise submit (Pages::Admin::Users::Edit'sdevelopercheckbox), and a decision about whether something exists rather than whether it shows (Organizations::Tabs#render_tab?oncustom_layouts). - Cache rows, never cells. A
cache(...)inside a cell digestsUI::Table::Base's template rather than the calling partial's, so it needs acache_fragment_nameprefix to avoid sharing a fragment with every other table caching that record. Passcache_key:andcache_records:toUI::Table::Baseinstead —admin/payments/_table.html.erbis the pattern. A fragment cached per organization can hold nothing that varies by viewer — the org search's rows and cards cache on the organization, so its serials render for the organization (Atoms::Serial::Component, andBike#serial_displaytake one) rather thancurrent_user, or one member's page is served to the next. A row key has three inputs and one exclusion: the record (automatic), every flag fixed for the render (cache_key: cache_fragment_name([name, *flags])), every other record the row renders (cache_records:, which mirrors the controller'sincludes— a cell reading an association the controller doesn't preload is an N+1 and a stale row at once; one that can't be preloaded, because a method re-queries over it likeTheftAlert#bike, stays out of the key rather than costing a query per row on every hit), and neversort_state.search_params, which varies per request: wrap the table inupdate-cached-sortable-linksand let it rewrite those hrefs client-side. - A component that
includes a helper is coupled to whatever ivars that helper reads.GraphingHelper#time_range_countsfalls back to@time_rangeoff the object it's mixed into, so moving that ivar out of the component silently returns nil rather than failing. Pass the value as an argument when converting a component to explicit arguments. - Moving a view into a component turns its locals into methods. A
<% x = … %>computed once per template becomes a method run once per call site — which is how a single pluck becomes one per table row. Memoize anything that queries as you move it. - Converting a partial — to a component, or from haml to ERB — is a faithful move, not a cleanup. Carry the markup over verbatim, including comments and commented-out code: those are often a deliberate stash (a link temporarily disabled, a snippet someone expects to restore). The only changes a conversion introduces are the ones the move requires —
t(".x")→translation(".x"), addinghelpers.where a helper now needs it. Dead code worth removing goes in its own commit.
Turbo is opt-in, and opting a form in has consequences
application.js sets Turbo.session.drive = false, so links and forms submit natively
until something carries data-turbo="true". These bite the first time a form opts
in, none of which shows up as an error — the page just behaves oddly:
- A controller-rendered component takes its content type from the request. A Turbo
submission sends
Accept: text/vnd.turbo-stream.htmlfirst, andrender Foo::Component.new(...)has no template format to override it, so the response comes back as a stream message — which Turbo appends to the current page instead of replacing it. Two steps of a wizard end up on screen at once. Fix it at the controller withbefore_action { request.format = :html }for actions that only ever render pages. (An.html.erbview doesn't have this problem: the template's own format sets the content type.) data-turbo="true"on a form opts in every link inside it too — navigability is resolved withclosest("[data-turbo]"), so it isn't scoped to the submission. A link that leaves for a legacy jQuery page needsdata: {turbo: false}, or it gets Turbo-rendered into a body whoseloadPageScriptnever runs. Links to pages the Stimulus redesign owns are fine.data-turbois opt-out on any value but"false"— an emptydata-turbo="", from interpolating a false into the attribute, reads as opted in. Render the attribute conditionally (tag.attributes(data: {turbo: (true if @turbo)})) rather than its value;UI::Tabsis the example.- Turbo restores its own snapshot on back/forward, which
Cache-Control: no-storecan't reach. If what a page renders depends on server state, opt out withhelpers.content_for(:header) { tag.meta(name: "turbo-cache-control", content: "no-cache") }—Pages::Register::Parts::ShellandSharedBlocks::SearchResults::Frameare the examples — and a restoration re-fetches instead of showing a page the user has moved past.
RegisterController and the Pages::Register:: components are the worked example of both.
Admin screens
A record with more than one super-admin page gets Pages::Admin::Headers::Tabs::Component, with the
section's own tabs named in a component of their own — Pages::Admin::Organizations::Tabs is the
pattern — rather than restated in each view.
sortable_search_params (defined in the binxtils gem, Binxtils::SortableHelper) permits every
param starting with search_, plus the sort and period keys — which is how a filter link keeps the
rest of the table's state. Reach it through the reader, not the bare helper:
url_for(@index.sortable_search_params.merge(search_kind: "x")).
Screenshots
Not this skill's — frontend-screenshots owns them, including where the files land.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |