# RubyUI hands you components as source, and the docs app runs the local gem

> ruby_ui is a Ruby gem and a documentation site in one monorepo, where the components are designed to be copied and pasted into your own app rather than depended on as a versioned package. The two halves are wired together so that an edit under gem/lib/ruby_ui/ shows up in the running documentation app immediately, and the licence is MIT in gem/LICENSE.txt.

**ruby-ui/ruby_ui** — Ruby gem for RubyUI Components

- Repository: https://github.com/ruby-ui/ruby_ui
- Website: https://rubyui.com
- Stars: 1,036 · Forks: 69
- Language: Ruby
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/ruby-ui-ruby-ui

## Components you copy, not a gem you depend on

The project's own one line description is the most useful thing in the README: beautifully designed components that you can copy and paste into your apps, accessible, customizable, open source.

That copy and paste model is the defining decision, and it is worth being clear about what it means in practice. The gem is not a runtime dependency in the way a component library usually is. It is a source of components that you take into your repository and own from then on. Once the code is in your app, updating it is a merge you perform yourself.

The trade is the classic one, and it is a real trade rather than a slogan. A versioned component library gives you upgrades and a support commitment, and it also gives you the constraint of the library's release cycle and the risk of a breaking change arriving in your bundle. A copied component gives you the opposite: no upgrade path, and total freedom to change it.

For a Rails application whose components are going to diverge from the originals anyway, that is a reasonable bet. For a team that wants to receive fixes and improvements without asking, it is not.

The accessibility and customizability claims are part of the positioning, and the practical reading of the copy and paste model is that both are properties you inherit with the code. An accessible component that you then modify is still your responsibility to keep accessible, and the documentation site exists partly to show how each piece is meant to be used.

## Two sibling projects in one repository

The repository is a monorepo with two sibling projects, and the structure is given in the README.

```
ruby_ui/
├── gem/    # the ruby_ui gem (lib/, generators, tests, gemspec)
└── docs/   # the Rails app that powers https://rubyui.com
```

The gem/ directory is the ruby_ui gem itself, with the lib/ directory, generators, tests and the gemspec, and the README notes that gem build and gem release are run from that folder. The docs/ directory is the Rails 8 application that powers the documentation site, and it consumes the local gem through a path dependency of ../gem.

There is a quick links section, and it is short because the two projects are genuinely separate. To use the gem in your app, the README points at gem/README.md. The documentation site is at rubyui.com/docs/introduction, and contributions are described in CONTRIBUTING.md.

The layout table makes the split explicit. The gem/ path holds the ruby_ui gem, the docs/ path holds the Rails 8 app for the documentation site which consumes the local gem via path: "../gem", and .github/workflows/ci.yml is the unified CI.

For a reader deciding whether to depend on this, that distinction matters. The documentation site is a Rails application that happens to be the home of the components, and the components live in a gem that a Rails application can use. The website is not a hosted component service with a copy button, it is the project's own application, built on the code it is documenting.

## The docs app consumes the local gem, so changes appear at once

The sentence in the README that explains the whole development setup is this one: editing files under gem/lib/ruby_ui/ is reflected immediately when running the docs app, with no bundle update, no rebuild, and no PR coordination across two repos.

That is the payoff of the path dependency, and it is a bigger deal than it sounds. In a two repository setup, a change to a component means publishing a gem version, bumping the dependency in the documentation app, and waiting for the release to be available. The loop is measured in minutes and it breaks whenever someone forgets to publish.

Here the documentation app is pointed at the working copy, so what the docs app renders is the code in the repository as it stands. The feedback loop on a visual change is one page reload.

The consequence for the project is that the documentation site is a live test of the components, not a hand written description of them. Whatever the site shows is what the gem does, because it is running the gem. For a component library whose selling point is that it looks right, that is a useful property, and it is the reason the two projects live in one repository rather than two.

The same arrangement means the docs app cannot drift out of sync with the code, which is the usual failure mode of a separately maintained documentation site.

## CI runs the gem on two Ruby versions and builds a devcontainer

The CI description in the layout table is more specific than a usual badge, and it tells you what the project considers its support matrix.

