ply-css 1.6.0 → 1.7.0

package/CLAUDE.md

@@ -44,6 +44,7 @@ Create a custom theme by defining a `data-theme` value and overriding `--ply-*`
   --ply-color-body: #1a1a1a;
   --ply-color-headings: #78350f;
   --ply-border-color: #fbbf24;
+  --ply-border-radius: 0.375rem;
   --ply-color-accent: #b45309;
   --ply-btn-default-bg: #b45309;  /* Controls btn-primary + links */
   --ply-btn-default-bg-hover: #92400e;
@@ -166,6 +167,20 @@ For quick demos — gives you ply's classes and dark mode, but no Sass variables
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ply-css@1/dist/css/ply.min.css">
 ```
 
+## Tree-Shaking
+
+For production builds, purge unused ply classes with the built-in `ply-purge` CLI or PostCSS plugin. Typical result: ~5KB gzipped per page.
+
+- **PostCSS plugin**: `require('ply-css/purge')` — recommended for build pipelines
+- **CLI**: `npx ply-purge --css <file> --content '<glob>' -o <output>`
+- Auto-safelists dynamically-toggled classes (`active`, `sort-asc`, responsive grid variants)
+
+See PLY.md "Tree-Shaking" section for full usage examples.
+
+## Semantic Color Tokens
+
+Use `--ply-color-error` and `--ply-color-success` for error/success states instead of hardcoding red/green. These tokens are used by `.input-error`, `.input-success`, `.error`, `.success`, `.required`, and multi-step form states. They're themeable via custom `data-theme` overrides.
+
 ## File Structure
 
 - `src/scss/` — SCSS source (modern `@use`/`@forward` modules). **Use this when the project has a build step.**
@@ -173,6 +188,9 @@ For quick demos — gives you ply's classes and dark mode, but no Sass variables
   - `components/_variables.scss` — Spacing, font sizes, breakpoints, border radius
   - `components/_mixins.scss` — Button generator, clearfix, gradients, arrows, animations
 - `dist/css/` — Compiled CSS bundles (for CDN or direct linking)
+- `bin/ply-purge.js` — Standalone CLI for tree-shaking unused CSS
+- `purge.js` — PostCSS plugin for tree-shaking in build pipelines
+- `safelist.js` — Shared safelist for dynamically-toggled classes
 - `PLY.md` — Complete AI instruction file with class reference
 - `ply-classes.json` — Machine-readable class reference
 - `snippets/` — Copy-paste HTML examples

package/PLY.md

@@ -27,6 +27,7 @@ Create a custom theme by defining a `data-theme` value and overriding `--ply-*`
   --ply-color-body: #1a1a1a;
   --ply-color-headings: #78350f;
   --ply-border-color: #fbbf24;
+  --ply-border-radius: 0.375rem;
   --ply-color-accent: #b45309;
   --ply-btn-default-bg: #b45309;
   --ply-btn-default-bg-hover: #92400e;
@@ -355,7 +356,7 @@ See `snippets/responsive-header.html` for a full working example.
 - **`border-top`**, **`border-right`**, **`border-bottom`**, **`border-left`** — Single-side borders.
 - **`border-thick`** — 3px solid border (all sides). Also `border-top-thick`, `border-right-thick`, `border-bottom-thick`, `border-left-thick`.
 - **`no-border`** — Remove all borders. Also `no-border-top`, `no-border-right`, `no-border-bottom`, `no-border-left`.
-- **`border-radius`** — Default border radius. `border-radius-lg` (0.75rem), `border-radius-xl` (1.5rem), `circle` (100%).
+- **`border-radius`** — Uses `var(--ply-border-radius)` (default 0.25rem, themeable). `border-radius-lg`, `border-radius-xl`, `circle` (100%).
 
 ### Other Common Patterns
 
@@ -728,3 +729,39 @@ Ready-to-use HTML examples are in the `snippets/` directory:
 | `ply-core.min.css` | Grid, buttons, forms, nav, alerts, tables, typography, essential helpers | ~17KB |
 | `ply-essentials.min.css` | Grid, helpers, alignments, blocks only | ~7KB |
 | `ply-helpers.min.css` | Helper utilities only | ~5KB |
+
+## Tree-Shaking (Purge Unused CSS)
+
+For production builds, purge unused ply classes to get bundle sizes comparable
+to Tailwind's JIT output (~5KB gzipped for a typical page).
+
+### PostCSS Plugin (recommended for build pipelines)
+
+```sh
+npm install -D @fullhuman/postcss-purgecss
+```
+
+```js
+// postcss.config.js
+const plyPurge = require('ply-css/purge');
+
+module.exports = {
+  plugins: [
+    plyPurge({ content: ['./src/**/*.{html,jsx,tsx,vue}'] }),
+  ],
+};
+```
+
+### CLI (standalone or CI)
+
+```sh
+npm install -D purgecss
+npx ply-purge --css node_modules/ply-css/dist/css/ply.min.css \
+              --content 'src/**/*.{html,jsx,tsx}' \
+              -o public/ply.css
+```
+
+The purge tool auto-safelists dynamically-toggled classes (`active`,
+`sort-asc`, responsive grid variants) so they aren't incorrectly removed.
+Extend the safelist with `--safelist <class>` (CLI) or `safelist` option
+(PostCSS plugin).

package/README.md

@@ -37,7 +37,7 @@ CSS frameworks were designed for humans reading documentation. But increasingly,
 - **Start semantic** — ply automatically styles `<nav>`, `<table>`, `<code>`, `<blockquote>`, `<details>`, `<dialog>`, and more. Start with what HTML gives you, then reach for classes when you need them.
 - **AI-native** — ships with `PLY.md` (AI instruction file) and `ply-classes.json` (machine-readable class reference). Class names are predictable: `.alert-blue`, `.btn-sm`, `.unit-50`.
 - **Accessible by default** — `:focus-visible` outlines on all interactive elements (including `<summary>` and legacy components), `prefers-reduced-motion`, `prefers-color-scheme` dark mode, semantic HTML styling, WCAG AA contrast in both light and dark themes. Published [VPAT 2.5](https://plycss.com/docs/vpat) documenting conformance against all WCAG 2.1 Level A and AA criteria.
-- **Small footprint** — ~21KB gzipped (full), ~17KB (core). No JavaScript runtime, no build step, no tree-shaking.
+- **Small footprint** — ~21KB gzipped (full), ~17KB (core), ~5KB with tree-shaking. No JavaScript runtime, no build step required.
 - **Ratio-based grid** — think in percentages, not arbitrary columns. `unit-50` is 50%, `unit-33` is 33%. Responsive prefixes: `tablet-unit-*`, `phone-unit-*`.
 - **Custom theming** — override `--ply-*` CSS custom properties to create any theme. Light and dark modes built in.
 
@@ -99,6 +99,7 @@ Override `--ply-*` CSS custom properties to create any theme:
   --ply-color-accent: #92400e;     /* Icons, badges, section accents */
   --ply-btn-default-bg: #92400e;   /* Primary button + links */
   --ply-btn-secondary-bg: #78350f; /* Secondary button */
+  --ply-border-radius: 0.375rem;   /* Global border radius */
   --ply-btn-border-radius: 0.5rem; /* Button corner radius */
   --ply-font-body: Palatino, Georgia, serif;
   --ply-font-heading: Palatino, Georgia, serif;
@@ -131,6 +132,54 @@ For AI agents (Claude, Cursor, Copilot, Replit AI):
 
 ply is standalone — it should not be used alongside Tailwind, Bootstrap, or other CSS frameworks.
 
+## Tree-Shaking (Purge Unused CSS)
+
+ply ships all 457 classes in every bundle. For production, you can purge unused
+classes to get Tailwind-level bundle sizes (~5KB gzipped for a typical page).
+
+### PostCSS Plugin
+
+The recommended approach for projects with an existing PostCSS pipeline:
+
+```sh
+npm install -D @fullhuman/postcss-purgecss
+```
+
+```js
+// postcss.config.js
+const plyPurge = require('ply-css/purge');
+
+module.exports = {
+  plugins: [
+    plyPurge({ content: ['./src/**/*.{html,jsx,tsx,vue}'] }),
+  ],
+};
+```
+
+### CLI
+
+For standalone use or CI pipelines:
+
+```sh
+npm install -D purgecss
+npx ply-purge --css node_modules/ply-css/dist/css/ply.min.css \
+              --content 'src/**/*.{html,jsx,tsx}' \
+              -o public/ply.css
+```
+
+### Results
+
+| Scenario | Before | After (gzipped) | Reduction |
+|----------|--------|-----------------|-----------|
+| Single page (card) | 21 KB | ~5 KB | ~75% |
+| All snippets (13 pages) | 21 KB | ~11 KB | ~48% |
+| Real-world app page | 21 KB | ~5.5 KB | ~74% |
+
+The purge tool auto-safelists dynamically-toggled classes (`active`,
+`sort-asc`, etc.) and responsive grid variants so they aren't incorrectly
+removed. Pass additional safelisted classes with `--safelist` (CLI) or the
+`safelist` option (PostCSS).
+
 ## Development
 
 ```sh

