seams 0.1.0 → 0.2.0

data/lib/generators/seams/design/templates/app/views/ui/previews/_counter.html.erb.tt

@@ -0,0 +1,6 @@
+<%%# locals: () -%>
+<div class="row-wrap">
+  <%%= ui_counter(current: 2140, max: 4000) %>
+  <%%= ui_counter(current: 3902, max: 4000) %>
+  <%%= ui_counter(current: 4117, max: 4000) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_data_table.html.erb.tt

@@ -0,0 +1,14 @@
+<%%# locals: () -%>
+<%%= ui_data_table(
+      columns: [
+        { label: "Invoice" },
+        { label: "Date", sortable: true, sort: "descending" },
+        { label: "Status" },
+        { label: "Amount", num: true, sortable: true, sort: "none" }
+      ],
+      rows: [
+        ["INV-2031", "12 Jun 2026", ui_tag(label: "Paid", status: :ready), "$1,240.00"],
+        ["INV-2030", "28 May 2026", ui_tag(label: "Pending", status: :progress), "$860.50"],
+        ["INV-2029", "14 May 2026", ui_tag(label: "Overdue", status: :alert), "$2,015.75"]
+      ]
+    ) %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_dialog.html.erb.tt

@@ -0,0 +1,8 @@
+<%%# locals: () -%>
+<%%= ui_dialog(id: "guide-del", title: "Delete this item?", trigger: "Delete item…", destructive: true) do %>
+  <p class="small muted mb-4">This removes the item and everything inside it. It can't be undone.</p>
+  <div class="row-wrap" style="justify-content:flex-end">
+    <%%= ui_button(data: { action: "ui-dialog#close" }) { "Keep it" } %>
+    <%%= ui_button(variant: :danger) { "Delete permanently" } %>
+  </div>
+<%% end %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_diff.html.erb.tt

@@ -0,0 +1,10 @@
+<%%# locals: () -%>
+<%%= ui_diff(
+  file: "config/application.rb",
+  lines: [
+    [:ctx, "config.load_defaults 8.0"],
+    [:del, "config.time_zone = \"UTC\""],
+    [:add, "config.time_zone = \"London\""],
+    [:ctx, "config.eager_load = true"]
+  ]
+) %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_drawer.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<%%= ui_drawer(title: "History") do %>
+  <p class="small muted mb-3">Every saved revision, newest first.</p>
+  <p class="small">You can restore any version or compare it with the current draft.</p>
+<%% end %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_empty.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<%%= ui_empty(title: "Nothing here yet") do %>
+  <p class="muted">There's nothing to show right now. Create your first item to get started.</p>
+  <%%= ui_button(variant: :primary) { "Create item" } %>
+<%% end %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_field.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<div class="grid grid-2">
+  <%%= ui_field(label: "Project name", name: "name", value: "Acme", hint: "Shown across the app.") %>
+  <%%= ui_field(label: "Slug", name: "slug", value: "ac", error: "A slug needs at least 3 characters.") %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_input_group.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<div class="grid grid-2">
+  <%%= ui_input_group(name: "price", value: "9.99", prefix: "$", suffix: "/mo") %>
+  <%%= ui_input_group(name: "subdomain", value: "acme", suffix: ".example.com", placeholder: "your-team") %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_kbd.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<div class="row-wrap">
+  <%%= ui_kbd(keys: ["⌘", "K"]) %>
+  <%%= ui_kbd(keys: ["g", "then", "w"]) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_menu.html.erb.tt

@@ -0,0 +1,9 @@
+<%%# locals: () -%>
+<%%= ui_menu(
+  label: "Account",
+  items: [
+    { label: "Profile", href: "/account/profile" },
+    { label: "Billing", href: "/account/billing" },
+    { label: "Sign out", danger: true, separator_before: true }
+  ]
+) %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_meter.html.erb.tt

@@ -0,0 +1,6 @@
+<%%# locals: () -%>
+<div class="stack">
+  <%%= ui_meter(value: 38400, max: 60000, state: :under, label: "Usage") %>
+  <%%= ui_meter(value: 60200, max: 60000, state: :at, label: "Usage") %>
+  <%%= ui_meter(value: 71900, max: 60000, state: :over, label: "Usage") %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_note.html.erb.tt

