Getting Started

Installation, project structure, and quick start guide

Installation

Using the npm package? Run npx rizzo-css init — choose framework (Vanilla, Astro, or Svelte), then add to existing or create new project. For Astro/Svelte you’ll see What to include?: CSS only, Recommended set, All components, or Pick components. Create new gives a full clone (stylesheet link included); add to existing copies CSS + optional components (you must add the <link> yourself; the CLI prints the exact tag). The package includes dist/rizzo.min.css, the CLI (init / add / theme), and scaffolds plus 25 optional components (including ThemeSwitcher). Each scaffold has a README. See the npm package and project README for CLI details.

Rizzo CSS is built on Astro. To work on this docs site and reference components (clone the repo):

bash bash 
# Clone the project
git clone <repository-url>
cd rizzo-css
nodejs nodejs 
# Install dependencies
pnpm install

Project Structure

plaintext plaintext 
rizzo-css/
├── src/
│   ├── components/      # Astro components
│   │   ├── Accordion.astro
│   │   ├── Alert.astro
│   │   ├── Badge.astro
│   │   ├── Breadcrumb.astro
│   │   ├── Button.astro
│   │   ├── Card.astro
│   │   ├── CodeBlock.astro
│   │   ├── CopyToClipboard.astro
│   │   ├── Dropdown.astro
│   │   ├── FormGroup.astro
│   │   ├── Input.astro
│   │   ├── Textarea.astro
│   │   ├── Select.astro
│   │   ├── Checkbox.astro
│   │   ├── Radio.astro
│   │   ├── Modal.astro
│   │   ├── Navbar.astro
│   │   ├── Pagination.astro
│   │   ├── ProgressBar.astro
│   │   ├── Search.astro
│   │   ├── Spinner.astro
│   │   ├── Avatar.astro
│   │   ├── Divider.astro
│   │   ├── Table.astro
│   │   ├── Settings.astro
│   │   ├── Tabs.astro
│   │   ├── ThemeSwitcher.astro
│   │   ├── Toast.astro
│   │   ├── Tooltip.astro
│   │   └── icons/      # Icon components (same set for Astro, Svelte, Vanilla)
│   │       ├── Copy.astro
│   │       ├── Check.astro
│   │       ├── ChevronDown.astro
│   │       ├── Circle.astro
│   │       ├── Close.astro
│   │       ├── Cmd.astro
│   │       ├── Eye.astro
│   │       ├── Gear.astro
│   │       ├── IceCream.astro
│   │       ├── Moon.astro
│   │       ├── Owl.astro
│   │       ├── Palette.astro
│   │       ├── Rainbow.astro
│   │       ├── Search.astro
│   │       ├── Snowflake.astro
│   │       └── devicons/  # Devicon brand icons
│   │           ├── Astro.astro
│   │           ├── Bash.astro
│   │           ├── Css3.astro
│   │           ├── Git.astro
│   │           ├── Html5.astro
│   │           ├── Javascript.astro
│   │           ├── Nodejs.astro
│   │           ├── Plaintext.astro
│   │           ├── React.astro
│   │           ├── Svelte.astro
│   │           └── Vue.astro
│   ├── layouts/         # Page layouts
│   │   └── Layout.astro
│   ├── pages/           # Route pages
│   └── styles/          # CSS files
│       ├── accessibility.css
│       ├── base.css
│       ├── buttons.css
│       ├── components.css
│       ├── forms.css
│       ├── layout.css
│       ├── main.css
│       ├── pages.css
│       ├── reset.css
│       ├── spacing.css
│       ├── sizes.css
│       ├── typography.css
│       ├── utilities.css
│       ├── variables.css
│       ├── media-queries.css
│       └── themes/      # Theme files (14 themes: 7 dark, 7 light)
│           ├── dark/
│           │   ├── github-dark-classic.css
│           │   ├── shades-of-purple.css
│           │   ├── sandstorm-classic.css
│           │   ├── rocky-blood-orange.css
│           │   ├── minimal-dark-neon-yellow.css
│           │   ├── hack-the-box.css
│           │   └── pink-cat-boo.css
│           └── light/
│               ├── github-light.css
│               ├── red-velvet-cupcake.css
│               ├── orangy-one-light.css
│               ├── sunflower.css
│               ├── green-breeze-light.css
│               ├── cute-pink.css
│               └── semi-light-purple.css
├── docs/                # Documentation
├── public/              # Static assets
│   └── css/             # Generated CSS
│       └── main.min.css
└── scripts/             # Build scripts
    └── build-css.js