The unified CI in .github/workflows/ci.yml runs the gem tests on Ruby 3.3 and 3.4, runs the Rails docs app tests, and has a docker-build job that publishes the docs devcontainer to ghcr.io.

Two Ruby versions in the matrix is a reasonable floor for a gem that is used inside applications, and testing on both is the part that matters. The docker build job is the less usual element. Rather than building the documentation site in CI and shipping it somewhere, this job publishes a devcontainer image to a container registry, which means the environment for working on the docs app is a versioned, pullable artefact instead of a README full of setup instructions.

That is a good fit for a project whose contributors are working on both halves of the repository. A new contributor can pull the image and be inside a working Rails app with the local gem already wired in, which removes the most common reason a setup fails.

The repository root also carries a .claude/ directory and a CLAUDE.md file, and a .vscode/ directory, which is consistent with a project that expects editor and agent tooling to be configured. The root also holds design/ and mcp/ directories, and the README does not explain what they contain, which is a genuine documentation gap rather than something the file answers.

## Two sets of commands, and the gem side runs standardrb

The Development section gives the two command sets, and the README is explicit that the two projects are independent for everyday work, so you pick the one you need.

For gem work.

```bash
# Gem work
cd gem
bundle install
bundle exec rake          # tests + standardrb
```

For documentation work.

```bash
# Docs work (consumes the local gem via path: "../gem")
cd docs
bundle install
pnpm install
bin/dev                   # http://localhost:3000
```

The details worth noticing are that the gem's default rake task runs the tests and standardrb together, so the linter is part of the default loop rather than a separate thing to remember, and that the docs app needs both bundler and pnpm, which is the usual combination for a Rails application that also has a JavaScript asset pipeline.

bin/dev serves on http://localhost:3000, which is the standard Rails development server port, and with the path dependency in place the components the site renders are the ones in your working copy.

The release path follows the same split. The gemspec, the lib directory, the generators and the tests are all under gem/, so publishing a gem release is a command run from that directory rather than from the repository root, and the CHANGELOG in the repository covers both projects.

## Conclusion

RubyUI fits a Rails team that wants designed components in its own codebase and is prepared to own the code it takes, rather than tracking a gem version for a component library. It is the wrong choice if you need components to be updated by a dependency bump, because the copy and paste model deliberately has no update path. Verify first that the licence in gem/LICENSE.txt is the one you want, since the repository root has no licence file, and read the gem/README.md, because the top level README is about the repository rather than about using the components.

## FAQ

### What is RubyUI and how do I use it?

It is a gem of accessible, customizable components that you copy and paste into your apps rather than depend on as a package. The top level README points to gem/README.md for how to use the gem in your own application, and the documentation site is at rubyui.com/docs/introduction.

### How is the ruby_ui repository organised?

It is a monorepo with two sibling projects: gem/, which holds the ruby_ui gem with its lib, generators, tests and gemspec, and docs/, which is the Rails 8 application that powers the documentation site and consumes the local gem through a path dependency of ../gem.

### What does the CI for RubyUI run?

The unified CI in .github/workflows/ci.yml runs the gem tests on Ruby 3.3 and 3.4, runs the Rails docs app tests, and has a docker-build job that publishes the docs devcontainer to ghcr.io.

### How do I run the RubyUI tests?

From the gem directory, run bundle install and then bundle exec rake, which runs the tests and standardrb together. For the documentation app, cd docs, run bundle install and pnpm install, and start it with bin/dev on http://localhost:3000.

### What licence is RubyUI released under?

MIT, with the licence file at gem/LICENSE.txt. The repository root does not carry a licence file of its own, so the gem directory is where the terms live, and the last push to the repository was on 2026-10-11 with the newest release being v1.6.0 from 2026-08-05.

## Sources

- [Issues](https://github.com/ruby-ui/ruby_ui/issues)
- [Project website](https://rubyui.com)
- [README](https://github.com/ruby-ui/ruby_ui/blob/main/README.md)
- [Releases](https://github.com/ruby-ui/ruby_ui/releases)
- [ruby-ui/ruby_ui on GitHub](https://github.com/ruby-ui/ruby_ui)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ruby-ui-ruby-ui