Design System

Semantic Variables

Rizzo CSS uses a semantic theming system with CSS custom properties (variables) that adapt to the selected theme.

Core Variables

• --background - Main background color
• --background-alt - Alternative background (cards, panels)
• --text - Primary text color
• --text-dim - Dimmed/secondary text color
• --border - Border color
• --accent - Primary accent color
• --accent-hover - Accent color on hover

Semantic Colors

• --success - Success state color
• --success-text - Text color for success backgrounds (contrast-aware)
• --warning - Warning state color
• --warning-text - Text color for warning backgrounds (contrast-aware)
• --error - Error state color
• --error-text - Text color for error backgrounds (contrast-aware)
• --info - Informational color
• --info-text - Text color for info backgrounds (contrast-aware)

Contrast-Aware Text Colors

All semantic colors include corresponding text color variables that automatically provide proper contrast:

• --accent-text - Text color for accent backgrounds (white on dark accents, dark on light accents)
• --success-text - Text color for success backgrounds
• --warning-text - Text color for warning backgrounds (typically dark text on light yellow)
• --error-text - Text color for error backgrounds
• --info-text - Text color for info backgrounds

These variables ensure WCAG AA contrast compliance (4.5:1 for normal text, 3:1 for large text).

Typography System

Rizzo CSS includes a comprehensive typography system:

Font Families

• --font-family-sans - System sans-serif stack
• --font-family-serif - System serif stack
• --font-family-mono - System monospace stack
• --font-family - Default font family (sans-serif)

Font Weights

• --font-weight-light (300)
• --font-weight-normal (400)
• --font-weight-medium (500)
• --font-weight-semibold (600)
• --font-weight-bold (700)
• --font-weight-extrabold (800)

Font Sizes (scalable via --font-size-scale)

All sizes use calc() with --font-size-scale for dynamic scaling:

• --font-size-xs through --font-size-6xl (0.75rem to 3.75rem base)

Line Heights

• --line-height-tight through --line-height-loose (1.25 to 2)

Letter Spacing

• --letter-spacing-tighter through --letter-spacing-widest (-0.05em to 0.1em)

Shadow and Overlay Variables

• --shadow-color - Base shadow color (black: oklch(0% 0 0deg))
• --shadow-sm, --shadow, --shadow-md, --shadow-lg, --shadow-xl - Shadow presets with varying opacity
• --overlay - Overlay color for modals and overlays (50% opacity of --shadow-color)

Selection Color

• --selection - Text selection background color (default: oklch(70% 0.15 250deg))

Color Format

All colors use OKLCH format for better perceptual uniformity:

--accent: oklch(65% 0.25 290deg);

OKLCH format uses:

• Lightness as percentage (0% = black, 100% = white)
• Chroma as decimal (0 = grayscale, higher = more saturated)
• Hue in degrees (0-360deg)

OKLCH provides:

• Perceptually uniform color space
• Better color manipulation
• Consistent appearance across displays

Using Variables

In CSS

.my-component {
  background-color: var(--background);
  color: var(--text);
  border: var(--outline-width) solid var(--border);
}

.my-button {
  background-color: var(--accent);
  color: var(--accent-text);
}

.my-button:hover {
  background-color: var(--accent-hover);
  color: var(--accent-text);
}

In Components

Note: All component styles should be in external CSS files (components.css), not inline <style> blocks. Components use CSS variables from the semantic theme system.

Component CSS structure:

/* In src/styles/components.css */
.my-component {
  background: var(--background-alt);
  color: var(--text);
}

Naming Convention

All component classes use BEM (Block Element Modifier) naming:

• Block: .navbar, .theme-switcher
• Element: .navbar__container, .theme-switcher__menu
• Modifier: .navbar__menu--open, .theme-switcher__option--active

This ensures:

• Clear component structure
• Easy to understand relationships
• Consistent naming across the design system

Spacing Utilities

Rizzo CSS includes comprehensive spacing utilities for margins and padding using a consistent scale:

Spacing Scale

All spacing uses rem units for consistency and accessibility:

• 0 - 0
• 1 - 0.25rem (4px)
• 2 - 0.5rem (8px)
• 3 - 0.75rem (12px)
• 4 - 1rem (16px)
• 5 - 1.25rem (20px)
• 6 - 1.5rem (24px)
• 8 - 2rem (32px)
• 10 - 2.5rem (40px)
• 12 - 3rem (48px)
• 16 - 4rem (64px)
• 20 - 5rem (80px)
• 24 - 6rem (96px)

Margin Utilities

Margin classes: .m-{size}, .mt-{size}, .mr-{size}, .mb-{size}, .ml-{size}, .mx-{size}, .my-{size}

Auto margins: .m-auto, .mx-auto, .my-auto (for centering)

Padding Utilities

Padding classes: .p-{size}, .pt-{size}, .pr-{size}, .pb-{size}, .pl-{size}, .px-{size}, .py-{size}

Examples

Code Example

<!-- Margin examples -->
<div class="m-4">Margin on all sides</div>
<div class="mx-auto">Centered with auto margins</div>
<div class="mt-6 mb-4">Top and bottom margins</div>

