Getting Started

Installation, project structure, and quick start guide

Installation

You can run the CLI or install the npm package; both support npm, pnpm, yarn, and bun. Use the tabs below: click a tab to select your package manager, then copy the command. For the CLI: choose framework (Vanilla, Astro, Svelte, React, or Vue), then add to existing or create new project. Both use the same template choice (CSS only | Landing | Docs | Dashboard | Full). Add is for existing projects only: run npx rizzo-css add in your project root, choose a template, then select which components to add (or CSS only for the stylesheet only). CSS only = no components; Landing/Docs/Dashboard = component picker (all 53 or pick); Full = site clone (no picker). You must add the <link> yourself (CLI prints the exact tag). Create new: choose project location, then template — CSS only (stylesheet + license, README, .gitignore; no web pages or components), Landing (hero/features page), Docs (sidebar + sample doc), Dashboard (sidebar + stats/table), or Full (clone of the docs site). CSS only skips the component picker; Landing, Docs, and Dashboard then prompt for all 57 components or pick; Full skips the picker. We never overwrite existing files; any skipped content goes into RIZZO-SETUP.md. The package includes dist/rizzo.min.css, the CLI, and scaffolds. Component dependencies: Navbar adds Search and Settings; Settings adds ThemeSwitcher, FontSwitcher, SoundEffects; Toast adds Alert. add writes RIZZO-SETUP.md for all templates; Full also writes RIZZO-SNIPPET.txt unless --no-snippet. Init: --template css-only|landing|docs|dashboard|full. See the npm package and project README for CLI details.

Run the CLI

Click a tab to select your package manager, then use the copy button to copy the command.

Choose your package manager — click a tab to select, then copy the command.

npm pnpm yarn bun

Add to existing project:

Choose your package manager — click a tab to select, then copy the command.

npm pnpm yarn bun

To add a specific component without prompts, include its name: e.g. npx rizzo-css add Button or npx rizzo-css add ThemeSwitcher. Some components add others automatically (e.g. Navbar adds Search and Settings; Settings adds ThemeSwitcher, FontSwitcher, SoundEffects; Toast adds Alert). Run npx rizzo-css help components for the full list. Each component doc page has the exact command with copy buttons. For theme (list theme IDs), use the same pattern: npx rizzo-css theme, pnpm dlx rizzo-css theme, and so on.

Install the npm package

Choose your package manager, then copy the command to add Rizzo CSS to your project.

Choose your package manager — click a tab to select, then copy the command.

npm pnpm yarn bun

Installation by framework

Use the steps below for your framework. The CLI prints the exact <link> tag when you run init or add.

Vanilla JS

  1. New project: npx rizzo-css init → choose Vanilla JS → CSS only (index + CSS + RIZZO-SETUP.md; no components), Landing (CSS + RIZZO-SETUP.md, or full index + all components if you choose “all”), Docs / Dashboard (docs or dashboard overlay + component pages, all or pick; same five templates as Astro/Svelte), or Full (site clone: index + Navbar, Settings, Footer + all component pages + js + icons). We never overwrite — snippets in RIZZO-SETUP.md.
  2. Add to existing: Run npx rizzo-css add in your project root; add the printed <link> to your HTML.
  3. CSS: CLI writes css/rizzo.min.css. Link it or use a CDN (see README-RIZZO.md).
  4. Components: Same BEM classes as the Components docs. Core includes js/main.js for interactivity; see Vanilla component pages for copy-paste HTML.

Astro

  1. New project: npx rizzo-css init → choose Astro → CSS only / Landing / Docs / Dashboard / Full (CSS only = no components; Full = site clone; others = all 52 or pick components); pick package manager. Existing files are never overwritten; see RIZZO-SETUP.md for snippets.
  2. Add to existing: npx rizzo-css add in the project root, or npm create astro@latest my-app && cd my-app && npx rizzo-css add. Add the printed <link> to your root layout.
  3. CSS: public/css/rizzo.min.css. In layout: <link rel="stylesheet" href="/css/rizzo.min.css" /> or import 'rizzo-css'.
  4. Components: Copied to e.g. src/components/rizzo/. Use same BEM as Components; layout includes theme and toast.

