Kit de thèmes

A Vignettes theme sets colors, typography and sizes. This package provides what every theme shares: the semantic token contract, the Reveal.js patches, the slide skeleton, the media-layout grid, the spacing scale and the quicklink styles.

Install

pnpm add -D @vignettes/theme-kit sass

Use

// mytheme.scss
@use 'pkg:@vignettes/theme-kit';

:root {
  --accent: #e63946;
  --accent-soft: #fbdcdf;
  --accent-bg: #fef4f5;
  --surface: #ffffff;
  --surface-contrast: #1d1d1d;
  --on-contrast: #ffffff;
  --text-default: #1d1d1d;
  --text-title: #000000;
  --text-mention: #666666;
}

.reveal h1 { font-size: 3em; }

Compile it with Sass and its package importer, which resolves pkg::

import * as sass from 'sass'

const { css } = sass.compile('mytheme.scss', {
  importers: [new sass.NodePackageImporter()],
})

pkg: is Sass's own package syntax and needs Sass 1.71 or later. Inside a Vignettes application, pnpm build:themes does this for every theme it finds.

The token contract

Code that works under any theme reads these custom properties only. A theme sets them, and this package ships defaults so a theme that omits one still renders.

• --accent is the primary color, for links, dividers and accents.
• --accent-soft is a lighter accent, for hover tints.
• --accent-bg is a very light tint, for callout backgrounds.
• --accent-strong is the accent mixed with the title color, for text on --accent-soft or --accent-bg, derived from --accent by default.
• --accent-line is the accent mixed with the surface, for the outlines of a diagram: the cards, the subject regions and the edge labels, derived from --accent by default.
• --accent-on-contrast is the accent mixed with white, for a mark on --surface-contrast or on a dark code block, derived from --accent by default.
• --surface is the page background.
• --surface-contrast is the inverse surface, for dark blocks and code panels.
• --on-contrast is the text color on --surface-contrast.
• --text-default colors the body text, --text-title the headings and strong text, --text-mention the muted text (captions, small print).
• --border, --radius and --shadow give the outline, the corners and the elevation of a box drawn by a component.
• --code-min-size is the smallest size of a code block, in slide units, 0px by default.
• --text-step-1 to --text-step-4 are the type scale above the body text, in em of the text around, a ratio of 1.2 apart by default: the headings inside the body and the sizes of ::Highlight read them, so they follow a column that shrinks its text.
• --flow-space is the space inside a group of text of the body of a content slide: between a heading and its paragraph, two paragraphs, a paragraph and its list, two list items. --block-space is the space above and below a block other than text (columns, a diagram, an image, a ::Quote, a ::Highlight, code), --heading-space-before the space above a heading of the body. Each is in em of the element that carries the margin.
• --measure is the maximum line length of a paragraph or a list of the body of a content slide, 60ch by default.
• --code-surface and --code-surface-dark are the backgrounds of the code themes clair and nuit. By default they are the light and dark backgrounds of GitHub's code, #f6f8fa and #24292e, whatever the surface of the theme.

The kit derives three more tokens from the text intensities, at the root of the page: --on-surface-title, --on-surface-default and --on-surface-mention. A component that paints its own surface, such as a diagram card or a story frame, sets the text of that surface from them. A slide that changes its text colors, such as a dark section divider, leaves that surface with its dark text.

The card palette

color="green" on a node or a region of a diagram (@vignettes/schemas) reads three properties: --palette-green-text for the title and the icon of the node or the region, --palette-green-bg for the surface of a region and --palette-green-main for its outline. The kit defines blue, green, yellow, orange, brown, pink, purple and grey. A theme redefines these properties, and adds names of its own with the same three properties. A name the theme leaves undefined takes the accent tokens.

What it contains

_semantic-tokens.scss declares the contract above, _palette.scss the card palette. _reveal-patches.scss adapts Reveal.js defaults and bridges MDC's wrapper elements with display: contents. _slide-structure.scss is the flex skeleton of the three slide kinds the engine tags on each section: slide-h1 for a title slide, slide-h2 for a section divider, slide-h3 for a heading with body. It aligns the content of a slide vertically, as :layout{align} asks or by the default of the slide kind and of its layout, and reads two size tokens a theme sets on .reveal: --slide-heading-min-height, the height a content slide keeps for its heading, and --slide-body-padding-y, the space above and below its body. The rhythm tokens set the vertical margins of the blocks of the body of a content slide, and override the margins a theme or a component writes. _media-layouts.scss is the grid behind the media layouts. _spacing.scss and _quicklinks.scss cover the spacing scale and the in-deck navigation links.

The base skin

@use 'pkg:@vignettes/theme-kit/base';

Applies the nine color tokens to the page background, the text, the headings, the links, inline code, quotes, list markers and the navigation controls, with a system font. With the layout preset, a theme can consist of the tokens alone: examples/themes holds a dark theme and a brand theme written that way. A theme that draws these elements itself leaves the base skin out.

The layout preset

@use 'pkg:@vignettes/theme-kit/presets/layout';

Gives a theme the type scale and the spacing of the French state design system, and leaves the colors to the theme. Use it to keep those proportions under your own palette; @vignettes/theme-dsfr is the full theme.

Reference

docs/theme-system.md covers the theme manifest, the compilation, how a theme is discovered at runtime, and how slides nested under a section are tagged.

License

MIT