Skip to content

theming-rubyui.md

Latest commit

 

History

History
80 lines (61 loc) · 3.63 KB

theming-rubyui.md

File metadata and controls

80 lines (61 loc) · 3.63 KB
Raw

Theming with RubyUI

The admin renders your host app's RubyUI (Phlex) components, so it inherits your app's RubyUI theme automatically — there's no separate admin theme to keep in sync.

How styling is delivered

The admin renders the same RubyUI::* components you generated into your app, which emit Tailwind utility classes. Styling comes from your app's Tailwind build — there is no admin-specific stylesheet. You must ensure your Tailwind content/sources cover:

  • app/components/ruby_ui/** (your RubyUI components), and
  • the admin's own views (the engine's app/components/ruby_ui_admin/**), so the classes used by the admin's layout/lists/forms are generated.

Then point the admin layout at your compiled CSS via config.head_assets (see JavaScript › head assets). Because the admin uses your RubyUI components, any RubyUI design tokens they rely on (e.g. success / warning colors) must be defined in your theme.

Design tokens

RubyUI components resolve colors through CSS variables (design tokens) defined in your app's RubyUI stylesheet — typically:

:root {
  --background: #ffffff;
  --foreground: #0a0a0a;
  --muted: #f4f4f5;       --muted-foreground: #71717a;
  --border: #e4e4e7;      --input: #e4e4e7;       --ring: #18181b;
  --primary: #18181b;     --primary-foreground: #fafafa;
  --secondary: #f4f4f5;   --secondary-foreground: #18181b;
  --accent: #f4f4f5;      --accent-foreground: #18181b;
  --destructive: #ef4444;
  --popover: #ffffff;     --popover-foreground: #0a0a0a;
  /* Sidebar (left navigation) */
  --sidebar: #fafafa;             --sidebar-foreground: #3f3f46;
  --sidebar-accent: #f4f4f5;      --sidebar-accent-foreground: #18181b;
  --sidebar-border: #e5e7eb;      --sidebar-ring: #3b82f6;
}

Utilities like bg-background, text-muted-foreground, border-border, bg-primary/90, bg-sidebar, text-sidebar-accent-foreground resolve through these variables, so re-theming is a matter of changing the token values. The --sidebar-* tokens style the left navigation independently from the page (so you can give it its own surface colour).

Dark mode

A .dark variant is included. Add the dark class to a parent element (e.g. <html>) to switch. The tokens above have dark overrides bundled.

Make sure your Tailwind build covers the admin

Because the admin renders with your app's RubyUI components and its own Phlex views, your Tailwind build's content/sources must include both, or admin pages will be missing styles:

  • app/components/ruby_ui/** — your RubyUI components, and
  • the admin's views — the engine's app/components/ruby_ui_admin/** (in the installed gem).

Rather than hardcode the gem's path in @source (it varies per environment), run bin/rails ruby_ui_admin:tailwind_source to extract the admin's class inventory into app/assets/tailwind/ruby_ui_admin_classes.html, @source that (commit it; re-run on upgrade), then expose the compiled stylesheet to the admin layout through config.head_assets.

Integrating with the host's own Tailwind build (advanced)

If you'd rather own the build (e.g. to override tokens app-wide or share your design system), point your host Tailwind v4 entry at the engine's components and define the tokens yourself:

@import "tailwindcss";
@source "./ruby_ui_admin_classes.html"; /* generated by rake ruby_ui_admin:tailwind_source */
/* define the :root tokens above (or reuse your existing RubyUI tokens) */

Then disable the bundled stylesheet by ejecting the layout, or simply let both load (the host build wins by load order). Apps that already use RubyUI (with the same token vocabulary) only need the @source line.