keystone_ui-styles

Shared CSS for keystone_ui and keystone_ui-react: keystone's color variables, its light and dark mode, and the classes for buttons, panels and form fields.

Host apps do not install this gem directly. keystone_ui depends on it and brings it into the host's Tailwind build.

• Rails 7.0 or later
• tailwindcss-rails 4 or later

keystone_ui imports keystone_ui-styles into the host's Tailwind build through the keystone_source.css file it writes at boot. A host imports nothing for keystone_ui-styles itself.

A gem that needs the file directly can read its path from KeystoneUi::Styles.tailwind_file.

--color-accent-50 to --color-accent-950 default to Tailwind's blue, and --color-surface-50 to --color-surface-950 default to zinc. keystone_ui-colors overrides these variables on the page, and every class below reads them.

A page follows the operating system's setting. Setting data-theme on the html element overrides it:

<html data-theme="dark">   <!-- always dark -->
<html data-theme="light">  <!-- always light -->
<html data-theme="custom"> <!-- drawn from a background and a text colour -->
<html>                     <!-- follows the operating system -->

The dark: variant in the host's own Tailwind classes follows the same rule, and a custom page never takes it.

Dark mode applies on screens only. A dark page prints in its light colours, so a printed page or a PDF always has dark text on white paper.

On a custom page, white is --color-custom-background, and every gray-* and zinc-* shade is a blend of --color-custom-text into that background, from 3% at shade 50 to 100% at shade 950. They default to white and #18181b, and keystone_ui-colors sets them from the colours a user picks.

The classes below read these variables, so a host restyles every component that renders them by setting the variables in a plain :root rule in its own stylesheet. The defaults sit in Tailwind's base layer, so a :root rule outside any layer overrides them wherever it is imported.