@@ -0,0 +1,2 @@
+<%%# locals: () -%>
+<%%= ui_note do %>Use a note to call out a useful aside or a piece of context that supports the main content without interrupting it.<%% end %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_outline.html.erb.tt

@@ -0,0 +1,8 @@
+<%%# locals: () -%>
+<%%= ui_outline(items: [
+      { label: "Getting started", href: "#", level: 1, current: true },
+      { label: "Installation", href: "#", level: 2 },
+      { label: "Configuration", href: "#", level: 2 },
+      { label: "A worked example", href: "#", level: 3 },
+      { label: "Reference", href: "#", level: 1 }
+    ]) %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_pagination.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<div class="stack">
+  <%%= ui_pagination(current: 1, total: 5) %>
+  <%%= ui_pagination(current: 3, total: 5) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_panel.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<%%= ui_panel do %>
+  <p class="label">Summary</p>
+  <p class="mt-2">A panel groups related content on a raised surface. Use it to set a region apart from the page without the full weight of a card.</p>
+<%% end %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_popover.html.erb.tt

@@ -0,0 +1,2 @@
+<%%# locals: () -%>
+<%%= ui_popover(content: "Changes save automatically as you type.") %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_radio.html.erb.tt

@@ -0,0 +1,6 @@
+<%%# locals: () -%>
+<fieldset class="fieldset">
+  <legend>Default role</legend>
+  <%%= ui_radio(label: "Member", name: "role", value: "member", checked: true) %>
+  <%%= ui_radio(label: "Admin", name: "role", value: "admin") %>
+</fieldset>

data/lib/generators/seams/design/templates/app/views/ui/previews/_savestate.html.erb.tt

@@ -0,0 +1,4 @@
+<%%# locals: () -%>
+<%%= ui_savestate(state: :saved) %>
+<%%= ui_savestate(state: :saving) %>
+<%%= ui_savestate(state: :unsaved) %>

data/lib/generators/seams/design/templates/app/views/ui/previews/_segmented.html.erb.tt

@@ -0,0 +1,15 @@
+<%%# locals: () -%>
+<div class="stack">
+  <%%= ui_segmented(
+        name: "view",
+        label: "View",
+        selected: "list",
+        options: [["list", "List"], ["grid", "Grid"], ["board", "Board"]]
+      ) %>
+  <%%= ui_segmented(
+        name: "theme",
+        label: "Theme",
+        selected: "system",
+        options: [["light", "Light"], ["dark", "Dark"], ["system", "System"]]
+      ) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_stepper.html.erb.tt

@@ -0,0 +1,6 @@
+<%%# locals: () -%>
+<div class="stack">
+  <%%= ui_stepper(steps: ["Account", "Details", "Plan", "Payment", "Review"], current: 3) %>
+  <%%= ui_stepper(steps: ["Account", "Details", "Plan", "Payment", "Review"], current: 1) %>
+  <%%= ui_stepper(steps: ["Account", "Details", "Plan", "Payment", "Review"], current: 5) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_switch.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: () -%>
+<div class="stack">
+  <%%= ui_switch(label: "Make this project private", name: "private") %>
+  <%%= ui_switch(label: "Email me on activity", name: "activity_email", checked: true) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_tag.html.erb.tt

@@ -0,0 +1,8 @@
+<%%# locals: () -%>
+<div class="row-wrap">
+  <%%= ui_tag(label: "Ready", status: :ready) %>
+  <%%= ui_tag(label: "Building", status: :progress) %>
+  <%%= ui_tag(label: "Failed", status: :alert) %>
+  <%%= ui_tag(label: "Draft", status: :neutral) %>
+  <%%= ui_tag(label: "No dot", status: :neutral, dot: false) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_toast.html.erb.tt

@@ -0,0 +1,6 @@
+<%%# locals: () -%>
+<div class="toaster" style="position:static;width:340px;max-width:100%">
+  <%%= ui_toast(message: "Changes saved", kind: :ok) %>
+  <%%= ui_toast(message: "Couldn't save — check your connection", kind: :alert) %>
+  <%%= ui_toast(message: "Copied to clipboard", kind: :info) %>
+</div>

data/lib/generators/seams/design/templates/app/views/ui/previews/_toolbar.html.erb.tt