package/bin/ply-purge.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * ply-purge — Standalone CLI to tree-shake unused ply CSS.
+ *
+ * Usage:
+ *   npx ply-purge --css dist/css/ply.min.css --content 'src/**\/*.html' -o dist/css/ply.purged.css
+ *   npx ply-purge --css node_modules/ply-css/dist/css/ply.min.css --content 'app/**\/*.tsx' --content 'components/**\/*.tsx'
+ *
+ * Options:
+ *   --css <file>        Input CSS file (required)
+ *   --content <glob>    Content glob to scan for used classes (repeatable, required)
+ *   -o, --output <file> Output file (defaults to <input>.purged.css)
+ *   --safelist <class>  Additional class names to keep (repeatable)
+ *   --json              Print stats as JSON instead of human-readable
+ *   -h, --help          Show help
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const args = process.argv.slice(2);
+
+if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+  console.log(`
+ply-purge — Tree-shake unused ply CSS
+
+Usage:
+  ply-purge --css <file> --content <glob> [-o <output>]
+
+Options:
+  --css <file>         Input CSS file to purge
+  --content <glob>     Glob pattern for content files (repeatable)
+  -o, --output <file>  Output file (default: <name>.purged.css)
+  --safelist <class>   Extra class to preserve (repeatable)
+  --json               Output stats as JSON
+  -h, --help           Show this help
+
+Examples:
+  ply-purge --css node_modules/ply-css/dist/css/ply.min.css \\
+            --content 'src/**/*.{html,jsx,tsx}' \\
+            -o public/ply.css
+
+  ply-purge --css dist/css/ply.min.css \\
+            --content 'app/**/*.tsx' --content 'components/**/*.tsx'
+`.trim());
+  process.exit(0);
+}
+
+function parseArgs(argv) {
+  const result = { content: [], safelist: [], json: false };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--css" && argv[i + 1]) {
+      result.css = argv[++i];
+    } else if (arg === "--content" && argv[i + 1]) {
+      result.content.push(argv[++i]);
+    } else if ((arg === "-o" || arg === "--output") && argv[i + 1]) {
+      result.output = argv[++i];
+    } else if (arg === "--safelist" && argv[i + 1]) {
+      result.safelist.push(argv[++i]);
+    } else if (arg === "--json") {
+      result.json = true;
+    }
+    i++;
+  }
+  return result;
+}
+
+async function main() {
+  const opts = parseArgs(args);
+
+  if (!opts.css) {
+    console.error("Error: --css is required");
+    process.exit(1);
+  }
+  if (opts.content.length === 0) {
+    console.error("Error: at least one --content glob is required");
+    process.exit(1);
+  }
+
+  let PurgeCSS;
+  try {
+    PurgeCSS = require("purgecss").PurgeCSS;
+  } catch {
+    console.error(
+      "ply-purge requires purgecss.\n" +
+        "Install it: npm install -D purgecss"
+    );
+    process.exit(1);
+  }
+
+  const { safelistClasses, safelistPatterns } = require("../safelist");
+
+  const cssPath = path.resolve(opts.css);
+  if (!fs.existsSync(cssPath)) {
+    console.error(`Error: CSS file not found: ${cssPath}`);
+    process.exit(1);
+  }
+
+  const rawCss = fs.readFileSync(cssPath, "utf8");
+  const originalSize = Buffer.byteLength(rawCss, "utf8");
+
+  const purger = new PurgeCSS();
+  const results = await purger.purge({
+    content: opts.content,
+    css: [{ raw: rawCss }],
+    safelist: {
+      standard: [...safelistClasses, ...opts.safelist],
+      deep: safelistPatterns,
+      greedy: [/^:root$/, /^html$/, /^body$/],
+    },
+    defaultExtractor: (content) => {
+      const broadMatches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || [];
+      const innerMatches = content.match(/[^<>"'`\s.(){}[\]#,;]+/g) || [];
+      return [...new Set([...broadMatches, ...innerMatches])];
+    },
+  });
+
+  if (results.length === 0) {
+    console.error("Error: PurgeCSS returned no results");
+    process.exit(1);
+  }
+
+  const purgedCss = results[0].css;
+  const purgedSize = Buffer.byteLength(purgedCss, "utf8");
+
+  const outputPath = opts.output
+    ? path.resolve(opts.output)
+    : cssPath.replace(/(\.\w+)$/, ".purged$1");
+
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, purgedCss, "utf8");
+
+  const reduction = (((originalSize - purgedSize) / originalSize) * 100).toFixed(1);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify({
+        input: opts.css,
+        output: path.relative(process.cwd(), outputPath),
+        originalBytes: originalSize,
+        purgedBytes: purgedSize,
+        reductionPercent: parseFloat(reduction),
+      })
+    );
+  } else {
+    console.log(`ply-purge complete`);
+    console.log(`  Input:     ${opts.css} (${formatBytes(originalSize)})`);
+    console.log(
+      `  Output:    ${path.relative(process.cwd(), outputPath)} (${formatBytes(purgedSize)})`
+    );
+    console.log(`  Reduction: ${reduction}% removed`);
+  }
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});