tessl/npm-windicss

Next generation utility-first CSS framework with on-demand generation and Tailwind compatibility.

—

Pending

Overview

Eval results

Files

Built-in Plugins

Name: tessl/npm-windicss
Author: tessl

WindiCSS includes several official plugins that extend the framework with specialized utilities for aspect ratios, filters, forms, line clamping, typography, and scroll snap functionality. These plugins demonstrate best practices and provide commonly needed functionality out of the box.

Capabilities

Aspect Ratio Plugin

Provides utilities for maintaining aspect ratios of elements, useful for responsive images, videos, and containers.

import aspectRatio from "windicss/plugin/aspect-ratio";

/**
 * Aspect Ratio plugin configuration options
 */
interface AspectRatioOptions {
  /** Custom aspect ratio values */
  ratios?: Record<string, string>;
  /** Whether to include default ratios */
  includeDefaults?: boolean;
}

Usage Examples:

import Processor from "windicss";
import aspectRatio from "windicss/plugin/aspect-ratio";

// Basic usage
const processor = new Processor({
  plugins: [
    aspectRatio
  ]
});

// With custom ratios
const processorCustom = new Processor({
  plugins: [
    aspectRatio({
      ratios: {
        'golden': '1.618/1',
        'cinema': '2.39/1',
        'photo': '4/3'
      }
    })
  ]
});

// Generated utilities:
// aspect-square (1:1)
// aspect-video (16:9)
// aspect-golden (1.618:1)
// aspect-cinema (2.39:1)
// aspect-photo (4:3)

HTML Examples:

<!-- Square aspect ratio -->
<div class="aspect-square bg-gray-200">
  <img src="image.jpg" class="w-full h-full object-cover" alt="Square image">
</div>

<!-- Video aspect ratio -->
<div class="aspect-video bg-black">
  <iframe src="video.mp4" class="w-full h-full"></iframe>
</div>

<!-- Custom aspect ratio -->
<div class="aspect-golden">
  <div class="w-full h-full flex items-center justify-center bg-blue-500 text-white">
    Golden Ratio Container
  </div>
</div>

Filters Plugin

Adds utilities for CSS filter and backdrop-filter effects including blur, brightness, contrast, and more.

import filters from "windicss/plugin/filters";

/**
 * Filters plugin - no configuration options
 * Adds comprehensive filter and backdrop-filter utilities
 */

Usage Examples:

import Processor from "windicss";
import filters from "windicss/plugin/filters";

const processor = new Processor({
  plugins: [
    filters
  ]
});

// Generated filter utilities:
// blur-{size} - Apply blur filter
// brightness-{amount} - Adjust brightness
// contrast-{amount} - Adjust contrast  
// grayscale - Convert to grayscale
// hue-rotate-{degrees} - Rotate hue
// invert - Invert colors
// saturate-{amount} - Adjust saturation
// sepia - Apply sepia effect

// Generated backdrop-filter utilities:
// backdrop-blur-{size} - Backdrop blur
// backdrop-brightness-{amount} - Backdrop brightness
// backdrop-contrast-{amount} - Backdrop contrast
// backdrop-grayscale - Backdrop grayscale
// backdrop-hue-rotate-{degrees} - Backdrop hue rotation
// backdrop-invert - Backdrop invert
// backdrop-saturate-{amount} - Backdrop saturation
// backdrop-sepia - Backdrop sepia

HTML Examples:

<!-- Image filters -->
<img src="photo.jpg" class="blur-sm brightness-110 contrast-125" alt="Filtered image">

<!-- Backdrop effects for glass morphism -->
<div class="backdrop-blur-md backdrop-brightness-110 bg-white/20 rounded-lg p-6">
  <h3 class="text-gray-900 font-semibold">Glass Card</h3>
  <p class="text-gray-700">Content with backdrop blur effect</p>
</div>

<!-- Creative filter combinations -->
<div class="hover:grayscale-0 grayscale transition-all duration-300">
  <img src="artwork.jpg" alt="Artwork with hover effect">
</div>

<!-- Sepia photo effect -->
<div class="sepia-75 contrast-125 brightness-105">
  <img src="vintage.jpg" class="w-full h-auto" alt="Vintage style photo">
</div>

Forms Plugin

Provides base styles and utilities for form elements with consistent styling across browsers.

import forms from "windicss/plugin/forms";

/**
 * Forms plugin configuration options
 */
interface FormsOptions {
  /** CSS layer for form styles */
  layer?: 'base' | 'components';
  /** Whether to include default form styles */
  includeDefaults?: boolean;
}

