ply-css 1.6.1 → 1.7.0

package/CLAUDE.md

@@ -167,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.**
@@ -174,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

@@ -729,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.
 
@@ -132,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);
+});

package/dist/css/ply-core.css

@@ -25,13 +25,16 @@
   --ply-color-link-hover: #0347c6;
   --ply-color-link-hover: color-mix(in oklch, var(--ply-btn-default-bg), black 15%);
   --ply-color-focus: #0f62fe;
-  --ply-color-field-bg: #f4f4f4;
-  --ply-color-input-border: #8d8d8d;
-  --ply-color-input-bg: #f4f4f4;
-  --ply-color-code-bg: #f4f4f4;
-  --ply-color-code-border: #e0e0e0;
-  --ply-color-table-border: #e0e0e0;
-  --ply-color-table-stripped: #f4f4f4;
+  --ply-color-field-bg: var(--ply-bg-surface-alt);
+  --ply-color-input-border: var(--ply-border-strong);
+  --ply-color-input-bg: var(--ply-bg-surface-alt);
+  --ply-color-error: var(--ply-red-1);
+  --ply-color-success: var(--ply-green-1);
+  --ply-color-code-bg: var(--ply-bg-surface-alt);
+  --ply-color-code-border: var(--ply-border-color);
+  --ply-color-table-border: var(--ply-border-color);
+  --ply-color-table-striped: #f4f4f4;
+  --ply-color-table-stripped: var(--ply-color-table-striped);
   --ply-color-table-hovered: #e8e8e8;
   --ply-color-accent: #0353e9;
   --ply-btn-default-bg: #0353e9;
@@ -46,14 +49,14 @@
   --ply-btn-secondary-bg-active: color-mix(in oklch, var(--ply-btn-secondary-bg), black 25%);
   --ply-border-radius: 0.25rem;
   --ply-btn-border-radius: 2rem;
-  --ply-nav-bg: #ffffff;
-  --ply-nav-color: #161616;
-  --ply-nav-border: #161616;
+  --ply-nav-bg: var(--ply-bg-body);
+  --ply-nav-color: var(--ply-color-body);
+  --ply-nav-border: var(--ply-color-body);
   --ply-nav-hover: #e8e8e8;
   --ply-nav-active-color: #525252;
-  --ply-layer-0: #ffffff;
-  --ply-layer-1: #f4f4f4;
-  --ply-layer-2: #e0e0e0;
+  --ply-layer-0: var(--ply-bg-body);
+  --ply-layer-1: var(--ply-bg-surface-alt);
+  --ply-layer-2: var(--ply-bg-muted);
   --ply-layer-3: #c6c6c6;
   --ply-shadow-1: 0 1px 3px rgba(0, 0, 0, 0.08);
   --ply-shadow-2: 0 2px 8px rgba(0, 0, 0, 0.1);
