nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.4

data/lib/nitro_kit/installation.rb

@@ -23,10 +23,18 @@ module NitroKit
       Each skill resolves the installed gem with `bundle show nitro_kit` and reads
       its version-matched documentation.
 
+      In a greenfield application, run `bin/rails generate phlex:install` and use
+      Phlex for the application layout, route views, and reusable UI. In an
+      established application, preserve its existing view architecture and
+      introduce Phlex and Nitro Kit only at the requested boundary unless an
+      application-wide migration is explicitly authorized.
+
       Do not use Nitro Kit 1.x APIs, `nk_*` helpers, copied Nitro components, or
-      application-owned `controllers/nk`. Compose the installed Phlex Kit and keep
-      routes, records, authorization, queries, DOM IDs, and server responses in the
-      application.
+      application-owned `controllers/nk`. Include `NitroKit` once in the base Phlex
+      component and prefer capitalized Kit methods such as `Button(...)` and
+      `Card(...)`; use `.new` only when another API requires a component object.
+      Keep routes, records, authorization, queries, DOM IDs, and server responses
+      in the application.
 
       During migration, replace an existing form control only when Nitro Kit 2 has
       a genuine semantic and behavioral equivalent. Otherwise preserve the control
@@ -152,12 +160,17 @@ module NitroKit
       end
 
       def stimulus_loader_check
-        path = application_root.join("app/javascript/controllers/index.js")
-        ready = path.exist? && path.read.include?("eagerLoadControllersFrom")
+        javascript = application_root.glob("app/javascript/**/*.{js,ts}").select(&:file?).map(&:read)
+        loader = if javascript.any? { _1.include?("eagerLoadControllersFrom") }
+          "eager controller loading"
+        elsif javascript.any? { _1.match?(/\bapplication\.register\s*\(/) }
+          "explicit controller registration"
+        end
+
         Check.new(
-          status: ready ? :pass : :warn,
+          status: loader ? :pass : :warn,
           label: "Stimulus loader",
-          detail: ready ? "eager controller loading is configured" : "verify the application's controller registration"
+          detail: loader ? "#{loader} is configured" : "verify the application's controller registration"
         )
       end
 

data/lib/nitro_kit/migration_inventory.rb

@@ -1,4 +1,5 @@
 require "pathname"
+require "prism"
 require "ripper"
 
 module NitroKit
@@ -53,6 +54,187 @@ module NitroKit
       "@floating-ui/utils" => "remove the 1.x Floating UI pin or package after copied controllers are removed",
       "@github/combobox-nav" => "remove the 1.x combobox package; Nitro Kit 2 owns combobox behavior"
     }.freeze
