folio

Folio and host-app testing conventions. Use when adding, changing, debugging, or reviewing tests, test helpers, factories/fixtures, mocks, stubs, ViewComponent tests, JavaScript behavior tests, integration/system coverage, or files under test/ and packs/*/test.

Folio “HTML over wire” JSON APIs: controllers use render_component_json so the response body is JSON with a string "data" key holding rendered ViewComponent HTML; JavaScript uses Folio.Api.apiGet/apiPost and response.data, not pure domain JSON for client-side rendering. Use when adding or changing render_component_json, console/API endpoints that return component fragments, or consumers of response.data as HTML.

JavaScript conventions for Folio: ES6+, StandardJS linting, DOM APIs, Folio.Api fetch wrappers, debounce/throttle, flash events, and when to use Stimulus. Use when writing or editing .js files, adding behavior to components, or when the user asks about JavaScript patterns in Folio.

Folio optional pack boundary and namespace rules. Use when editing files in optional pack directories, adding pack controllers/components/models/lib code, wiring routes to pack code, or moving reusable behavior between a host app, the Folio engine, and an optional pack, including Packwerk verification.

Build or change Folio SimpleForm inputs and extensions: app/inputs classes, SimpleForm::Inputs overrides, register_stimulus wiring, input_controls, custom_html, standalone input JS/Sass assets, and rendered HTML tests.

Slim template formatting and best practices for Folio components and views. Use when writing or editing .slim templates, reviewing Slim formatting, or when the user asks about Slim conventions, multi-line attributes, or template structure in Folio.

Folio Stimulus conventions: controller registration, StimulusHelper data attributes, values/targets/actions, and controller file placement. Use when adding JavaScript behavior to a Folio component, wiring data-controller / data-action / data-target, using StimulusHelper in Slim, or writing a new Stimulus controller in Folio or a host app.

Develops and maintains Folio ViewComponents: generators, BEM, Slim, Stimulus data attributes, colocated assets, tests, and composition. Use when building or editing UI in app/components, adding Stimulus to a component, writing component tests, or when the user asks for ViewComponent / frontend component patterns in Folio or a host app on Folio.

Ruby/Rails code structure conventions for Folio: keeping model, controller, and concern entrypoints thin; extracting multi-step parsing, decision, or orchestration logic to focused classes under lib; and avoiding helper-method clusters on Rails integration objects. Use when adding or refactoring Ruby methods, controller actions, model hooks, concerns, or service-style code.

Folio embed-data conventions for folio_embed_data, as: :embed, canonical embed JSON, embed validation, rendering, migrations, and console forms. Use when replacing legacy embed URL, HTML, or source fields, or when changing model-backed Folio embeds.

Rails and ActiveModel model conventions for Folio: validations, form-facing attributes, console required-marker inference, attachment/file placement validation targets, and model behavior that affects admin forms. Use when adding or changing model validations, virtual attributes, attachment validations, or console-administered model fields.

Creates and edits custom Tiptap block-editor nodes in Folio: the node model (Folio::Tiptap::Node subclass with tiptap_node structure), the view component for rendering, tiptap_config (icons, groups, paste), and i18n. Use when adding a new Tiptap node, editing node structure or rendering, wiring node groups/icons, or when the user mentions `rails g folio:tiptap:node`.

File editing hygiene for Folio and host apps: trailing whitespace removal, single trailing newline (POSIX EOF), no BOM, consistent line endings, and Ruby argument wrapping, and programmatic file writes. Apply whenever editing or generating any file — code, config, markdown, YAML, or templates.

Migrates Trailblazer Cells (Cell::ViewModel) to ViewComponent in Folio: path and API mapping, cell( → render, model/options → initialize, engine CHANGELOG. Use when replacing `*Cell` with `*Component` or updating `cell(` call sites. Pair with the folio-view-component skill for generators, BEM, Stimulus, and tests.

Review repository code changes in the current local branch or an explicit diff. Use for prompts like "review", "review this branch", "code review", "pre-PR review", "review current branch", and "review my changes".

Add or update icons in the Folio engine or a Folio host app icon set: export from Figma, place SVG in the icon source directory, normalize fills/strokes to currentColor, run bin/icons, restart Rails so sprite and YAML metadata load.

Sass/SCSS styling conventions for Folio components: BEM nesting with &, colocated component stylesheets, scoping rules, and avoiding cross-component styling. Use when writing or editing .sass/.scss files, styling ViewComponents, or when the user asks about CSS/Sass conventions in Folio.

Converts legacy front-end scripts (jQuery, global document listeners, IIFEs) to Stimulus controllers plus vanilla DOM/fetch, aligned with Folio ViewComponent patterns. Use when migrating jQuery handlers, `$(document).on`, CoffeeScript-era bundles, or ad-hoc `window.*` APIs to Stimulus; when the user asks to remove jQuery from a feature; or when adding behavior to Folio components.