@@ -150,13 +153,8 @@
     --ply-color-link-hover: #619bff;
     --ply-color-link-hover: color-mix(in oklch, #4589ff, white 15%);
     --ply-color-focus: #0f62fe;
-    --ply-color-field-bg: #262626;
-    --ply-color-input-border: #6f6f6f;
-    --ply-color-input-bg: #262626;
-    --ply-color-code-bg: #262626;
-    --ply-color-code-border: #393939;
-    --ply-color-table-border: #393939;
-    --ply-color-table-stripped: #1c1c1c;
+    --ply-color-table-striped: #1c1c1c;
+    --ply-color-table-stripped: var(--ply-color-table-striped);
     --ply-color-table-hovered: #353535;
     --ply-color-accent: #4589ff;
     --ply-btn-default-bg: #0f62fe;
@@ -172,14 +170,8 @@
     --ply-btn-default-color: #fff;
     --ply-btn-secondary-color: #161616;
     --ply-btn-ghost-color: #4589ff;
-    --ply-nav-bg: #161616;
-    --ply-nav-color: #f4f4f4;
-    --ply-nav-border: #f4f4f4;
     --ply-nav-hover: #353535;
     --ply-nav-active-color: #a8a8a8;
-    --ply-layer-0: #161616;
-    --ply-layer-1: #262626;
-    --ply-layer-2: #393939;
     --ply-layer-3: #525252;
     --ply-shadow-1: 0 1px 3px rgba(0, 0, 0, 0.2);
     --ply-shadow-2: 0 2px 8px rgba(0, 0, 0, 0.3);
@@ -266,13 +258,8 @@
   --ply-color-link-hover: #619bff;
   --ply-color-link-hover: color-mix(in oklch, #4589ff, white 15%);
   --ply-color-focus: #0f62fe;
-  --ply-color-field-bg: #262626;
-  --ply-color-input-border: #6f6f6f;
-  --ply-color-input-bg: #262626;
-  --ply-color-code-bg: #262626;
-  --ply-color-code-border: #393939;
-  --ply-color-table-border: #393939;
-  --ply-color-table-stripped: #1c1c1c;
+  --ply-color-table-striped: #1c1c1c;
+  --ply-color-table-stripped: var(--ply-color-table-striped);
   --ply-color-table-hovered: #353535;
   --ply-color-accent: #4589ff;
   --ply-btn-default-bg: #0f62fe;
@@ -288,14 +275,8 @@
   --ply-btn-default-color: #fff;
   --ply-btn-secondary-color: #161616;
   --ply-btn-ghost-color: #4589ff;
-  --ply-nav-bg: #161616;
-  --ply-nav-color: #f4f4f4;
-  --ply-nav-border: #f4f4f4;
   --ply-nav-hover: #353535;
   --ply-nav-active-color: #a8a8a8;
-  --ply-layer-0: #161616;
-  --ply-layer-1: #262626;
-  --ply-layer-2: #393939;
   --ply-layer-3: #525252;
   --ply-shadow-1: 0 1px 3px rgba(0, 0, 0, 0.2);
   --ply-shadow-2: 0 2px 8px rgba(0, 0, 0, 0.3);
@@ -1234,15 +1215,15 @@ meter {
 .req,
 .required {
   font-weight: normal;
-  color: var(--ply-red-1);
+  color: var(--ply-color-error);
 }
 
 .error {
-  color: var(--ply-red-1);
+  color: var(--ply-color-error);
 }
 
 .success {
-  color: var(--ply-green-1);
+  color: var(--ply-color-success);
 }
 
 .text-xs {
@@ -2587,8 +2568,9 @@ table.table-stroked th {
   border-bottom: 1px solid var(--ply-color-table-border, #ccc);
 }
 
+table.table-striped tbody tr:nth-child(odd) td,
 table.table-stripped tbody tr:nth-child(odd) td {
-  background: var(--ply-color-table-stripped, #f8f8f8);
+  background: var(--ply-color-table-striped, var(--ply-color-table-stripped, #f8f8f8));
 }
 
 table.table-hovered tbody tr:hover td {
@@ -3716,16 +3698,16 @@ input.input-error,
 textarea.input-error,
 select.input-error,
 .input-error {
-  border-color: #de2c3b;
-  box-shadow: 0 0 0 2px rgba(222, 44, 59, 0.3), 0 1px 2px rgba(0, 0, 0, 0.2) inset;
+  border-color: var(--ply-color-error);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--ply-color-error) 30%, transparent), 0 1px 2px rgba(0, 0, 0, 0.2) inset;
 }
 
 input.input-success,
 textarea.input-success,
 select.input-success,
 .input-success {
-  border-color: #1a7a32;
-  box-shadow: 0 0 0 2px rgba(26, 122, 50, 0.3), 0 1px 2px rgba(0, 0, 0, 0.2) inset;
+  border-color: var(--ply-color-success);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--ply-color-success) 30%, transparent), 0 1px 2px rgba(0, 0, 0, 0.2) inset;
 }
 
 input.input-gray,