# 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. Canonical HTML: https://gallery.nitrokit.dev/gallery/agent-guide ## 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 Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section. - 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. ## Foundations Public design tokens that ground every Nitro Kit component. - Colors: https://gallery.nitrokit.dev/gallery/foundations/colors - Typography: https://gallery.nitrokit.dev/gallery/foundations/typography - Spacing & sizing: https://gallery.nitrokit.dev/gallery/foundations/spacing-sizing - Effects: https://gallery.nitrokit.dev/gallery/foundations/effects ## Components Every gem-owned component, exhaustively permuted. - Button: https://gallery.nitrokit.dev/gallery/components/button - Button group: https://gallery.nitrokit.dev/gallery/components/button-group - Button to: https://gallery.nitrokit.dev/gallery/components/button-to - Appearance picker: https://gallery.nitrokit.dev/gallery/components/appearance-picker - Checkbox: https://gallery.nitrokit.dev/gallery/components/checkbox - Checkbox group: https://gallery.nitrokit.dev/gallery/components/checkbox-group - Combobox: https://gallery.nitrokit.dev/gallery/components/combobox - Control group: https://gallery.nitrokit.dev/gallery/components/control-group - Dropzone: https://gallery.nitrokit.dev/gallery/components/dropzone - Field: https://gallery.nitrokit.dev/gallery/components/field - Field group: https://gallery.nitrokit.dev/gallery/components/field-group - Fieldset: https://gallery.nitrokit.dev/gallery/components/fieldset - Input: https://gallery.nitrokit.dev/gallery/components/input - Label: https://gallery.nitrokit.dev/gallery/components/label - Radio button: https://gallery.nitrokit.dev/gallery/components/radio-button - Radio button group: https://gallery.nitrokit.dev/gallery/components/radio-button-group - Rich text area: https://gallery.nitrokit.dev/gallery/components/rich-text-area - Select: https://gallery.nitrokit.dev/gallery/components/select - Switch: https://gallery.nitrokit.dev/gallery/components/switch - Textarea: https://gallery.nitrokit.dev/gallery/components/textarea - Command palette: https://gallery.nitrokit.dev/gallery/components/command-palette - Dialog: https://gallery.nitrokit.dev/gallery/components/dialog - Dropdown: https://gallery.nitrokit.dev/gallery/components/dropdown - Sheet: https://gallery.nitrokit.dev/gallery/components/sheet - Tooltip: https://gallery.nitrokit.dev/gallery/components/tooltip - Alert: https://gallery.nitrokit.dev/gallery/components/alert - Empty state: https://gallery.nitrokit.dev/gallery/components/empty-state - Toast: https://gallery.nitrokit.dev/gallery/components/toast - Accordion: https://gallery.nitrokit.dev/gallery/components/accordion - Avatar: https://gallery.nitrokit.dev/gallery/components/avatar - Avatar stack: https://gallery.nitrokit.dev/gallery/components/avatar-stack - Badge: https://gallery.nitrokit.dev/gallery/components/badge - Details table: https://gallery.nitrokit.dev/gallery/components/details-table - Icon: https://gallery.nitrokit.dev/gallery/components/icon - Progressive image: https://gallery.nitrokit.dev/gallery/components/progressive-image - Stat grid: https://gallery.nitrokit.dev/gallery/components/stat-grid - Table: https://gallery.nitrokit.dev/gallery/components/table - Typeset: https://gallery.nitrokit.dev/gallery/components/typeset - Pagination: https://gallery.nitrokit.dev/gallery/components/pagination - Pagination bar: https://gallery.nitrokit.dev/gallery/components/pagination-bar - Tabs: https://gallery.nitrokit.dev/gallery/components/tabs - Toolbar: https://gallery.nitrokit.dev/gallery/components/toolbar - Card: https://gallery.nitrokit.dev/gallery/components/card - Container: https://gallery.nitrokit.dev/gallery/components/container - Flex: https://gallery.nitrokit.dev/gallery/components/flex - Grid: https://gallery.nitrokit.dev/gallery/components/grid - Application navigation: https://gallery.nitrokit.dev/gallery/components/app-navigation - Application shell: https://gallery.nitrokit.dev/gallery/components/app-shell - Authentication shell: https://gallery.nitrokit.dev/gallery/components/auth-shell - Danger zone: https://gallery.nitrokit.dev/gallery/components/danger-zone - Data section: https://gallery.nitrokit.dev/gallery/components/data-section - Form section: https://gallery.nitrokit.dev/gallery/components/settings-section - Page header: https://gallery.nitrokit.dev/gallery/components/page-header - Settings layout: https://gallery.nitrokit.dev/gallery/components/settings-layout ## Compositions Executable composition tests: the system exercised whole. - Sign in: https://gallery.nitrokit.dev/gallery/compositions/sign-in/default - Password reset: https://gallery.nitrokit.dev/gallery/compositions/password-reset/request - Email verification: https://gallery.nitrokit.dev/gallery/compositions/email-verification/pending - Invitation acceptance: https://gallery.nitrokit.dev/gallery/compositions/invitation-acceptance/valid - Account creation: https://gallery.nitrokit.dev/gallery/compositions/account-creation/default - Account security: https://gallery.nitrokit.dev/gallery/compositions/account-security/recovery-request - Workspace onboarding: https://gallery.nitrokit.dev/gallery/compositions/onboarding/workspace - Branched onboarding: https://gallery.nitrokit.dev/gallery/compositions/onboarding-branches/choose-path - Workspace dashboard: https://gallery.nitrokit.dev/gallery/compositions/dashboard/new - Workspace settings: https://gallery.nitrokit.dev/gallery/compositions/settings/profile - Workspace users: https://gallery.nitrokit.dev/gallery/compositions/users/index - Team management: https://gallery.nitrokit.dev/gallery/compositions/team-management/members - API credentials: https://gallery.nitrokit.dev/gallery/compositions/api-credentials/list - Organization overview: https://gallery.nitrokit.dev/gallery/compositions/organization-overview/active - Organization settings: https://gallery.nitrokit.dev/gallery/compositions/organization-settings/general - Team activity: https://gallery.nitrokit.dev/gallery/compositions/team-activity/recent - Team member: https://gallery.nitrokit.dev/gallery/compositions/team-member/active - Subscription billing: https://gallery.nitrokit.dev/gallery/compositions/billing/plans - Checkout and payment: https://gallery.nitrokit.dev/gallery/compositions/checkout/review - Checkout results: https://gallery.nitrokit.dev/gallery/compositions/checkout-result/invoice-issued - Data resource overview: https://gallery.nitrokit.dev/gallery/compositions/data-resource-overview/index - Data resource activity: https://gallery.nitrokit.dev/gallery/compositions/data-resource-activity/recent - Data resource settings: https://gallery.nitrokit.dev/gallery/compositions/data-resource-settings/general - Product resource lifecycle: https://gallery.nitrokit.dev/gallery/compositions/product-resource/index - API webhooks: https://gallery.nitrokit.dev/gallery/compositions/api-webhooks/list - Integration management: https://gallery.nitrokit.dev/gallery/compositions/integration-management/catalog - File uploads: https://gallery.nitrokit.dev/gallery/compositions/uploads/empty - Activity and audit log: https://gallery.nitrokit.dev/gallery/compositions/activity-audit/normal - Changelog: https://gallery.nitrokit.dev/gallery/compositions/changelog/latest - Help center: https://gallery.nitrokit.dev/gallery/compositions/help-center/faq - System status and errors: https://gallery.nitrokit.dev/gallery/compositions/system-status/403 - Product landing: https://gallery.nitrokit.dev/gallery/compositions/landing/default - Public pricing: https://gallery.nitrokit.dev/gallery/compositions/pricing/monthly - Product features: https://gallery.nitrokit.dev/gallery/compositions/features/overview - Public contact: https://gallery.nitrokit.dev/gallery/compositions/contact/form - Sidebar operations application: https://gallery.nitrokit.dev/gallery/compositions/application-sidebar - Topbar media application: https://gallery.nitrokit.dev/gallery/compositions/application-topbar - Hybrid account application: https://gallery.nitrokit.dev/gallery/compositions/application-hybrid