nitro_kit 2.0.0.alpha.3 → 2.0.0.alpha.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac13933782cc8434035e1b9e27f836b19dfe96a0f98124b91f2a4d62a4222d7e
-  data.tar.gz: 3ac6f8709fba0d6b5bffdac9eca6f21db615408303284afbc7ef7dbb7809d8d4
+  metadata.gz: 2f703b97ad2c84b8c66a306453dd1070554fe7c45f994a36672639af781856ed
+  data.tar.gz: 9343dd1db39ec96141f560eeebf0edd873d3b68960a36ffdc0abe413b0b66491
 SHA512:
-  metadata.gz: 3e7e6d588753fada85d9435dade70583da5322dab94a09a97c125f8847fcef74c99d8ed8654230d839babfb230cc589c73e8de8b60671665f90229a958b1705e
-  data.tar.gz: c13cc9b6315a6e5e17a34b1bcb9a7d1d8f624abbb3ffc53940a8c3f743c774efb6988dd8cddc36b45224afd44b41d0ccdbb57a0e5eacca07c4731b52cc21fa81
+  metadata.gz: 13e10affc36f849b140ee76f99fb6c7ce4403767d1b2da3a20decb2d15fbcc898bf725b637db7d1f2476c7fd12059e4ffb4449a137309253119de03eb18450a6
+  data.tar.gz: 4889ff8fdd803acfb652511c0938247a5edc0e1ead51687c5ed97966bf2493038def6d2d34b91a1b498310d78c62390ab29cee5fce3763393e9aa01f986263e0

data/CHANGELOG.md

@@ -2,6 +2,200 @@
 
 ## Unreleased
 
