Skip to content

custom-stylesheets.md

Latest commit

 

History

History
50 lines (32 loc) · 2.5 KB

custom-stylesheets.md

File metadata and controls

50 lines (32 loc) · 2.5 KB
Raw

Custom stylesheets

Hive can apply a shareable CSS theme from a public GitHub repository. The feature is available on three public/read-only surfaces:

Surface Example
ClankeR leaderboard /contribute/leaderboard?style=owner/repo/path/to/theme.css@ref
Spoke dashboard /?style=owner/repo/path/to/theme.css@ref
Snapshot preview /snapshot?style=owner/repo/path/to/theme.css@ref

The @ref suffix is optional and defaults to HEAD. Use the owner/repo/path.css triplet form, not a raw URL.

Token-based themes

For dashboard theme work, prefer token overrides from the dashboard design system over selector-level restyling. The #8536 contract is live: a portable dashboard theme is a small CSS file or preset token map that sets only documented canonical :root tokens, with an optional light-mode block. Deprecated legacy variables are still accepted and aliased for existing themes, but arbitrary selectors remain part of the custom stylesheet escape hatch rather than the stable design-system API.

Fetching and scoping

Hive fetches public GitHub raw content server-side without credentials, limits the response to 128 KiB, sanitizes it, then serves the sanitized stylesheet from same-origin endpoints. Dashboard and snapshot CSS is scoped to #hive-dashboard-root; leaderboard CSS is scoped to #tab-leaderboard. Login and setup overlays remain outside the dashboard theme surface.

Sanitizer rules

Allowed CSS includes normal declarations, custom properties (--name and var(--name)), attribute and pseudo selectors, gradients, calc() / clamp(), modern color functions, and recursive @media, @supports, @container, and @keyframes rules. @font-face is retained only when every src URL is same-origin, relative, or data:.

Hive removes @import, external or protocol-relative url() fetches, CSS escape sequences, image-set(), and legacy executable CSS vectors such as expression(), behavior, and -moz-binding.

When anything is removed, the response includes X-Hive-Style-Dropped: N. Add report=1 to /api/style or /api/leaderboard/style to get JSON containing the sanitized CSS and a short list of drop reasons.

Example

:root {
  --hive-accent: #f59e0b;
}

.card, .panel {
  border-color: var(--hive-accent);
}

@media (prefers-color-scheme: dark) {
  .metric-value { color: color-mix(in srgb, var(--hive-accent), white 20%); }
}

Share it as:

/snapshot?style=your-org/your-theme/hive.css@main