Usage Examples:

import Processor from "windicss";
import forms from "windicss/plugin/forms";

// Basic usage
const processor = new Processor({
  plugins: [
    forms
  ]
});

// With custom configuration
const processorCustom = new Processor({
  plugins: [
    forms({
      layer: 'components',
      includeDefaults: false
    })
  ]
});

// Provides normalized styles for:
// - Input fields (text, email, password, number, etc.)
// - Select dropdowns
// - Textareas
// - Checkboxes and radio buttons
// - File inputs
// - Form labels and fieldsets

HTML Examples:

<!-- Styled form with forms plugin -->
<form class="space-y-4">
  <!-- Text input with enhanced styling -->
  <div>
    <label class="block text-sm font-medium text-gray-700">Email</label>
    <input 
      type="email" 
      class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500"
      placeholder="you@example.com"
    >
  </div>

  <!-- Select dropdown -->
  <div>
    <label class="block text-sm font-medium text-gray-700">Country</label>
    <select class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500">
      <option>United States</option>
      <option>Canada</option>
      <option>Mexico</option>
    </select>
  </div>

  <!-- Checkbox with custom styling -->
  <div class="flex items-center">
    <input 
      type="checkbox" 
      class="h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded"
    >
    <label class="ml-2 block text-sm text-gray-900">
      I agree to the terms and conditions
    </label>
  </div>

  <!-- Textarea -->
  <div>
    <label class="block text-sm font-medium text-gray-700">Message</label>
    <textarea 
      rows="4" 
      class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500"
      placeholder="Your message..."
    ></textarea>
  </div>
</form>

Line Clamp Plugin

Adds utilities for truncating text to a specific number of lines using CSS line clamping.

import lineClamp from "windicss/plugin/line-clamp";

/**
 * Line Clamp plugin configuration options
 */
interface LineClampOptions {
  /** Custom line counts to generate utilities for */
  lines?: number[];
  /** Whether to include default line counts */
  includeDefaults?: boolean;
}

Usage Examples:

import Processor from "windicss";
import lineClamp from "windicss/plugin/line-clamp";

// Basic usage
const processor = new Processor({
  plugins: [
    lineClamp
  ]
});

// With custom line counts
const processorCustom = new Processor({
  plugins: [
    lineClamp({
      lines: [1, 2, 3, 4, 5, 6, 8, 10],
      includeDefaults: true
    })
  ]
});

// Generated utilities:
// line-clamp-1 - Clamp to 1 line
// line-clamp-2 - Clamp to 2 lines  
// line-clamp-3 - Clamp to 3 lines
// line-clamp-none - Remove line clamping

HTML Examples:

<!-- Single line truncation -->
<h3 class="line-clamp-1 text-lg font-semibold">
  This is a very long heading that will be truncated to a single line with an ellipsis
</h3>

<!-- Multi-line truncation for descriptions -->
<p class="line-clamp-3 text-gray-600 leading-relaxed">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor 
  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud 
  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute 
  irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat.
</p>

<!-- Card with clamped content -->
<div class="bg-white rounded-lg shadow-md p-6">
  <h4 class="line-clamp-1 text-xl font-bold text-gray-900 mb-2">
    Article Title That Might Be Very Long
  </h4>
  <p class="line-clamp-4 text-gray-600 mb-4">
    Article excerpt that provides a preview of the content but is limited to 
    exactly four lines to maintain consistent card heights in a grid layout.
    This ensures a clean, uniform appearance across multiple cards.
  </p>
  <button class="text-blue-600 hover:text-blue-800 font-medium">
    Read More
  </button>
</div>

<!-- Remove line clamping on hover -->
<div class="line-clamp-2 hover:line-clamp-none transition-all duration-200">
  <p>
    Hover over this text to see the full content without line clamping.
    This is useful for interactive elements where you want to show more detail on hover.
  </p>
</div>

Typography Plugin

Comprehensive typography plugin that provides beautiful default styles for rendered HTML content like blog posts, articles, and documentation.

import typography from "windicss/plugin/typography";

/**
 * Typography plugin configuration options
 */
interface TypographyOptions {
  /** CSS class name for typography styles */
  className?: string;
  /** Size modifiers to generate */
  modifiers?: string[];
  /** Whether to include headings styling */
  headings?: boolean;
  /** Whether to include code styling */
  code?: boolean;
  /** Whether to include table styling */
  tables?: boolean;
  /** Custom color themes */
  themes?: Record<string, TypographyTheme>;
}

