Moss is a CSS framework and design system that's built around style variables, which are design tokens and CSS custom properties with particular capabilities and conventions.

Moss can be used with any website and JS framework. It exports 🗎 one main stylesheet and a replaceable 🗎 theme stylesheet, and it also exports the underlying CSS data, types, and helpers for more complex usage.

See the docs and readme.

Details:

• plain CSS
• zero dependencies
• exports one main stylesheet that doubles as a reset with basic HTML tag styles
• exports a basic theme that can be replaced with your own
• also exports the underlying CSS data, helpers, and types, which can be used in many ways, including outputting an optimized utilities class file
• uses its own concept of style variables, a specialization of CSS custom properties and design tokens
  • variables are the main source of truth
  • each variable provides values to light and/or dark mode
  • includes optional utility and component classes that use the variables
• themes are groups of variables
• dark mode is a first-class concept in the system, not a theme, instead each theme can support light and/or dark color-schemes
• is agnostic to JS frameworks, for example usage see Themed in my Svelte UI library Fuz

The stylesheets:

• 🗎 @ryanatkn/moss/style.css - the main stylesheet and CSS reset
• 🗎 @ryanatkn/moss/theme.css - or bring your own
• 🗎 src/routes/moss.css - a generated reference implementation using Moss's helpers that includes only the utility classes your code uses, generated by Gro with 🗎 src/routes/moss.gen.css.ts using the Moss helpers in 🗎 @ryanatkn/moss/gen_moss_css.js. I can add a Vite plugin if there's demand.
• There are not yet tools for optimizing away unused variables, so style.css and theme.css have some bloat.

Moss is being made to support Zzz and my other projects that focus on end-users, so it'll grow relatively slowly as I encounter more usecases. It's hobby-ready but expect a lot of breaking changes. Feel free to take the code and ideas for your own purposes.

In the docs, you'll see I'm writing asides using "⚠️" with open questions and other discussion of uncertainties. Your input is appreciated in the GitHub issues and discussions, or find me on Bluesky. See 🗎 contributing.md for more 🌿

Moss supports both the browser's color-scheme and custom themes based on variables, which use CSS custom properties.

Moss works with any JS framework, but it provides only stylesheets, not integrations. This website uses my Svelte UI library Fuz to provide the UI below to control the Moss color scheme and themes.

Moss supports color-scheme with dark and light modes. To apply dark mode manually, add the dark class to the root html element.

The Fuz integration detects the default with prefers-color-scheme, and users can also set it directly with a component like this one:

The builtin themes support both dark and light color schemes. Custom themes may support one or both color schemes.

A theme is a simple JSON collection of variables that can be transformed into CSS that set custom properties. Each variable can have values for light and/or dark color schemes. In other words, "dark" isn't a theme, it's a mode that any theme can implement.

These docs are a work in progress, for now see 🗎 @ryanatkn/moss/theme.ts and 🗎 @ryanatkn/moss/themes.ts.

Style variables, or just "variables" in Moss, are CSS custom properties that can be grouped into a theme. Each variable can have values for light and/or dark color-schemes. They're design tokens with an API.

The goal of the variables system is to provide runtime theming that's efficient and ergnomic for both developers and end-users. Variables can be composed in multiple ways:

• by CSS classes, both utility and component
• by other variables, both in calculations and to add useful semantics (e.g. button_fill_hover defaults to fg_2 but can be themed independently)
• in JS like the Svelte components in Fuz

Variables also provide an interface that's generally secure for user-generated content, if you're into that kind of thing.

The result is a flexible system that aligns with modern CSS to deliver high-capability UX and DX with low overhead.

export interface Theme {
	name: string;
	variables: Style_Variable[];
}

export interface Style_Variable {
	name: string;
	light?: string;
	dark?: string;
	summary?: string;
}

Moss has three CSS files, two of which are required:

<!-- +layout.svelte -->
<script>
	import '@ryanatkn/moss/style.css'; // required
	import '@ryanatkn/moss/theme.css'; // required, can bring your own
	import '$routes/moss.css'; // optional, generated by `gen_moss_css`
	// ...
</script>

