Nitro Kit 2.0

Agent guide

Everything a coding agent needs to compose Nitro Kit correctly. The gallery enumerates and proves the system; nitrokit.dev teaches it to humans.
The same content is served as plain text at /llms.txt.

The composition model

A Nitro component is a Phlex class. You render it directly, and that is the entire public API. There is no helper layer, no template registry, and no generator that copies component source into an application.

Render a component with render NitroKit::Button.new("Save", variant: :primary). Arguments are the contract; a wrong keyword or an unknown enumerated value raises ArgumentError at render time.
Compound components yield themselves: render NitroKit::Card.new do |card| card.title("Plan"); card.body { ... } end. The compound methods are the component's published anatomy, and the blocks take ordinary Phlex content.
Rails forms use form_with(model: record, builder: NitroKit::FormBuilder). Rails keeps naming, ids, values, CSRF, multipart, and ActiveModel errors; Nitro renders the controls.
Layout is Flex(dir:, gap:, align:, justify:, wrap:) and Grid(cols:, gap:). Responsive properties take a required base value plus fixed sm md lg xl 2xl overrides.
Extend by wrapping Nitro components inside your own Phlex classes. Subclassing is allowed for a narrow fixed vocabulary, but private methods are not an API.
Theme with the documented --nk-* custom properties, globally or scoped to a subtree. Never edit the generated nitro_kit.css, and never depend on private --_nk-* variables.

Every component page is self-contained

Fetch one component page and you have enough to compose that component correctly. The reference sections below the examples are rendered from one source into every page, so nothing requires reading a second page.

[data-gallery-reference="contract"] carries that component's own options, slots, and closed vocabularies.
[data-gallery-reference="patterns"] inlines the application conventions that apply to the component, such as queryable collections on Table or destructive actions on Dialog.
[data-gallery-reference="system-rules"] repeats the rules at the end of this page, identically, on every component page.
Every example pairs a Preview tab, a Responsive tab, and a Code tab. The Code tab holds the executable Ruby that rendered the preview above it, extracted from the source, so it cannot drift.
Component pages live at /gallery/components/:slug. Compositions live at /gallery/compositions/:slug(/:state) and are executable whole-application tests: the same components under real states, including empty, loading, error, dense, and mobile.
Select on data-nk, component-qualified data-slot, data-variant, data-size, and data-state. Gallery chrome uses data-gallery. Nothing in the system uses classes.

Why the system refuses things

Nitro Kit says no to a few things an agent will otherwise try. The reasons are here so you stop fighting the API and reach for the supported path instead.

Why is there no class: prop?

Because it is a second styling API in disguise. The moment components accept arbitrary classes, every internal class name becomes something an application depends on, and every upgrade can quietly break its styling.

Components render classless, self-describing markup, and customization flows through the documented --nk-* custom properties. When an external script or widget genuinely needs a hook there is desperately_need_a_class:, which emits both the class and data-nk-escape="class" and is named that way so you think twice. class: and style: are rejected everywhere, including inside html:.

Why is every option an explicit keyword?

So a mistake tells you instead of rendering something slightly wrong. No component takes a catch-all **options, so a misspelled keyword raises ArgumentError rather than leaking into the HTML, and an unknown enumerated value raises with the accepted set in the message.

Do not route around this. If an option you want does not exist, compose the component inside your own Phlex class rather than trying to pass extra attributes through.

Why Phlex rather than templates?

Because components are Ruby, and Ruby is good at this. A Phlex component is a plain class with a constructor and a view_template, composed like any other object. There is no partial whose locals you have to guess at and no helper soup.

It also lets a component check its own inputs. The constructor is the contract, and the contract is enforced where the component is rendered.

Why not just write HTML?

You still get HTML, and it stays native: real buttons, real forms, real details/summary, native dialogs, and Popover menus. The question is only what you author against.

Raw HTML is a wide-open API: any attribute, any structure, any typo. A component kit needs a narrower contract so markup, accessibility, and styling can be promised to agree. Named slots and content blocks still accept ordinary Phlex content.

Why not Tailwind?

Nitro Kit ships static plain CSS. There is no Tailwind build requirement and no runtime dependency, so the components render the same in every application.

An application may still use Tailwind, and an optional Tailwind v4 adapter maps Nitro's tokens into Tailwind theme variables so utilities and components share values. Do not put utility classes inside the components; that is what the components are for.

What does Nitro Kit own, and what does the application own?

Nitro Kit owns the reusable parts: component markup, CSS, and a little behavior where the browser needs help. The application owns data, routes, authorization, business rules, and how the pieces compose into product.

The line matters in practice. AppShell gives you responsive chrome but you decide the navigation. Table renders sortable headers and aria-sort but you supply the URLs and the sort policy. Do not push product decisions into a component.

How much JavaScript is there?

As little as possible. Accordions are details/summary, dialogs use native commands, dropdowns use Popover, and tooltips use CSS hover and focus.

What remains is a handful of small Stimulus controllers for the gaps, such as menu keyboard navigation and Active Storage uploads. They are progressive, they clean up in disconnect, and they behave through Turbo Drive, Frames, Streams, and morphs. Do not add a controller to reimplement behavior a component already has.

Does it work with Rails forms and Turbo?

Yes, that is the home turf. Use form_with with NitroKit::FormBuilder and keep everything Rails gives you: naming, ids, model values, CSRF, multipart forms, and real ActiveModel errors wired to the controls.

Turbo Frames and Streams use the normal Rails helpers from Phlex. Active Storage direct uploads work through Dropzone, with plain form submission as the no-JavaScript fallback. Nitro Kit does not wrap Rails; it stays out of the way where Rails is already good.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.