interface TypographyTheme {
  colors: {
    text: string;
    headings: string;
    lead: string;
    links: string;
    bold: string;
    counters: string;
    bullets: string;
    hr: string;
    quotes: string;
    captions: string;
    code: string;
    pre: string;
  };
}

Usage Examples:

import Processor from "windicss";
import typography from "windicss/plugin/typography";

// Basic usage
const processor = new Processor({
  plugins: [
    typography
  ]
});

// With full configuration
const processorAdvanced = new Processor({
  plugins: [
    typography({
      className: 'prose',
      modifiers: ['sm', 'lg', 'xl', '2xl'],
      headings: true,
      code: true,
      tables: true,
      themes: {
        dark: {
          colors: {
            text: '#e5e7eb',
            headings: '#f9fafb',
            lead: '#d1d5db',
            links: '#60a5fa',
            bold: '#f9fafb',
            counters: '#9ca3af',
            bullets: '#6b7280',
            hr: '#374151',
            quotes: '#9ca3af',
            captions: '#9ca3af',
            code: '#e5e7eb',
            pre: '#d1d5db'
          }
        }
      }
    })
  ]
});

// Generated utilities:
// prose - Base typography styles
// prose-sm - Small size variant
// prose-lg - Large size variant
// prose-xl - Extra large variant
// prose-2xl - 2X large variant
// prose-gray - Gray color theme
// prose-blue - Blue color theme
// prose-dark - Dark theme

HTML Examples:

<!-- Basic prose styling -->
<article class="prose max-w-none">
  <h1>The Future of Web Development</h1>
  <p class="lead">
    An exploration of emerging technologies and their impact on how we build for the web.
  </p>
  
  <h2>Introduction</h2>
  <p>
    Web development continues to evolve at a rapid pace. From <strong>framework innovations</strong> 
    to new browser APIs, developers have more tools than ever to create amazing experiences.
  </p>
  
  <blockquote>
    <p>The best way to predict the future is to invent it.</p>
    <cite>Alan Kay</cite>
  </blockquote>
  
  <h3>Key Technologies</h3>
  <ul>
    <li>Web Components and Custom Elements</li>
    <li>Progressive Web Apps (PWAs)</li>
    <li>WebAssembly (WASM)</li>
    <li>Edge Computing</li>
  </ul>
  
  <pre><code class="language-javascript">
// Example of modern JavaScript
const fetchData = async (url) => {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (error) {
    console.error('Fetch failed:', error);
  }
};
  </code></pre>
</article>

<!-- Different sizes and themes -->
<div class="grid grid-cols-1 md:grid-cols-2 gap-8">
  <!-- Small prose -->
  <article class="prose prose-sm prose-blue">
    <h2>Compact Article</h2>
    <p>This content uses smaller typography for sidebar or compact layouts.</p>
  </article>
  
  <!-- Large prose with dark theme -->
  <article class="prose prose-lg prose-dark bg-gray-900 p-6 rounded-lg">
    <h2>Large Dark Article</h2>
    <p>This content uses larger typography with a dark color scheme.</p>
  </article>
</div>

<!-- Blog post layout -->
<main class="max-w-4xl mx-auto px-4 py-8">
  <article class="prose prose-lg prose-gray mx-auto">
    <header class="mb-8">
      <h1>Building Scalable Design Systems</h1>
      <p class="lead">
        How to create and maintain design systems that grow with your organization.
      </p>
      <div class="flex items-center space-x-4 text-sm text-gray-500">
        <span>By Jane Smith</span>
        <span>•</span>
        <time datetime="2024-01-15">January 15, 2024</time>
        <span>•</span>
        <span>8 min read</span>
      </div>
    </header>
    
    <!-- Article content automatically styled -->
    <h2>Getting Started</h2>
    <p>Design systems are more than just UI component libraries...</p>
  </article>
</main>

Scroll Snap Plugin

Provides utilities for CSS scroll snap functionality, enabling smooth scrolling experiences and carousel-like behavior.

import scrollSnap from "windicss/plugin/scroll-snap";

/**
 * Scroll Snap plugin - no configuration options
 * Adds comprehensive scroll snap utilities
 */

Usage Examples:

import Processor from "windicss";
import scrollSnap from "windicss/plugin/scroll-snap";

const processor = new Processor({
  plugins: [
    scrollSnap
  ]
});

