iron_admin 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +129 -1
  3. data/README.md +48 -1
  4. data/UPGRADING.md +495 -8
  5. data/app/assets/tailwind/iron_admin/engine.css +79 -4
  6. data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
  7. data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
  8. data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
  9. data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
  10. data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
  11. data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
  12. data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
  13. data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
  14. data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
  15. data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
  16. data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
  17. data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
  18. data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
  19. data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
  20. data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
  21. data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
  22. data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
  23. data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
  24. data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
  25. data/app/components/iron_admin/filters/bar_component.rb +56 -9
  26. data/app/components/iron_admin/filters/control_styles.rb +82 -0
  27. data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
  28. data/app/components/iron_admin/filters/date_range_component.rb +10 -6
  29. data/app/components/iron_admin/filters/search_component.html.haml +4 -4
  30. data/app/components/iron_admin/filters/search_component.rb +3 -5
  31. data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
  32. data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
  33. data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
  34. data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
  35. data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
  36. data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
  37. data/app/components/iron_admin/form/checkbox_component.rb +2 -3
  38. data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
  39. data/app/components/iron_admin/form/control_classes.rb +108 -0
  40. data/app/components/iron_admin/form/date_picker_component.rb +3 -7
  41. data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
  42. data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
  43. data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
  44. data/app/components/iron_admin/form/nested_form_component.rb +12 -2
  45. data/app/components/iron_admin/form/select_component.html.haml +1 -1
  46. data/app/components/iron_admin/form/select_component.rb +2 -16
  47. data/app/components/iron_admin/form/text_input_component.rb +1 -5
  48. data/app/components/iron_admin/form/textarea_component.rb +1 -5
  49. data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
  50. data/app/components/iron_admin/layout/flash_component.rb +4 -3
  51. data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
  52. data/app/components/iron_admin/layout/navbar_component.rb +29 -1
  53. data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
  54. data/app/components/iron_admin/layout/shell_component.rb +16 -3
  55. data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
  56. data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
  57. data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
  58. data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
  59. data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
  60. data/app/components/iron_admin/resources/actions_component.rb +34 -2
  61. data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
  62. data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
  63. data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
  64. data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
  65. data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
  66. data/app/components/iron_admin/resources/data_table_component.rb +34 -3
  67. data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
  68. data/app/components/iron_admin/resources/related_list_component.rb +26 -2
  69. data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
  70. data/app/components/iron_admin/resources/show_field_component.rb +10 -4
  71. data/app/components/iron_admin/resources/styles.rb +136 -0
  72. data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
  73. data/app/components/iron_admin/ui/alert_component.rb +27 -31
  74. data/app/components/iron_admin/ui/badge_component.rb +40 -20
  75. data/app/components/iron_admin/ui/button_component.rb +37 -11
  76. data/app/components/iron_admin/ui/card_component.rb +3 -3
  77. data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
  78. data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
  79. data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
  80. data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
  81. data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
  82. data/app/components/iron_admin/ui/modal_component.rb +6 -4
  83. data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
  84. data/app/components/iron_admin/ui/pagination_component.rb +26 -9
  85. data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
  86. data/app/components/iron_admin/ui/scopes_component.rb +44 -11
  87. data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
  88. data/app/controllers/iron_admin/application_controller.rb +58 -4
  89. data/app/controllers/iron_admin/audit_controller.rb +30 -6
  90. data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
  91. data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
  92. data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
  93. data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
  94. data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
  95. data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
  96. data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
  97. data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
  98. data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
  99. data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
  100. data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
  101. data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
  102. data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
  103. data/app/controllers/iron_admin/exports_controller.rb +2 -2
  104. data/app/controllers/iron_admin/imports_controller.rb +1 -1
  105. data/app/controllers/iron_admin/resources_controller.rb +48 -41
  106. data/app/controllers/iron_admin/search_controller.rb +1 -2
  107. data/app/controllers/iron_admin/themes_controller.rb +50 -0
  108. data/app/controllers/iron_admin/tools_controller.rb +58 -5
  109. data/app/helpers/iron_admin/action_form_helper.rb +19 -0
  110. data/app/helpers/iron_admin/application_helper.rb +93 -16
  111. data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
  112. data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
  113. data/app/helpers/iron_admin/field_display_helper.rb +88 -43
  114. data/app/helpers/iron_admin/related_records_helper.rb +51 -0
  115. data/app/helpers/iron_admin/theme_helper.rb +56 -46
  116. data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
  117. data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
  118. data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
  119. data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
  120. data/app/javascript/iron_admin/index.js +4 -0
  121. data/app/views/iron_admin/audit/index.html.haml +78 -81
  122. data/app/views/iron_admin/dashboard/index.html.haml +10 -9
  123. data/app/views/iron_admin/form/_action_field.html.haml +50 -0
  124. data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
  125. data/app/views/iron_admin/imports/new.html.haml +14 -13
  126. data/app/views/iron_admin/imports/preview.html.haml +24 -21
  127. data/app/views/iron_admin/resources/_form.html.haml +70 -68
  128. data/app/views/iron_admin/resources/action_form.html.haml +16 -59
  129. data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
  130. data/app/views/iron_admin/resources/edit.html.haml +3 -3
  131. data/app/views/iron_admin/resources/index.html.haml +87 -74
  132. data/app/views/iron_admin/resources/new.html.haml +2 -2
  133. data/app/views/iron_admin/resources/show.html.haml +53 -41
  134. data/app/views/iron_admin/search/index.html.haml +17 -9
  135. data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
  136. data/app/views/iron_admin/shared/error.html.haml +16 -12
  137. data/app/views/iron_admin/tools/action_form.html.haml +9 -55
  138. data/app/views/iron_admin/tools/show.html.haml +4 -5
  139. data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
  140. data/app/views/layouts/iron_admin/application.html.haml +4 -17
  141. data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
  142. data/config/importmap.rb +2 -0
  143. data/config/locales/en.yml +23 -0
  144. data/config/routes.rb +1 -0
  145. data/docs/FAQ.md +87 -37
  146. data/docs/README.md +8 -2
  147. data/docs/components/README.md +6 -2
  148. data/docs/components/dashboard-components.md +24 -35
  149. data/docs/components/filter-components.md +44 -92
  150. data/docs/components/form-components.md +16 -32
  151. data/docs/components/resource-components.md +46 -27
  152. data/docs/components/ui-components.md +44 -26
  153. data/docs/getting-started/installation.md +5 -1
  154. data/docs/getting-started/quick-start.md +36 -23
  155. data/docs/guides/authentication.md +182 -42
  156. data/docs/guides/components.md +97 -15
  157. data/docs/guides/custom-adapters.md +24 -4
  158. data/docs/guides/dashboard.md +68 -44
  159. data/docs/guides/export.md +24 -8
  160. data/docs/guides/extending.md +206 -51
  161. data/docs/guides/fields.md +229 -70
  162. data/docs/guides/imports.md +33 -18
  163. data/docs/guides/resources.md +333 -111
  164. data/docs/guides/theming.md +930 -58
  165. data/docs/guides/troubleshooting.md +7 -3
  166. data/docs/plugin-system-design.md +8 -7
  167. data/docs/reference/configuration.md +51 -16
  168. data/docs/reference/routes.md +1 -0
  169. data/docs/reference/theme-properties.md +101 -38
  170. data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
  171. data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
  172. data/lib/iron_admin/action_field.rb +11 -0
  173. data/lib/iron_admin/adapters/active_record.rb +95 -0
  174. data/lib/iron_admin/adapters/base.rb +107 -0
  175. data/lib/iron_admin/adapters/http/query.rb +21 -0
  176. data/lib/iron_admin/adapters/http.rb +84 -4
  177. data/lib/iron_admin/adapters/mongoid.rb +96 -2
  178. data/lib/iron_admin/audit_log.rb +64 -6
  179. data/lib/iron_admin/authentication_warning.rb +31 -0
  180. data/lib/iron_admin/concerns/filter_definable.rb +15 -1
  181. data/lib/iron_admin/concerns/nestable.rb +25 -0
  182. data/lib/iron_admin/concerns/scope_countable.rb +56 -0
  183. data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
  184. data/lib/iron_admin/configuration/components.rb +14 -3
  185. data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
  186. data/lib/iron_admin/configuration/theme.rb +292 -87
  187. data/lib/iron_admin/configuration.rb +340 -45
  188. data/lib/iron_admin/dashboard.rb +22 -38
  189. data/lib/iron_admin/engine.rb +16 -2
  190. data/lib/iron_admin/errors.rb +3 -0
  191. data/lib/iron_admin/field.rb +78 -17
  192. data/lib/iron_admin/field_inferrer.rb +61 -3
  193. data/lib/iron_admin/field_override_warning.rb +67 -0
  194. data/lib/iron_admin/import/import_preview.rb +56 -7
  195. data/lib/iron_admin/import/importer.rb +91 -14
  196. data/lib/iron_admin/import/tenant_precheck.rb +67 -0
  197. data/lib/iron_admin/plugin/registration.rb +64 -0
  198. data/lib/iron_admin/plugin_registry.rb +3 -2
  199. data/lib/iron_admin/policy.rb +22 -12
  200. data/lib/iron_admin/policy_coverage_warning.rb +46 -0
  201. data/lib/iron_admin/request_context.rb +18 -0
  202. data/lib/iron_admin/resource.rb +218 -77
  203. data/lib/iron_admin/resource_registry.rb +86 -13
  204. data/lib/iron_admin/scope_counts.rb +73 -0
  205. data/lib/iron_admin/tenant_scope.rb +30 -0
  206. data/lib/iron_admin/tool.rb +61 -12
  207. data/lib/iron_admin/tool_context.rb +10 -6
  208. data/lib/iron_admin/version.rb +1 -1
  209. data/lib/iron_admin.rb +29 -2
  210. metadata +37 -7
@@ -1,102 +1,974 @@
1
1
  # Theming
2
2
 
3
- IronAdmin provides a granular theme system with 40+ CSS class properties. All use Tailwind CSS classes.
3
+ Every admin page is drawn from a **theme**, an `IronAdmin::Configuration::Theme`. Its
4
+ properties hold Tailwind CSS classes, plus a few CSS colors for charts, a font stylesheet URL
5
+ and a color scheme. IronAdmin ships one theme, **Neutral**, and uses it by default. You can:
4
6
 