The moss.css file is created on demand with the utility classes that your code uses, if any. For now it requires Gro to generate it, but it isn't hard to make your own integration using the helpers 🗎 gen_moss_css.ts. I can add a Vite plugin if there's demand.

Moss supports utility classes that cost nothing until you opt-in. The main stylesheet and theme are required and build around CSS custom properties - utility classes offer an orthogonal API that some developers prefer some of the time. They leverage Moss's base frameworky parts, and are well-integrated with the other APIs and tools.

Moss exports 🗎 helpers to generate styles on demand based on class usage in your source files, so you can ship the minimal code needed. Some values are interpreted to efficiently support large value ranges, e.g. opacity_0 through opacity_100 and font_weight_1 to font_weight_1000.

$globals include inherit|initial|revert|revert_layer|unset.

Moss's 🗎 main stylesheet provides styles for the base HTML elements using the framework's variables, acting as a modern CSS reset with sensible defaults and integrated theming. It includes Moss-specific CSS classes - not utility classes in the strict sense - that provide common generic functionality.

.unstyled

<ul>
	<li>1</li>
	<li>2</li>
</ul>

• a
• b

<ul class="unstyled">
	<li>a</li>
	<li>b</li>
</ul>

• 1
• 2

The .unstyled class lets Moss provide solid default element styles with a simple and generic opt-out:

:where(:is(ul, ol, menu):not(.unstyled)) {
	padding-left: var(--space_xl4);
}

Respecting .unstyled isn't a straightforward choice in all cases. Help is appreciated to refine the internals. For example, should input respect it? Maybe? All styles or a subset?

Moss provides a palette of color and hue variables designed to support concise authoring in light and dark modes, as well as straightforward theming by both developers and end-users at runtime. The colors have more semantics than just plain values, so they automatically adapt to dark mode and custom themes, at the cost of having different values depending on color scheme and theme.

Adapting colors to dark mode

A color's subjective appearance depends on the context in which it's viewed, especially the surrounding colors and values. Moss's semantic colors are designed to work across color schemes, so each Moss color variable has two values, one for light and one for dark mode. The exceptions are the lightest (1) and darkest (9) variants, although this may change if it yields better results.

Custom themes

Instead of "blue" and "red", colors are named with letters like "a" and "b", so you can change the primary "a" from blue to any color in a theme without breaking the name-to-color correspondence everywhere. This also flexibly handles more colors and cases than using names like "primary", and although it takes some learning, it's a simple pattern to remember. ("primary" and its ilk require learning too!)

A downside of this approach is that changing a color like the primary "a" affects the many places it's used. Sometimes you may want to change the color of a specific element or state, not all the things. In those cases, use plain CSS and optionally Moss variables. Compared to most libraries, Moss provides fewer handles for granular color customizations, but the benefits include consistency, efficiency, DRY authoring, and ease of app-wide theming.

For performance reasons, Moss does not currently have an extensive set of variants, like specialized states for elements or color values like "blue". Each of the 7 hues has 9 HSL color values (e.g. hsl(120 55% 36%)) and 9 HSL component values (e.g. 120 55% 36%, useful to efficiently apply custom alpha), handling most cases, and the base colors can be customized with platform APIs like the color-mix CSS function.

Variants will be expanded when Moss includes a Vite plugin or other build tooling for optimization. A downside of removing unused styles is that they won't be available to your end-users at runtime. We'll probably end up with an interpreted language like Tailwind's just-in-time compiler.

Hue variables contain a single hue number. Each color variable combines a hue variable with hardcoded saturation and lightness values for light and dark modes.

Hue variables therefore provide a single source of truth that's easy to theme, but to achieve pleasing results, setting the hue alone is not always sufficient. Custom colors will often require you to set per-variable saturation and lightness values.

Hue variables are also useful to construct custom colors not covered by the color variables. For example, Moss's base stylesheet uses hue_a for the semi-transparent ::selection. (try selecting some text - same hue!)

Unlike the color variables, the hue variables are the same in both light and dark modes.

• hue_a

  NaN

  primary
• hue_b

  NaN

  success
• hue_c

  NaN

  error/danger
• hue_d

  NaN

  secondary/accent
