What is zudo-css?
zudo-css is a CSS best practices documentation site designed primarily for AI coding agents. It provides curated CSS techniques and patterns as structured references that AI agents can consume and apply during development.
Purpose
AI coding agents frequently produce CSS that works but follows outdated patterns, overcomplicates simple tasks, or misses modern CSS features. This documentation addresses that gap by providing:
- Problem-first articles that start with what goes wrong
- Live CssPreview demos showing each technique in action
- Decision guidance for choosing between approaches
- Common AI mistakes sections highlighting specific pitfalls
Tech Stack
The site is built with:
- Astro 5 — static site generator with Content Collections
- MDX — content format combining Markdown with interactive components
- Tailwind CSS v4 — utility-first styling via
@tailwindcss/vite - React 19 — interactive islands for TOC, sidebar, and color scheme picker
- Shiki — syntax highlighting with dual-theme support
Deployed to Cloudflare Pages via GitHub Actions.
Article Categories
Articles are organized by CSS domain:
| Category | Topics |
|---|---|
| Layout | Centering, Flexbox, Grid, subgrid, positioning, stacking context, anchor positioning, aspect-ratio, logical properties, gap vs margin, multi-column, fit/max/min-content, clamp() |
| Typography | Three-tier font-size strategy, fluid font sizing, line height, text overflow/clamping, vertical rhythm, font loading, variable fonts, Japanese fonts, text-wrap balance/pretty |
| Color | Three-tier color strategy, palette strategy, OKLCH, color-mix(), currentColor, dark mode, contrast/accessibility |
| Visual | Layered shadows, smooth shadow transitions, gradients, borders, clip-path/mask, filters, backdrop-filter, blend modes, 3D transforms, @property, CSS-only patterns |
| Responsive | Container queries, fluid design with clamp(), media query best practices, responsive grid patterns, responsive images |
| Interactive | Transitions, hover/focus/active states, scroll snap, scroll-driven animations, view transitions, (), ()/(), parent-state child styling, form controls, touch targets, overscroll, prefers-reduced-motion |
| Methodology | Component-first strategy, tight token strategy (component tokens, typography tokens, color tokens), two-tier size strategy, BEM, CSS Modules, cascade layers, custom properties patterns, theming recipes |
Article Structure
Every article follows a consistent pattern:
- The Problem — common mistakes and what goes wrong
- The Solution — recommended approach with CssPreview demos
- Additional sections — deeper techniques with more demos
- When to Use — decision guidance for applying the technique
CssPreview Demos
The most valuable part of each article. CssPreview renders CSS demos inside isolated iframes with viewport controls (Mobile 320px, Tablet 768px, Full width). All interactions are CSS-only — no JavaScript inside demos.
AI Integration
The site includes a css-wisdom Claude Code skill that indexes all articles. Once installed, AI agents can invoke /css-wisdom <topic> to look up relevant CSS patterns during development. See the css-wisdom Skill page for details.