| --ks-radius-pill | Progress bar, hero badge and swipe button corners | Fully rounded | | --ks-color-hover-border | Link card and feature card border on hover | Accent 500 at 50% | | --ks-color-tint, --ks-color-tint-border | Feature icon, hero badge, active tab and current table row background, and the hero badge border | Accent 500 at 10% and 20% | | --ks-color-border-subtle | Call to action, feature card, code, accordion and disclosure border | --color-surface-200 | | --ks-color-fill-muted | Call to action and code caption background | --color-surface-50 | | --ks-color-raised | Feature card background | --color-white | | --ks-color-text-display, --ks-color-text-display-muted | Marketing titles and values, and their subtitles | --color-surface-900, --color-surface-500 | | --ks-color-text-body | Accordion and disclosure body text | --color-surface-600 | | --ks-color-icon-soft | Disclosure icon | --color-surface-400 | | --ks-color-track, --ks-color-meter | Progress track, and the progress bar, funnel accent step and bucket fill | --color-surface-200, --color-accent-500 | | --ks-color-text-meter-label | Progress and funnel labels | --color-surface-700 | | --ks-color-funnel-accent, -sky, -violet, -amber, -rose | The five funnel step colours | The matching Tailwind 500 shade | | --ks-color-funnel-band, --ks-color-text-funnel-band | The joined funnel's band between steps and its percent | --color-surface-800, --color-white, and --color-surface-100, --color-surface-900 on a dark page | | --ks-color-chart-1 to --ks-color-chart-5 | The five chart series colours, for a chart to read | --color-accent-600, then teal, amber, violet and rose at Tailwind's 600 shade, and --color-accent-400, then the same four at Tailwind's 400 shade, on a dark page | | --ks-color-over-goal, --ks-color-over-goal-warning | Bucket fill over its goal | --color-green-500, --color-amber-500 | | --ks-color-table-head, --ks-color-table-body, --ks-color-divider | Table head and body background, and the line between rows | --color-gray-50, --color-white, --color-gray-200 | | --ks-shadow-surface-dark | Table shadow on a dark page | None | | --ks-color-code, --ks-color-text-code | Code block background and text | --color-surface-900, --color-surface-100 | | --ks-color-pipeline, --ks-color-pipeline-box, --ks-color-pipeline-border | Pipeline and box background, and their border | --color-surface-800, --color-surface-900, --color-surface-700 | | --ks-color-text-on-dark, --ks-color-pipeline-muted, --ks-color-pipeline-label, --ks-color-pipeline-amber | Pipeline title, subtitle, box label and amber count | --color-white, --color-surface-400, --color-surface-500, --color-amber-400 | | --ks-color-nav, --ks-color-nav-border | Bottom nav, desktop nav menu and sidebar background, and the bottom nav, nav menu, sidebar and open sidebar group border and the lines between their links | --base-bg-low, then --color-white; --base-border-tertiary, then --color-gray-200 | | --ks-color-nav-text, --ks-color-nav-text-hover | Bottom nav item and sidebar group label, and nav links on hover | --base-text-tertiary, then --color-gray-500; --base-text-secondary, then --color-gray-700 | | --ks-color-nav-link, --ks-color-nav-active, --ks-color-nav-indicator | Nav link and sidebar tab text, the current page's link or tab, and the underline under the current link on wide screens and the bar beside the current sidebar tab | --base-text, --text-primary and --border-primary, then --color-gray-900, --color-accent-600 and --color-accent-600 | | --ks-color-nav-menu-mobile, --ks-color-nav-hover | Nav menu background on small screens, a menu link on hover, and the current sidebar tab | --base-bg-base, then --color-white; --base-bg-hover, then --color-gray-50 | | --ks-shadow-menu | Desktop nav menu shadow | --shadow-md | | --ks-font-weight-normal | Mobile header subtitle weight | --font-weight-normal | | --ks-color-hover-soft | Settings link on hover | --color-gray-50 | | --ks-color-on-hover | Settings link and tab text on hover | --ks-color-text | | --ks-color-on-hover-muted | Menu option, menu move button and copy button text on hover | --ks-color-text-label | | --ks-color-focus | Input and checkbox focus border and ring | --color-accent-500, and --color-accent-400 on a dark page | | --ks-color-link-strong-hover | Section action and card link on hover | --color-accent-900, and --color-accent-300 on a dark page | | --ks-color-badge-neutral | Neutral badge background | --color-gray-100, and --color-zinc-700 on a dark page | | --ks-color-page, --ks-color-on-page | The html element background and text | transparent and CanvasText, the browser defaults, so a page keeps the colours it has, and the html element tells the browser the page's mode so those defaults turn dark on a dark page | Each colour variable in the table whose component changes on a dark page has a -dark partner, such as --ks-color-surface-dark, that it reads there.

The navigation colours read the --base-* variables keystone_ui's nav used before, when a host sets them, so a host that coloured its nav that way keeps its colours.

Many roles default to a base role, so setting the base role recolours all of them, and setting one of them on its own still overrides it:

The base roles draw from the surface scale, which keystone_ui-colors sets per account. The nav roles read the old --base-* variables first when a host sets them.

Alerts and badges read a shade scale per status instead: --ks-color-success-*, --ks-color-warning-*, --ks-color-danger-* and --ks-color-info-*, each with shades 50, 100, 300, 400, 600, 700, 800 and 900, and 500 for danger. They default to Tailwind's green, yellow and red, and to the accent scale for info. An alert uses shades 50 and 800, and 900 and 300 on a dark page. A badge uses 100 and 700, and 900 and 400 on a dark page.

:root {
  --ks-radius-control: 9999px;
  --ks-font-weight-strong: 500;
  --ks-color-accent: #6200ee;
  --ks-color-accent-dark: #bb86fc;
}

On small screens the page's main element is padded to clear the bottom nav, and a page inside Hotwire Native hides the bottom nav and drops that padding.

<button class="ks-button ks-button-primary ks-button-md">Save</button>

MIT