raysan-ui guidelines

01

Principles

Four rules that settle most design decisions before they come up.

02

Brand

Four brand elements carry the identity. Use them sparingly so they stay special.

03

Color

Material Design 3 color roles. Each role comes as a pair: a fill and an "on" color for text and icons placed on it. Ratios are calculated live for the current theme; switch themes to check dark.

Accent roles

Containers

Surfaces

Higher containers sit closer to the reader. Page background is surface; quiet panels use surface-container-low or surface-container.

Text & lines

Brand accents

Raw brand colors, prefixed --rd-. Use them for illustration, charts and brand moments. For UI, reach for a role first.

Using color

04

Typography

Two families. Sizes follow a classic scale (12 · 14 · 16 · 18 · 21 · 24 · 36 · 48 · 72) with line heights on an 8px rhythm.

Use the role, not the size: font: var(--title-m) in CSS or class="title-m" in HTML. Display sizes step down automatically on phones.

05

Iconography

Two tiers. Brand icons mark the things that matter most: callout sections, app icons and favicons. UI icons do the everyday work: buttons, lists, navigation. If everything gets a brand icon, nothing stands out.

Brand icons

Mid to high importance. A coral-to-peach tile with flat white shapes in two tones, drawn as SVG.

1. Tile48 × 48, corner radius 10 (20.8%). Coral #ff7e5f to peach #feb47b, left to right.
2. Glyph areaShapes sit inside an 86% box (dashed), leaving an even margin.
3. Back layerSupporting shapes in white at 50%.
4. Front layerOne or two hero shapes in solid white, overlapping the back layer.
5. KnockoutsSmall details (a dot, a code bracket) cut out in the tile gradient.

Callout sectionsFeature and service cards, section intros. Use the 48px tile above the card title.

App iconsEach app gets its own drawn tile. Export 192 and 512 PNGs for the web manifest and 180 for apple-touch-icon.

FaviconsSame tile as an SVG favicon. At 16–32px, drop the back layer and keep only the front shape so it reads.

Not forButtons, lists, navigation or anything repeated many times on a screen. Those are UI icons.

check_circle

DoBuild from simple geometric shapes, two tones of white, soft corners.

cancel

Don'tUse outlines, extra colors or detailed illustration. It turns muddy at small sizes.

Quick brand tile

No custom drawing yet? .brand-icon-ms puts a filled Material Symbol on the tile. Good for prototypes; draw a proper two-tone SVG before launch.

<!-- Drawn icon (preferred) -->
<img class="brand-icon" src="icons/brand/product-ux.svg" alt="" width="48" height="48">

<!-- Quick tile -->
<span class="brand-icon brand-icon-ms" aria-hidden="true"><span class="ms">timer</span></span>

<!-- Sizes: .sm 32 · default 48 · .lg 64 · .xl 96 -->

UI icons

Everyday icons. Material Symbols Rounded, outlined by default. Write the icon name inside <span class="ms">; add .fill for the selected or active state. Decorative icons get aria-hidden="true".

06

Shape & elevation

Soft and friendly. Cards use extra-large corners; anything you press is fully rounded. The system is flat: no drop shadows, outlines do the structural work.

07

Spacing & layout

Spacing moves in 4px steps, mostly 8, 12, 16, 24, 32 and 48. Page margins and grid gaps grow with the screen.

Content sits in .wrap (max 1120px, centered). Use .stack for vertical rhythm and .row for inline groups.

08

Motion

Motion explains a change; it never decorates. Short for small things, longer for big moves, always the emphasized easing. Everything stops when the visitor asks for reduced motion.

09

Components

The building blocks. Each one is a class (or one tag) you add to plain HTML.

10

Theming a project

A project can wear its own brand (Porsche red for Garage Log, Anycubic blue for the resin matrix) without forking the system. Load a small theme file after raysan-ui and override only the tokens that change.

/* garage-log/theme.css */
:root {
  --md-primary: #8c0000;
  --md-primary-container: #f7dcdc;
  --md-on-primary-container: #5c0000;
  --rd-brand-bar: linear-gradient(90deg,#8c0000,#d5001c);
}
:root[data-theme="dark"] {
  --md-primary: #ffb4a9;
  --md-primary-container: #5c1a12;
  --md-on-primary-container: #ffdad5;
}

11

Accessibility

Check these before every launch. Most are already handled if you stick to tokens and components.

• check_circleText meets 4.5:1 contrast (3:1 for 24px+ or bold 18px+). The color badges above show it live.
• check_circleEverything works with a keyboard and the focus ring is visible.
• check_circleIcon-only buttons have an aria-label; decorative icons have aria-hidden="true".
• check_circleEvery form field has a visible label and errors explain how to fix them.
• check_circleImages have alt text (empty alt="" if decorative).
• check_circlePage works at phone width with no sideways scrolling.
• check_circleChecked in both light and dark.
• check_circleAnimations stop under reduced motion (built into base.css).

12

Get started

Copy template/index.html into a new repo, or paste this into any page's <head>. Pinning to @0.1 picks up fixes but never breaking changes.

<script>try{if(localStorage.getItem("theme")==="dark")document.documentElement.setAttribute("data-theme","dark")}catch(e){}</script>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&family=Sofia+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;1,400&family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/raysantos/raysan-ui@0.1/css/tokens.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/raysantos/raysan-ui@0.1/css/base.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/raysantos/raysan-ui@0.1/css/components.css">
<script src="https://cdn.jsdelivr.net/gh/raysantos/raysan-ui@0.1/js/theme-toggle.js" defer></script>
<script src="https://cdn.jsdelivr.net/gh/raysantos/raysan-ui@0.1/js/scroll-progress.js" defer></script>