+## 2.0.0.alpha.5
+
+### Added
+
+- Add a copyable product bootstrap prompt that tells coding agents to install
+  Nitro Kit before planning an application and to discover optional product
+  patterns when catalog tools are available.
+
+### Changed
+
+- Teach the installed agent guidance and bundled Codex plugin to search an
+  available Nitro Kit catalog by product workflow without making catalog access
+  a requirement, and clarify that Nitro Kit Doctor checks integration health
+  rather than product completeness.
+
+## 2.0.0.alpha.4
+
+### Added
+
+- Add `label_visible: false` to `AppearancePicker`'s segmented presentation:
+  the legend hides visually while the fieldset keeps its accessible name,
+  and the segmented row now fills its container like every other control,
+  with the segments sharing the width equally.
+- Add collapsible `AppNavigation` sections: `section(label:, collapsible:
+true, expanded:)` renders native `details` and `summary` with an owned
+  chevron, so groups disclose without JavaScript and open state stays on
+  the native `open` attribute. Collapsible sections require a label.
+- Assert the stylesheet conventions as tests. Spacing steps, geometry
+  through tokens, the type and shadow scales, themeable opacity, guarded
+  motion and hover, the four z-index tiers, and the destructive spellings
+  are now nine architecture tests with no allowlist, so a new violation
+  fails instead of accumulating. The conventions themselves are documented
+  in the style guide: the spacing step set, the z-index tiers, the
+  color-mix percentage vocabulary, and the single deliberate easing curve.
+- Add `--nk-icon-size-{xs,sm,md,lg,xl}` and `--nk-avatar-size-{xs,sm,md,lg}`.
+  The Icon and Avatar ladders were literals repeated across five files;
+  AvatarStack duplicated the entire avatar ladder. Alert's status icon and
+  Accordion's chevron now resolve through the icon axis, so an application
+  retheming icon sizes moves every owned glyph with them.
+- Document the size vocabularies: one contract table of the six size ramps
+  and why each stops where it does, so a caller can predict which sizes a
+  component accepts without trying them.
+- Add `--nk-choice-size-{md,lg}` and derive every checkbox and radio
+  dimension from them: box, glyph proportions, description indent, and the
+  native input sizes. The two sizes are one rule apart, the large radio dot
+  finally scales with its control, and both indicators share one guarded
+  transition.
+- Add `--nk-control-padding-inline`. Buttons, inputs, selects, and textareas
+  share one inline padding instead of two nearby values.
+- Add the full color scales as public tokens: `--nk-{family}-{50..950}` for all
+  twenty-two families — the five neutrals slate, gray, zinc, neutral, and stone,
+  plus seventeen chromatic hues. Every semantic role and badge color samples
+  these scales, so swapping the neutral or the accent means re-pointing roles at
+  another family rather than inventing values. Scale values are Nitro's own
+  harmonized ramps: smooth lightness, chroma, and hue curves fitted through the
+  familiar palette, bounded to an imperceptible perceptual distance per value.
+  The customization guide documents every step and ships neutral-swap and
+  accent recipes.
+- Add `--nk-white` and `--nk-black`. The surface, foreground, and overlay
+  roles that used raw white and black resolve through them, so warm-paper and
+  true-black themes are two overrides.
+- Add the public tint palette: `--nk-palette-*` roles for all twenty-two
+  badge colors — the five semantic families and the seventeen decorative hues —
+  so `Badge`'s colors are themeable like every other part of the system. Each
+  resolves to a scale step: the 400 tint with a 700-800 foreground in light and
+  the 200 foreground in dark. Semantic families default to the same steps as
+  their hue families, so an `info` badge renders exactly like a `blue` badge
+  and a `warning` alert is amber in both appearances, until a theme separates
+  them.
+- Add the title scale: `--nk-title-{page,section,surface,compact}-{size,weight}`.
+  Every owned title and legend resolves through one of four roles instead of
+  fifteen components choosing among six sizes and two weights. Fieldset
+  legends join the other surface titles at bold, and Alert titles match
+  Toast titles, which the shared status palette already made visual twins.
+- Add `--nk-disabled-opacity` and `--nk-shadow-xs`, and resolve every
+  disabled control and Button's raised shadow through them. Disabled state
+  was four different opacities; Button drew its shadows by hand.
+
+### Breaking changes
+
+- Settle the destructive vocabulary on two deliberate spellings. Actions and
+  Alert say `destructive`: Button and Dropdown items keep their variant,
+  and Alert renames its `:error` variant to `:destructive`. Toast items
+  keep `:error`, the announcement spelling, and both resolve to the same
+  tint family in the shared palette. Badge and AppNavigation rename their
+  `danger` semantic color to `destructive`, and the tokens follow:
+  `--nk-color-danger*` becomes `--nk-color-destructive*` and
+  `--nk-palette-danger*` becomes `--nk-palette-destructive*`. Form and
+  field error semantics are unchanged.
+- Remove `Alert::VARIANT_PALETTE`. Alert variants resolve through the shared
+  semantic palette instead of mapping to hue families.
+- Remove `zinc` from `Badge`'s color vocabulary; use `neutral`, which renders
+  the same by default and follows an application's neutral theme. A gray badge
+  frozen to one gray family had no categorical job the semantic name does not
+  do better.
+- Change `Badge`'s default color from `:zinc` to `:neutral`. Both render the
+  same way; the semantic name is now the default because it follows an
+  application's theme.
+
+### Changed
+
+- Quiet the dark-mode borders one step, from `--nk-zinc-700` to
+  `--nk-zinc-800`, so dark surfaces read as soft fills instead of outlined
+  boxes.
+- Render every owned glyph through the Icon component. Accordion, Select,
+  Combobox, and AppNavigation drew their chevrons as hand-approximated SVG
+  paths; they now render the real Lucide `chevron-down` at the same sizes,
+  so one icon set covers the whole library and the glyphs ride the
+  `--nk-icon-size-*` axis.
+- Default Dropzone to the `minimal` presentation: the drop target is the
+  only visible affordance, and the native file input stays focusable,
+  named, and operable underneath — file selection and keyboard flows are
+  unchanged. `presentation: :input` still shows the native control beside
+  the drop target.
+- Align the default radius at `--nk-radius-lg` (8px): inputs, selects,
+  textareas, the rich text editor, navigation rows, pagination links,
+  dropzone, grouped choice frames, and the segmented appearance picker now
+  share Button's radius instead of sitting one step smaller. Nested pieces
+  are concentric — inner radius is the container's minus its padding — so
+  segmented options, dropdown items, combobox options, and command palette
+  destinations sit flush inside their containers. Buttons' smaller sizes
+  keep their own ramp; badges, tooltips, and chips keep their compact radii.
+- Lower the default control height from 40px to 36px:
+  `--nk-control-height-md` is now `2.25rem`, so medium buttons, inputs,
+  selects, menu rows, and the choice controls' hit areas tighten together.
+- Meet the 44px touch target on coarse pointers: Button extends an
+  invisible tap area to the large control step, so a touch just outside a
+  small or default button still lands on it while the rendered size stays
+  put, asserted by a touch-emulation hit test.
+- Derive the remaining owned geometry from the token system. Switch is now
+  four declared inputs — block heights ride the control ramp, the track is
+  the block plus the handle's travel — so density presets finally reach
+  switches, and Textarea's minimum height rides `--nk-space`. The
+  AppearancePicker control resolves through `--nk-choice-size-md` and the
+  Accordion trigger through `--nk-control-height-lg`, the values they
+  already rendered. Every dimension was verified pixel-identical.
+- Widen the Select chevron gutter from 36px to 40px. The gutter is now
+  derived — inline padding, icon, inline padding — so the chevron sits
+  symmetrically instead of at an arbitrary offset.
+- Tighten extra-small Badge inline padding from 5px to 4px, making the
+  badge padding ramp an even 4/6/8.
+- Size fixed overlays with `100%` instead of `100vw`. Dropdown menus, the
+  combobox listbox, the toast column, and the app shell drawer capped
+  themselves against `100vw`, which includes the scrollbar, so classic
+  scrollbars pushed them past the visible viewport. Percentages resolve
+  against the initial containing block, which excludes it. Tooltip keeps
+  `100vw` deliberately and documents why.
+- Finish the logical-property pass: the remaining physical `width`,
+  `height`, and `min-/max-` declarations now use their logical forms, so
+  every component behaves in vertical writing modes.
+- Dim Table's sort indicator through the color channel instead of a raw
+  `opacity`, and guard the remaining control transitions and the
+  DetailsTable hover for reduced motion and touch.
+- Dress the AvatarStack overflow chip as one of the heads: the same neutral
+  fill as the avatar fallbacks and the same hairline ring, instead of an
+  elevated fill with no ring.
+- Read data-entry controls at `--nk-text-base` below the md breakpoint and
+  `--nk-text-sm` from md up, so a focused control never zooms the viewport
+  on small screens; buttons read `--nk-text-sm` at every width. Select and
+  Textarea follow the same rule instead of inheriting the page font.
+- Even the control height ramp: `--nk-control-height-sm` is the 2rem small
+  Button already rendered, and Button consumes the token, so the theme
+  customizer's density exports reach small buttons instead of being
+  silently ignored.
+- Resolve `Badge`, `Alert`, and `Toast::Item` colors from public tokens through
+  one shared palette. Badge colors were previously hardcoded in private
+  `--_nk-*` variables, which are not a theme API, so badge color was the one
+  thing in the library an application could not rebrand.
+- Separate `Badge`'s two color axes. Semantic families follow the
+  `--nk-palette-{family}` tint roles and move with an application's brand;
+  decorative hues follow the `--nk-palette-{hue}` roles and stay the color they
+  name. `red` and `danger` previously resolved to identical CSS and are now
+  independently themeable.
+
+- Soften the toast shadow from the dialog tier to the floating-element tier,
+  matching dropdowns and comboboxes. It carried the strongest shadow in the
+  system on a card-radius surface, fitting no rung of the elevation ladder.
+
+### Fixed
+
+- Stop Avatar rings from painting through overlapping stack siblings. The
+  ring pseudo-element carries a z-index but the avatar root was not a
+  stacking context, so in an AvatarStack every ring floated above every
+  neighboring avatar's fill and the stack looked translucent. Avatars are
+  now isolated, so each one paints atomically and covers the ring beneath
+  it.
+- Render an `Alert` and a `Toast::Item` of the same variant identically. Both
+  declare the same variant vocabulary but resolved it from different sources, so
+  one "success" appeared as two different greens and rethemeing a semantic token
+  moved only the toast.
+- Raise the orange badge foreground so it clears WCAG AA against its own tint.
+  It rendered at 4.31:1 in light appearance. Every semantic family and hue is
+  now asserted at 4.5:1 or better in both appearances.
+
 ## 2.0.0.alpha.3
 
 ### Added