<!-- Padding examples -->
<div class="p-4">Padding on all sides</div>
<div class="px-6 py-4">Horizontal and vertical padding</div>

Container Utilities

Container utilities provide responsive containers with automatic centering and padding:

Container Sizes

• .container-sm - 640px max-width
• .container-md - 768px max-width
• .container-lg - 1024px max-width
• .container-xl - 1280px max-width
• .container-2xl - 1536px max-width
• .container-full - 100% width (with padding)

Note: The default .container class (1200px) is also available in layout.css.

Examples

Code Example

<!-- Small container -->
<div class="container-sm">
  Content constrained to 640px
</div>

<!-- Large container -->
<div class="container-lg">
  Content constrained to 1024px
</div>

<!-- Full width with padding -->
<div class="container-full">
  Full width with horizontal padding
</div>

Max-Width Utilities

Max-width utilities constrain element width without centering or padding:

Size-Based Max-Width

• .max-w-none - No max-width
• .max-w-xs - 20rem (320px)
• .max-w-sm - 24rem (384px)
• .max-w-md - 28rem (448px)
• .max-w-lg - 32rem (512px)
• .max-w-xl - 36rem (576px)
• .max-w-2xl - 42rem (672px)
• .max-w-3xl - 48rem (768px)
• .max-w-4xl - 56rem (896px)
• .max-w-5xl - 64rem (1024px)
• .max-w-6xl - 72rem (1152px)
• .max-w-7xl - 80rem (1280px)
• .max-w-full - 100%

Screen-Based Max-Width

• .max-w-screen-sm - 640px
• .max-w-screen-md - 768px
• .max-w-screen-lg - 1024px
• .max-w-screen-xl - 1280px
• .max-w-screen-2xl - 1536px

Examples

Code Example

<!-- Constrain text width for readability -->
<p class="max-w-2xl">
  This paragraph is constrained to 672px for optimal readability.
</p>

<!-- Constrain to screen breakpoint -->
<div class="max-w-screen-lg">
  Content constrained to 1024px
</div>

Sizing Utilities

Rizzo CSS includes comprehensive sizing utilities for width, height, and min/max dimensions:

Width Utilities

• .w-auto, .w-full, .w-screen, .w-fit, .w-max, .w-min
• .w-0, .w-1 through .w-64 (0 to 16rem in increments)

Height Utilities

• .h-auto, .h-full, .h-screen, .h-fit, .h-max, .h-min
• .h-0, .h-1 through .h-64 (0 to 16rem in increments)

Min-Width Utilities

• .min-w-0, .min-w-full, .min-w-min, .min-w-max, .min-w-fit

Min-Height Utilities

• .min-h-0, .min-h-full, .min-h-screen, .min-h-fit, .min-h-max, .min-h-min

Max-Height Utilities

• .max-h-none, .max-h-full, .max-h-screen, .max-h-fit, .max-h-max, .max-h-min
• .max-h-0, .max-h-1 through .max-h-64 (0 to 16rem in increments)

Examples

Code Example

<!-- Full width and height -->
<div class="w-full h-screen">Full viewport</div>

<!-- Fixed dimensions -->
<div class="w-64 h-48">Fixed size</div>

<!-- Minimum height -->
<div class="min-h-screen">At least viewport height</div>

<!-- Maximum height with scrolling -->
<div class="max-h-96 overflow-auto">Scrollable content</div>

Media Queries

Rizzo CSS includes a dedicated media-queries.css file with responsive breakpoints:

Breakpoints

• 640px (sm) - Small devices, landscape phones
• 768px (md) - Tablets
• 1024px (lg) - Desktops
• 1280px (xl) - Large desktops
• 1536px (2xl) - Larger desktops

Usage

/* Mobile-first approach */
@media (width >= 768px) {
  /* Tablet and up styles */
}

@media (width <= 1023px) {
  /* Tablet and down styles */
}

Accessibility Media Queries

The media queries file also includes:

• prefers-reduced-motion - Respects user motion preferences
• prefers-contrast: high - Enhanced contrast support

Display Utilities

Display utilities control how elements are displayed:

Display Types

• .block, .inline-block, .inline
• .flex, .inline-flex
• .grid, .inline-grid
• .table, .table-row, .table-cell
• .contents, .list-item
• .hidden - Hide element (display: none)

Responsive Display

All display utilities have responsive variants using breakpoint prefixes:

• .sm:display - Applies at 640px and up
• .md:display - Applies at 768px and up
• .lg:display - Applies at 1024px and up
• .xl:display - Applies at 1280px and up
• .xxl:display - Applies at 1536px and up

Code Example

<!-- Hide on mobile, show on desktop -->
<div class="hidden md:block">Visible on tablet and up</div>

<!-- Flex on mobile, grid on desktop -->
<div class="flex lg:grid">Responsive layout</div>

Position Utilities

Position utilities control element positioning:

Position Types

• .static - Default positioning
• .relative - Relative to normal position
• .absolute - Absolute positioning
• .fixed - Fixed to viewport
• .sticky - Sticky positioning