Development

Start the development server:

nodejs nodejs 
pnpm dev

The site will be available at http://localhost:4321

Building

Build for production:

nodejs nodejs 
pnpm build

This will:

  1. Build and minify CSS to public/css/main.min.css
  2. Build the Astro site to dist/

Using Components

Rizzo CSS includes a comprehensive set of accessible components. Each component has its own dedicated documentation page with live examples, usage instructions, and API details.

Component Documentation

  • Navbar - Responsive, accessible navigation bar
  • Settings - Comprehensive settings panel
  • Theme Switcher - Accessible theme switcher
  • Button - Semantic button component
  • Badge - Small labels and tags with variants and sizes
  • Accordion - Collapsible sections with single/multiple open and keyboard navigation
  • Breadcrumb - Navigation breadcrumbs with separator customization
  • Pagination - Pagination navigation with prev/next, page numbers, and ellipsis
  • Progress Bar - Progress bar with variants, sizes, and indeterminate state
  • Spinner - Accessible loading spinner with variants and sizes
  • Avatar - User avatar with image or initials fallback
  • Divider - Horizontal or vertical divider with optional label
  • Table - Data table with sorting and filtering
  • Icons - Reusable SVG icon components (same set for Astro, Svelte, Vanilla; includes Cmd icon)
  • CopyToClipboard - Copy to clipboard component
  • Forms - Form components (FormGroup, Input, Textarea, Select, Checkbox, Radio)
  • Cards - Flexible card component
  • Modal - Accessible modal/dialog component
  • Alert - Alert/notification component with auto-dismiss
  • Toast - Fixed position toast notifications
  • Search - Search with Algolia integration; Cmd icon + K in trigger (same size as search icon); same live example on Astro, Svelte, and Vanilla
  • Tooltip - Accessible tooltip component with positioning options
  • Dropdown - Accessible dropdown menu with keyboard navigation and nested submenus
  • Tabs - Accessible tabs component with keyboard navigation and ARIA tab pattern

See the Components Documentation for an overview and links to all component pages.

Using Themes

Rizzo CSS includes 14 built-in themes (7 dark, 7 light). Themes are applied via the data-theme attribute on the HTML element:

html html 
<html lang="en" data-theme="github-dark-classic">

See Theming Documentation for more details.

CSS Architecture

File Organization

CSS is organized into logical files:

  • variables.css - Default theme variables and typography system
  • reset.css - Modern CSS reset
  • base.css - Base HTML element styles
  • typography.css - Typography system (font families, sizes, weights, line heights, utilities)
  • accessibility.css - Accessibility utilities
  • buttons.css - Button component styles
  • layout.css - Layout utilities
  • spacing.css - Margin and padding utility classes
  • sizes.css - Width, height, min/max dimensions, and container utilities
  • utilities.css - Utility classes (colors, borders, focus states)
  • forms.css - Form component styles
  • pages.css - Page-specific styles
  • media-queries.css - Responsive breakpoints and media query definitions
  • components.css - Component styles (Accordion, Alert, Avatar, Badge, Breadcrumb, Card, CodeBlock, CopyToClipboard, Divider, Dropdown, Modal, Navbar, Pagination, Progress Bar, Search, Settings, Spinner, Table, Tabs, ThemeSwitcher, Toast, Tooltip)
  • themes/ - Theme definitions (dark/light)

Semantic Variables

All styles use semantic theme variables:

css css 
.my-component {
  background-color: var(--background);
  color: var(--text);
  border: 1px solid var(--border);
}

PostCSS Processing

  • Development: PostCSS processes imports and adds vendor prefixes
  • Production: CSS is minified via build:css script
  • Linting: Stylelint configured for BEM naming convention
  • No Inline Styles: All component styles are in external CSS files

Spacing Utilities

Rizzo CSS includes comprehensive spacing utilities for margins and padding:

html html 
<!-- Margin utilities -->
<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 utilities -->
<div class="p-4">Padding on all sides</div>
<div class="px-6 py-4">Horizontal and vertical padding</div>

<!-- Sizes: 0, 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px), 24 (96px) -->

See Design System Documentation for available variables and utilities.