Skip to content

Stylesheet Targets

Jump to bottom
Danielle Foré edited this page Oct 27, 2025 · 9 revisions

This is a summary of the design targets and goals for Granite. When adding new styles, they should meet these goals to form a cohesive and predictable whole.

Widgets that behave similarly should look similarly. Widgets that behave differently should look differently.

Levels Theory

Widget backgrounds are styled according to "level" or "elevation". Elements gets darker the further away they are in interaction hierarchy. For example, buttons and entries are lightest and containers like sidebars are darkest. Widgets in dark style should follow this same progression from lightest in front to darkest in back, and not simply be inverted.

Padding, Margins, and Border Radii

The base grid unit should be 3px. Sometimes widgets with borders will be "off by one" to align visually.

Border radii should increase as they nest where reasonable. For example button radii is 3px to nest neatly into 6px radii windows, popovers, and OSDs. To faciliate this we have defined $window_radius and other radii should divide this variable

States & Pseudo Classes

Active

Interactive widgets must respond to activation

Clicked widgets like buttons and list items should press in and spring back up along the Z axis

fec7a7684ced28c0.mp4

Dragged widgets like slider handles should lift off the surface and be dropped back onto it

97f0af7516192838.mp4

Checked

Widgets that represent an on/off state should use accent color when they are :checked

Focus

Focus should be indicated by a ring using the system accent color

Focus states should use :focus-visible when possible instead of :focus to avoid erroneous keyboard navigation indicators

Hover

Never hide widgets behind hover states. It is not available on touch for example

Backdrop

Nuetral color, remove accent colors

Reduce depth by

  • using smaller shadows
  • Reducing contrast between levels

Text contrast must still pass WCAG A. Backdrop windows must still be legible. Do not use blur or otherwise obscure backdrop window contents

Accessibiltiy

In the case of padding and margins, use rem() pixels so that they scale with text size adjustments

Contrast

Colors must pass WCAG AA contrast by default

if a high-contrast style class exists, it must pass WCAG AAA

When transparency is used, a high-contrast style class must also be added which is opaque

Quirks

Buttons

for image buttons, toggles are square and regular buttons are circular

Clone this wiki locally