@@ -0,0 +1,11 @@
+<%%# locals: () -%>
+<%%= ui_toolbar(
+      label: "Text formatting",
+      items: [
+        { label: "Heading" },
+        { label: "Bold" },
+        { label: "Italic" },
+        { label: "Link", icon: :edit, sep_before: true },
+        { label: "Preview", icon: :eye }
+      ]
+    ) %>

data/lib/generators/seams/design/templates/lib/design/components.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Design
+  class << self
+    # Component names, derived from the preview partials under
+    # app/views/ui/previews/. Memoised; reset on code reload via the engine's
+    # to_prepare hook so new components appear without a server restart.
+    def component_names
+      @component_names ||= Dir[previews_root.join("_*.html.erb")]
+        .map { |path| File.basename(path).delete_prefix("_").delete_suffix(".html.erb") }
+        .sort
+    end
+
+    def reset_component_names!
+      @component_names = nil
+    end
+
+    def previews_root
+      Engine.root.join("app", "views", "ui", "previews")
+    end
+  end
+end

data/lib/generators/seams/design/templates/lib/design.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "design/version"
+require "design/components"
+require "design/engine"
+
+# Design — the seams design system, as a callable component library.
+#
+# A component is a strict-locals ERB partial under app/views/ui/ that has a
+# companion preview under app/views/ui/previews/. The preview is what makes a
+# component "public": it gives the auto-wired `ui_<name>` helper and the living
+# guide their list. Internal partials (icon, icon_sprite) have no preview, so
+# they get no helper and never appear in the guide.
+#
+# Plain ERB by design — the whole surface stays inside the host's Herb + RuboCop
+# gate, with no view framework and no extra dependency.
+module Design
+end

data/lib/generators/seams/design/templates/lib/engine.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Design
+  # A deliberately NON-isolated engine (proposals/design_system_engine.md, D4):
+  # its app/views/ui partials and its UiHelper must be visible to the host AND
+  # to every other engine's views, so a component can be invoked anywhere. Rails
+  # appends the engine's app/views to the application's view paths automatically;
+  # the helper (and the auto-derived ui_<name> component helpers) are wired into
+  # ActionController::Base explicitly below.
+  #
+  # This engine intentionally does NOT isolate its namespace — that is the whole
+  # point. An isolated engine would scope the partials and keep the helper out of
+  # the host's controllers, which is exactly what this engine must NOT do.
+  class Engine < ::Rails::Engine
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "design.helpers" do |app|
+      app.config.to_prepare do
+        # Re-derive on every reload so a newly added component (a new preview
+        # partial under app/views/ui/previews/) gets its ui_<name> helper
+        # without a server restart.
+        Design.reset_component_names!
+        Design::UiHelper.define_component_helpers!
+        ActionController::Base.helper(Design::UiHelper)
+      end
+    end
+
+    initializer "design.append_migrations" do |app|
+      unless app.root == root
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/design/templates/lib/generators/design/component/component_generator.rb.tt

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Design
+  module Generators
+    # rails g design:component badge
+    #
+    # Scaffolds a component (a strict-locals partial under app/views/ui/) and its
+    # preview (under app/views/ui/previews/). The preview is what makes the
+    # component "public": it gets an auto-wired ui_<name> helper AND a section in
+    # the living gallery, both automatically, with no extra wiring. The generator
+    # gives you the skeleton and the conventions; you fill in the markup with the
+    # design system's Tailwind classes.
+    #
+    # Ported from quire-saas's Compositor (compositor:component), generalised:
+    # compositor/ -> ui/, compositor_<name> -> ui_<name>, Compositor:: -> Design::.
+    class ComponentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Scaffold a design-system component partial (app/views/ui/) and its preview."
+
+      def create_component_partial
+        template "component.html.erb.tt", view_path("ui/_#{file_name}.html.erb")
+      end
+
+      def create_preview_partial
+        template "preview.html.erb.tt", view_path("ui/previews/_#{file_name}.html.erb")
+      end
+
+      def next_steps
+        say ""
+        say "  design:component #{file_name} scaffolded.", :green
+        say "  1. Build the markup in app/views/ui/_#{file_name}.html.erb"
+        say "     using the design system's classes; bake in accessibility."
+        say "  2. Show its states in app/views/ui/previews/_#{file_name}.html.erb"
+        say "  3. ui_#{file_name} is now callable in every view; see /design/guide."
+        say ""
+      end
+
+      private
+
+      # The design engine is non-isolated, so its partials live in the engine's
+      # own app/views/ui/ tree (which Rails appends to the host's view paths).
+      # Resolve the engine root at runtime so the generator writes into the
+      # engine wherever the host vendored it.
+      def view_path(relative)
+        File.join(Design::Engine.root, "app", "views", relative)
+      end
+    end
+  end
+end