Svelte (SvelteKit)

  1. New project: npx rizzo-css init → choose Svelte → CSS only / Landing / Docs / Dashboard / Full (CSS only = no components; Full = site clone; others = all 52 or pick components); pick package manager. Existing files are never overwritten; see RIZZO-SETUP.md for snippets.
  2. Add to existing: npx rizzo-css add in the project root, or npm create svelte@latest my-app && cd my-app && npx rizzo-css add. Add the printed <link> to app.html.
  3. CSS: static/css/rizzo.min.css. In app.html: <link rel="stylesheet" href="/css/rizzo.min.css" />.
  4. Components: import { Button, Badge, Card, ... } from '$lib/rizzo'. See Svelte docs and component pages (Astro | Vanilla | Svelte | Vue | React tabs).

React

  1. New project: npx rizzo-css init → choose React → CSS only / Landing / Docs / Dashboard / Full (same template options as Astro/Svelte). Existing files are never overwritten; see RIZZO-SETUP.md for snippets.
  2. Add to existing: npx rizzo-css add in the project root. Add the printed <link> to your root layout or index.html.
  3. CSS: Same path as your framework (e.g. public/css/rizzo.min.css or src/styles/rizzo.min.css). Link in layout or import in app entry.
  4. Components: Scaffold copies React components to your project. See React component docs for live examples and TSX code blocks.

Vue

  1. New project: npx rizzo-css init → choose Vue → CSS only / Landing / Docs / Dashboard / Full (same template options as Astro/Svelte). Existing files are never overwritten; see RIZZO-SETUP.md for snippets.
  2. Add to existing: npx rizzo-css add in the project root. Add the printed <link> to your root layout or index.html.
  3. CSS: Same path as your framework. Link in layout or import in app entry.
  4. Components: Scaffold copies Vue (.vue) components to your project. See Vue component docs for live examples and SFC code blocks.

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
bash bash 
# 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
│   │   ├── FrameworkCodeTabs.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, React, Vue, Vanilla)
│   │       ├── Copy.astro
│   │       ├── Check.astro
│   │       ├── ChevronDown.astro
│   │       ├── Circle.astro
│   │       ├── Close.astro
│   │       ├── Cat.astro
│   │       ├── Cmd.astro
│   │       ├── Gear.astro
│   │       ├── Search.astro
│   │       ├── (theme icons: Owl, Palette, Sun, Flame, Heart, Leaf, Shield, Zap, Rainbow, Cake, Sunset, Cherry, Brush, Lemon, etc.)
│   │       └── 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:

bash bash 
pnpm dev

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

Building

Build for production:

bash bash 
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. Every component page includes Astro | Vanilla | Svelte | Vue | React code tabs with complete, copy-paste examples. Interactive components (Navbar, Settings, Modal, Dropdown, Tabs, Accordion, Search, etc.) run their scripts after the DOM is ready, so they work when you import or copy them into your project. Search, Settings, and the Navbar mobile menu are fully keyboard-navigable (Tab, Escape, focus trap where applicable) and close when you click outside the panel or menu in all five frameworks.

Component Documentation

  • Accordion - Collapsible sections with single/multiple open and keyboard navigation
  • Alert - Alert/notification component with auto-dismiss
  • Avatar - User avatar with image or initials fallback
  • Badge - Small labels and tags with variants and sizes
  • Breadcrumb - Navigation breadcrumbs with separator customization
  • Button - Semantic button component
  • Cards - Flexible card component
  • Copy to Clipboard - Copy to clipboard component
  • Docs Sidebar - Documentation sidebar navigation with grouped links and active state
  • Divider - Horizontal or vertical divider with optional label
  • Dropdown - Accessible dropdown menu with keyboard navigation and nested submenus
  • Footer - Site footer with copyright and optional link list
  • Font Switcher - Font pair (sans + mono) dropdown with preview
  • Forms - Form components (FormGroup, Input, Textarea, Select, Checkbox, Radio)
  • Icons - Reusable SVG icon components (same set for Astro, Svelte, React, Vue, Vanilla; includes Cmd icon)
  • Modal - Accessible modal/dialog component
  • Navbar - Responsive, accessible navigation bar
  • Pagination - Pagination navigation with prev/next, page numbers, and ellipsis
  • Progress Bar - Progress bar with variants, sizes, and indeterminate state
  • Search - Search with Algolia on docs; package scaffold has overlay with header (search icon, input, close), sample results to edit, keyboard and click-outside to close
  • Settings - Comprehensive settings panel
  • Sound Effects - Toggle for play sound on click (Web Audio); off by default
  • Spinner - Accessible loading spinner with variants and sizes
  • Table - Data table with sorting and filtering
  • Tabs - Accessible tabs component with keyboard navigation and ARIA tab pattern
  • Theme Switcher - Accessible theme switcher
  • Toast - Fixed position toast notifications
  • Tooltip - Accessible tooltip component with positioning options

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.