5
- ## Basic Configuration
7
+ - change the default theme's properties with `config.theme`,
8
+ - register more named themes with `config.register_theme`,
9
+ - choose which theme each request uses with `config.theme_resolver`. By default the resolver
10
+ reads a cookie that the theme switcher in the navbar sets.
11
+
12
+ ![The Meridian Magazine dashboard in four themes: Neutral, light with black buttons; Midnight, dark with a violet accent; Editorial, cream paper with black rules and serif headings; Brutalist, monospace with thick black borders, hard shadows and yellow accents](../site/assets/images/themes.png)
13
+
14
+ The [Meridian Magazine demo](https://github.com/rubylab-app/meridian_magazine) registers three
15
+ themes beside Neutral: Midnight, Editorial and Brutalist. Each is one `config.register_theme`
16
+ block, and the switcher in its navbar moves between the four.
17
+
18
+ Sections:
19
+
20
+ - [Neutral, the default look](#neutral-the-default-look)
21
+ - [Customizing the default theme](#customizing-the-default-theme)
22
+ - [Theme properties](#theme-properties)
23
+ - [Registering more themes](#registering-more-themes)
24
+ - [Themes from plugins](#themes-from-plugins)
25
+ - [Choosing the default theme](#choosing-the-default-theme)
26
+ - [Picking a theme per request](#picking-a-theme-per-request)
27
+ - [The theme switcher and its cookie](#the-theme-switcher-and-its-cookie)
28
+ - [Using the theme in your own components](#using-the-theme-in-your-own-components)
29
+ - [Fonts](#fonts)
30
+ - [Color scheme, dark themes and charts](#color-scheme-dark-themes-and-charts)
31
+ - [Badges, alerts and chips](#badges-alerts-and-chips)
32
+ - [Rich text](#rich-text)
33
+ - [Tailwind: literal classes and source scanning](#tailwind-literal-classes-and-source-scanning)
34
+ - [For contributors: the theme guards](#for-contributors-the-theme-guards)
35
+
36
+ ## Neutral, the default look
37
+
38
+ Neutral is a minimal light look in the style of current developer tools:
39
+
40
+ - a `zinc-50` page and sidebar, with a white navbar and white cards, panels and tables,
41
+ - 1px `zinc-200` borders on cards and panels, input outlines that keep 3:1 contrast
42
+ (`zinc-500` at 80%), 8px corners on cards and panels (`rounded-lg`), 6px corners on
43
+ buttons and inputs (`rounded-md`), and almost no shadow (`shadow-xs`),
44
+ - the [Inter](https://rsms.me/inter/) typeface, loaded from Google Fonts (see [Fonts](#fonts)),
45
+ - a black primary button and an indigo accent for links, focus outlines, the current sidebar
46
+ link and charts,
47
+ - compact tables: `px-4 py-2.5` cells, sentence-case headers, and tabular digits in number and
48
+ currency columns,
49
+ - tinted badges with a colored dot,
50
+ - 36px buttons and inputs, and a 56px navbar whose search box takes the focus on ⌘K (Ctrl K on
51
+ platforms other than Apple's), except in a rich text field, where the shortcut adds a link.
52
+
53
+ Neutral's text colors meet WCAG AA contrast on the backgrounds they are drawn on.
54
+
55
+ ## Customizing the default theme
56
+
57
+ `config.theme` yields the default theme. That is Neutral, unless you
58
+ [choose another default](#choosing-the-default-theme). The block can set any property, and
59
+ the properties you leave alone keep their Neutral values:
6
60
 
7
61
  ```ruby
62
+ # config/initializers/iron_admin.rb
8
63
  IronAdmin.configure do |config|
9
64
  config.theme do |t|
10
- t.btn_primary = "bg-blue-600 text-white hover:bg-blue-700"
11
- t.sidebar_bg = "bg-slate-900"
12
- t.link = "text-blue-600 hover:text-blue-800"
65
+ t.btn_primary = "bg-emerald-700 text-white hover:bg-emerald-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
66
+ t.link = "text-emerald-700 hover:text-emerald-600"
67
+ t.focus_ring = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-emerald-600"
68
+ t.input_focus = "focus:border-emerald-600 focus:ring-3 focus:ring-emerald-600/15"
13
69
  end
14
70
  end
15
71
  ```
16
72
 
17
- ## Full Theme Example (Rose/Slate)
73
+ `config.theme` also returns the theme, so `config.theme.link = "text-emerald-700"` works too.
74
+
75
+ An assignment replaces the whole value: the theme does not merge your classes with Neutral's.
76
+ When you change a property that has hover or focus states, write those classes as well.
77
+
78
+ ### Change whole groups
79
+
80
+ Properties work together. If you give the sidebar a dark background, change its text colors
81
+ too, or Neutral's dark text stays on your dark background:
18
82
 
19
83
  ```ruby
20
84
  config.theme do |t|
21
- t.btn_primary = "bg-rose-600 text-white hover:bg-rose-700 focus:ring-2 focus:ring-rose-500/20 focus:ring-offset-1"
22
- t.btn_secondary = "bg-white text-slate-700 border border-slate-300 hover:bg-slate-50 hover:border-slate-400"
23
- t.btn_danger = "bg-red-600 text-white hover:bg-red-700"
24
- t.btn_ghost = "bg-slate-100 text-slate-700 hover:bg-slate-200"
85
+ t.sidebar_bg = "bg-zinc-900"
86
+ t.sidebar_border = ""
87
+ t.sidebar_title = "text-white"
88
+ t.sidebar_link = "text-zinc-400"
89
+ t.sidebar_link_hover = "hover:bg-zinc-800 hover:text-white"
90
+ t.sidebar_link_active = "bg-zinc-800 text-white"
91
+ t.sidebar_group_label = "text-zinc-400"
92
+ end
93
+ ```
25
94
 
26
- t.link = "text-rose-600 hover:text-rose-800"
27
- t.link_muted = "text-slate-500 hover:text-slate-700"
95
+ ### The current page in the sidebar
28
96
 
29
- t.input_border = "border-slate-300 hover:border-slate-400"
30
- t.input_focus = "focus:border-rose-500 focus:ring-2 focus:ring-rose-500/20"
31
- t.checkbox_checked = "checked:border-rose-600 checked:bg-rose-600 focus:ring-2 focus:ring-rose-500/20"
97
+ The sidebar link for the current page gets `aria-current="page"` and the `sidebar_link_active`
98
+ classes **instead of** `sidebar_link` and `sidebar_link_hover`, so give it a text color as well
99
+ as a background. The link is `relative`, so `before:` utilities can draw a marker. Neutral
100
+ draws a white pill with a thin ring and a 2px indigo bar on its left edge.
32
101
 
33
- t.scope_active = "border-rose-600 text-rose-600"
34
- t.scope_inactive = "border-transparent text-slate-500 hover:text-slate-700 hover:border-slate-300"
102
+ - The **Dashboard** link is current on the dashboard only.
103
+ - A **resource** link is current on every page of that resource: index, show, new and edit
104
+ (including the form shown again after a failed save), imports and action forms.
105
+ - A **tool** link is current on the tool's page and its action forms.
106
+ - A custom **menu item** (for example from a plugin) is current when the request path is the
107
+ item's path. The query string, the fragment and a trailing slash are ignored. For an item
108
+ with an absolute URL, the scheme and host must match too.
35
109
 
36
- t.badge_count = "bg-rose-600 text-white"
110
+ `sidebar_link_hover` must use `hover:` variants (for example `hover:bg-zinc-800`). Without
111
+ them, every link looks like the current one.
37
112
 
38
- t.sidebar_bg = "bg-slate-950"
39
- t.sidebar_title = "text-white"
40
- t.sidebar_link = "text-slate-400"
41
- t.sidebar_link_hover = "hover:bg-slate-800 hover:text-white"
42
- t.sidebar_group_label = "text-slate-500"
113
+ ### Theme helpers in views
114
+
115
+ Templates of the engine, and views you override in `app/views/iron_admin/`, can call
116
+ `IronAdmin::ThemeHelper`. Its `t` returns the theme of the current request, and its `cp_`
117
+ helpers return ready-made class strings:
118
+
119
+ ```ruby
120
+ t.link # => "text-indigo-600 hover:text-indigo-700"
121
+ cp_btn_primary # => "inline-flex h-9 shrink-0 items-center … bg-zinc-900 text-white hover:bg-zinc-700 …"
122
+ cp_input_class # => "block w-full h-9 px-3 text-sm … border-zinc-500/80 hover:border-zinc-500 …"
123
+ cp_input_class(error: true) # input_error replaces input_border and input_focus
124
+ cp_card # => "bg-white border border-zinc-200 rounded-lg shadow-xs"
125
+ cp_sidebar_link # => "text-zinc-600 hover:bg-zinc-200/60 hover:text-zinc-900"
126
+ ```
127
+
128
+ The button and input helpers (`cp_btn_primary`, `cp_btn_secondary`, `cp_btn_danger`,
129
+ `cp_btn_ghost`, `cp_input_class`, `cp_select_class`, `cp_textarea_class`, `cp_checkbox_class`,
130
+ `cp_radio_class`, `cp_file_input_class`) return complete controls built by
131
+ `IronAdmin::Form::ControlClasses`: buttons, inputs and selects are 36px high, checkboxes and
132
+ radio buttons 16px.
133
+
134
+ ## Theme properties
135
+
136
+ A theme has 96 properties. Most hold Tailwind classes. The table lists each one with its
137
+ Neutral value and what it controls.
138
+
139
+ **What a property may hold.** A CSS property is set either by a template or by a theme
140
+ property, never both, because Tailwind v4 does not guarantee which of two conflicting utilities
141
+ wins. Templates own the layout, spacing, sizes and font sizes. Theme properties own colors,
142
+ backgrounds, border colors, border width (`border_width`), radius (`border_radius`,
143
+ `control_radius`, `checkbox_radius`), shadows, font families, text transform and letter
144
+ spacing. A few properties are complete recipes that also set a size, weight or padding:
145
+ `page_title`, `card_title`, `table_header_text`, `table_cell_padding`, `metric_label` and
146
+ `metric_value`. So:
147
+
148
+ - don't add padding, heights or font sizes to a color property such as `card_bg`. Two padding
149
+ classes on one element have no reliable winner;
150
+ - don't use Tailwind's `dark:` variant. It follows the visitor's operating system, not the
151
+ theme. Write a [dark theme](#registering-more-themes) with dark colors instead.
152
+
153
+ ### Buttons and links
154
+
155
+ | Property | Neutral value | Controls |
156
+ |----------|---------------|----------|
157
+ | `btn_primary` | `bg-zinc-900 text-white hover:bg-zinc-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500` | Primary buttons, such as form submit buttons and the filter panel's Apply: colors, hover and keyboard focus outline. Primary buttons don't get `focus_ring`, so keep `focus-visible:` classes in this value |
158
+ | `btn_secondary` | `bg-white text-zinc-900 border border-zinc-200 hover:bg-zinc-50 hover:border-zinc-300` | Secondary buttons, such as member and bulk actions and the Filters button: colors, border (width included) and hover |
159
+ | `btn_danger` | `bg-red-600 text-white hover:bg-red-700` | Destructive buttons, such as Delete |
160
+ | `btn_ghost` | `bg-transparent text-zinc-700 hover:bg-zinc-100 hover:text-zinc-900` | Ghost and icon buttons: the menu and close buttons, the theme switcher, modal close buttons. They get no `control_shadow` |
161
+ | `link` | `text-indigo-600 hover:text-indigo-700` | Links in tables and text, such as an index row's record link and "View all" |
162
+ | `link_muted` | `text-zinc-500 hover:text-zinc-900` | Secondary links, such as breadcrumbs and the filter panel's Clear link |
163
+
164
+ ### Forms and controls
165
+
166
+ | Property | Neutral value | Controls |
167
+ |----------|---------------|----------|
168
+ | `focus_ring` | `focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-500` | Keyboard focus outline of every interactive element except text inputs (which use `input_focus`) and primary buttons: secondary, danger and ghost buttons, sidebar links, scope tabs, pagination, dropdown and switcher items, list rows. Use `focus-visible:` variants |
169
+ | `input_border` | `border-zinc-500/80 hover:border-zinc-500` | Border color, with hover, of inputs, selects, textareas, the file input and the navbar search. An empty input shows nothing but this outline, so it keeps 3:1 contrast against `card_bg` (WCAG 1.4.11): zinc-500 at 80% is 3.3:1 on white, zinc-200 to zinc-400 are below 3:1 |
170
+ | `input_focus` | `focus:border-indigo-500 focus:ring-3 focus:ring-indigo-500/15` | Focus state of those controls: border color and ring |
171
+ | `input_error` | `border-red-500 focus:border-red-600 focus:ring-3 focus:ring-red-500/20` | Used **instead of** `input_border` and `input_focus` on a control whose value failed validation, so include the focus ring. Its border keeps 3:1 too: red-500 is 3.8:1 on white, red-400 2.9:1 |
172
+ | `placeholder_text` | `placeholder:text-zinc-500` | Placeholder color, with the `placeholder:` variant |
173
+ | `checkbox_checked` | `checked:border-indigo-600 checked:bg-indigo-600 focus:ring-3 focus:ring-indigo-500/15` | Checked checkboxes and radio buttons: border and background color, and their focus ring. The check mark and the dot are always white, in light and dark themes, so pick a checked background with at least 3:1 contrast against white (not zinc-50, 100 or 200 in a dark theme) |
174
+ | `checkbox_border` | `border-zinc-500` | Border color of unchecked checkboxes and radio buttons. It is all that shows an unchecked control, so it keeps 3:1 contrast against `card_bg` (WCAG 1.4.11): zinc-500 is 4.8:1 on white, zinc-300 and zinc-400 are below 3:1. They don't use `input_border`, whose hover color would cover the checked border |
175
+ | `checkbox_radius` | `rounded-sm` | Radius of checkboxes. Radio buttons are always round |
176
+ | `control_radius` | `rounded-md` | Radius of buttons, inputs, selects, dropdown and switcher items, sidebar links, pagination links, icon tiles and tooltips |
177
+ | `control_shadow` | `shadow-xs` | Shadow of inputs, selects, textareas, checkboxes, radio buttons and every button except ghost ones. Empty = none |
178
+ | `disabled_text` | `text-zinc-300` | Unavailable pagination links (Previous on the first page, Next on the last) |
179
+ | `rich_text_editor` | `border rounded-md border-zinc-500/80 hover:border-zinc-500 bg-white text-zinc-900 shadow-xs focus:border-indigo-500 focus:ring-3 focus:ring-indigo-500/15` | The rich text editor box (Action Text's `<trix-editor>`): border width and color, radius, background, text color, shadow and focus state, written as for an input. Neutral outlines it like its inputs. Empty = the look of Trix's own stylesheet (see [Rich text](#rich-text)) |
180
+ | `rich_text_toolbar` | `[&_.trix-button-group]:border-zinc-200! [&_.trix-button-group]:rounded-md! [&_.trix-button-group]:overflow-hidden! [&_.trix-button]:border-zinc-200! [&_.trix-button]:border-b-0! [&_.trix-button.trix-active]:bg-zinc-100! [&_.trix-dialog]:border! [&_.trix-dialog]:border-zinc-200! [&_.trix-dialog]:rounded-lg! [&_.trix-dialog]:shadow-lg! [&_.trix-input--dialog]:border-zinc-500/80! [&_.trix-input--dialog]:rounded-md!` | Classes of the box around the rich text toolbar and editor, which style the toolbar's buttons, groups and link dialog with descendant variants and the important modifier, such as `[&_.trix-button-group]:border-zinc-700!`. Empty = Trix's look (see [Rich text](#rich-text)) |
181
+
182
+ ### Scope tabs and counts
183
+
184
+ | Property | Neutral value | Controls |
185
+ |----------|---------------|----------|
186
+ | `scope_active` | `border-zinc-900 text-zinc-900` | The current scope tab: underline color and text color |
187
+ | `scope_inactive` | `border-transparent text-zinc-500 hover:text-zinc-900 hover:border-zinc-300` | The other scope tabs, with their hover |
188
+ | `badge_count` | `bg-zinc-100 text-zinc-700` | Count bubbles, such as the number of active filters on the Filters button |
189
+
190
+ ### Sidebar
191
+
192
+ | Property | Neutral value | Controls |
193
+ |----------|---------------|----------|
194
+ | `sidebar_bg` | `bg-zinc-50` | Sidebar background, also as the mobile drawer |
195
+ | `sidebar_border` | `lg:border-r border-zinc-200` | The edge between the sidebar and the page: side, width and color. With `lg:`, the mobile drawer has no border |
196
+ | `sidebar_title` | `text-zinc-900` | Text color of the sidebar, which the brand (`config.title`) uses |
197
+ | `sidebar_link` | `text-zinc-600` | Text color of the sidebar links |
198
+ | `sidebar_link_hover` | `hover:bg-zinc-200/60 hover:text-zinc-900` | Hover of the sidebar links (use `hover:` variants) |
199
+ | `sidebar_link_active` | `bg-white text-zinc-900 shadow-xs ring-1 ring-zinc-200 before:absolute before:left-0 before:inset-y-2 before:w-0.5 before:rounded-full before:bg-indigo-500` | The link of the current page, **instead of** `sidebar_link` and `sidebar_link_hover` (see [above](#the-current-page-in-the-sidebar)) |
200
+ | `sidebar_group_label` | `text-zinc-500` | Color of the group labels. Their case comes from `label_transform` |
201
+
202
+ ### Navbar
203
+
204
+ | Property | Neutral value | Controls |
205
+ |----------|---------------|----------|
206
+ | `navbar_bg` | `bg-white` | Navbar background |
207
+ | `navbar_border` | `border-zinc-200` | Color of the navbar's bottom border |
208
+ | `navbar_border_width` | `border-b` | Side and width of that border, such as `border-b-3` for a heavy rule |
209
+ | `navbar_search_bg` | `bg-zinc-50` | Background of the navbar search box |
210
+ | `navbar_search_focus_bg` | `focus:bg-white` | Its background while it has the focus |
211
+ | `navbar_text` | `text-zinc-600` | Navbar text, such as the current user's name |
212
+ | `kbd` | `border-zinc-200 bg-white text-zinc-500` | The ⌘K hint in the search box: border, background and text color |
213
+ | `skip_link` | `focus:bg-white focus:text-zinc-900 focus:ring-2 focus:ring-indigo-500` | The "Skip to content" link once it has the focus (use `focus:` variants) |
214
+
215
+ ### Tables
216
+
217
+ | Property | Neutral value | Controls |
218
+ |----------|---------------|----------|
219
+ | `table_header_bg` | `bg-zinc-50` | Background of the header row (also of the sticky actions column's header) |
220
+ | `table_header_text` | `text-xs font-medium text-zinc-500` | Header cells: size, weight and color. Their case comes from `label_transform` |
221
+ | `table_cell_padding` | `px-4 py-2.5` | Padding of header and body cells, which sets how dense tables are |
222
+ | `table_frame` | `""` | Extra classes for the panel a table scrolls in, such as a ring. Empty = none |
223
+ | `table_sticky_shadow` | `shadow-[-4px_0_6px_-4px_rgba(0,0,0,0.08)]` | Edge shadow of the sticky actions column of index tables (`config.sticky_actions_column`), cast by a box laid over each sticky cell (browsers do not paint a cell's own shadow in a table with collapsed borders). A hard shadow such as `shadow-[-1px_0_0_#000]` draws a rule. Empty = none |
224
+ | `table_row_hover` | `hover:bg-zinc-50` | Hover of table rows and of the dashboard's quick links and activity feed rows. These rows hold `muted_text`, which keeps AA contrast on it |
225
+ | `table_sticky_row_hover` | `""` | Background of the sticky actions cell while its row is hovered. Each index row is a `group/row`, so use `group-hover/row:` variants in the color of `table_row_hover`, such as `group-hover/row:bg-zinc-50`. Empty = the cell keeps `card_bg` |
226
+ | `table_border` | `divide-zinc-200` | Lines between table rows and between the items of divided lists (dashboard lists, key/value fields). Use `divide-*` classes |
227
+ | `table_head_border` | `""` | The line between a table's header row and its body, for example a black rule over hairline row lines. Use `divide-*` classes. Empty = `table_border` |
228
+
229
+ ### Cards and panels
230
+
231
+ | Property | Neutral value | Controls |
232
+ |----------|---------------|----------|
233
+ | `card_bg` | `bg-white` | Background of cards, panels, tables and inputs, and of floating surfaces while `popover_bg` is empty |
234
+ | `card_border` | `border-zinc-200` | Border color of those surfaces, and of the lines inside them (panel headers, the scope tab bar, modal sections) |
235
+ | `card_shadow` | `shadow-xs` | Shadow of cards and panels |
236
+ | `popover_shadow` | `shadow-lg` | Shadow of floating surfaces: dropdown menus, the filter panel, belongs-to autocomplete results, the theme switcher panel and modals. Empty = none |
237
+ | `popover_bg` | `""` | Background of those floating surfaces, such as a raised tone that sets them apart from the cards under them in a dark theme. Empty = `card_bg`, so a theme that changes `card_bg` keeps its popovers on it. Pick an `item_hover` that shows on it |
238
+ | `card_title` | `text-sm font-semibold text-zinc-900` | Titles (h2) of cards, panels, dashboard widgets and modals: size, weight and color |
239
+
240
+ ### Typography
241
+
242
+ | Property | Neutral value | Controls |
243
+ |----------|---------------|----------|
244
+ | `font_family` | `font-[family-name:Inter,ui-sans-serif,system-ui,sans-serif]` | Font family of every page (on `<body>`). Empty = the browser's default |
245
+ | `font_stylesheet_url` | `https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap` | Stylesheet that the layout links for the theme's fonts. `nil` = none (see [Fonts](#fonts)) |
246
+ | `heading_font` | `""` | Extra font family classes for page titles, card titles and the sidebar brand. Empty = `font_family` |
247
+ | `heading_weight` | `font-semibold` | Weight of the sidebar brand and of the `cp_heading` helper |
248
+ | `page_title` | `text-xl font-semibold tracking-tight text-zinc-900` | Page titles (h1): size, weight, tracking and color |
249
+ | `label_transform` | `""` | Case and letter spacing of small labels: sidebar group labels, table headers, metric labels and filter labels. Empty = as written. `uppercase tracking-wider` gives the 0.7 look |
250
+ | `field_label_transform` | `""` | Case and letter spacing of field labels: the labels of resource, nested record, import and action forms, and the field names on show pages. Empty = as written. Separate from `label_transform`, so the 0.7 look keeps sentence-case form labels |
251
+ | `body_text` | `text-zinc-900` | Main text color: the page, table cells, inputs, dropdown items |
252
+ | `muted_text` | `text-zinc-500` | Secondary text: hints, timestamps, record ids, empty states, pagination summaries |
253
+ | `label_text` | `text-zinc-700` | Form and filter labels |
254
+ | `error_text` | `text-red-600` | Validation messages, required marks, negative deltas, import rows with errors, and old values in the audit log |
255
+ | `success_text` | `text-emerald-700` | Positive deltas, the icon of a true boolean, and new values in the audit log |
256
+
257
+ ### Layout and surfaces
258
+
259
+ | Property | Neutral value | Controls |
260
+ |----------|---------------|----------|
261
+ | `main_bg` | `bg-zinc-50` | Page background (`<body>` and the main area) |
262
+ | `border_radius` | `rounded-lg` | Radius of cards, panels, alerts, dropdowns and modals. Buttons and inputs use `control_radius` |
263
+ | `border_width` | `border` | Width of the outline of cards, panels, popovers, modals, alerts, inputs, checkboxes and pagination links. One-sided dividers (panel headers, footers, table rows, scope tabs) keep their template width; `sidebar_border` and `btn_secondary` carry their own, and `navbar_border_width` sets the navbar's |
264
+ | `color_scheme` | `"light"` | `"light"` or `"dark"`: the CSS color scheme of the page (see [Color scheme](#color-scheme-dark-themes-and-charts)). Not a Tailwind class |
265
+ | `swatch` | `rounded-full bg-white ring-1 ring-inset ring-zinc-500/80` | This theme's 12px swatch in the theme switcher: its shape (Neutral's is a dot), fill and ring |
266
+ | `surface_muted` | `bg-zinc-50` | Secondary backgrounds: readonly and disabled inputs, nested form rows, file previews, the empty state icon, audit change details |
267
+ | `item_hover` | `hover:bg-zinc-100` | Hover of dropdown and switcher items, search result rows and pagination links (rows with `muted_text` use `table_row_hover`) |
268
+ | `item_active` | `bg-zinc-100` | The belongs-to autocomplete option that the arrow keys highlight |
269
+ | `icon_muted` | `text-zinc-400` | Decorative icons, such as the search icon, breadcrumb separators and the empty state icon |
270
+ | `overlay_bg` | `bg-zinc-900/40` | Backdrop behind modals and the mobile sidebar drawer |
271
+
272
+ ### Feedback: alerts, badges and other elements
273
+
274
+ | Property | Neutral value | Controls |
275
+ |----------|---------------|----------|
276
+ | `alert_palette` | Hash, see [below](#badges-alerts-and-chips) | Classes (background, border color, text color) of alerts by type: `:success`, `:error`, `:warning`, `:info`. Flash messages, form errors and the audit log's warning use it |
277
+ | `alert_shadow` | `""` | Shadow of those alerts, flash messages, form errors and the audit log's warning. Empty = none |
278
+ | `badge_palette` | Hash, see [below](#badges-alerts-and-chips) | Badge classes by color name: status badges, `:badge` fields, audit actions and activity feed icons |
279
+ | `badge_dot_palette` | Hash, see [below](#badges-alerts-and-chips) | Classes of the dot inside each badge, by color name. An empty Hash (`{}`) draws no dots |
280
+ | `badge_shape` | `rounded-md font-medium` | Radius and weight of badges, chips and count bubbles |
281
+ | `chip` | `bg-zinc-100 text-zinc-700 ring-1 ring-inset ring-zinc-200` | Chips: tags, has-and-belongs-to-many records on show pages, file names, boolean group values and the column names on import pages |
282
+ | `danger_item` | `text-red-600 hover:bg-red-50 hover:text-red-700` | Destructive dropdown items, with their hover |
283
+ | `tooltip` | `bg-zinc-900 text-white` | Tooltip background and text color |
284
+ | `code_block` | `bg-zinc-950 text-zinc-100` | Background and text color of `:code` and `:json` values |
285
+ | `code_font` | `font-mono` | Font family of code-like text: `:code` values, the inputs of `:code`, `:json`, `:key_value`, `:markdown` and `:color` fields, and the audit log's change details |
286
+ | `progress_track` | `bg-zinc-200` | Track of progress bars (`:progress` fields and dashboard progress widgets) |
287
+ | `pagination_active` | `bg-zinc-900 text-white border-zinc-900` | The current page in the pagination |
288
+
289
+ ### Dashboard
290
+
291
+ | Property | Neutral value | Controls |
292
+ |----------|---------------|----------|
293
+ | `metric_label` | `text-xs font-medium text-zinc-500` | Label of metric, stat and progress cards: size, weight and color. Its case comes from `label_transform` |
294
+ | `metric_value` | `text-2xl font-semibold tracking-tight tabular-nums text-zinc-900` | The figure of those cards: size, weight, tracking and color |
295
+ | `metric_icon` | `bg-zinc-100 text-zinc-500` | The tile behind a card's icon: background and icon color |
43
296
 
44
- t.navbar_bg = "bg-white"
45
- t.navbar_border = "border-slate-200"
46
- t.navbar_search_bg = "bg-slate-50"
297
+ ### Charts
47
298
 
48
- t.table_header_bg = "bg-slate-50"
49
- t.table_row_hover = "hover:bg-slate-50"
50
- t.table_border = "divide-slate-200"
299
+ These hold CSS colors and Chart.js values, not Tailwind classes, because Chart.js draws on a canvas.
51
300
 
52
- t.card_bg = "bg-white"
53
- t.card_border = "border-slate-200"
301
+ | Property | Neutral value | Controls |
302
+ |----------|---------------|----------|
303
+ | `chart_colors` | `#6366f1`, `#0d9488`, `#b446c3`, `#d07d34`, `#2584c0`, `#d43b51` (indigo, teal and muted fuchsia, amber, sky and rose) | Slice colors of the dashboard charts, in order (an Array). Bar charts fill every bar with the first one. Each Neutral color has 3:1 contrast or more on the white cards, which WCAG 1.4.11 asks of graphical objects, and Neutral's order keeps each color apart from the next, and the last from the first, for normal vision and the common color vision deficiencies |
304
+ | `chart_border_color` | `rgb(99, 102, 241)` | Line color of line, area and radar charts, and the fill of progress bars without a color of their own |
305
+ | `chart_grid_color` | `rgba(228, 228, 231, 1)` | Grid lines and axis lines |
306
+ | `chart_text_color` | `rgb(113, 113, 122)` | Tick labels, radar point labels and the legend |
307
+ | `chart_point_style` | `circle` | Shape of the legend markers, a Chart.js point style: `circle`, `rect`, `rectRounded`, `triangle` and so on |
308
+ | `chart_slice_border_color` | `#ffffff` | Outline of the slices of pie, doughnut and polar area charts (a CSS color). Neutral's is the white of its cards, so a gap sets each slice apart from the next; a theme with other cards sets their color. `nil` = each slice in its own color |
309
+ | `chart_border_width` | `nil` | Width in pixels (an Integer) of slice and bar outlines and of lines. Bars are outlined in `chart_border_color`. `nil` = the Chart.js defaults (no bar outline) |
54
310
 
55
- t.body_text = "text-slate-900"
56
- t.muted_text = "text-slate-500"
57
- t.label_text = "text-slate-700"
311
+ A theme also has a `name` (a Symbol, the value its cookie stores) and a `label` (the text in
312
+ the switcher), set when the theme is registered. `dark?` and `scheme_class` read `color_scheme`.
313
+
314
+ ## Registering more themes
315
+
316
+ `config.register_theme(name, label: name.to_s.titleize)` builds a new theme with the Neutral
317
+ values, yields it, and stores it under `name`:
318
+
319
+ - every theme starts from the **pristine** Neutral values. It doesn't matter whether you call
320
+ `register_theme` before or after `config.theme`; the changes `config.theme` makes to the
321
+ default theme never carry over;
322
+ - the label defaults to the titleized name (`:high_contrast` is "High Contrast");
323
+ - a Symbol, a String and any other case are the same name (`:Harbor` and `"harbor"`);
324
+ - registering a name the app already owns replaces that theme, and registering `:neutral`
325
+ replaces the built-in theme. A name a plugin owns raises `IronAdmin::PluginError` instead
326
+ (see [Themes from plugins](#themes-from-plugins));
327
+ - a blank name raises `ArgumentError`;
328
+ - the method returns the theme. The theme is stored only after the block returns.
329
+
330
+ Once two or more themes are registered, the navbar shows the
331
+ [theme switcher](#the-theme-switcher-and-its-cookie).
332
+
333
+ ### A complete dark theme
334
+
335
+ This theme sets every property that holds a color. The ones it leaves alone (fonts, radii,
336
+ `border_width`, `table_cell_padding`, `label_transform`, `badge_shape` and so on) keep their
337
+ Neutral values.
338
+
339
+ ```ruby
340
+ # config/initializers/iron_admin.rb
341
+ IronAdmin.configure do |config|
342
+ config.register_theme(:midnight, label: "Midnight") do |t|
343
+ t.color_scheme = "dark"
344
+ t.swatch = "rounded-full bg-zinc-900 ring-1 ring-inset ring-zinc-600"
345
+
346
+ # Page, sidebar and navbar
347
+ t.main_bg = "bg-zinc-950"
348
+ t.body_text = "text-zinc-100"
349
+ t.muted_text = "text-zinc-400"
350
+ t.label_text = "text-zinc-300"
351
+ t.page_title = "text-xl font-semibold tracking-tight text-zinc-50"
352
+ t.sidebar_bg = "bg-zinc-950"
353
+ t.sidebar_border = "lg:border-r border-zinc-800"
354
+ t.sidebar_title = "text-zinc-50"
355
+ t.sidebar_link = "text-zinc-400"
356
+ t.sidebar_link_hover = "hover:bg-zinc-800/60 hover:text-zinc-50"
357
+ t.sidebar_link_active = "bg-zinc-800 text-zinc-50 before:absolute before:left-0 before:inset-y-2 before:w-0.5 before:rounded-full before:bg-indigo-400"
358
+ t.sidebar_group_label = "text-zinc-400"
359
+ t.navbar_bg = "bg-zinc-950"
360
+ t.navbar_border = "border-zinc-800"
361
+ t.navbar_search_bg = "bg-zinc-900"
362
+ t.navbar_search_focus_bg = "focus:bg-zinc-900"
363
+ t.navbar_text = "text-zinc-400"
364
+ t.kbd = "border-zinc-700 bg-zinc-800 text-zinc-400"
365
+ t.skip_link = "focus:bg-zinc-900 focus:text-zinc-50 focus:ring-2 focus:ring-indigo-400"
366
+ t.overlay_bg = "bg-black/60"
367
+
368
+ # Buttons, links and focus
369
+ t.btn_primary = "bg-zinc-50 text-zinc-900 hover:bg-zinc-200 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-400"
370
+ t.btn_secondary = "bg-zinc-900 text-zinc-100 border border-zinc-700 hover:bg-zinc-800 hover:border-zinc-600"
371
+ t.btn_danger = "bg-red-600 text-white hover:bg-red-700"
372
+ t.btn_ghost = "bg-transparent text-zinc-300 hover:bg-zinc-800 hover:text-zinc-50"
373
+ t.link = "text-indigo-400 hover:text-indigo-300"
374
+ t.link_muted = "text-zinc-400 hover:text-zinc-50"
375
+ t.focus_ring = "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-400"
376
+
377
+ # Inputs
378
+ t.input_border = "border-zinc-500 hover:border-zinc-400" # 3.7:1 on the zinc-900 cards
379
+ t.input_focus = "focus:border-indigo-400 focus:ring-3 focus:ring-indigo-400/25"
380
+ t.input_error = "border-red-500 focus:border-red-400 focus:ring-3 focus:ring-red-400/25"
381
+ t.placeholder_text = "placeholder:text-zinc-400"
382
+ t.checkbox_checked = "checked:border-indigo-500 checked:bg-indigo-500 focus:ring-3 focus:ring-indigo-400/25"
383
+ t.checkbox_border = "border-zinc-500"
384
+ t.control_shadow = ""
385
+ t.disabled_text = "text-zinc-600"
386
+
387
+ # Scope tabs and counts
388
+ t.scope_active = "border-zinc-50 text-zinc-50"
389
+ t.scope_inactive = "border-transparent text-zinc-400 hover:text-zinc-50 hover:border-zinc-600"
390
+ t.badge_count = "bg-zinc-800 text-zinc-300"
391
+
392
+ # Cards, tables and surfaces
393
+ t.card_bg = "bg-zinc-900"
394
+ t.card_border = "border-zinc-800"
395
+ t.card_shadow = ""
396
+ t.popover_shadow = "shadow-xl shadow-black/40"
397
+ t.card_title = "text-sm font-semibold text-zinc-50"
398
+ t.table_header_bg = "bg-zinc-950"
399
+ t.table_header_text = "text-xs font-medium text-zinc-400"
400
+ t.table_row_hover = "hover:bg-zinc-800/50"
401
+ t.table_border = "divide-zinc-800"
402
+ t.table_sticky_shadow = "shadow-[-4px_0_6px_-4px_rgba(0,0,0,0.6)]"
403
+ t.surface_muted = "bg-zinc-950"
404
+ t.item_hover = "hover:bg-zinc-800"
405
+ t.item_active = "bg-zinc-800"
406
+ t.icon_muted = "text-zinc-500"
407
+
408
+ # Text in states
409
+ t.error_text = "text-red-400"
410
+ t.success_text = "text-emerald-400"
411
+
412
+ # Alerts, badges, chips and other elements
413
+ t.alert_palette = {
414
+ success: "bg-emerald-950/60 border-emerald-900 text-emerald-200",
415
+ error: "bg-red-950/60 border-red-900 text-red-200",
416
+ warning: "bg-amber-950/60 border-amber-900 text-amber-200",
417
+ info: "bg-blue-950/60 border-blue-900 text-blue-200",
418
+ }
419
+ t.badge_palette = {
420
+ green: "bg-emerald-400/10 text-emerald-300 ring-1 ring-inset ring-emerald-400/20",
421
+ red: "bg-red-400/10 text-red-300 ring-1 ring-inset ring-red-400/20",
422
+ yellow: "bg-amber-400/10 text-amber-300 ring-1 ring-inset ring-amber-400/20",
423
+ blue: "bg-blue-400/10 text-blue-300 ring-1 ring-inset ring-blue-400/30",
424
+ indigo: "bg-indigo-400/10 text-indigo-300 ring-1 ring-inset ring-indigo-400/30",
425
+ purple: "bg-purple-400/10 text-purple-300 ring-1 ring-inset ring-purple-400/30",
426
+ pink: "bg-pink-400/10 text-pink-300 ring-1 ring-inset ring-pink-400/20",
427
+ orange: "bg-orange-400/10 text-orange-300 ring-1 ring-inset ring-orange-400/20",
428
+ teal: "bg-teal-400/10 text-teal-300 ring-1 ring-inset ring-teal-400/20",
429
+ gray: "bg-zinc-400/10 text-zinc-300 ring-1 ring-inset ring-zinc-400/20",
430
+ }
431
+ t.badge_dot_palette = {
432
+ green: "bg-emerald-400", red: "bg-red-400", yellow: "bg-amber-400", blue: "bg-blue-400",
433
+ indigo: "bg-indigo-400", purple: "bg-purple-400", pink: "bg-pink-400", orange: "bg-orange-400",
434
+ teal: "bg-teal-400", gray: "bg-zinc-500",
435
+ }
436
+ t.chip = "bg-zinc-800 text-zinc-300 ring-1 ring-inset ring-zinc-700"
437
+ t.danger_item = "text-red-400 hover:bg-red-500/10 hover:text-red-300"
438
+ t.tooltip = "bg-zinc-100 text-zinc-900"
439
+ t.code_block = "bg-black text-zinc-100"
440
+ t.progress_track = "bg-zinc-800"
441
+ t.pagination_active = "bg-zinc-50 text-zinc-900 border-zinc-50"
442
+
443
+ # Dashboard and charts
444
+ t.metric_label = "text-xs font-medium text-zinc-400"
445
+ t.metric_value = "text-2xl font-semibold tracking-tight tabular-nums text-zinc-50"
446
+ t.metric_icon = "bg-zinc-800 text-zinc-400"
447
+ t.chart_colors = %w[
448
+ rgba(129,140,248,0.85) rgba(56,189,248,0.85) rgba(52,211,153,0.85)
449
+ rgba(251,191,36,0.85) rgba(251,113,133,0.85) rgba(167,139,250,0.85)
450
+ ]
451
+ t.chart_border_color = "rgb(129, 140, 248)"
452
+ t.chart_grid_color = "rgba(63, 63, 70, 1)"
453
+ t.chart_text_color = "rgb(161, 161, 170)"
454
+ # The gap between pie and doughnut slices, in the color of the cards (zinc-900)
455
+ t.chart_slice_border_color = "rgb(24, 24, 27)"
456
+ end
58
457
  end
59
458
  ```
60
459
 
61
- ## Theme Properties by Category
460
+ `color_scheme = "dark"` makes the browser draw scrollbars, date pickers and other native
461
+ controls in dark colors; see [Color scheme](#color-scheme-dark-themes-and-charts).
62
462
 
63
- See [Theme Properties Reference](../reference/theme-properties.md) for the complete list with defaults.
463
+ ## Themes from plugins
64
464
 
65
- ### Categories
465
+ A theme can ship as its own gem. Name the gem `iron_admin-theme-<name>`. A compound name keeps
466
+ an underscore inside that segment: `iron_admin-theme-high_contrast` loads
467
+ `iron_admin/theme/high_contrast`. The namespace `IronAdmin::Theme` is reserved for these gems.
468
+ The guide to writing a theme gem comes later. `admin.theme` belongs to the experimental plugin
469
+ API, which may change before 1.0. See the [plugin system design](../plugin-system-design.md).
66
470
 
67
- - **Buttons**: `btn_primary`, `btn_secondary`, `btn_danger`, `btn_ghost`
68
- - **Links**: `link`, `link_muted`
69
- - **Focus & Inputs**: `focus_ring`, `input_border`, `input_focus`, `checkbox_checked`
70
- - **Scopes/Tabs**: `scope_active`, `scope_inactive`
71
- - **Badge**: `badge_count`
72
- - **Sidebar**: `sidebar_bg`, `sidebar_title`, `sidebar_link`, `sidebar_link_hover`, `sidebar_group_label`
73
- - **Navbar**: `navbar_bg`, `navbar_border`, `navbar_search_bg`, `navbar_search_focus_bg`
74
- - **Table**: `table_header_bg`, `table_row_hover`, `table_border`
75
- - **Cards**: `card_bg`, `card_border`, `card_shadow`
76
- - **Typography**: `font_family`, `heading_weight`, `body_text`, `muted_text`, `label_text`
77
- - **Layout**: `border_radius`
471
+ A theme gem that ships CSS defines a `Rails::Engine` with `engine_name "iron_admin_theme_<name>"`
472
+ and ships `app/assets/tailwind/iron_admin_theme_<name>/engine.css`. `bin/rails tailwindcss:build`
473
+ writes `app/assets/builds/tailwind/iron_admin_theme_<name>.css` from that file.
78
474
 
79
- ## Theme Helpers in Views
475
+ Installing one:
80
476
 
81
- Theme values are accessible via helper methods prefixed with `cp_`:
477
+ 1. Add the gem (`gem "iron_admin-theme-high_contrast"`).
478
+ 2. Call `IronAdmin.register_plugin` with the plugin class
479
+ (`IronAdmin.register_plugin(IronAdmin::Theme::HighContrast)`).
480
+ 3. When the gem ships that `engine.css`, add
481
+ `@import "../builds/tailwind/iron_admin_theme_<name>";` to the app's Tailwind entry
482
+ (`app/assets/tailwind/application.css`), beside the engine's import. An import with no
483
+ bridge file makes `tailwindcss:build` fail, and `assets:precompile` with it.
484
+ 4. Run `bin/rails tailwindcss:build`.
485
+
486
+ Requiring the gem already runs its Ruby. Explicit activation is not a sandbox: trust a theme
487
+ gem the way you trust any other gem you install.
488
+
489
+ The plugin registers the theme with `admin.theme` in its `setup` block. That plugin owns the
490
+ name. `IronAdmin.register_plugin` activates the plugin at once, inside your initializer, so
491
+ whichever registration of the name runs second raises `IronAdmin::PluginError` at boot. The
492
+ message names the theme and both owners. Rename one theme, or remove one registration.
493
+
494
+ Activating the plugin again does not rebuild the theme. Adjust a value on the theme object
495
+ after `register_plugin`. Before that call the theme is not registered, so `find_theme` is `nil`:
82
496
 
83
497
  ```ruby
84
- cp_btn_primary # => "bg-indigo-600 text-white hover:bg-indigo-700 ..."
85
- cp_sidebar_bg # => "bg-gray-900"
86
- cp_card # => "bg-white"
87
- cp_link # => "text-indigo-600 hover:text-indigo-900"
498
+ IronAdmin.register_plugin(IronAdmin::Theme::HighContrast)
499
+ IronAdmin.configuration.find_theme(:high_contrast).btn_primary = "..."
88
500
  ```
89
501
 
90
- ## Badge Colors
502
+ Reloads in development keep that object, so the change stays. A change made in an initializer
503
+ is applied again on every boot. The plugin's own values only change after a restart.
504
+
505
+ ## Choosing the default theme
506
+
507
+ `config.default_theme` names the theme a request gets when the resolver names no registered
508
+ theme. It is `:neutral` unless you change it:
91
509
 
92
510
  ```ruby
93
511
  IronAdmin.configure do |config|
94
- config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"
512
+ config.register_theme(:midnight, label: "Midnight") { |t| ... }
513
+ config.default_theme = :midnight
95
514
  end
96
515
  ```
97
516
 
98
- Used with badge fields:
517
+ - `config.theme` yields and returns the theme that `default_theme` names **at the moment you
518
+ call it**. Set `default_theme` after registering that theme. Before the theme exists,
519
+ `config.theme` still configures Neutral.
520
+ - If `default_theme` names a theme that is not registered, Neutral is used.
521
+ - `config.themes` returns the registered themes as an ordered Hash (`{ name => theme }`),
522
+ the default theme first. The switcher lists them in that order.
523
+ - A blank name raises `ArgumentError`.
524
+
525
+ To change the look without offering a choice, customize the default theme with `config.theme`
526
+ and register nothing: with one theme, the navbar shows no switcher.
527
+
528
+ ## Picking a theme per request
529
+
530
+ Before every admin request, and before authentication (so error pages and login redirects
531
+ already use it), `IronAdmin::ApplicationController` calls the resolver and stores the theme it
532
+ names for the request. By default the resolver reads the `iron_admin_theme` cookie that the
533
+ switcher sets.
534
+
535
+ `config.theme_resolver` takes a block that receives the request (an
536
+ `ActionDispatch::Request`) and returns a theme name (a String, a Symbol or `nil`):
537
+
538
+ - a name that is not registered, a blank name and `nil` give the default theme;
539
+ - if the block raises, IronAdmin logs a warning (`[IronAdmin] theme_resolver raised …`) and
540
+ uses the default theme, so a failing resolver never breaks a page;
541
+ - the block runs on every admin request, so keep it cheap;
542
+ - the block gets no controller and no current user, because it runs before authentication.
543
+ Read what you need from the request: `request.cookies`, `request.cookie_jar`,
544
+ `request.session`, `request.env["warden"]`, `request.host`, `request.query_parameters`.
545
+
546
+ `config.theme_resolver` without a block returns the current resolver. The default one is
547
+ `IronAdmin::Configuration::DEFAULT_THEME_RESOLVER`.
548
+
549
+ ### A theme saved per user
550
+
551
+ Say your users have an `admin_theme` string column. With Devise (Warden), the resolver can
552
+ read the signed-in user:
99
553
 
100
554
  ```ruby
101
- field :status, type: :badge, colors: { active: :green, suspended: :red }
555
+ config.theme_resolver do |request|
556
+ # The switcher's cookie wins, so switching keeps working; the user's saved theme
557
+ # applies in a browser that has no cookie yet.
558
+ request.cookies[IronAdmin::Configuration::THEME_COOKIE].presence ||
559
+ request.env["warden"]&.user&.admin_theme
560
+ end
102
561
  ```
562
+
563
+ With a Devise scope other than the default one, pass it: `request.env["warden"]&.user(:admin)`.
564
+ Without Devise, look the user up from the session, for example
565
+ `User.find_by(id: request.session[:user_id])&.admin_theme`.
566
+
567
+ The switcher only sets the cookie; it doesn't save anything to your users. If the resolver
568
+ ignores the cookie, the switcher seems to do nothing. To save the choice to the user, render
569
+ your own switcher (see [below](#replacing-or-hiding-the-switcher)) that posts to your own
570
+ controller.
571
+
572
+ ### A theme from a query parameter
573
+
574
+ This resolver lets a link such as `/admin/users?theme=midnight` pick the theme, and saves it
575
+ in the cookie through `request.cookie_jar`, as the switcher does, so the next pages keep it:
576
+
577
+ ```ruby
578
+ config.theme_resolver do |request|
579
+ picked = IronAdmin.configuration.find_theme(request.query_parameters["theme"])
580
+ if picked
581
+ request.cookie_jar[IronAdmin::Configuration::THEME_COOKIE] = {
582
+ value: picked.name.to_s, expires: 1.year, httponly: true, same_site: :lax, secure: request.ssl?,
583
+ }
584
+ picked.name
585
+ else
586
+ request.cookies[IronAdmin::Configuration::THEME_COOKIE]
587
+ end
588
+ end
589
+ ```
590
+
591
+ `find_theme` returns `nil` for anything that is not a registered name, so only real theme
592
+ names reach the cookie. Rails writes the cookies set on `request.cookie_jar` to the response.
593
+ Because a GET request now changes the cookie, any link, including one on another site, can
594
+ switch a visitor's theme. That's harmless for a look, but don't decide anything sensitive this
595
+ way.
596
+
597
+ ## The theme switcher and its cookie
598
+
599
+ When two or more themes are registered, the navbar shows a swatch button (its accessible name
600
+ is "Theme: <label>"). It opens a menu with one button per theme: the theme's swatch and label,
601
+ a check mark and `aria-pressed="true"` on the current one.
602
+
603
+ - **Keyboard:** Tab reaches the button, Enter or Space opens it, Tab moves through the themes,
604
+ and Escape closes the menu and returns the focus to the button. A click outside closes it
605
+ too. The `cp-disclosure` Stimulus controller handles Escape and outside clicks.
606
+ - **Request:** each theme button submits a form, `POST /admin/theme` (`iron_admin.theme_path`)
607
+ with `theme` (the name) and `return_to` (the current path). A page that answers a POST, such
608
+ as an import preview or a form shown again with errors, may have no GET route, so there
609
+ `return_to` is the path of the page the browser came from when that is on this site, and
610
+ is left out otherwise (the switch then leads to the admin root). The form has the CSRF
611
+ token, and the endpoint is protected against forgery and authenticated like every admin
612
+ page. It has `data-turbo="false"`: the browser loads the next page in full, so the `<html>`
613
+ class, the fonts and the color scheme change with it.
614
+ - **Response:** for a registered name, the endpoint stores it in the cookie. Any other value
615
+ leaves the cookie as it is and sets the flash alert `iron_admin.theme_switcher.unknown`
616
+ ("That theme is not available."). It then redirects with `303 See Other` to `return_to` when
617
+ that is a path on this site (it starts with a single `/`, has no backslash, space or control
618
+ character, and has no scheme or host), and to the admin root otherwise.
619
+ - **Cookie:** `iron_admin_theme` (`IronAdmin::Configuration::THEME_COOKIE`). It holds the
620
+ theme's name in plain text and lasts one year, with `HttpOnly`, `SameSite=Lax`, and `Secure`
621
+ on HTTPS requests. Editing it can only pick another registered theme, because the resolver
622
+ ignores names that are not registered.
623
+ - **Translations:** `iron_admin.theme_switcher.button_label` ("Theme: %{theme}"),
624
+ `iron_admin.theme_switcher.menu_label` ("Themes") and `iron_admin.theme_switcher.unknown`.
625
+
626
+ The endpoint stores only the themes registered in configuration. A custom resolver can accept
627
+ other inputs, but the endpoint never does.
628
+
629
+ ### Replacing or hiding the switcher
630
+
631
+ The switcher fills the `theme_switcher` component slot (see
632
+ [Components](components.md#overriding-components)). The built-in navbar renders it only when
633
+ two or more themes are registered, with `themes:` (an Array of themes, default first),
634
+ `current_theme:` and `current_user:`.
635
+
636
+ To keep several themes but hide the switcher, for example when the resolver picks the theme
637
+ per tenant, use a component that renders nothing:
638
+
639
+ ```ruby
640
+ # app/components/no_theme_switcher_component.rb
641
+ class NoThemeSwitcherComponent < ViewComponent::Base
642
+ def render?
643
+ false
644
+ end
645
+
646
+ # ViewComponent needs a template or a call method, even for a component that never renders.
647
+ def call; end
648
+ end
649
+
650
+ # config/initializers/iron_admin.rb
651
+ config.components.theme_switcher = "NoThemeSwitcherComponent"
652
+ ```
653
+
654
+ A switcher of your own can post to `helpers.iron_admin.theme_path` with `theme` and
655
+ `return_to`, as the built-in one does, or to a controller of yours that also saves the choice.
656
+ A custom navbar (`config.components.navbar`) can render the slot with
657
+ `helpers.iron_admin_component(:theme_switcher, themes: IronAdmin.configuration.themes.values,
658
+ current_theme: IronAdmin.current_theme, current_user: @current_user)`.
659
+
660
+ ## Using the theme in your own components
661
+
662
+ `IronAdmin.current_theme` returns the theme of the current request. Outside a request, for
663
+ example in a component spec, a mailer or a background job, it returns the default theme. Read
664
+ it in every component, view or helper you add to the admin panel:
665
+
666
+ ```ruby
667
+ # app/components/admin_notice_component.rb
668
+ class AdminNoticeComponent < ViewComponent::Base
669
+ def initialize(message:)
670
+ @message = message
671
+ end
672
+
673
+ def call
674
+ tag.div(@message, class: "p-4 text-sm #{theme.card_bg} #{theme.border_width} #{theme.card_border} " \
675
+ "#{theme.border_radius} #{theme.card_shadow} #{theme.body_text}")
676
+ end
677
+
678
+ private
679
+
680
+ def theme
681
+ IronAdmin.current_theme
682
+ end
683
+ end
684
+ ```
685
+
686
+ Don't read `IronAdmin.configuration.theme` in components. It always returns the default
687
+ theme, so a component that uses it keeps the default look while the rest of the page shows
688
+ another theme.
689
+
690
+ The engine's own recipes are available too, so your controls can match the built-in ones:
691
+ `IronAdmin::Form::ControlClasses.button(theme, :secondary)` (`:primary`, `:secondary`,
692
+ `:danger` or `:ghost`), `.input(theme)`, `.select(theme)`, `.textarea(theme)` and
693
+ `.checkbox(theme)`. Each returns the classes of a complete control: 36px high, or 16px for a
694
+ checkbox.
695
+
696
+ ## Fonts
697
+
698
+ Four properties set the type:
699
+
700
+ - `font_family`: the font family class of every page, on `<body>`;
701
+ - `heading_font`: extra font family classes for page titles, card titles and the sidebar
702
+ brand. Leave it empty to use `font_family`;
703
+ - `code_font`: the font family of code-like text (code blocks, code, JSON and markdown
704
+ inputs, audit change details). Neutral uses Tailwind's `font-mono` stack;
705
+ - `font_stylesheet_url`: a stylesheet the layout links in `<head>` to load the fonts.
706
+
707
+ When `font_stylesheet_url` is present, the layout links it with `<link rel="stylesheet">`. When
708
+ it is on `fonts.googleapis.com`, the layout first adds `<link rel="preconnect">` tags for
709
+ `fonts.googleapis.com` and `fonts.gstatic.com`, so the browser opens those connections early.
710
+ Charts draw their text in the font of the card around them, and redraw once a web font has
711
+ loaded.
712
+
713
+ Neutral loads Inter from Google Fonts with `display=swap`. The browser shows text in a fallback
714
+ font right away and swaps in Inter once it arrives, so text is never invisible while the font
715
+ loads.
716
+
717
+ **Privacy.** With a Google Fonts URL, every page view makes the visitor's browser request
718
+ `fonts.googleapis.com` and `fonts.gstatic.com`, which sends Google the visitor's IP address and
719
+ user agent. In the EU, some courts and data protection authorities treat this as a transfer of
720
+ personal data that needs consent. If that applies to you, turn the request off or host the
721
+ font yourself.
722
+
723
+ **Content Security Policy.** If your app sends a CSP header, allow both hosts, or the browser
724
+ blocks the font and Inter never loads:
725
+
726
+ ```ruby
727
+ # config/initializers/content_security_policy.rb
728
+ Rails.application.configure do
729
+ config.content_security_policy do |policy|
730
+ policy.style_src :self, "https://fonts.googleapis.com"
731
+ policy.font_src :self, "https://fonts.gstatic.com"
732
+ # ... the rest of your policy
733
+ end
734
+ end
735
+ ```
736
+
737
+ **Turning the Google Fonts request off.** Set `font_stylesheet_url` to `nil`. Every
738
+ registered theme starts from Neutral and links Inter too, so do it for each theme. After the
739
+ last `register_theme`, one loop covers them all:
740
+
741
+ ```ruby
742
+ IronAdmin.configure do |config|
743
+ config.register_theme(:midnight) { |t| ... }
744
+
745
+ config.themes.each_value { |theme| theme.font_stylesheet_url = nil }
746
+ end
747
+ ```
748
+
749
+ Without the stylesheet, pages use Inter where it is installed on the visitor's computer, and
750
+ `ui-sans-serif` / `system-ui` (the operating system's font) elsewhere. For the system font
751
+ everywhere, also set `t.font_family = "font-sans"`, Tailwind's system stack.
752
+
753
+ **Hosting Inter yourself.** Put the font files and a stylesheet with their `@font-face` rules
754
+ in your app (for example `public/fonts/inter.css`), then point the theme at it:
755
+ `t.font_stylesheet_url = "/fonts/inter.css"`. The layout adds no preconnect tags for a URL
756
+ that is not on Google Fonts.
757
+
758
+ **Another font.** Use Tailwind's `font-[family-name:…]` arbitrary value and the font's
759
+ stylesheet:
760
+
761
+ ```ruby
762
+ config.theme do |t|
763
+ t.font_family = "font-[family-name:Geist,ui-sans-serif,system-ui,sans-serif]"
764
+ t.font_stylesheet_url = "https://fonts.googleapis.com/css2?family=Geist:wght@400..700&display=swap"
765
+ t.heading_font = "font-serif" # titles in the system serif
766
+ end
767
+ ```
768
+
769
+ ## Color scheme, dark themes and charts
770
+
771
+ `color_scheme` is `"light"` or `"dark"`. It is not a Tailwind class. The layout turns it into:
772
+
773
+ - a `scheme-light` or `scheme-dark` class on `<html>`, which sets the CSS `color-scheme`, so
774
+ the browser draws scrollbars, date and time pickers, select menus and autofill in light or
775
+ dark colors;
776
+ - a `<meta name="color-scheme" content="light">` (or `"dark"`) tag;
777
+ - a lighter chevron in selects under `scheme-dark` (drawn by the engine's stylesheet). The
778
+ check mark and the radio dot stay white under `scheme-dark`.
779
+
780
+ `color_scheme` doesn't recolor anything else: a dark theme sets dark classes in its properties,
781
+ as the [Midnight example](#a-complete-dark-theme) does. Charts don't read `color_scheme`
782
+ either. Chart.js draws on a canvas, so the chart properties hold CSS colors (hex, `rgb()` or
783
+ `rgba()`) and a dark theme sets all five:
784
+
785
+ - `chart_colors`: the slices of pie, doughnut and polar area charts, in order. A bar chart's
786
+ bars are one series, so it fills them all with the first color;
787
+ - `chart_border_color`: the line of line, area and radar charts, whose fill is the same color
788
+ at 10% opacity. It also fills progress bars that have no color of their own;
789
+ - `chart_grid_color`: grid and axis lines;
790
+ - `chart_text_color`: tick labels, radar point labels and the legend;
791
+ - `chart_slice_border_color`: the outline of every slice. Neutral's is white, the color of its
792
+ cards, which draws a gap between neighboring slices; a dark theme sets its own card color
793
+ (or another outline, such as black), or white gaps show on its dark cards.
794
+
795
+ Two more chart properties shape the marks: `chart_point_style` (the legend markers) and
796
+ `chart_border_width` (the outline width of slices and bars, and the width of lines).
797
+
798
+ A chart's own colors win over the theme: `chart :revenue, type: :bar, colors: ["#0ea5e9"]` in
799
+ a dashboard (or `colors:` on `ChartComponent`) replaces `chart_colors`, and its first color
800
+ replaces `chart_border_color`. A bar chart given its own colors fills its bars with them one by
801
+ one. A dashboard `progress` widget's `color:` is a CSS color, and a
802
+ `:progress` field's `color:` option is a Tailwind class such as `bg-emerald-600`. Both replace
803
+ `chart_border_color` for that bar.
804
+
805
+ ## Badges, alerts and chips
806
+
807
+ Badges take their classes from three properties:
808
+
809
+ - `badge_palette`: a Hash from color name to classes. Neutral has `:green`, `:red`, `:yellow`,
810
+ `:blue`, `:indigo`, `:purple`, `:pink`, `:orange`, `:teal` and `:gray`; an unknown color
811
+ uses `:gray`;
812
+ - `badge_dot_palette`: a Hash from the same names to the classes of a 6px dot before the text.
813
+ An empty Hash (`{}`) draws badges without dots;
814
+ - `badge_shape`: the radius and weight of every badge.
815
+
816
+ | Color | Neutral `badge_palette` | Neutral `badge_dot_palette` |
817
+ |-------|-------------------------|-----------------------------|
818
+ | `:green` | `bg-emerald-50 text-emerald-700 ring-1 ring-inset ring-emerald-600/20` | `bg-emerald-500` |
819
+ | `:red` | `bg-red-50 text-red-700 ring-1 ring-inset ring-red-600/10` | `bg-red-500` |
820
+ | `:yellow` | `bg-amber-50 text-amber-800 ring-1 ring-inset ring-amber-600/20` | `bg-amber-500` |
821
+ | `:blue` | `bg-blue-50 text-blue-700 ring-1 ring-inset ring-blue-700/10` | `bg-blue-500` |
822
+ | `:indigo` | `bg-indigo-50 text-indigo-700 ring-1 ring-inset ring-indigo-700/10` | `bg-indigo-500` |
823
+ | `:purple` | `bg-purple-50 text-purple-700 ring-1 ring-inset ring-purple-700/10` | `bg-purple-500` |
824
+ | `:pink` | `bg-pink-50 text-pink-700 ring-1 ring-inset ring-pink-700/10` | `bg-pink-500` |
825
+ | `:orange` | `bg-orange-50 text-orange-800 ring-1 ring-inset ring-orange-600/20` | `bg-orange-500` |
826
+ | `:teal` | `bg-teal-50 text-teal-700 ring-1 ring-inset ring-teal-600/20` | `bg-teal-500` |
827
+ | `:gray` | `bg-zinc-50 text-zinc-600 ring-1 ring-inset ring-zinc-500/10` | `bg-zinc-400` |
828
+
829
+ The palettes are plain Hashes, and each theme has its own copy, so you can add a color to one
830
+ theme:
831
+
832
+ ```ruby
833
+ config.theme do |t|
834
+ t.badge_palette[:cyan] = "bg-cyan-50 text-cyan-700 ring-1 ring-inset ring-cyan-600/20"
835
+ t.badge_dot_palette[:cyan] = "bg-cyan-500"
836
+ end
837
+ ```
838
+
839
+ **`config.badge_colors`.** This Hash decides which color a value gets: it maps status values
840
+ such as `"active"` to color names such as `"green"` (see
841
+ [Badge Colors](fields.md#badge-colors) for the defaults). A field's own `colors:` option wins
842
+ over it. An entry keyed by a color name Symbol with classes as its value
843
+ (`config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"`) sets the classes of that color in
844
+ **every** theme, and those badges have no dot. That keeps the look of apps that set such
845
+ classes before 0.8. For a color that changes with the theme, set the theme's `badge_palette`
846
+ instead. Add entries with `[]=` or `merge!`: assigning a new Hash to `config.badge_colors`
847
+ replaces the default status mapping.
848
+
849
+ **Alerts.** `alert_palette` holds the background, border color and text color of each alert
850
+ type. Flash messages, the form's base errors and the audit log's warning use it. An unknown
851
+ type uses the `:info` entry:
852
+
853
+ | Type | Neutral `alert_palette` |
854
+ |------|-------------------------|
855
+ | `:success` | `bg-emerald-50 border-emerald-200 text-emerald-800` |
856
+ | `:error` | `bg-red-50 border-red-200 text-red-800` |
857
+ | `:warning` | `bg-amber-50 border-amber-200 text-amber-800` |
858
+ | `:info` | `bg-blue-50 border-blue-200 text-blue-800` |
859
+
860
+ **Chips.** Tags, has-and-belongs-to-many records on show pages, file names, boolean group
861
+ values and the column names on import pages use `chip` with `badge_shape`. The activity feed tints its icons from `badge_palette`
862
+ (an item's `icon_color` is one of its color names).
863
+
864
+ ## Rich text
865
+
866
+ `:rich_text` fields use Action Text's Trix editor, and the layout links Trix's stylesheet
867
+ (`trix.css`). That stylesheet is not in a cascade layer, so its rules win over every Tailwind
868
+ utility, whatever their order. Two properties restyle it, and Neutral sets both: its editor is
869
+ outlined like its inputs, and its toolbar groups take its borders and radii. Set them to `""`
870
+ for Trix's own look.
871
+
872
+ - `rich_text_editor` holds the classes of the editor box, written as for an input, for
873
+ example `border border-zinc-700 rounded-md bg-zinc-900 text-zinc-100 focus:border-violet-500
874
+ focus:ring-3 focus:ring-violet-500/30`. Include a border width class: once the property is
875
+ set, the engine's stylesheet hands Trix's border and radius over to these classes.
876
+ - `rich_text_toolbar` holds classes of the box around the toolbar and the editor. Trix builds
877
+ the toolbar in JavaScript, so style its parts through descendant variants, and end each class
878
+ with Tailwind's important modifier `!`, which lets it win over Trix's stylesheet:
879
+
880
+ ```ruby
881
+ t.rich_text_toolbar = "[&_.trix-button-group]:border-zinc-700! [&_.trix-button]:border-zinc-700! " \
882
+ "[&_.trix-button.trix-active]:bg-violet-500/20! [&_.trix-dialog]:bg-zinc-800! " \
883
+ "[&_.trix-input--dialog]:bg-zinc-900! [&_.trix-input--dialog]:border-zinc-600!"
884
+ ```
885
+
886
+ The parts are `.trix-button-group` (a group of buttons, with a border and radius),
887
+ `.trix-button` (a button; its left border separates it from the previous one),
888
+ `.trix-button.trix-active` (a pressed button), `.trix-dialog` (the link dialog) and
889
+ `.trix-input--dialog` (its URL field). Parts the theme leaves alone keep Trix's look.
890
+
891
+ The toolbar icons are black images. Under `color_scheme = "dark"` the engine's stylesheet
892
+ inverts them, so they show on a dark background.
893
+
894
+ Whatever the theme, the field's template and the engine's stylesheet own the rest: the editor's
895
+ text is `text-sm`, like the other inputs; the editor takes its accessible name from the field's
896
+ label (`aria-labelledby`, since a `<label for>` cannot name a `<trix-editor>`); and the box
897
+ around the toolbar carries a `cp-rich-text-field` mark, which makes the toolbar's button groups
898
+ wrap onto more rows on a narrow screen instead of scrolling out of reach.
899
+
900
+ ## Tailwind: literal classes and source scanning
901
+
902
+ IronAdmin ships no compiled CSS. Your app's Tailwind v4 build (tailwindcss-rails) generates
903
+ every class it finds in the files it scans. The engine's own templates and the Neutral values in
904
+ `lib/` are scanned through the `iron_admin` bridge file (see
905
+ [Installation](../getting-started/installation.md)). **The classes in your themes live in your
906
+ app, so your build must scan the file that defines them.**
907
+
908
+ Tailwind detects sources automatically from the directory the build runs in, and skips files
909
+ that `.gitignore` lists. `bin/rails tailwindcss:build` and `bin/dev` run from the app's root, so
910
+ a theme in `config/initializers/iron_admin.rb` is usually found without any setup. Name the file
911
+ explicitly when your CSS turns automatic detection off (`@import "tailwindcss" source(none);`),
912
+ when the file is ignored by Git, or just to be safe:
913
+
914
+ ```css
915
+ /* app/assets/tailwind/application.css */
916
+ @import "tailwindcss";
917
+ @import "../builds/tailwind/iron_admin";
918
+ @source "../../../config/initializers/iron_admin.rb";
919
+ ```
920
+
921
+ Paths in `@source` are relative to the CSS file. After you change a theme, rebuild the CSS
922
+ (`bin/rails tailwindcss:build`), or keep `bin/rails tailwindcss:watch` running. If you commit
923
+ `app/assets/builds/tailwind.css`, commit the rebuilt file too.
924
+
925
+ **Write every class as a complete literal.** Tailwind reads your source files as text: it never
926
+ runs Ruby. A class built by interpolation, such as `"bg-#{color}-600"`, never appears in the
927
+ text, so Tailwind generates no CSS for it and the element is unstyled. Write each class in full.
928
+ A Hash from names to full class strings is fine, and so is a long value split into several
929
+ string literals at a space between classes. Don't split one class, and in particular an
930
+ arbitrary value such as `shadow-[0_1px_2px_rgba(0,0,0,0.05)]`, across two string literals or
931
+ lines.
932
+
933
+ **Tables and tab rows that scroll sideways fade at the edge.** The engine stylesheet's
934
+ `cp-scroll-fade` class masks a frame whose content is wider than it: the frame fades out toward
935
+ each edge it can still scroll to, driven by a CSS scroll timeline, so a frame that fits, or a
936
+ browser without scroll timelines, shows no fade. The mask works on any theme's colors and lifts
937
+ while the frame or a control in it has the keyboard focus. Put the border of a scrolling table
938
+ on a box around the masked one, as `Resources::Styles.table_panel` and
939
+ `Resources::Styles::SCROLL_FRAME` do, or the fade takes the border with it.
940
+
941
+ **Use Tailwind v4 utilities.** Utilities that v4 removed, such as `bg-opacity-50` (use
942
+ `bg-black/50`) and `flex-grow` (use `grow`), generate nothing, and some names changed size:
943
+ v4's `shadow-xs` is v3's `shadow-sm`, and v4's `shadow-sm` is v3's `shadow`. Variants such as `hover:`, `focus:`, `focus-visible:`, `before:`, `lg:` and
944
+ `placeholder:` work in every property.
945
+
946
+ ## For contributors: the theme guards
947
+
948
+ Every color the panel draws belongs to the theme, so a registered theme can restyle all of it.
949
+ Several specs keep it that way:
950
+
951
+ - `spec/iron_admin/theme_hardcoded_colors_spec.rb` scans every `app/**/*.{haml,erb,rb,js}` file.
952
+ It fails on any Tailwind color utility (`bg`, `text`, `border`, `divide`, `ring`, `outline`,
953
+ `placeholder`, `fill`, `stroke`, `from`, `via`, `to`, `shadow`, `decoration`, `accent`,
954
+ `caret`, with any variants) that uses a palette color, `white` or `black`, or an arbitrary
955
+ color value such as `bg-[#fafafa]`. It also fails on inline `style` declarations, SVG
956
+ attributes and JavaScript style assignments that hard-code a color. `text-current`,
957
+ `bg-transparent`, `border-transparent`, `fill-current`, `stroke-current` and `inherit` are
958
+ allowed, and so are styles built from theme values or record data. Each failure names the
959
+ file, the line and the class. Take the color from a theme property instead. Colors belong in
960
+ the Neutral values (`lib/iron_admin/configuration/theme/neutral_defaults.rb`), which the guard
961
+ doesn't scan.
962
+ - `spec/iron_admin/engine_theme_reads_spec.rb` fails when `app/` or `lib/` reads
963
+ `IronAdmin.configuration.theme`. Read `IronAdmin.current_theme` (or `t` in views).
964
+ - `spec/iron_admin/engine_tailwind_classes_spec.rb` fails on utilities Tailwind v4 removed, on
965
+ an important modifier placed before the variants, on fractional values in the HAML class
966
+ shorthand (`.gap-1.5` renders the classes `gap-1` and `5`; write
967
+ `class: "gap-1.5"`), and on arbitrary values split across string literals.
968
+ - `spec/lib/iron_admin/configuration/theme_spec.rb` checks every Neutral value and fails when a
969
+ property is not set in `Theme#initialize`, so copies and registered themes always carry it.
970
+
971
+ To add a property: add an `attr_accessor` with YARD to its group in `theme.rb`, set its Neutral
972
+ value in the matching `init_*_defaults` method of `theme/neutral_defaults.rb`, add it to the
973
+ Neutral catalog in `theme_spec.rb`, add a row to the tables in this guide, and add a CHANGELOG
974
+ entry.