// Generated utilities:
// snap-none - Disable scroll snap
// snap-x - Horizontal scroll snap
// snap-y - Vertical scroll snap
// snap-both - Both directions
// snap-mandatory - Mandatory snapping
// snap-proximity - Proximity snapping
// snap-start - Snap to start of element
// snap-end - Snap to end of element
// snap-center - Snap to center of element

HTML Examples:

<!-- Horizontal scrolling carousel -->
<div class="flex overflow-x-auto snap-x snap-mandatory space-x-4 p-4">
  <div class="flex-none w-80 h-64 bg-blue-500 rounded-lg snap-start"></div>
  <div class="flex-none w-80 h-64 bg-green-500 rounded-lg snap-start"></div>
  <div class="flex-none w-80 h-64 bg-purple-500 rounded-lg snap-start"></div>
  <div class="flex-none w-80 h-64 bg-red-500 rounded-lg snap-start"></div>
</div>

<!-- Vertical scrolling sections -->
<div class="h-screen overflow-y-auto snap-y snap-mandatory">
  <section class="h-screen bg-blue-100 snap-start flex items-center justify-center">
    <h2 class="text-4xl font-bold">Section 1</h2>
  </section>
  <section class="h-screen bg-green-100 snap-start flex items-center justify-center">
    <h2 class="text-4xl font-bold">Section 2</h2>
  </section>
  <section class="h-screen bg-purple-100 snap-start flex items-center justify-center">
    <h2 class="text-4xl font-bold">Section 3</h2>
  </section>
</div>

<!-- Image gallery with center snapping -->
<div class="flex overflow-x-auto snap-x snap-mandatory space-x-2 p-4">
  <img src="image1.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 1">
  <img src="image2.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 2">
  <img src="image3.jpg" class="flex-none w-64 h-48 object-cover rounded snap-center" alt="Image 3">
</div>

<!-- Card carousel with proximity snapping -->
<div class="flex overflow-x-auto snap-x snap-proximity space-x-4 p-4">
  <div class="flex-none w-72 bg-white rounded-lg shadow-md p-6 snap-start">
    <h3 class="font-semibold mb-2">Card 1</h3>
    <p class="text-gray-600">Card content here...</p>
  </div>
  <div class="flex-none w-72 bg-white rounded-lg shadow-md p-6 snap-start">
    <h3 class="font-semibold mb-2">Card 2</h3>
    <p class="text-gray-600">Card content here...</p>
  </div>
</div>

Plugin Usage Best Practices

Examples of using multiple plugins together effectively.

// Comprehensive setup with all plugins
import Processor from "windicss";
import aspectRatio from "windicss/plugin/aspect-ratio";
import filters from "windicss/plugin/filters";
import forms from "windicss/plugin/forms";
import lineClamp from "windicss/plugin/line-clamp";
import typography from "windicss/plugin/typography";
import scrollSnap from "windicss/plugin/scroll-snap";

const processor = new Processor({
  plugins: [
    aspectRatio,
    filters,
    forms,
    lineClamp({
      lines: [1, 2, 3, 4, 5, 6]
    }),
    typography({
      modifiers: ['sm', 'base', 'lg', 'xl'],
      themes: {
        brand: {
          colors: {
            text: '#1f2937',
            headings: '#111827',
            links: '#3b82f6'
          }
        }
      }
    }),
    scrollSnap
  ],
  theme: {
    extend: {
      // Custom theme extensions work with plugins
      typography: {
        DEFAULT: {
          css: {
            maxWidth: 'none',
            color: '#374151'
          }
        }
      }
    }
  }
});

// Complex component using multiple plugins
const blogPostHTML = `
<article class="prose prose-lg prose-brand mx-auto">
  <div class="aspect-video mb-6">
    <img src="hero.jpg" class="w-full h-full object-cover rounded-lg" alt="Hero">
  </div>
  
  <h1 class="line-clamp-2">Very Long Blog Post Title That Might Wrap</h1>
  
  <div class="backdrop-blur-sm bg-blue-500/10 p-4 rounded-lg mb-6">
    <p class="line-clamp-3 text-blue-800">
      This is a highlighted excerpt that provides a preview of the article content.
    </p>
  </div>
  
  <div class="flex overflow-x-auto snap-x snap-mandatory space-x-4 my-8">
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
    <div class="flex-none aspect-square w-48 bg-gray-200 rounded-lg snap-start"></div>
  </div>
  
  <p>Article content continues with beautiful typography...</p>
</article>
`;

Install with Tessl CLI