Z-Index Scale

• .z-0, .z-10, .z-20, .z-30, .z-40, .z-50, .z-auto
• Component-specific z-index classes: .z-dropdown (1000), .z-modal (2000), .z-tooltip (3000), .z-toast (4000), .z-navbar (5000)

Code Example

<!-- Fixed header -->
<header class="fixed top-0 z-navbar">Fixed header</header>

<!-- Sticky sidebar -->
<aside class="sticky top-4">Sticky sidebar</aside>

Border Utilities

Border utilities provide comprehensive border styling:

Border Radius

• .rounded-none, .rounded-sm, .rounded, .rounded-md, .rounded-lg, .rounded-xl, .rounded-2xl, .rounded-3xl, .rounded-full
• Side-specific: .rounded-t-*, .rounded-r-*, .rounded-b-*, .rounded-l-*

Border Width

• .border-0, .border, .border-2, .border-4, .border-8
• Side-specific: .border-t-*, .border-r-*, .border-b-*, .border-l-*

Border Colors (using theme variables)

• .border-transparent
• .border-color (uses --border)
• .border-accent (uses --accent)
• .border-success, .border-warning, .border-error, .border-info

Code Example

<!-- Rounded card -->
<div class="rounded-lg border border-color">Card</div>

<!-- Full rounded button -->
<button class="rounded-full border-2 border-accent">Button</button>

Flexbox Utilities

Comprehensive flexbox utilities for flexible layouts:

Flex Direction

• .flex-row, .flex-row-reverse, .flex-col, .flex-col-reverse

Justify Content & Align Items

• .justify-start, .justify-end, .justify-center, .justify-between, .justify-around, .justify-evenly
• .items-start, .items-end, .items-center, .items-baseline, .items-stretch

Flex Grow/Shrink

• .flex-1, .flex-auto, .flex-initial, .flex-none
• .grow, .grow-0, .shrink, .shrink-0

Code Example

<!-- Centered flex container -->
<div class="flex items-center justify-center">Centered content</div>

<!-- Space between items -->
<div class="flex justify-between">Space between</div>

Grid Utilities

CSS Grid utilities for complex layouts:

Grid Template Columns

• .grid-cols-1 through .grid-cols-12, .grid-cols-none

Grid Column/Row Span

• .col-span-1 through .col-span-6, .col-span-full
• .row-span-1 through .row-span-6, .row-span-full

Code Example

<!-- 3-column grid -->
<div class="grid grid-cols-3 gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  Responsive grid
</div>

Gap Utilities

Gap utilities for flexbox and grid layouts using the spacing scale:

Gap Classes

• .gap-0, .gap-1 through .gap-24 (using spacing scale variables)
• .gap-x-* - Column gap
• .gap-y-* - Row gap

Code Example

<!-- Grid with gap -->
<div class="grid grid-cols-3 gap-4">Grid with spacing</div>

<!-- Different row and column gaps -->
<div class="flex flex-col gap-y-2 gap-x-4">Different gaps</div>

Animation & Transition Utilities

Transition utilities that respect prefers-reduced-motion:

Transition Properties

• .transition-none, .transition-all, .transition
• .transition-colors, .transition-opacity, .transition-shadow, .transition-transform

Transition Duration & Timing

• .duration-75 through .duration-1000
• .ease-linear, .ease-in, .ease-out, .ease-in-out
• .transition-fast (150ms), .transition-base (200ms), .transition-slow (300ms)

Accessibility: All transition utilities automatically respect prefers-reduced-motion and reduce to 0.01ms duration when the user prefers reduced motion.

Code Example

<!-- Fast color transition -->
<button class="transition-colors duration-200">Hover me</button>

<!-- Combined transition -->
<div class="transition-base hover:shadow-lg">Smooth transition</div>

Best Practices

1. Always use semantic variables - Never hardcode colors
2. Use contrast-aware text colors - Use --accent-text, --success-text, etc. when using colored backgrounds
3. Use appropriate variables - --background-alt for cards, --background for page background
4. Use utility classes - Leverage spacing, sizing, display, position, border, flexbox, grid, and gap utilities for consistent styling
5. Use spacing utilities - Use margin and padding utility classes for consistent spacing
6. Mobile-first responsive design - Start with mobile styles, then add larger breakpoint styles using responsive utility prefixes (sm:, md:, lg:, xl:, xxl:)
7. Maintain contrast - All themes meet WCAG AA contrast requirements automatically
8. Test with multiple themes - Verify components work with both light and dark themes
9. No inline styles - All CSS should be in external files (components.css, buttons.css, etc.)
10. Follow BEM naming - Use block__element--modifier pattern for all component classes
11. Accessibility first - All components must be keyboard navigable and screen reader friendly
12. Use typography variables - Use --font-size-*, --font-weight-*, --line-height-* for consistent typography
13. Respect font size scale - All font sizes automatically scale with --font-size-scale variable
14. Respect reduced motion - All transition utilities automatically respect prefers-reduced-motion
15. Use theme-aware utilities - Border colors, text colors, and background colors use semantic theme variables