Human guide

Reading a component page

Every component has one page, reached from the sidebar. It opens with the component's purpose, then works through examples: the plain cases first, then variants, sizes, states, long content, disabled and error cases, and narrow widths.

• Preview shows the rendered example in an isolated canvas.
• Responsive shows the same example at fixed device widths, so you can see how it reflows without resizing your window.
• Code shows the Ruby that rendered the preview. It is extracted from the executable source, not retyped, so it is always copyable and always current.
• The appearance picker in the sidebar switches light, dark, and system. Every example is expected to hold up in all three.

Below the examples each page repeats three reference sections: the component's contract, the application patterns it belongs to, and the system rules. They are there so a coding agent can fetch a single page and compose correctly. People can read them as the precise version of the prose on nitrokit.dev.

What the compositions are

The Compositions section of the sidebar is not a showcase. Each entry is an executable composition test: a realistic screen — sign in, billing, a settings page, a whole application shell — assembled only from Nitro components and run by the test suite.

Most compositions have several states listed in their URL, such as empty, loading, error, dense, and mobile. They exist to prove the components survive real pressure together, and they double as the most honest example of how much application code a screen actually takes.

Theming basics

Nitro Kit owns component CSS and its default light and dark themes. Applications customize by overriding documented --nk-* custom properties: semantic colors, typography, spacing, radii, borders, focus geometry, shadows, motion, control heights, content widths, and shell chrome.

• Load nitro_kit first and your own stylesheet after it. Nitro's selectors sit inside :where() in named cascade layers, so an ordinary rule wins without !important.
• Override globally on :root, or scope a subtree by putting the variables on a wrapper element. Nitro descendants inherit them.
• Color tokens need three selectors: light, a prefers-color-scheme fallback for visitors without JavaScript, and explicit [data-theme="dark"].
• Variables beginning with --_nk- are private component mechanics. Never override them, and never edit the generated stylesheet.

The interactive theme Customizer — pick an accent, neutral, radius, density, font, and shell, then copy the CSS — lives on the documentation site at nitrokit.dev/customize.

Where to go next

• nitrokit.dev — installation, guides, and the component documentation written for people.
• nitrokit.dev/customize — the theme Customizer and its copyable exports.
• nitrokit.dev/pro — Nitro Kit Pro: the application blocks, flows, and templates catalog.
• The agent guide and /llms.txt — the same system, written for coding agents.