+    BUTTON_TREATMENT_DEFINITION = /@utility\s+btn\b|\.btn(?:\s|[,{.:])/.freeze
+    BUTTON_CLASS = /(?<![a-z0-9_-])btn(?:-[a-z0-9_-]+)?(?![a-z0-9_-])/i.freeze
+    ERB_TAG_PATTERN = /<%(?!%|#)(==|[-=])?(.*?)(?:-)?%>/m
+    TABLE_COMPOUND_KEYWORDS = {
+      caption: %i[html aria data desperately_need_a_class],
+      thead: %i[html aria data desperately_need_a_class],
+      tbody: %i[html aria data desperately_need_a_class],
+      tr: %i[html aria data desperately_need_a_class],
+      th: %i[align scope sort href sort_data html aria data desperately_need_a_class],
+      td: %i[align html aria data desperately_need_a_class]
+    }.freeze
+
+    class ContractVisitor < Prism::Visitor
+      private
+        def positional_arguments(node)
+          Array(node.arguments&.arguments).reject { _1.is_a?(Prism::KeywordHashNode) }
+        end
+
+        def keyword_names(node)
+          Array(node.arguments&.arguments).grep(Prism::KeywordHashNode).flat_map(&:elements).filter_map do |element|
+            element.key.unescaped.to_sym if element.is_a?(Prism::AssocNode) && element.key.is_a?(Prism::SymbolNode)
+          end
+        end
+
+        def dynamic_arguments?(node)
+          Array(node.arguments&.arguments).any? do |argument|
+            argument.is_a?(Prism::SplatNode) || argument.is_a?(Prism::BlockArgumentNode) ||
+              (argument.is_a?(Prism::KeywordHashNode) && argument.elements.any? { _1.is_a?(Prism::AssocSplatNode) })
+          end
+        end
+
+        def table_keyword_issues(node)
+          allowed = TABLE_COMPOUND_KEYWORDS[node.name]
+          return [] unless allowed
+
+          (keyword_names(node) - allowed).map do |keyword|
+            guidance = if keyword == :class
+              "Table##{node.name} does not accept class: directly; move it to desperately_need_a_class:"
+            elsif keyword == :style
+              "Table##{node.name} does not allow style overrides; preserve this as application-owned HTML"
+            else
+              "Table##{node.name} does not accept #{keyword}: directly; move it to html: { #{keyword}: ... }"
+            end
+            RuntimeContractVisitor::Issue.new(line: node.location.start_line, guidance:)
+          end
+        end
+
+        def receiver_named?(receiver, name)
+          receiver.is_a?(Prism::LocalVariableReadNode) && receiver.name == name ||
+            receiver.is_a?(Prism::CallNode) && receiver.receiver.nil? && receiver.name == name && receiver.arguments.nil?
+        end
+    end
+
+    class RuntimeContractVisitor < ContractVisitor
+      Issue = Data.define(:line, :guidance)
+
+      attr_reader :issues
+
+      def initialize
+        @issues = []
+      end
+
+      def visit_call_node(node)
+        inspect_button(node)
+        inspect_table(node)
+        inspect_table_local(node)
+        inspect_icon_triggers(node)
+        super
+      end
+
+      private
+        def inspect_button(node)
+          return unless node.name == :new && node.receiver&.respond_to?(:full_name)
+          return unless node.receiver.full_name == "NitroKit::Button"
+          return unless keyword_names(node).intersect?(%i[icon icon_end])
+          return if positional_arguments(node).any? { !_1.is_a?(Prism::NilNode) }
+          return if node.block || dynamic_arguments?(node)
+          return if keyword_names(node).intersect?(%i[label aria])
+
+          issues << Issue.new(
+            line: node.location.start_line,
+            guidance: "icon-only NitroKit::Button requires label:, aria: { label: ... }, or aria: { labelledby: ... }"
+          )
+        end
+
+        def inspect_table(node)
+          constructor = positional_arguments(node).first
+          return unless node.name == :render && table_constructor?(constructor)
+
+          receiver_name = required_block_parameter_name(node)
+          return unless receiver_name
+          return if receiver_name == :table
+
+          visitor = TableCompoundVisitor.new(receiver_name)
+          visitor.visit(node.block.body) if node.block.body
+          issues.concat(visitor.issues)
+        end
+
+        def inspect_table_local(node)
+          return unless receiver_named?(node.receiver, :table)
+
+          issues.concat(table_keyword_issues(node))
+        end
+
+        def inspect_icon_triggers(node)
+          constructor = positional_arguments(node).first
+          return unless node.name == :render && node.block && constructor.is_a?(Prism::CallNode)
+          return unless constructor.name == :new && constructor.receiver&.respond_to?(:full_name)
+
+          component = constructor.receiver.full_name.delete_prefix("NitroKit::")
+          return unless %w[Dropdown Sheet].include?(component)
+
+          receiver_name = required_block_parameter_name(node)
+          return unless receiver_name
+
+          visitor = IconTriggerVisitor.new(receiver_name, component)
+          visitor.visit(node.block.body) if node.block.body
+          issues.concat(visitor.issues)
+        end
+
+        def required_block_parameter_name(node)
+          return unless node.block.is_a?(Prism::BlockNode)
+
+          parameter = node.block.parameters&.parameters&.requireds&.first
+          parameter.name if parameter.is_a?(Prism::RequiredParameterNode)
+        end
+
+        def table_constructor?(node)
+          node.is_a?(Prism::CallNode) && node.name == :new &&
+            node.receiver&.respond_to?(:full_name) && node.receiver.full_name == "NitroKit::Table"
+        end
+    end
+
+    class IconTriggerVisitor < ContractVisitor
+      attr_reader :issues
+
+      def initialize(receiver_name, component)
+        @receiver_name = receiver_name
+        @component = component
+        @issues = []
+      end
+
+      def visit_call_node(node)
+        if unnamed_icon_trigger?(node)
+          issues << RuntimeContractVisitor::Issue.new(
+            line: node.location.start_line,
+            guidance: "icon-only #{@component}#trigger requires label:, aria: { label: ... }, or aria: { labelledby: ... }"
+          )
+        end
+        super
+      end
+
+      private
+        def unnamed_icon_trigger?(node)
+          return false unless node.name == :trigger
+          return false unless node.receiver.is_a?(Prism::LocalVariableReadNode) && node.receiver.name == @receiver_name
+          return false unless keyword_names(node).intersect?(%i[icon icon_end])
+          return false if positional_arguments(node).any? { !_1.is_a?(Prism::NilNode) }
+          return false if node.block || dynamic_arguments?(node)
+          return false if keyword_names(node).intersect?(%i[label aria])
+
+          true
+        end
+    end
+
+    class TableCompoundVisitor < ContractVisitor
+      attr_reader :issues
+
+      def initialize(receiver_name)
+        @receiver_name = receiver_name
+        @issues = []
+      end
+
+      def visit_call_node(node)
+        if receiver_named?(node.receiver, @receiver_name)
+          issues.concat(table_keyword_issues(node))
+        end
+        super
+      end
+    end
+    private_constant :ContractVisitor, :RuntimeContractVisitor, :IconTriggerVisitor, :TableCompoundVisitor
 
     attr_reader :application_root
 
@@ -66,6 +248,8 @@ module NitroKit
         "Copied or shadow components" => copied_components,
         "Custom or legacy controllers" => controllers,
         "Vendored dependencies" => vendored_dependencies,
+        "Application-owned button treatments" => application_button_treatments,
+        "2.0 runtime contract errors" => runtime_contract_errors,
         "Known replacements" => replacement_summary,
         "Unresolved or application-owned items" => disposition_summary
       }
@@ -129,19 +313,98 @@ module NitroKit
             VENDORED_MODULES.each do |name, guidance|
               findings << Finding.new(status: :unresolved, path: location(path, line_number), guidance:) if line.include?(name)
             end
-            if line.match?(/\btailwind_merge\b/)
-              findings << Finding.new(
-                status: :unresolved,
-                path: location(path, line_number),
-                guidance: "remove tailwind_merge; Nitro Kit 2 ships static CSS and does not use it"
-              )
-            end
           end
         end
 
         findings.uniq { [ _1.path, _1.guidance ] }
       end
 
+      def application_button_treatments
+        return [] unless application_stylesheets.any? { _1.read.match?(BUTTON_TREATMENT_DEFINITION) }
+
+        source_files.filter_map do |path|
+          lines = path.each_line.with_index(1).filter_map do |line, line_number|
+            next if line.lstrip.start_with?("#", "<%#")
+
+            line_number if line.match?(BUTTON_CLASS)
+          end
+          next if lines.empty?
+
+          Finding.new(
+            status: :application_owned,
+            path: "#{relative(path)}:#{lines.join(',')}",
+            guidance: "review the application-owned button treatment; migrate ordinary actions to NitroKit::Button and preserve specialized controls as semantic application HTML"
+          )
+        end
+      end
+
+      def runtime_contract_errors
+        source_files.flat_map do |path|
+          source = runtime_ruby_source(path)
+          next [] unless source
+
+          result = Prism.parse(source)
+          issues = if result.success?
+            runtime_contract_issues(result.value)
+          elsif path.extname == ".erb"
+            erb_runtime_contract_issues(path.read)
+          else
+            []
+          end
+          issues.map do |issue|
+            Finding.new(
+              status: :unresolved,
+              path: location(path, issue.line),
+              guidance: issue.guidance
+            )
+          end
+        end
+      end
+
+      def runtime_contract_issues(node, line_offset: 0)
+        visitor = RuntimeContractVisitor.new
+        visitor.visit(node)
+        visitor.issues.map { _1.with(line: _1.line + line_offset) }
+      end
+
+      def erb_runtime_contract_issues(source)
+        source.to_enum(:scan, ERB_TAG_PATTERN).flat_map do
+          match = Regexp.last_match
+          fragment = match[2].sub(/\bdo(?:\s*\|[^|]*\|)?\s*\z/, "")
+          result = Prism.parse(fragment)
+          next [] unless result.success?
+
+          line_offset = source[0...match.begin(2)].count("\n")
+          runtime_contract_issues(result.value, line_offset:)
+        end
+      end
+
+      def runtime_ruby_source(path)
+        case path.extname
+        when ".rb" then path.read
+        when ".erb" then erb_ruby_source(path.read)
+        end
+      end
+
+      def erb_ruby_source(source)
+        ruby = source.gsub(/[^\n]/, " ")
+        source.to_enum(:scan, ERB_TAG_PATTERN).each do
+          match = Regexp.last_match
+          next if match[1]&.include?("=") && !standalone_erb_tag?(source, match)
+
+          ruby[match.begin(2)...match.end(2)] = match[2]
+        end
+        ruby
+      end
+
+      def standalone_erb_tag?(source, match)
+        line_break = source.rindex("\n", match.begin(0) - 1)
+        line_start = line_break ? line_break + 1 : 0
+        line_end = source.index("\n", match.end(0)) || source.length
+
+        source[line_start...match.begin(0)].strip.empty? && source[match.end(0)...line_end].strip.empty?
+      end
+
       def replacement_summary
         unresolved_findings.group_by(&:guidance).map do |guidance, findings|
           Finding.new(
@@ -173,7 +436,7 @@ module NitroKit
       end
 
       def all_findings
-        @all_findings ||= (legacy_helpers + copied_components + controllers + vendored_dependencies)
+        @all_findings ||= (legacy_helpers + copied_components + controllers + vendored_dependencies + application_button_treatments + runtime_contract_errors)
           .uniq { [ _1.status, _1.path, _1.guidance ] }
       end
 
@@ -181,6 +444,10 @@ module NitroKit
         application_root.glob("app/**/*.{rb,erb,haml,slim}").select(&:file?)
       end
 
+      def application_stylesheets
+        application_root.glob("app/**/*.{css,scss,sass}").select(&:file?)
+      end
+
       def dependency_files
         files = %w[Gemfile config/importmap.rb package.json].filter_map do |name|
           path = application_root.join(name)

data/lib/nitro_kit/upgrade_smoke_test.rb

@@ -171,34 +171,32 @@ module NitroKit
 
         private
           def install_routes!
-            collisions = %w[GET PATCH].select { |method| route_matches?(method) }
+            collisions = %w[GET PATCH].select { |method| exact_route_matches?(method) }
             if collisions.any?
               raise "Nitro Kit upgrade smoke route #{PATH} collides with host #{collisions.join("/")} routing"
             end
 
-            Rails.application.routes.append(&ROUTE_BLOCK)
+            Rails.application.routes.prepend(&ROUTE_BLOCK)
             Rails.application.reload_routes!
           end
 
           def uninstall_routes!
-            append_blocks.delete(ROUTE_BLOCK)
+            prepend_blocks.delete(ROUTE_BLOCK)
             Rails.application.reload_routes!
           end
 
-          def route_matches?(method)
-            request = ActionDispatch::Request.new(
-              Rack::MockRequest.env_for(PATH, method:)
-            )
-            Rails.application.routes.router.recognize(request) { return true }
-            false
+          def exact_route_matches?(method)
+            Rails.application.routes.routes.any? do |route|
+              route.verb.to_s.match?(method) && route.path.spec.to_s.split("(", 2).first == PATH
+            end
           end
 
           def route_block_installed?
-            append_blocks.include?(ROUTE_BLOCK)
+            prepend_blocks.include?(ROUTE_BLOCK)
           end
 
-          def append_blocks
-            Rails.application.routes.instance_variable_get(:@append)
+          def prepend_blocks
+            Rails.application.routes.instance_variable_get(:@prepend)
           end
 
           def ensure_test_environment!

data/lib/nitro_kit/version.rb

@@ -1,3 +1,3 @@
 module NitroKit
-  VERSION = "2.0.0.alpha.2"
+  VERSION = "2.0.0.alpha.4"
 end

data/lib/rails/commands/nitro_kit/nitro_kit_command.rb

@@ -1,14 +1,21 @@
+require "json"
 require "rails/command"
 
 module Rails
   module Command
     class NitroKitCommand < Base
       desc "doctor", "Verify the Nitro Kit 2 application and agent integration"
+      option :format, type: :string, default: "text", enum: %w[text json],
+        desc: "Output human-readable text or structured JSON"
       def doctor
         checks = installation.checks
-        checks.each do |check|
-          color = { pass: :green, warn: :yellow, fail: :red }.fetch(check.status)
-          say_status(check.status.to_s.upcase, "#{check.label}: #{check.detail}", color)
+        if options[:format] == "json"
+          say JSON.pretty_generate(checks.map { { status: _1.status, label: _1.label, detail: _1.detail } })
+        else
+          checks.each do |check|
+            color = { pass: :green, warn: :yellow, fail: :red }.fetch(check.status)
+            say_status(check.status.to_s.upcase, "#{check.label}: #{check.detail}", color)
+          end
         end
 
         exit 1 if checks.any? { _1.status == :fail }

data/plugins/nitro-kit/skills/nitro-kit-hotwire/SKILL.md

@@ -22,6 +22,8 @@ Make the server response and stable DOM boundary the interaction API. Add Stimul
    - application-wide confirmation and settings forms:
      `application_foundation.md`
 6. Inspect the installed Nitro component contract used by the recipe. Never assume a recipe from another version still matches.
+7. Read `NITRO_KIT_ROOT/docs/browser_support.md` for the canonical
+   full/reduced/unavailable no-JavaScript classification.
 
 Do not proceed with a remembered Nitro Kit 1.x API. Do not copy or recreate
 the installed gem's `nk--*` controllers under `app/javascript/controllers/nk`.
@@ -41,6 +43,8 @@ Keep frames around complete resource or collection regions, not individual butto
 - Redirect successful non-GET form submissions with `303 See Other`.
 - Render invalid HTML and Turbo submissions with `422 Unprocessable Entity` and the same invalid model instance.
 - Preserve an HTML response branch as the progressive fallback.
+- Do not describe that HTML branch as a JavaScript-free interaction when its
+  control still depends on Turbo or a closed overlay.
 - Let GET query parameters be the source of truth for filtering, sorting, and pagination.
 - Use native Nitro Dialog behavior for reviewed destructive actions. Use `data: { turbo_confirm: ... }` for compact confirmations that do not need a dialog.
 - Render flash through `NitroKit::Toast::FlashMessages`; the application owns setting the flash.

data/plugins/nitro-kit/skills/nitro-kit-rails/SKILL.md

@@ -21,12 +21,21 @@ established application outside the requested scope.
 7. For authentication, teams, application navigation, or settings, read
    `NITRO_KIT_ROOT/docs/patterns/application_foundation.md` completely.
 8. Read the matching Hotwire recipe before implementing an interaction.
+9. Read `NITRO_KIT_ROOT/docs/browser_support.md` before claiming an
+   interaction works without JavaScript.
 
 Never use a Nitro Kit 1.x helper, copied component, controller, or Tailwind
 contract as a substitute for the installed API.
 
 ## Follow the application grammar
 
+- In a greenfield application, run `bin/rails generate phlex:install` and use
+  Phlex for the application layout, route-level views, and reusable UI. Render
+  `Views::*` objects from controllers instead of creating ERB wrappers around
+  Phlex. In an established application, preserve its view architecture and
+  introduce Phlex only at the requested boundary unless an application-wide
+  migration is explicitly authorized. Judge this from existing view code, not
+  the Rails version or apparent age.
 - Scope tenant data through `Current.team` or `Current.account`; record
   `Current.user` as the actor.
 - Put domain behavior on the model before introducing another abstraction.
@@ -42,10 +51,13 @@ contract as a substitute for the installed API.
   Nitro Kit 1.x source as the fallback.
 - Redirect successful mutations with `303`; render invalid models with `422`.
 - Render HTML on the server and add Hotwire progressively.
+- Set the document language on the root `html` element.
 - Test with Minitest and fixtures, including tenancy and unhappy paths.
 - In authenticated admin areas, default to a hybrid `AppShell` with the route's
   one `h1` and basic actions in its `Toolbar`. Keep one page gutter and avoid
-  repeated headings or automatic Card wrappers.
+  repeated headings or automatic Card wrappers. At narrow widths, let trailing
+  actions stack below a Back affordance and title instead of clipping the title
+  or hiding persistent actions.
 - In a new team-aware application, create the first user's `Team` and owner
   `Membership` together. Put roles on memberships and scope product records
   through `Current.team`.

data/plugins/nitro-kit/skills/nitro-kit-ui/SKILL.md

@@ -14,31 +14,45 @@ Use the documentation shipped with the application's installed gem as the source
 3. Run `bundle show nitro_kit` and treat its output as `NITRO_KIT_ROOT`.
 4. Read `NITRO_KIT_ROOT/docs/agent_guide.md` completely.
 5. Read the relevant sections of `NITRO_KIT_ROOT/docs/component_contracts.md`. Read `customization.md` only for themes, tokens, or application composition.
-6. Inspect the installed component source when constructor or compound-slot details remain unclear. Never guess a component API from memory.
+6. For any interactive component or no-JavaScript claim, read the canonical
+   classifications in `NITRO_KIT_ROOT/docs/browser_support.md`.
+7. Inspect the installed component source when constructor or compound-slot details remain unclear. Never guess a component API from memory.
 
 For a Nitro Kit 1.x migration, read
 `NITRO_KIT_ROOT/docs/migration_1_to_2.md` before editing. Inventory product
-flows and behavior first. If the Nitro Kit MCP catalog is available, search it
-by workflow rather than old component name, then select high-level
-compositions before replacing atoms.
+flows, behavior, application-owned button classes and Rails button helpers,
+joined controls, and the existing semantic color, focus, radius, density, and
+typography tokens first. Capture representative wide and narrow screenshots.
+If the Nitro Kit MCP catalog is available, search it by workflow rather than
+old component name, then select high-level compositions before replacing
+atoms.
 
 If the gem is not installed, say that the skill requires Nitro Kit and follow the application's requested installation scope. Do not substitute APIs from an older Nitro Kit release.
 
 ## Build the interface
 
-1. Reuse the highest-level Nitro block that matches the page region, then compose components inside it.
-2. Include `NitroKit` once in the application's base Phlex component and use capitalized Kit methods such as `Button(...)` and `Card(...)`. Use `.new` only when another API needs a component object. Keep product-specific components under the application's namespace, commonly `UI::*`.
-3. Use `NitroKit::FormBuilder` explicitly with Rails `form_with` for model-backed forms.
-4. Keep routes, authorization, records, query policy, DOM IDs, Turbo boundaries, and response semantics in the application.
-5. Use documented `--nk-*` properties for theming and Nitro layout primitives for layout.
-6. Verify closed options and required compound declarations before rendering.
-7. For authenticated CRUD, prefer a hybrid `AppShell` with a `Toolbar` that
+1. In a greenfield application, run `bin/rails generate phlex:install` and use
+   Phlex for the application layout, route-level `Views::*`, and reusable UI.
+   Do not add ERB wrappers whose only purpose is to render Phlex. In an
+   established application with meaningful view conventions, preserve them
+   and introduce Phlex and Nitro Kit only at the requested boundary unless an
+   application-wide migration is explicitly authorized. Determine this from
+   the existing view architecture, not the Rails version or apparent age.
+2. Reuse the highest-level Nitro block that matches the page region, then compose components inside it.
+3. Include `NitroKit` once in the application's base Phlex component and use capitalized Kit methods such as `Button(...)` and `Card(...)`. Use `.new` only when another API needs a component object. Keep product-specific components under the application's namespace, commonly `UI::*`.
+4. Use `NitroKit::FormBuilder` explicitly with Rails `form_with` for model-backed forms.
+5. Keep routes, authorization, records, query policy, DOM IDs, Turbo boundaries, and response semantics in the application.
+6. Translate the application's semantic theme into documented `--nk-*` properties instead of choosing similar raw palette values. Use `--nk-button-radius` when Button shape intentionally differs from inputs and surfaces.
+7. Verify closed options and required compound declarations before rendering.
+8. For authenticated CRUD, prefer a hybrid `AppShell` with a `Toolbar` that
    owns the route's single `h1` and basic actions. The shell main region owns
    one content gutter. Do not repeat that heading in `PageHeader`, or wrap each
-   table, form, and detail region in another Card.
-8. For team administration and account settings, read
+   table, form, and detail region in another Card. At narrow widths, preserve
+   the full title and persistent actions by stacking the trailing actions below
+   the title rather than clipping either region.
+9. For team administration and account settings, read
    `docs/patterns/application_foundation.md`. Put Settings after an
-   `AppNavigation` spacer and use `SettingsLayout` with plain `FormSection`
+   `AppNavigation` spacer and use `SettingsLayout` with plain `SettingsSection`
    regions instead of a stack of Cards.
 
 ## Preserve the boundary
@@ -53,10 +67,13 @@ If the gem is not installed, say that the skill requires Nitro Kit and follow th
 - Never downgrade a specialized control to a generic Nitro control for visual
   consistency, and never retain copied Nitro Kit 1.x source as the fallback.
 - Do not introduce `nk_*` helpers, a general ERB bridge, or generated variant helpers.
-- Do not pass `class:` or `style:`. Prefer component options, composition, or theme tokens. Use `desperately_need_a_class:` only for a genuine external integration boundary.
+- Pass native attributes through each component method's documented `html:`, `aria:`, or `data:` boundary; for example, use `table.tr(html: { id: dom_id(record) })`, not `table.tr(id: ...)`. Do not pass `class:` or `style:`. Prefer component options, composition, wrappers, or theme tokens. Use `desperately_need_a_class:` only for a named external integration boundary that requires a class hook; it accepts Rails-style strings, symbols, nested arrays, and conditional hashes without manual joining.
+- Give every icon-only Button, Dropdown trigger, and Sheet trigger an explicit `label:` or ARIA label. For custom `form.field` blocks, render an explicit field label instead of relying on an unused implicit model translation.
 - Do not add application-specific behavior to Nitro-owned Stimulus controllers.
 - Do not recreate a Nitro component with raw HTML unless the installed catalog cannot express the semantics.
 
 ## Verify
 
 Run the smallest relevant application tests. For component rendering, assert semantic elements and owned `data-nk` or slot attributes rather than private implementation helpers. Exercise invalid and empty states when the UI accepts user input or collections.
+
+For a migration, Doctor is an inventory, not visual proof. Run representative form and component rendering with `ActiveModel::Translation.raise_on_missing_translations` enabled when the application uses strict i18n. Compare the same representative flows in a browser at wide and narrow widths, exercise keyboard focus, and inspect computed styles for missing application classes, stacked Button content, broken compound corners, double focus rings, clipping, and theme drift. Re-audit rendered native buttons, Rails button helpers, and application-owned button classes before declaring the conversion complete. Search the whole application for `desperately_need_a_class:` and review every result, aiming for zero. Move layout and visual treatment to application-owned wrappers, remove generic class forwarding, accept incidental Nitro defaults, and keep unmatched product UI application-owned; retain only documented external-integration hooks.