A modern CSS design system built on Astro with semantic theming, accessibility-first components, and PostCSS optimization.
- 🎨 14 Built-in Themes - 7 dark and 7 light themes with semantic variable support (including GitHub Dark Classic and GitHub Light)
- ♿ Accessibility First - WCAG AA compliant with full keyboard navigation and screen reader support
- 🎯 Semantic Theming - All components use semantic CSS variables that adapt automatically
- 📦 Comprehensive Components - 24 accessible, themeable components with dedicated doc pages (Astro reference + Svelte examples)
- 🔀 Multi-framework - Vanilla JS, Astro, and Svelte supported with the same CSS and component styles; CLI offers all three (Vanilla JS = yellow, Astro = orange, Svelte = orange-red). All scaffolds include theme persistence (localStorage key
theme, System option) and global toast (showToast,removeToast,removeAllToasts); Vanilla scaffold also includes a full Settings panel (openSettings()). Framework switcher on docs (View as: Astro | Svelte | Vanilla). Svelte docs at /docs/svelte; Vanilla docs at /docs/vanilla/components with copy-paste HTML, optional JS, and live demos - 🛠️ Utility Classes - Display, position, borders, flexbox, grid, gap, animations, and more
- 🎨 OKLCH Colors - Perceptually uniform color space for better color manipulation
- 📱 Responsive - Mobile-first design with responsive breakpoints
- ⚡ Optimized - PostCSS processing with minification and vendor prefixes
- 🎯 Design System as Source of Truth - 165+ CSS variables ensure all styling is consistent and framework-portable
- Astro
5.17.1- Web framework (docs site + reference components) - Svelte
5.50.0- Framework docs and components at /docs/svelte; Svelte scaffold uses Svelte Kit - Vite
7.3.1- Build tool for Svelte scaffold - TypeScript
5.9.3- Type safety - PostCSS
8.5.6- CSS transformation with import support - postcss-import
16.1.1- CSS import support (SCSS/SASS-like) - Autoprefixer
10.4.23- Automatic vendor prefixes - cssnano
7.1.2- CSS minification - Stylelint
17.0.0- CSS linter - Algolia
5.47.0- Search integration (docs site) - OKLCH color format - Perceptually uniform color space
Using Rizzo? npx rizzo-css init — choose framework (Vanilla, Astro, or Svelte), then add to existing or create new. New → full clone. Or pnpm add rizzo-css and import 'rizzo-css'. CSS only: npx rizzo-css add (auto-detects framework). Full guide: GETTING_STARTED. React/Vue: same CSS; wrappers planned.
What ships: rizzo-css includes dist, CLI, and scaffolds (vanilla, astro-app, svelte-app) plus optional 25 components (including ThemeSwitcher). Create new project → full clone (stylesheet link included). Add to existing → CSS + optional components; you must add the stylesheet <link> yourself (CLI prints the exact tag). Each scaffold has a README. Same CSS and BEM for all three.
- Node.js 18+
- pnpm (recommended) or npm
pnpm installpnpm devSite available at http://localhost:4321
| Command | Description |
|---|---|
pnpm rizzo-css |
Run the CLI from this repo (e.g. pnpm rizzo-css init, pnpm rizzo-css add, pnpm rizzo-css theme). Elsewhere use npx rizzo-css. |
pnpm dev |
Start development server |
pnpm build |
Lint CSS, build minified CSS, and build the docs site (Astro). Use for preview/deploy. |
pnpm build:css |
Build minified CSS only → public/css/main.min.css and packages/rizzo-css/dist/rizzo.min.css |
pnpm build:package |
Full package prep: lint, build CSS, copy scaffold, run prepare-* scripts. Use before publish:package. |
pnpm publish:package |
Run build:package then publish the rizzo-css npm package |
pnpm preview |
Preview production build |
pnpm lint:css |
Lint CSS files |
pnpm lint:css:fix |
Auto-fix CSS linting issues |
Use PostCSS imports (similar to SCSS/SASS) in src/styles/main.css:
@import url('./variables.css');
@import url('./reset.css');
@import url('./base.css');
@import url('./typography.css');
@import url('./accessibility.css');
/* ... */Development:
- PostCSS processes imports and adds vendor prefixes
- Source CSS is used directly
- All 14 themes are available
Production:
- CSS is minified and optimized via
build:cssscript - Layout automatically uses
public/css/main.min.cssin production builds - Minification preserves pseudo-element syntax (
::before,::after)
CSS is organized into logical files (variables, reset, base, typography, components, themes, etc.). All components use BEM naming (e.g. .navbar, .navbar__container, .navbar__menu--open). See Design System for the full file list and variable reference.
Rizzo CSS includes 14 built-in themes (7 dark, 7 light) with semantic variable support:
- All components automatically adapt to the selected theme
- Themes use OKLCH color format for better color manipulation
- Contrast-aware text colors - Automatic text color selection based on background lightness for WCAG AA compliance
- System preference - First visit uses OS light/dark (
prefers-color-scheme); “System” option in the theme switcher follows OS and updates when the OS preference changes - Unique theme icons - Each theme has a distinct icon in the theme switcher (Owl, Palette, Flame, Sunset, Zap, Shield, Heart, Sun, Cake, Lemon, Rainbow, Leaf, Cherry, Brush)
- Settings panel for theme switching, font size adjustment, and accessibility options
- All settings persist in localStorage - Theme (including
system), font size, reduced motion, high contrast, and scrollbar style preferences are automatically saved and restored - Shadow and overlay variables for theme-aware effects
See Theming Documentation for details.
Accessible, themeable components:
- Navbar - Responsive navigation with dropdown menus, search, and settings button. Docs dropdown shows Introduction and Foundations (Getting Started, Design System, Theming, Accessibility, Colors). Components dropdown has Overview plus two columns of component links. Theming is under Docs (no separate Themes nav item). Mobile: full docs structure in the Docs dropdown; menu toggle, search, and settings with smooth transitions
- Settings - Settings panel with theme switcher, font size control, and accessibility options (reduce motion, high contrast, scrollbar style). All settings persist in localStorage. Close button (X) bordered and visible on hover. Opening/closing animations, mobile responsive
- ThemeSwitcher - Accessible dropdown with System option (follows OS light/dark), Preference + Dark/Light groups, theme-specific icons, and active state styling. Preview panel shows current theme by default and hovered theme on hover. All theme switchers (Settings, docs) use the same full-width trigger and dropdown.
- Button - Semantic button component with variants using theme variables
- Badge - Small labels and tags for displaying status, categories, or counts with variants, sizes, and pill option
- Icons - Reusable SVG icon components using Tabler Icons and Devicons (same set for Astro, Svelte, and Vanilla; includes Cmd icon for keyboard shortcuts; 20+ regular icons plus brand icons for CSS3, HTML5, JavaScript, Node.js, Astro, Svelte, React, Vue, and more)
- Form Components - Complete form system (FormGroup, Input, Textarea, Select, Checkbox, Radio) with validation states
- Card - Flexible card component with variants, sections, and image support
- Modal - Accessible modal/dialog component with focus trapping and keyboard navigation. Three sizes: sm, md (default), lg
- CopyToClipboard - Copy to clipboard component with visual feedback
- CodeBlock - Code block component with integrated copy-to-clipboard functionality and language icons. Displays colored brand icons (Devicons) for supported languages at 20px size for better visibility. Language text appears on large screens, icons only on mobile. Icons and copy button are vertically centered on all screen sizes. Used throughout documentation for code examples
- Search - Search component with Algolia integration; trigger uses Cmd icon and K at same size as search icon (20px); Cmd+K/Ctrl+K toggles open/close (including when focus is in search), Escape closes, backdrop or X to close; same live standalone example on Astro, Svelte, and Vanilla doc pages; mobile responsive
- Alert - Alert/notification component with variants, dismissible functionality, auto-dismiss, and dynamic creation via JavaScript
- Toast - Fixed position toast notifications with auto-dismiss and programmatic control. Available globally via
window.showToast(). Six position options with automatic stacking - Tooltip - Accessible tooltip component with four position options (top, bottom, left, right), keyboard support, and theme-aware styling
- Dropdown - Accessible dropdown menu component with keyboard navigation, nested submenus (up to 3 levels), menu items, separators, and custom click handlers
- Tabs - Accessible tabs component with keyboard navigation, ARIA tab pattern, and three variants (default, pills, underline)
All components:
- Use semantic theme variables with contrast-aware text colors
- Are fully keyboard accessible
- Have no inline styles (all CSS in external files)
- Follow BEM naming convention
- Include theme flash prevention on page load (inline script in Layout)
- Meet WCAG AA contrast requirements
- Theme switcher displays active theme name and icon in trigger button
- Individual documentation pages with live examples
See Components Documentation for usage examples.
Live site: rizzo-css.vercel.app
Comprehensive documentation is in the docs/ directory and on the live site. Site nav: Home | Docs (Introduction, Foundations) | Components. Theming is under Docs → Foundations.
- Getting Started - CLI (
npx rizzo-css init/add), npm install, import CSS, use components (Astro/Svelte), JavaScript utilities (theme, storage, clipboard, toast), and docs layout / site nav - Design System - Variables, file organization, and utilities
- Components - Component library and usage (25 components)
- Theming - Themes, system preference, custom themes (also linked under Docs → Foundations on the site)
- Colors - Color reference (OKLCH, Hex, RGB, HSL)
- Accessibility - Guidelines and utility classes; Accessibility testing - Checklist (keyboard, screen reader, tools)
- Framework Structure - Astro vs Svelte layout; framework switcher
- Multi-Framework Strategy - Svelte (done); React/Vue (planned)
- Publishing - How to publish the npm package
- TODO - Roadmap and tasks