data/lib/generators/seams/design/templates/lib/generators/design/component/templates/component.html.erb.tt

@@ -0,0 +1,5 @@
+<%%# locals: (variant: :default, content: nil, **attrs) -%>
+<%%# TODO: build the <%= file_name %> component from the design system's classes.
+    Bake in accessibility (roles, aria-*, label association). Splat **attrs onto
+    the root element so callers can pass id / data-* / aria-* without forking. -%>
+<%%= tag.div class: class_names("<%= file_name %>", "<%= file_name %>-#{variant}" => variant.to_s != "default"), **attrs do %><%%= content %><%% end %>

data/lib/generators/seams/design/templates/lib/generators/design/component/templates/preview.html.erb.tt

@@ -0,0 +1,3 @@
+<%%# locals: () -%>
+<%%# TODO: show every state of <%= file_name %>. -%>
+<%%= ui_<%= file_name %> { "<%= file_name.humanize %>" } %>

data/lib/generators/seams/design/templates/spec/runtime/design_boot_spec.rb.tt

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# Boot spec for the seams design engine — Phase 1 (skeleton). Covers:
+#
+#   - the engine constant loads and is NOT isolated (proposals/
+#     design_system_engine.md, D4)
+#   - the auto-wire registry (Design.component_names) derives the public
+#     component list from the preview partials and resets on demand
+#   - the host-wide UiHelper loads and is mixed into ActionController::Base,
+#     so ui_* helpers resolve in host + engine views
+#   - Design::FormBuilder loads and subclasses the standard Rails builder
+#     (so it is safe as the app-wide default)
+#   - the icon sprite + icon partials live in the engine's view path
+#
+# Later sub-issues add the token, component, gallery and FormBuilder-field
+# specs; this proves the load-bearing skeleton boots.
+RSpec.describe "Design engine boot", type: :integration do
+  describe "the engine constant" do
+    it "loads" do
+      expect(defined?(Design::Engine)).to eq("constant")
+    end
+
+    it "is NON-isolated (no isolated namespace)" do
+      # An isolated engine sets Engine.isolated? true and scopes its helpers /
+      # routes. The design engine must NOT — its partials + helpers are host-wide.
+      expect(Design::Engine.isolated?).to be(false)
+    end
+  end
+
+  describe "the auto-wire registry" do
+    it "derives the public component list from the preview partials" do
+      # The seed set (button, tag) each ships a preview, so they appear in the
+      # public list; the internal icon partials have no preview, so they don't.
+      expect(Design.component_names).to be_an(Array)
+      expect(Design.component_names).to include("button", "tag")
+    end
+
+    it "auto-derives a ui_<name> helper for every public component" do
+      Design::UiHelper.define_component_helpers!
+      helpers = ActionController::Base.helpers
+      expect(helpers).to respond_to(:ui_button)
+      expect(helpers).to respond_to(:ui_tag)
+    end
+
+    it "resets the memoised component list on demand" do
+      Design.component_names
+      expect { Design.reset_component_names! }.not_to raise_error
+    end
+  end
+
+  describe "the host-wide UiHelper" do
+    it "exposes the hand-written ui_icon" do
+      expect(defined?(Design::UiHelper)).to eq("constant")
+      expect(Design::UiHelper.instance_methods).to include(:ui_icon)
+    end
+
+    it "is mixed into ActionController::Base so ui_* resolve host-wide" do
+      expect(ActionController::Base.helpers).to respond_to(:ui_icon)
+    end
+  end
+
+  describe "Design::FormBuilder" do
+    it "subclasses the standard Rails builder" do
+      expect(defined?(Design::FormBuilder)).to eq("constant")
+      expect(Design::FormBuilder.ancestors).to include(ActionView::Helpers::FormBuilder)
+      expect(Design::FormBuilder.instance_methods).to include(:ui_text_field)
+    end
+  end
+
+  describe "the engine view path" do
+    it "ships the icon sprite + icon partials" do
+      root = Design::Engine.root
+      expect(File.exist?(root.join("app/views/ui/_icon.html.erb"))).to be(true)
+      expect(File.exist?(root.join("app/views/ui/_icon_sprite.html.erb"))).to be(true)
+    end
+  end
+end