data/README.md

@@ -4,51 +4,62 @@
 
 # Nitro Kit
 
-**Rails front-end for the agent era.**
+**Audience:** Rails developers evaluating or installing Nitro Kit.
 
-Nitro Kit is a gem-owned, agent-native UI system for Ruby on Rails. The `2.0.0.alpha.3` prerelease is a ground-up rebuild under active testing and must not be treated as stable. New documentation and the Nitro Kit Pro alpha catalog are coming next.
+Nitro Kit is a gem-owned Phlex UI system for Rails. The `2.0.0.alpha.5` prerelease
+is under active testing and is not stable.
 
 [![RubyGems](https://img.shields.io/gem/v/nitro_kit.svg)](https://rubygems.org/gems/nitro_kit)
 
-## Installation
+## Install
 
-Install the prerelease explicitly and keep it pinned while evaluating it.
+Pin the prerelease:
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.3"
+gem "nitro_kit", "2.0.0.alpha.5"
 ```
 
-Use the released gem and commit `Gemfile` with `Gemfile.lock`. Before upgrading, review the changelog, run `bundle update nitro_kit`, rerun the installer, and test the application.
-
 ```sh
 bundle install
 bin/rails generate nitro_kit:install
 bin/rails nitro_kit:doctor
 ```
 
-Example migration prompt:
+Commit `Gemfile` and `Gemfile.lock`. Before upgrading, review the changelog,
+run `bundle update nitro_kit`, rerun the installer, and test the application.
+Production applications should use a released gem with a committed lockfile.
+
+Start with:
 
-> Upgrade this Rails app to Nitro Kit `2.0.0.alpha.3`. Run the installer, follow its diagnostics, preserve existing behavior and styling, and use Nitro Kit MCP patterns where helpful. Run tests and summarize changes or unresolved issues.
+- [Rails integration](docs/rails_integration.md)
+- [Component contracts](docs/component_contracts.md)
+- [Customization](docs/customization.md)
+- [Browser support](docs/browser_support.md)
+- [Nitro Kit 1.x migration](docs/migration_1_to_2.md)
+- [Coding-agent guide](docs/agent_guide.md)
 
-Example new application prompt:
+Nitro Kit targets maintained evergreen browsers from roughly the previous two
+years, with Mobile Safari as a first-class target. See the
+[browser support policy](docs/browser_support.md) for exact fallback behavior.
 
-> Build this Rails app with Nitro Kit `2.0.0.alpha.3`. Run the installer, follow the included agent guide, compose gem-owned components, and use Nitro Kit MCP patterns where helpful. Add tests and summarize the result.
+## Prompting a coding agent
 
-The [agent guide](docs/agent_guide.md), [Rails integration guide](docs/rails_integration.md), [component contracts](docs/component_contracts.md), and [browser support policy](docs/browser_support.md) are included with the gem.
+Add this to a product bootstrap prompt so the agent installs Nitro Kit, uses
+its guidance, and discovers optional product patterns when available:
 
-## Browser support
+```text
+Add Nitro Kit 2 to this Rails app and use it for the product's application UI.
 
-Nitro Kit uses modern web standards while keeping core content and actions
-usable for the overwhelming majority of people on maintained browsers. The
-practical target is current stable and popular evergreen releases from roughly
-the previous two years, with Mobile Safari as a first-class target. Small,
-feature-detected fallbacks preserve essential behavior without holding
-components to the oldest browser's feature set; visual polish may degrade. See
-the [browser support policy](docs/browser_support.md) for the dated browser
-matrix and canonical full/reduced/unavailable no-JavaScript classifications.
+Set up Nitro Kit before planning or implementing the product:
+- Add and pin the current Nitro Kit 2 prerelease in the Gemfile, run bundle install, run bin/rails generate nitro_kit:install, and run bin/rails nitro_kit:doctor.
+- Load the generated project-local Nitro Kit skills and installed, version-matched docs.
+- Check whether Nitro Kit catalog or MCP tools are available. If they are, inventory and search them by product workflow, retrieve relevant patterns, and state what you will use, adapt, or defer.
+- If no catalog is available, continue with the bundled docs and component contracts; catalog access is optional.
+```
 
-Maintaining Nitro Kit 1? Its frozen documentation remains at [v1.nitrokit.dev](https://v1.nitrokit.dev).
+Maintaining Nitro Kit 1? Its frozen documentation remains at
+[v1.nitrokit.dev](https://v1.nitrokit.dev).
 
 ## License
 
-Nitro Kit is distributed under the custom [NitroKit License](LICENSE).
+Nitro Kit uses the custom [NitroKit License](LICENSE).

data/STYLE_GUIDE.md

@@ -303,6 +303,16 @@ Variants assign private values and generic state consumes them:
 
 Never target an unqualified `[data-slot]`. Never use `transition: all`.
 
+Interaction treatments respond to capability: hover effects sit under `@media (hover: hover)`, and Button extends an invisible touch target to the large control step under `@media (pointer: coarse)`, so taps meet the 44px minimum while the rendered size stays put. Control text keys to the width axis: data-entry controls read `--nk-text-base` below the `md` breakpoint, where a focused control under 16px zooms the viewport, and `--nk-text-sm` from `md` up; buttons read `--nk-text-sm` at every width.
+
+Spacing multipliers on `--nk-space` come from the step set `0.5 1 1.5 2 2.5 3 4 5 6 7 8 10 12 16 24`. Panel and overlay maximums are viewport policy and stay literal rem values; everything a component owns rides a token or a step.
+
+`z-index` has four tiers and no other values: `1`–`3` layer parts inside one component, `10`–`30` layer application-shell chrome, `50` lifts the floating overlays that are not top-layer elements, and `100` is the system tier for the toast column and the skip link. Native dialogs and popovers rely on the top layer instead of a z-index. An element that carries a z-index inside a component must also make its component a stacking context (`isolation: isolate`), or the index leaks into sibling components.
+
+Translucency is mixed in `oklab`, never applied through `opacity`, so dimming cannot cascade into descendants; `opacity` is reserved for `--nk-disabled-opacity` and animating whole overlays. The mixing percentages are a fixed vocabulary: hairline rings and quiet borders mix `10%` of the foreground or black pole, hover washes mix `5%` in light and `15%` of white in dark, inset bevel highlights mix `15–20%` of white, status surfaces tint `12%` in light and `20%` in dark, status borders carry `45%` of their accent, and de-emphasized fills mix `40–65%` toward the surface. A new value in this list is a design decision, not a rounding choice.
+
+Motion uses the one easing curve `--nk-ease` in both directions, deliberately: enter and exit stay interruptible and reversible, and a dedicated accelerate/decelerate pair is a future decision to make once, globally, not per component. Durations come from the three `--nk-duration-*` steps, and every transition and animation stands down under `prefers-reduced-motion`.
+
 ## Tokens and themes
 
 Public `--nk-*` variables cover themeable decisions: semantic colors, paired foregrounds, typography, spacing, radii, control dimensions, shadows, borders, motion, and content widths.

data/app/assets/stylesheets/nitro_kit-tailwind-v4.css

@@ -19,9 +19,9 @@
     --color-ring: var(--nk-color-focus);
     --color-primary: var(--nk-color-primary);
     --color-primary-foreground: var(--nk-color-primary-foreground);
-    --color-destructive: var(--nk-color-danger);
-    --color-destructive-content: var(--nk-color-danger-content);
-    --color-destructive-foreground: var(--nk-color-danger-foreground);
+    --color-destructive: var(--nk-color-destructive);
+    --color-destructive-content: var(--nk-color-destructive-content);
+    --color-destructive-foreground: var(--nk-color-destructive-foreground);
 
     --radius-sm: var(--nk-radius-sm);
     --radius-md: var(--nk-radius-md);