• hue_e

  NaN

  tertiary/highlight
• hue_f

  NaN

  quaternary/muted
• hue_g

  NaN

  quinary/decorative
• hue_h

  NaN

  senary/caution
• hue_i

  NaN

  septenary/info
• hue_j

  NaN

  octonary/flourish

There are 9 variables per color, numbered 1 to 9, lightest to darkest. The 5th variable of each color is used as the base for things like buttons.

Note that these values differ between light and dark modes! See the discussion above for why.

These colors were eyeballed by a programmer, and will change :]

• color_a_1

  rgb()
• color_a_2

  rgb()
• color_a_3

  rgb()
• color_a_4

  rgb()
• color_a_5

  rgb()
• color_a_6

  rgb()
• color_a_7

  rgb()
• color_a_8

  rgb()
• color_a_9

  rgb()
• color_b_1

  rgb()
• color_b_2

  rgb()
• color_b_3

  rgb()
• color_b_4

  rgb()
• color_b_5

  rgb()
• color_b_6

  rgb()
• color_b_7

  rgb()
• color_b_8

  rgb()
• color_b_9

  rgb()
• color_c_1

  rgb()
• color_c_2

  rgb()
• color_c_3

  rgb()
• color_c_4

  rgb()
• color_c_5

  rgb()
• color_c_6

  rgb()
• color_c_7

  rgb()
• color_c_8

  rgb()
• color_c_9

  rgb()
• color_d_1

  rgb()
• color_d_2

  rgb()
• color_d_3

  rgb()
• color_d_4

  rgb()
• color_d_5

  rgb()
• color_d_6

  rgb()
• color_d_7

  rgb()
• color_d_8

  rgb()
• color_d_9

  rgb()
• color_e_1

  rgb()
• color_e_2

  rgb()
• color_e_3

  rgb()
• color_e_4

  rgb()
• color_e_5

  rgb()
• color_e_6

  rgb()
• color_e_7

  rgb()
• color_e_8

  rgb()
• color_e_9

  rgb()
• color_f_1

  rgb()
• color_f_2

  rgb()
• color_f_3

  rgb()
• color_f_4

  rgb()
• color_f_5

  rgb()
• color_f_6

  rgb()
• color_f_7

  rgb()
• color_f_8

  rgb()
• color_f_9

  rgb()
• color_g_1

  rgb()
• color_g_2

  rgb()
• color_g_3

  rgb()
• color_g_4

  rgb()
• color_g_5

  rgb()
• color_g_6

  rgb()
• color_g_7

  rgb()
• color_g_8

  rgb()
• color_g_9

  rgb()
• color_h_1

  rgb()
• color_h_2

  rgb()
• color_h_3

  rgb()
• color_h_4

  rgb()
• color_h_5

  rgb()
• color_h_6

  rgb()
• color_h_7

  rgb()
• color_h_8

  rgb()
• color_h_9

  rgb()
• color_i_1

  rgb()
• color_i_2

  rgb()
• color_i_3

  rgb()
• color_i_4

  rgb()
• color_i_5

  rgb()
• color_i_6

  rgb()
• color_i_7

  rgb()
• color_i_8

  rgb()
• color_i_9

  rgb()
• color_j_1

  rgb()
• color_j_2

  rgb()
• color_j_3

  rgb()
• color_j_4

  rgb()
• color_j_5

  rgb()
• color_j_6

  rgb()
• color_j_7

  rgb()
• color_j_8

  rgb()
• color_j_9

  rgb()

Buttons have a .selected state that can be used for various UI purposes, like showing a selected item in a menu or a styling button's aria-pressed state. Instead of having two distinct styles of buttons with outlined and filled variants, Moss makes outlined buttons the default, and selected buttons are filled. There's also the .deselectable modifier class for buttons that remain clickable when selected. Themes can customize this behavior.

<button>a button</button>

<button disabled>
	:|
</button>

<button class="plain">
	+
</button>

<button class="icon_button">
	+
</button>

<button class="plain icon_button">
	+
</button>

.selected variants

<button class="plain selected">
	+
</button>

<button class="icon_button selected">
	+
</button>

<button class="plain icon_button selected">
	+
</button>

