Theming Janela

Janela publishes the hooks; a theme supplies the taste. This page is the contract: the class names and custom properties the engine renders, which your own stylesheet or somebody else’s theme may target, and which will not change without an entry in UPGRADING.md (ADR 036).

Two stylesheets ship in the gem.

<%= stylesheet_link_tag "janela" %>   <%# the hooks, and enough style to be legible %>
<%= stylesheet_link_tag "vitral" %>   <%# optional: one theme, stained glass %>

janela.css is not a look. It is the grid, the pane’s own markup and enough base styling that a table does not run its label into its number. Everything decorative is a theme’s, and vitral is one theme rather than the theme.

The contract

Custom properties

Setting any of these moves everything that depends on it.

:root {
  --janela-space: 0.3rem;
  --janela-accent: #7c3aed;
}

The grid

A frame’s stored integers choose these. Nothing an analyst types reaches CSS as a length: the number selects a rule that is already written (ADR 016).

Below 40rem the grid collapses to one column. That is in the stylesheet rather than in the data, because a dashboard nobody can read on a phone is not a choice worth offering.

The pane

What janela_pane and janela_frame put in your own pages. These are the names a theme spends most of its time on.

The dark values that passed the palette check on a dark surface are #3987e5, #d95926, #199e70, #c98500, #d55181, #008300, #9085e9 and #e66767. janela.css ships no dark scheme (ADR 023), so a dark theme sets the eight properties to them.

A table pane renders a <caption> and a chart pane a <figcaption>, each its own accessible name; the chart’s canvas points to its figcaption with aria-labelledby rather than repeating the string in aria-label, so the two cannot drift apart (ADR 042).

Hiding a heading you already wrote

Put janela-own-headings on any ancestor and a table’s caption, a single value’s label and a chart’s title are hidden from sight while staying in the accessibility tree.

<div class="janela-own-headings">
  <h3>Revenue by status</h3>
  <%= janela_pane Order, :revenue, by: :status %>
</div>

Use it when your own markup already says what the pane is, so the text is not on screen twice. It hides rather than removes on purpose: a pane with no visible caption still needs its accessible name, so a screen reader lands on a grid of numbers with nothing to say what they measure. display: none would do that, which is why this rule ships here rather than being left for each host to write.

What is not the contract

janela.css also styles Janela’s own pages, the frame index and the editing forms: janela-page, janela-card, janela-button, janela-form, janela-field, janela-list, janela-crumb, janela-flash and the rest. They are plain class names that the engine’s own pages use, not scoped to janela-page, so they affect your pages only if your own markup uses the same names. Avoid them.

Those names may change in any release. They are the engine’s own chrome rather than an interface. Restyle them if you want Janela’s pages to match your application, and expect to revisit it after an upgrade; or point Janela.theme at a stylesheet of your own, below.

Writing a theme

A theme is any stylesheet, named once:

# config/initializers/janela.rb
Janela.theme = "midnight"

The name is resolved against your own asset paths, so midnight.css in your application works exactly as the gem’s own vitral does. A name that your asset pipeline cannot find raises when the page renders, rather than quietly rendering an unthemed one.

That setting links the theme into Janela’s own pages. Your pages load whatever your layout says, so if you want the same look around a pane you have embedded yourself, link the stylesheet there too. The asymmetry is deliberate: Janela is an isolated engine and does not write your layout (ADR 011).

A theme targets the contract above and nothing else. If it cannot be written that way, the contract is missing something, which is worth an issue rather than a workaround.

Vitral

The theme the gem ships. A vitral is a stained glass window: each pane holds one of five colours, dark leading runs between them, and the light comes from behind.

<%= stylesheet_link_tag "vitral" %>
<body class="vitral">

Nothing is repainted until that class is present, so linking the stylesheet can never be the thing that broke a page.

Its own public classes, so the page around a dashboard can be made of the same window: vitral-pane, vitral-panes, vitral-button, vitral-button-primary, vitral-lattice.

Retheme it from its custom properties rather than by forking it. The light is --vitral-light-cobalt, -teal, -amber, -rose, -violet; the glass is --vitral-pane-1 through -5; the leading is --vitral-came; and --vitral-ink, --vitral-muted, --vitral-ground, --vitral-radius, --vitral-shadow and --vitral-blur do what they say.

:root {
  --vitral-pane-1: rgba(120, 60, 200, 0.3);
  --vitral-came: #1b1b1b;
}

It works without JavaScript. Janela’s own pages load none (ADR 011), so the stained glass is CSS and the lattice that leans toward the pointer is a separate optional controller. Reduced motion, reduced transparency and increased contrast each fall back to a still, solid window, and so does a browser without backdrop-filter.

test/dummy has a live page at /vitral showing all of it against real panes.