data/lib/generators/seams/design/templates/spec/runtime/form_builder_spec.rb.tt

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# Design::FormBuilder — the host default builder (#19). Renders real forms
+# through the dummy app's view stack so the ui/field partial + the aria/error
+# wiring are exercised end to end, not stubbed.
+#
+# What it guards:
+#
+#   - Design::FormBuilder is the app-wide default, so `form_with` yields it
+#     without passing `builder:` — f.ui_text_field is available;
+#   - f.ui_text_field renders the ui/field markup: an associated <label>, a
+#     value-bound .input, and (when given) a hint linked via aria-describedby;
+#   - on a model with a validation error, the field switches to the error state:
+#     aria-invalid="true", the error message, and aria-describedby pointing at
+#     the error node instead of the hint.
+RSpec.describe "Design::FormBuilder", type: :integration do
+  # A minimal ActiveModel object so we can drive validations + errors through a
+  # real form, with no schema or table.
+  let(:form_model_class) do
+    Class.new do
+      include ActiveModel::Model
+      attr_accessor :title
+
+      validates :title, presence: true
+
+      def self.name = "Project"
+    end
+  end
+
+  # Render a form the way a view would, through ApplicationController so the
+  # host-default builder + the engine's ui/ partials resolve. An inline template
+  # is the reliable way to exercise form_with's block + the ui/field partial
+  # outside a request.
+  def render_form(model)
+    ApplicationController.render(
+      inline: <<~ERB,
+        <%%= form_with(model: @model, url: "/", builder: Design::FormBuilder) do |form| %>
+          <%%= form.ui_text_field :title, label: "Title", hint: "Shown everywhere." %>
+        <%% end %>
+      ERB
+      assigns: { model: model }
+    )
+  end
+
+  describe "the default builder" do
+    it "only ADDS ui_* helpers — it is safe to make the app-wide default" do
+      # The standard field helpers are untouched, which is what makes it safe to
+      # set as config.action_view.default_form_builder (the generator does this
+      # in the host's config/application.rb; covered by the generator spec).
+      expect(Design::FormBuilder.ancestors).to include(ActionView::Helpers::FormBuilder)
+      expect(Design::FormBuilder.instance_methods).to include(:ui_text_field, :ui_submit)
+    end
+
+    it "renders an associated label + value-bound input" do
+      model = form_model_class.new(title: "Acme")
+      html = render_form(model)
+
+      expect(html).to include(">Title</label>")
+      expect(html).to include('class="input"')
+      expect(html).to include('value="Acme"')
+      # the label's `for` targets the input's id (association is not by guesswork)
+      label_for = html[/<label[^>]*for="([^"]+)"/, 1]
+      expect(html).to include(%(id="#{label_for}"))
+    end
+
+    it "links the hint via aria-describedby when there is no error" do
+      model = form_model_class.new(title: "Acme")
+      html = render_form(model)
+
+      hint_id = html[/<p[^>]*class="hint"[^>]*id="([^"]+)"/, 1]
+      expect(hint_id).to end_with("-hint")
+      expect(html).to include(%(aria-describedby="#{hint_id}"))
+      expect(html).to include("Shown everywhere.")
+      expect(html).not_to include('aria-invalid="true"')
+    end
+  end
+
+  describe "the error state" do
+    it "wires aria-invalid + aria-describedby to the error, and drops the hint" do
+      model = form_model_class.new(title: nil)
+      model.validate
+      html = render_form(model)
+
+      expect(html).to include('aria-invalid="true"')
+      # the message comes from the model's errors, rendered into the error node
+      error_id = html[/<p[^>]*class="hint"[^>]*id="([^"]+)"/, 1]
+      expect(error_id).to end_with("-error")
+      expect(html).to include(%(aria-describedby="#{error_id}"))
+      expect(html).to include(model.errors[:title].first)
+      # in the error state the hint is suppressed, so describedby points at the
+      # error rather than the hint
+      expect(html).not_to include("Shown everywhere.")
+    end
+  end
+end

