velvetkit 0.1.0.beta

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f176f98bff0013d64b619054845556e1323b6c285e374297238d9e13896c444
+  data.tar.gz: 37703180175c2b19f0630f92801e5831843531a97b1e1dfe3cd9f47f5995e6ad
+SHA512:
+  metadata.gz: e4432fd886028e08a31f840bebc3e9128fa84f19da9ab4d8bb1f40e78f623580279228c248bd21f98e6d9e1fe56adaa951cdadc508958386b0db4cdd652d53c6
+  data.tar.gz: b2be00dac1a8d5e8682b0ae02dae3670511644c92703397ad153a8934b5843087c9dfb0c88c4ca58ed81b36dbb5b441ed6021d69db2a3a45060712bac14884e9

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0.beta — 2026-10-26
+
+- First release of the component library.
+- `velvetkit:install` and `velvetkit:add` generators, with a configurable namespace.
+- 39 components, their Stimulus controllers, tests and Lookbook previews.
+- `Select` is a styled dropdown (listbox, keyboard, type-ahead), with
+  `searchable:` and `multiple:`; it posts through a hidden native select, so
+  forms work unchanged. The browser's own control is now `NativeSelect`.
+- `velvetkit:add --all`, and support for cssbundling-rails Tailwind entry points.
+- Docs site for velvetkit.com in `site/`, built from the registry.
+- `velvetkit:ai`, run by `install` and kept current by `add`: `docs/velvetkit.md`,
+  a Claude Code skill and an AGENTS.md section, so agents use the kit.
+- Primary colour is velvet, `#4D1A7F`, lifted in dark mode to stay readable.
+- Fix: `Icon` dropped its icon name when given `data:` attributes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rain Root
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,197 @@
+# VelvetKit
+
+Accessible UI components for Rails, built on [ViewComponent](https://viewcomponent.org),
+Tailwind CSS 4 and Stimulus. Website: **https://velvetkit.com**
+
+VelvetKit doesn't load a component library at runtime. A generator copies the
+components you ask for, plus the ones they depend on, into your app. After
+that they're your code, under whatever module name you choose, and you can
+change them however you like.
+
+```bash
+bin/rails generate velvetkit:add dialog
+#  create  app/components/ui/base.rb
+#  create  app/components/ui/icon.rb
+#  create  app/components/ui/spinner.rb
+#  create  app/components/ui/button.rb
+#  create  app/components/ui/dialog.rb …
+#  create  app/javascript/controllers/ui/dialog_controller.ts
+```
+
+## Requirements
+
+- Rails 7.1+, Ruby 3.2+
+- Tailwind CSS 4
+- A JavaScript bundler that compiles TypeScript (Bun or esbuild through
+  `jsbundling-rails`). The Stimulus controllers are `.ts` files.
+
+## Install
+
+```ruby
+# Gemfile
+gem "velvetkit", group: :development
+```
+
+```bash
+bundle install
+bin/rails generate velvetkit:install                 # components under UI::
+bin/rails generate velvetkit:install --namespace=Kit # or under Kit::
+```
+
+`install` does the following:
+
+- writes `config/velvetkit.yml` with the namespace
+- adds `view_component` and `tailwind_merge` to the Gemfile
+- adds an acronym inflection when the namespace needs one (`UI`, not `Kit`)
+- copies the base component, design tokens (`app/assets/tailwind/velvetkit.css`),
+  translations (`config/locales/velvetkit.en.yml`) and Lucide icon setup
+  (`app/javascript/velvetkit_icons.ts`), and imports the CSS and icons from
+  your entry points
+- installs `@hotwired/stimulus`, `lucide` and `tw-animate-css` with your
+  package manager, which it picks from your lockfile
+
+## Add components
+
+```bash
+bin/rails generate velvetkit:add                  # list what's available
+bin/rails generate velvetkit:add date_picker menu # add these and what they use
+```
+
+`add` does the following for each component:
+
+- copies the component, its templates and sub-components
+- copies its Stimulus controllers and any lazily-loaded entry points (AG Grid
+  for `data_grid`, Cally for `date_picker`)
+- copies its Minitest tests and Lookbook previews. A preview that shows
+  components you haven't added is skipped, and `add` tells you which.
+- registers its controllers in `app/javascript/controllers/index.js` when
+  that file lists controllers one by one
+- installs any npm packages it needs, and adds any gems it needs (`pagy` for
+  `pagination`) to the Gemfile
+
+Options: `--namespace=Kit`, `--skip-tests`, `--skip-previews`,
+`--skip-packages` (list the packages instead of installing them), and the usual
+`--force`/`--skip` for files that already exist.
+
+## AI agents
+
+`install` also writes three files so coding agents use your components
+instead of inventing new ones:
+
+- `docs/velvetkit.md`: the rules for building UI with the kit, then every
+  installed component's arguments, slots, notes and working examples, all in
+  your namespace. `add` rewrites it whenever you add components.
+- `.claude/skills/velvetkit/SKILL.md`: a Claude Code skill pointing at it.
+- A short section in `AGENTS.md` pointing at it, for Codex, Cursor and others.
+  Your own notes in that file are kept.
+
+Run `bin/rails generate velvetkit:ai` to regenerate them, or install with
+`--skip-ai` to leave them out. velvetkit.com also serves
+[llms.txt](https://velvetkit.com/llms.txt), and every component page has a
+Markdown version.
+
+## Namespacing
+
+Every component is written once, against `UI`. The generators rewrite each file
+as they copy it, so with `--namespace=Kit`:
+
+| In the registry              | In your app                   |
+| ---------------------------- | ----------------------------- |
+| `UI::Button`                 | `Kit::Button`                 |
+| `app/components/ui/`         | `app/components/kit/`         |
+| `data-controller="ui--menu"` | `data-controller="kit--menu"` |
+| `t("ui.dialog.close_label")` | `t("kit.dialog.close_label")` |
+| `"ui-dialog-#{id}"`          | `"kit-dialog-#{id}"`          |
+
+The namespace must be a single constant name, like `UI`, `Kit` or `VelvetKit`.
+
+## Theming
+
+Components style themselves from the CSS variables in `velvetkit.css`
+(`--primary`, `--radius`, `--sidebar`, …), with a `.dark` set alongside. To
+retheme, change those values. Don't change the components.
+
+For dark mode without a flash on load, add `theme_toggle` and render its
+partial in your layout's `<head>`:
+
+```erb
+<%= render "layouts/theme_script" %>
+```
+
+## Developing VelvetKit
+
+```bash
+bundle install
+bundle exec rake test:gem         # namespace rewriting, registry, generators
+bundle exec rake test:components  # every component, from the registry, as UI::
+bundle exec rake test:namespaced  # every component copied out as Kit::, then tested
+```
+
+`registry/` holds the components, laid out like a Rails app.
+`registry/components.yml` holds only what the files can't say themselves
+(descriptions, package and gem versions). Dependencies, Stimulus controllers
+and npm imports are read from the source, so they can't drift.
+
+## The docs site (velvetkit.com)
+
+`site/` is a Rails app that serves https://velvetkit.com. It installs the kit
+from `registry/` the way any app would, with `bin/sync-kit` (it runs
+`velvetkit:install` and `velvetkit:add --all`). The copied files are
+gitignored, so the registry is the only source.
+
+The pages build themselves from the registry:
+
+- each component page renders that component's Lookbook preview templates
+  live, next to their source
+- the "Comes with" list comes from the same dependency scan `add` uses
+- the arguments and slots are read from the component's Ruby
+
+To document a component, write or improve its preview. The site picks it up.
+
+```bash
+cd site
+bun install && bundle install
+bin/dev            # sync the kit, then run Rails, JS and CSS watchers
+bin/rails test     # every page renders, every live example, SEO and AI endpoints
+bin/ux-check       # real clicks, keys and clipboard in headless Chrome (site on :3000)
+```
+
+### Deploying
+
+The image is built from the `Dockerfile` at the repository root. It needs
+the gem and the registry as well as `site/`.
+
+**Dokploy:** create an Application from this repository with build type
+**Dockerfile**. The defaults fit: Dockerfile path `Dockerfile`, context `.`.
+Then:
+
+- Environment:
+  - `SECRET_KEY_BASE`, required: generate one with `openssl rand -hex 64`.
+  - `SITE_URL`, if the site isn't served at https://velvetkit.com.
+- Domains: `velvetkit.com` on container port **80**, with HTTPS on. Traefik
+  terminates TLS and the app trusts it (`assume_ssl`).
+- Health check: the image declares one against `GET /up`.
+
+**Kamal:** fill in the TODOs in `site/config/deploy.yml`, then run
+`bin/kamal deploy` from `site/`. It uses the same Dockerfile.
+
+**Anywhere else:**
+
+```bash
+docker build -t velvetkit-site .
+docker run -p 8080:80 -e SECRET_KEY_BASE=$(openssl rand -hex 64) -e FORCE_SSL=false velvetkit-site
+```
+
+### SEO and AI
+
+Every page has its own title, description, canonical URL and Open Graph
+and Twitter cards, using `public/og.png`. The home page carries JSON-LD for
+`SoftwareApplication` and `WebSite`; docs pages carry `TechArticle` and
+`BreadcrumbList`. `/sitemap.xml` and `/robots.txt` are built from the
+routes, and robots explicitly welcomes AI crawlers and points them at
+`/llms.txt`. Component pages link their Markdown version with
+`rel="alternate"`.
+
+## License
+
+MIT

data/lib/generators/velvetkit/add/add_generator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "json"
+require_relative "../helpers"
+
+module Velvetkit
+  module Generators
+    class AddGenerator < Rails::Generators::Base
+      include Helpers
+
+      desc <<~DESC
+        Copy VelvetKit components into the app, with every component they use.
+
+        Run with no components to list what is available.
+
+          bin/rails generate velvetkit:add dialog date_picker
+      DESC
+
+      argument :components, type: :array, default: [], banner: "component component ..."
+
+      class_option :namespace, type: :string,
+                               desc: "Module for the components (default: #{CONFIG_FILE}, else UI)"
+      class_option :all, type: :boolean, default: false, desc: "Add every component"
+      class_option :skip_tests, type: :boolean, default: false, desc: "Don't copy component tests"
+      class_option :skip_previews, type: :boolean, default: false, desc: "Don't copy Lookbook previews"
+      class_option :skip_packages, type: :boolean, default: false,
+                                   desc: "List the npm packages to add instead of installing them"
+
+      def list_components
+        return if requested.any?
+
+        say "Usage: bin/rails generate velvetkit:add COMPONENT [COMPONENT ...]\n\n"
+        registry.names.each { |name| say format("  %-16s %s", name, registry.description(name)) }
+      end
+
+      def copy_components
+        resolved.each do |name|
+          files = registry.component_files(name) + registry.javascript_files(name)
+          files += registry.test_files(name) unless options[:skip_tests]
+          files.uniq.each { |file| copy_from_registry(file) }
+        end
+      end
+
+      def copy_previews
+        return if options[:skip_previews]
+
+        resolved.each do |name|
+          needs = registry.preview_requires(name, resolved)
+          if needs.any?
+            say_status :skip, "#{name} preview, it also shows #{needs.join(', ')}", :yellow
+          else
+            registry.preview_files(name).each { |file| copy_from_registry(file) }
+          end
+        end
+      end
+
+      # Apps that list controllers in a manifest (jsbundling with
+      # stimulus:manifest:update) need each one registered; apps that load the
+      # directory (importmap, eagerLoadControllersFrom) need nothing.
+      def register_stimulus_controllers
+        manifest = File.join(destination_root, "app/javascript/controllers/index.js")
+        return unless File.exist?(manifest) && !File.read(manifest).match?(/(eager|lazy)LoadControllersFrom/)
+
+        controllers.each do |file|
+          path = kit_namespace.rewrite_path(file).delete_prefix("app/javascript/controllers/").delete_suffix("_controller.ts")
+          identifier = path.tr("_", "-").gsub("/", "--")
+          next if File.read(manifest).match?(/["']#{Regexp.escape(identifier)}["']/)
+
+          constant = "#{path.camelize.gsub('::', '__')}Controller"
+          append_to_file "app/javascript/controllers/index.js", <<~JS
+            \nimport #{constant} from "./#{path}_controller"
+            application.register("#{identifier}", #{constant})
+          JS
+        end
+      end
+
+      def add_gems
+        gemfile = File.read(File.join(destination_root, "Gemfile"))
+        resolved.flat_map { |name| registry.gems(name).to_a }.uniq.each do |name, version|
+          gem name, version unless gemfile.match?(/gem ["']#{name}["']/)
+        end
+      end
+
+      def add_packages
+        install_packages(resolved.flat_map { |name| registry.packages(name) }.uniq)
+      end
+
+      # Keep the agents' reference listing what is installed now.
+      def refresh_ai_reference
+        return if resolved.empty? || !File.exist?(File.join(destination_root, "docs/velvetkit.md"))
+
+        invoke "velvetkit:ai", [], namespace: kit_namespace.name
+      end
+
+      private
+
+      def resolved
+        @resolved ||= requested.empty? ? [] : registry.resolve(requested)
+      end
+
+      def requested
+        options[:all] ? registry.names : components
+      end
+
+      def controllers
+        resolved.flat_map { |name| registry.stimulus_controllers(name) }.uniq
+      end
+    end
+  end
+end

data/lib/generators/velvetkit/ai/ai_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require_relative "../helpers"
+
+module Velvetkit
+  module Generators
+    # Tells AI coding agents how to build UI in this app with its components.
+    #
+    # Writes docs/velvetkit.md (the rules, then a reference for each installed
+    # component, in the app's namespace) and points agents at it: a Claude
+    # Code skill, and a section in AGENTS.md for Codex, Cursor and the rest.
+    # `add` runs this again whenever the reference exists, so it stays current.
+    class AiGenerator < Rails::Generators::Base
+      include Helpers
+
+      REFERENCE = "docs/velvetkit.md"
+      SKILL = ".claude/skills/velvetkit/SKILL.md"
+      MARKER = "<!-- velvetkit -->"
+
+      desc <<~DESC
+        Write docs/velvetkit.md for AI agents, describing the components
+        installed in this app, and point Claude Code and AGENTS.md at it.
+      DESC
+
+      class_option :namespace, type: :string,
+                               desc: "Module the components are under (default: #{CONFIG_FILE}, else UI)"
+
+      def write_reference
+        create_file REFERENCE, Velvetkit.agent_guide(installed, namespace: kit_namespace), force: true
+      end
+
+      def write_claude_skill
+        create_file SKILL, <<~MARKDOWN, force: true
+          ---
+          name: velvetkit
+          description: Build Rails UI with this app's #{kit_namespace.name}:: components (VelvetKit ViewComponents). Use when writing or changing views, forms, layouts, pages or ViewComponents.
+          ---
+
+          This app's UI is built from VelvetKit components under `#{kit_namespace.name}::`.
+          Before writing or changing any view, read `#{REFERENCE}`: it has the rules
+          and every installed component's arguments, slots and working examples.
+
+          Need a component that isn't installed? Run `bin/rails generate velvetkit:add <name>`
+          instead of writing one.
+        MARKDOWN
+      end
+
+      def point_agents_md_at_reference
+        section = <<~MARKDOWN
+          #{MARKER}
+          ## UI components
+
+          Build UI from the app's VelvetKit components (`#{kit_namespace.name}::Button`,
+          `#{kit_namespace.name}::Dialog`, …). Read `#{REFERENCE}` before writing views: it lists
+          the rules and every installed component with working examples.
+        MARKDOWN
+
+        agents = File.join(destination_root, "AGENTS.md")
+        if !File.exist?(agents)
+          create_file "AGENTS.md", "# Agent notes\n\n#{section}"
+        elsif !File.read(agents).include?(MARKER)
+          append_to_file "AGENTS.md", "\n#{section}"
+        end
+      end
+
+      private
+
+      # Components present in the app, matched against the registry.
+      def installed
+        folder = File.join(destination_root, "app/components", kit_namespace.path)
+        present = Dir.glob("*.rb", base: folder).map { |file| File.basename(file, ".rb") } +
+                  Dir.glob("*/", base: folder).map { |dir| dir.chomp("/") }
+        registry.names & present
+      end
+    end
+  end
+end

data/lib/generators/velvetkit/helpers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "velvetkit"
+
+module Velvetkit
+  module Generators
+    # What the install and add generators share: where the registry is, which
+    # namespace the app uses, and how a file gets from one to the other.
+    module Helpers
+      LOCKFILES = {
+        "bun.lock" => "bun add",
+        "bun.lockb" => "bun add",
+        "yarn.lock" => "yarn add",
+        "pnpm-lock.yaml" => "pnpm add",
+        "package-lock.json" => "npm install"
+      }.freeze
+
+      private
+
+      def registry
+        Velvetkit.registry
+      end
+
+      # --namespace, else config/velvetkit.yml, else UI.
+      def kit_namespace
+        @kit_namespace ||= Namespace.new(options[:namespace] || configured_namespace || Namespace::CANONICAL)
+      end
+
+      def configured_namespace
+        config = File.join(destination_root, CONFIG_FILE)
+        YAML.load_file(config)&.fetch("namespace", nil) if File.exist?(config)
+      end
+
+      def copy_from_registry(file)
+        create_file kit_namespace.rewrite_path(file), kit_namespace.rewrite(registry.read(file))
+      end
+
+      def install_packages(packages)
+        package_json = File.join(destination_root, "package.json")
+        missing = packages - installed_packages(package_json)
+        return if missing.empty?
+
+        specs = missing.map { |package| "#{package}@#{registry.package_version(package)}" }
+        if options[:skip_packages] || !File.exist?(package_json)
+          say_status :packages, "add these to package.json: #{specs.join(' ')}", :yellow
+        else
+          run "#{package_manager} #{specs.join(' ')}"
+        end
+      end
+
+      def installed_packages(package_json)
+        return [] unless File.exist?(package_json)
+
+        json = JSON.parse(File.read(package_json))
+        json.fetch("dependencies", {}).keys + json.fetch("devDependencies", {}).keys
+      end
+
+      def package_manager
+        LOCKFILES.each { |lockfile, command| return command if File.exist?(File.join(destination_root, lockfile)) }
+        "npm install"
+      end
+    end
+  end
+end

data/lib/generators/velvetkit/install/install_generator.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "json"
+require_relative "../helpers"
+
+module Velvetkit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Helpers
+
+      desc <<~DESC
+        Set the app up for VelvetKit: choose the namespace, and add the base
+        component, design tokens, translations and icons every component uses.
+
+          bin/rails generate velvetkit:install --namespace=Kit
+      DESC
+
+      class_option :namespace, type: :string, default: Namespace::CANONICAL,
+                               desc: "Module to put the components under"
+      class_option :skip_tests, type: :boolean, default: false, desc: "Don't copy the base component's test"
+      class_option :skip_packages, type: :boolean, default: false,
+                                   desc: "List the npm packages to add instead of installing them"
+      class_option :skip_ai, type: :boolean, default: false,
+                             desc: "Don't write docs/velvetkit.md and the pointers to it for AI agents"
+
+      def write_config
+        create_file CONFIG_FILE, <<~YAML
+          # VelvetKit — https://velvetkit.com
+          # `bin/rails generate velvetkit:add` puts components under this module.
+          namespace: #{kit_namespace.name}
+        YAML
+      end
+
+      def add_gems
+        gemfile = File.read(File.join(destination_root, "Gemfile"))
+        gem "view_component" unless gemfile.match?(/gem ["']view_component["']/)
+        gem "tailwind_merge" unless gemfile.match?(/gem ["']tailwind_merge["']/)
+      end
+
+      # Zeitwerk maps app/components/ui to Ui unless told UI is an acronym.
+      def add_inflection
+        return unless kit_namespace.acronym?
+
+        inflections = "config/initializers/inflections.rb"
+        rule = %(inflect.acronym "#{kit_namespace.name}")
+        block = <<~RUBY
+          ActiveSupport::Inflector.inflections(:en) do |inflect|
+            #{rule}
+          end
+        RUBY
+        return create_file(inflections, block) unless exists?(inflections)
+        return if read(inflections).include?(rule)
+
+        append_to_file inflections, "\n#{block}"
+      end
+
+      def copy_foundation
+        Registry::FOUNDATION.each { |file| copy_from_registry(file) }
+      end
+
+      # tailwindcss-rails and cssbundling-rails keep the entry point in
+      # different places; the tokens always live in app/assets/tailwind.
+      TAILWIND_ENTRIES = {
+        "app/assets/tailwind/application.css" => "./velvetkit.css",
+        "app/assets/stylesheets/application.tailwind.css" => "../tailwind/velvetkit.css"
+      }.freeze
+
+      def import_stylesheet
+        entry, path = TAILWIND_ENTRIES.find { |file, _| exists?(file) }
+        return say_status(:css, "import velvetkit.css from your Tailwind entry point", :yellow) unless entry
+        return if read(entry).include?("velvetkit.css")
+
+        inject_into_file entry, %(@import "#{path}";\n), after: /@import ["']tailwindcss["'];?\n/
+      end
+
+      def import_icons
+        entry = %w[app/javascript/application.js app/javascript/application.ts].find { |file| exists?(file) }
+        return say_status(:js, "import ./velvetkit_icons from your JavaScript entry point", :yellow) unless entry
+        return if read(entry).include?("velvetkit_icons")
+
+        append_to_file entry, %(import "./velvetkit_icons"\n)
+      end
+
+      def add_base_component
+        invoke "velvetkit:add", [ "base" ], namespace: kit_namespace.name, skip_tests: options[:skip_tests], skip_packages: true
+      end
+
+      def add_packages
+        install_packages(Registry::FOUNDATION_PACKAGES)
+      end
+
+      def write_ai_reference
+        invoke "velvetkit:ai", [], namespace: kit_namespace.name unless options[:skip_ai]
+      end
+
+      private
+
+      def exists?(file)
+        File.exist?(File.join(destination_root, file))
+      end
+
+      def read(file)
+        File.read(File.join(destination_root, file))
+      end
+    end
+  end
+end

data/lib/velvetkit/namespace.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string"
+require "active_support/core_ext/object/blank"
+
+module Velvetkit
+  # The Ruby module the components live under in the host app.
+  #
+  # The registry is written once, against `UI`. Every file is rewritten on the
+  # way into the host, so `Kit` turns `UI::Button` into `Kit::Button`,
+  # `app/components/ui/` into `app/components/kit/`, the `ui--dialog` Stimulus
+  # identifier into `kit--dialog`, and the `ui.` I18n scope into `kit.`.
+  class Namespace
+    CANONICAL = "UI"
+    FORMAT = /\A[A-Z][A-Za-z0-9]*\z/
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_s
+      return if FORMAT.match?(@name)
+
+      raise Error, "Namespace must be a single Ruby constant name like UI or Kit, got #{name.inspect}"
+    end
+
+    # True when Rails cannot get from the directory name back to the constant
+    # without an inflection: `ui`.camelize is `Ui`, not `UI`.
+    def acronym?
+      name.underscore.camelize != name
+    end
+
+    # Directory name and I18n scope: UI → ui, VelvetKit → velvet_kit.
+    def path
+      acronym? ? name.downcase : name.underscore
+    end
+
+    # Prefix for Stimulus identifiers and DOM ids: VelvetKit → velvet-kit.
+    def dom
+      path.dasherize
+    end
+
+    def rewrite_path(file)
+      file.gsub(%r{(?<=\A|/)ui(?=/)}, path)
+    end
+
+    def rewrite(source)
+      source
+        .gsub(/\bUI(?=::)/, name)                     # UI::Button
+        .gsub(/\bmodule UI\b/, "module #{name}")      # module UI; end
+        .gsub("ui--", "#{dom}--")                     # Stimulus identifiers
+        .gsub(/(?<=["'`])ui-(?=[a-z`])/, "#{dom}-")   # DOM ids, storage keys
+        .gsub(/(?<=["'`])ui\.(?=[a-z`])/, "#{path}.") # I18n keys
+        .gsub(/^(\s+)ui:$/, "\\1#{path}:")            # locale file scope
+        .gsub(%r{(?<=/)ui(?=/)}, path)                # controllers/ui/… paths
+    end
+  end
+end