Stylesheet Targets

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.
• As much as can be done in stock Gtk.CSS should be. If we can move away from SCSS, we should.
• Widgets we support should be in Granite.Demo. We shouldn't have to use Gtk.Demo to test styles
• Adw widgets might be styled in Granite on a case-by-case basis. Ideally we have Granite-equivalent widgets. Adw widgets should not be added to Granite.Demo. We don't want to introduce a dependency on Adw in Granite.

Levels Theory

• Widget backgrounds should be styled according to "level" or "elevation", as an ideal but not a hard rule.
• 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
• backdrop and disabled states are also considered "further away" in interaction hierarchy.

Padding, Margins, and Border Radii

The base grid unit should be 2px. 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 4px to nest neatly into 8px 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

• Anything non-flat that is dragged should lift off the surface and be dropped back onto it. Slider handles, tabs, etc

97f0af7516192838.mp4

Checked

• Widgets that represent an on/off state should use accent color when they are :checked
• Non-flat ToggleButtons are just buttons and don't have :checked states

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
• Focus rings for linked widgets/widgets that have adjacent siblings, should be inside the widget

Hover

• Hover is a progressive enhancement. It is not available on touch for example
• Never hide widgets or important information behind hover states.
• Any interactive widgets that are completely flat should have a hover state
• Flat interactive widgets, like menu items or image buttons, should have a filled background shape on hover if they don't have one in their normal state

Backdrop

• Nuetral color, remove accent colors
• Text contrast must still pass WCAG A. Backdrop windows must still be legible. Do not use blur or otherwise obscure backdrop window contents
• Non-stateful/aesthetic animation should stop in background. Stateful animations (like progress pulses) should continue to make sure we're not communicating that progress has stopped.

Reduce depth by

• using smaller shadows
• Reducing contrast between levels

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
• We should force symbolic icons when high-contrast is used, except for app icons

Reduced Motion

• Interactive components should still be stateful. Buttons need to press in, but they shouldn't bounce. Don't translate between states
• Widgets should still react to multitouch as normal since they behave more like drag handles, but don't animate when interacted in other ways like keyboard shortcuts

Texting Scaling

• We should scale icons. This is the expected behavior for folks that use text-scaling settings

Icons

• There must be an app icon style class that includes shadows
• Drop 24px app icons
• Drop 16px and 24px color action icons
• Sidebars should use symbolic icons
• Symbolic tool icons should have colors. See if we can expand -gtk-icon-palette to use the full palette for symbolics. Possible Granite.Symbol that has mono/accent/colored styles
• Symbolic icon stroke width should match text stroke width?

---

Quirks

• Scrollbars that are always visible should maybe be non-flat?

Flat interactive widgets

• If an interactive widget is in a clear action bar (like a sidebar, toolbar, or popover), it's okay for them to be flat. Otherwise they must have an affordance for interaction
• Containers for flat items like list items, menu items, etc should have padding and be rounded.

Buttons

• For image buttons, toggles are square and regular buttons are circular