data/lib/generators/seams/design/templates/spec/runtime/guide_spec.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# The living-gallery smoke test. Drives the real /design/guide route through the
+# dummy app's full Rack stack, so a component that breaks its preview (or the
+# guide chrome itself) fails CI. Also proves the route is dev/test-only.
+RSpec.describe "Design living gallery", type: :request do
+  describe "GET /design/guide" do
+    it "renders the gallery from the real previews" do
+      get "/design/guide"
+
+      expect(response).to have_http_status(:ok)
+      # The seed components appear, each rendered from its own preview.
+      expect(response.body).to include("ui_button")
+      expect(response.body).to include("ui_tag")
+      # The button preview's content proves the partial actually rendered.
+      expect(response.body).to include("Primary")
+    end
+
+    it "lists exactly the public component set" do
+      get "/design/guide"
+
+      Design.component_names.each do |name|
+        expect(response.body).to include("ui_#{name}")
+      end
+    end
+  end
+
+  describe "production guard" do
+    it "is unavailable in production (the controller 404s)" do
+      # The controller's before_action heads :not_found unless Rails.env.local?.
+      # We assert the guard exists rather than reload the whole app into the
+      # production environment inside the suite.
+      source = Design::Engine.root.join("app/controllers/design/guide_controller.rb").read
+      expect(source).to include("Rails.env.local?")
+      expect(source).to include("head :not_found")
+    end
+  end
+end

data/lib/generators/seams/design/templates/spec/runtime/ui_components_spec.rb.tt

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+# The strict-locals contract + a per-component render smoke test for the seed
+# component set. Lives under spec/runtime so it renders through the dummy app's
+# real view stack (the engine's ui/ partials are on its view path because the
+# engine is non-isolated).
+#
+# What it guards:
+#
+#   - every component partial declares a `locals:` magic comment, so its public
+#     surface is explicit (the contract that makes the auto-wire + the override
+#     story honest);
+#   - a required strict local that is omitted RAISES rather than silently
+#     rendering nothing — the heart of the "strict locals" contract;
+#   - every seed component renders without error from its own preview.
+#
+# Rendering is done through ApplicationController so the auto-wired ui_* helpers
+# (mixed into ActionController::Base by the engine) resolve inside the previews.
+RSpec.describe "Design ui_* components", type: :integration do
+  # Render a partial the way a view would, with the design helpers available.
+  def render_partial(path, **locals)
+    ApplicationController.render(partial: path, locals: locals)
+  end
+
+  describe "the strict-locals contract" do
+    it "every component partial declares a `locals:` magic comment" do
+      root = Design::Engine.root.join("app", "views", "ui")
+      partials = Dir[root.join("_*.html.erb")]
+      expect(partials).not_to be_empty
+
+      partials.each do |partial|
+        first_line = File.foreach(partial).first.to_s
+        expect(first_line).to match(/locals:/),
+                              "#{File.basename(partial)} is missing its `# locals:` strict-locals header"
+      end
+    end
+
+    it "raises when a required local is omitted (ui/tag needs label:)" do
+      # _tag.html.erb declares `locals: (label:, ...)` — label: is required, so
+      # rendering without it must raise rather than render an empty tag.
+      expect { render_partial("ui/tag") }.to raise_error(ArgumentError)
+    end
+
+    it "renders ui/tag when the required local is supplied" do
+      html = render_partial("ui/tag", label: "Ready", status: :ready)
+      expect(html).to include("Ready")
+    end
+  end
+
+  describe "the seed components render from their previews" do
+    it "renders every public component's preview without error", :aggregate_failures do
+      Design.component_names.each do |name|
+        expect { render_partial("ui/previews/#{name}") }
+          .not_to raise_error, "ui/previews/_#{name} failed to render"
+      end
+    end
+
+    it "ships the button + tag seed components" do
+      expect(Design.component_names).to include("button", "tag")
+    end
+
+    it "renders ui_button with its block content" do
+      html = render_partial("ui/button", variant: :primary, content: "Save")
+      expect(html).to include("Save")
+      expect(html).to include("btn-primary")
+    end
+  end
+end