.selected and .deselectable variants

<button class="plain selected deselectable">
	+
</button>

<button class="icon_button selected deselectable">
	+
</button>

<button class="plain icon_button selected deselectable">
	+
</button>

a link in a p

a link with .selected

code in a p

a pre is
  preformatted
					text

code in a pre
		 	is a
				 block

<header>header</header>

<footer>footer</footer>

<section>section</section>

• a
• b
• see

ul with .unstyled

• a
• b
• see

1. one
2. two
3. etc

ol with .unstyled

1. one
2. two
3. etc

menu with .unstyled

<table>
	<thead>
		<tr>
			<th>th</th>
			<th>th</th>
			<th>th</th>
		</tr>
	</thead>
	<tbody>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
	</tbody>
</table>

<table class="width_100">
	...
</table>

<form>
	<fieldset>
		<legend>
			a <Mdn_Link path="Web/HTML/Element/legend" />
		</legend>
		<label>
			<div class="title">
				username
			</div>
			<input
				bind:value={username}
				placeholder=">"
			/>
		</label>
		...
	</fieldset>
	...
</form>

h1

h2

h3

h4

h5

h6

paragraphs

paragraphs

paragraphs

p with some small text

p _sub p ^sup p

Font weight values can be any integer from 1 to 1000.

There are no variables for font-weight but there are utility classes.

Each border utility class has a corresponding outline variant using the same border variables (like outline_color_b, outline_width_4, and outline_style_solid), and there are also two special outline variables:

Interpreted utility classes, 0 to 100 (%).

Interpreted utility classes, 0 to 100 (%).

Moss is designed around two simplistic models of light, one for dark mode and one for light mode, mapping to the web platform's color-scheme. The goal is easy authoring with simple and consistent rules for arbitrary compositions and states. Each theme can choose to implement either light mode or dark mode or both.

Light mode's starting point is plain white documents (like paper) where we can think of UI construction as assembling elements that contrast against the white background, replacing some of the white blankness with darkened values/color/shape. In other words, we start with full lightness and subtract light to make visuals. Black shadows on the white background make natural sense, and white glows against a white background are invisible.

In contrast, dark mode's starting point is a lightless void where we add light. We add elements which emanate light. I think of videogames and virtual/augmented/actual reality. Black shadows are invisible against a black background, and white glows make natural sense against a black background.

This distinction leads to complication. For example, applying a black shadow to an element has a particular visual impact on the typical light mode page, but viewed in dark mode, it would disappear completely against a black background.

Moss provides APIs that simplify or hide this complexity. For example, the lighten and darken variables are the same in light and dark modes, but fg and bg are equivalent values that swap places in dark mode. Thus bg and fg are called color-scheme-aware, and lighten and darken are color-scheme-agnostic. (maybe you can think of better terminology? I like the word "adaptive" but idk) The colors docs elaborate more on this point and the shadows docs implement more of the idea.

Opacity is used to enable arbitrary stacking that visually inherits its context. Not all cases are properly handled yet, and some choices are made for performance reasons, like avoiding opacity on text. (assuming this is still a thing?)

Many styles are designed to stack, so things can appear in different contexts while retaining relative color value distinctiveness ("color value" as in darkness-lightness). Internally this uses simple transparency instead of complex selectors or other structure.

<div class="fg_1 p_sm">
	<div class="fg_1 p_sm">
		<div class="fg_1 p_sm">
			<div class="fg_1 p_sm">
				<div class="bg p_sm">
					...
				</div>
			</div>
		</div>
</div>

This adds some complexity and performance costs, and it's currently incomplete, but so far it feels like an elegant solution with many unfinished details, and I plan to continue integrating the idea in more places while considering alternative designs. However alpha transparency has multiple costs, so I'm trying to be mindful to not use alpha for text and other cases that are more performance-sensitive, but we may need to change this behavior for the base cases, or include performance themes.

Interpreted utility classes, 0 to 100 (%).

Shadows darken in light mode and lighten in dark mode.

Hightlights lighten in light mode and darken in dark mode.

Glows lighten in both light and dark mode.

Shrouds darken in both light and dark mode.

These are darker in light mode than in dark mode.