Configuration

Once you've installed Rails UI, you'll be prompted to configure some basic settings. Enter your app name, support email, choose a theme, and adjust brand colors. Pages that come with each theme along with its brand colors are installed by default.

The railsui.yml config file

When you install Rails UI, a railsui.yml file is added to your config directory. This file manages your configuration options and is automatically generated, but you can manually adjust it if needed.

General

Some general options all you to customize the display name of your app as well as add a support email. These primarily get used in email templates, pages, and some front-facing areas of a given template like a footer.

Access those in this manner:

Railsui.config.application_name
Railsui.config.support_email

Select a theme

In Rails UI, components and views (pre-designed UI) are theme-driven. Each theme includes a preview for you to get a feel for the design and layout.

Every theme comes with UI components, pre-designed views, mailers, and custom color schemes by default. You can customize these at any time since it's integrated inside your app.

Themes are based on real-world use cases and niches. We source most ideas from the SaaS (software as a service) space given that Ruby on Rails is a great framework to leverage for that use case.

We'll add more free and premium themes as time goes on to grow Rails UI into a larger library.

Changing themes

New in version 3 of Rails UI is the ability to change your theme. This is possible any time but does come with some caveats.

Here's what happens when you change your theme:

• Rails UI generated pages (app/views/rui) and images (app/assets/images/railsui) are replaced with the newly chosen theme's files.
  • Tip: To keep using any views in the app/views/rui directory or images in the app/assets/images/railsui directory, copy these files to a backup location or elsewhere in your app before making changes. For best results, consider pages as code snippets for your app and treat them as read-only.
• Your colors will be preserved.

  • Tip: Run rails railsui:colors to quickly see the default colors of your selected theme. If you want to see another theme's colors, run rails 'railsui:colors[theme_name]'.

• Your tailwind.config.js file will be scanned and optimized to use the new theme's Rails UI preset along with other necessary Rails UI configuration settings.

Configuring colors

A theme comes with two additional color palettes in addition to Tailwind CSS default colors.

We make use of a primary and secondary palette in addition to the Tailwind CSS default color library. This is handy because setting colors in one place makes any theme quickly adapt to your brand colors. There's no need to go find and replace Tailwind CSS utility classes.

At any time you can modify the primary and secondary color palettes using the color pickers in the configuration form. We recommend leveraging a tool to help with the different shades and tints you may need. Try this tool for help.

How do I use custom colors?

Much like Tailwind you can use both primary and secondary Rails UI colors using the 11-point shading classes. Each theme has a unique set of colors associated with it by default. Your components and Rails UI views will automatically update with your chosen colors. All default Tailwind colors are still accessible.

For example, to use the primary color use it's key name and shade variant:

• .html

<div class="bg-primary-500 rounded-sm p-1 text-white">Primary</div>

Do I need to use the default theme colors?

No, you can change colors at any time. In fact, we encourage it. For best results you'll need the 11-shade equivalent. There are online tools to aid with this.

If you change a theme your color palette will not change. There is another button "Reset to default colors for active theme" that will do just that if clicked. We don't change colors so it's easier to add your own custom colors and retain their state in your application.

What happens to my colors if I change themes?

The short answer is nothing. When installing Rails UI we pre-load the Hound theme's colors because it's the default theme. When you change themes you can either maintain the current color palette, add your custom color palatte, or click the button to reset to default colors for your currently active theme.

If you aren't sure of the color scheme you want to use yet I recommend resetting to the defaults for each theme until you dial that part in.

Is there a way to preview theme colors?

Yes. To view default theme colors, run:

• bash

# Lists colors for active theme
  bin/rails railsui:colors
  # List colors for specific theme. Pass the theme name.
  bin/rails 'railsui:colors[hound]'

  # Example output:
  # Colors for Hound theme:
  # ---
  # primary:
  #  '50': "#eef2ff"
  #  '100': "#e0e7ff"
  #  '200': "#c7d2fe"
  #  '300': "#a5b4fc"
  #  '400': "#818cf8"
  #  '500': "#6366f1"
  #  '600': "#4f46e5"
  #  '700': "#4338ca"
  #  '800': "#3730a3"
  #  '900': "#312e81"
  #  '950': "#1e1b4b"
  # secondary:
  #   '50': "#f8fafc"
  #   '100': "#f1f5f9"
  #   '200': "#e2e8f0"
  #   '300': "#cbd5e1"
  #   '400': "#94a3b8"
  #   '500': "#64748b"
  #   '600': "#475569"
  #   '700': "#334155"
  #   '800': "#1e293b"
  #   '900': "#0f172a"
  #   '950': "#020617"

Pages

Each theme includes 20+ views (we refer to as pages), with more added over time. There's a button to link out directly to the live page in your app.

Installing pages

When you install a theme, pages are automatically added to your project.

Copy any templates and partials you customize to other view directories to avoid losing changes when switching themes.

Customizing pages

Pages installed to app/views/rui/pages may be customized at any time. We recommend creating new views and pasting the code from these templates there to avoid being overwritten.