ply-css 1.4.0 → 1.5.0

package/CLAUDE.md

@@ -7,7 +7,7 @@ This is the ply CSS framework repository. See **PLY.md** for the complete class
 **`ply-classes.json`** is the complete searchable reference. Before writing any custom CSS, search it first:
 
 - **`classes`** — Every ply class with category, description, and examples. Search here before inventing a class name.
-- **`customProperties`** — All 60+ `--ply-*` CSS variables organized by category (typography, background, text, borders, interactive, elevation, brand, palette) with light/dark values. Use these instead of hardcoding colors or font stacks.
+- **`customProperties`** — All 120+ `--ply-*` CSS variables organized by category (typography, background, text, borders, interactive, elevation, brand, palette, color surfaces) with light/dark values. Use these instead of hardcoding colors or font stacks.
 - **`semanticElements`** — Every HTML element ply auto-styles (`<dialog>`, `<details>`, `<table>`, `<code>`, `<kbd>`, `<mark>`, `<progress>`, `<meter>`, etc.) with tips on usage. Check here before building a custom component — ply may already style the native element.
 
 **Rule: If you're about to write custom CSS, search `ply-classes.json` first.** If a class, variable, or semantic element already does what you need, use it.

package/PLY.md

@@ -1,6 +1,6 @@
 # PLY — AI-Ready CSS Framework
 
-ply is a ratio-based, flexbox CSS framework with dark mode, accessibility defaults, and a small footprint (18.5KB gzip full, ~15KB core). 457 utility classes, 100+ CSS custom properties, 13 auto-styled semantic elements.
+ply is a ratio-based, flexbox CSS framework with dark mode, accessibility defaults, and a small footprint (~21KB gzip full, ~17KB core). 457 utility classes, 120+ CSS custom properties, 13 auto-styled semantic elements.
 
 **Differentiators:** Small bundle, AI-parseable class system, accessible out of the box, dark mode built-in.
 
@@ -9,7 +9,7 @@ ply is a ratio-based, flexbox CSS framework with dark mode, accessibility defaul
 **`ply-classes.json`** is the complete searchable reference. Before writing any custom CSS, search it first:
 
 - **`classes`** — Every ply class (457) with category, description, and usage examples. Search here before inventing a class name or writing a custom style.
-- **`customProperties`** — All `--ply-*` CSS variables organized by category (background, text, borders, interactive, forms, code, tables, buttons, navigation, elevation, brand, palette). Each entry includes light and dark mode values. Use these instead of hardcoding colors.
+- **`customProperties`** — All `--ply-*` CSS variables organized by category (background, text, borders, interactive, forms, code, tables, buttons, navigation, elevation, brand, palette, colorSurfaces, spacing). Each entry includes light and dark mode values. Use these instead of hardcoding colors.
 - **`semanticElements`** — Every HTML element ply auto-styles (`<dialog>`, `<details>`, `<table>`, `<code>`, `<kbd>`, `<mark>`, `<progress>`, `<meter>`, headings, form controls) with styling details and usage tips. Check here before building a custom component.
 
 The JSON is the source of truth. If a class, variable, or semantic element already does what you need, use it instead of writing custom CSS.
@@ -55,6 +55,33 @@ See `customProperties` in `ply-classes.json` for the full list of overridable va
 
 ply uses `color-mix()` to auto-compute hover/active button states from your base color. This works in all modern browsers (Chrome 111+, Firefox 113+, Safari 16.4+, Edge 111+). On older browsers (pre-2023), `color-mix()` is ignored and the fallback hex values from ply's default theme are used instead. For custom themes targeting legacy browsers, also set `--ply-btn-default-bg-hover`, `--ply-btn-default-bg-active`, `--ply-btn-secondary-bg-hover`, and `--ply-btn-secondary-bg-active` explicitly. In modern browsers, `color-mix()` overrides these fallbacks automatically.
 
+## Color Surfaces
+
+Theme-aware surface and border colors for building colored cards, badges, and alerts that work in both light and dark mode. Available for all 10 palette colors: blue, red, green, yellow, indigo, purple, pink, orange, teal, cyan.
+
+| Variable | Light Mode | Dark Mode | Use |
+|---|---|---|---|
+| `--ply-{color}-surface` | Pastel | Dark muted | Card/badge background |
+| `--ply-{color}-border` | Light tint | Medium dark | Colored borders |
+| `--ply-{color}-1` | Base | Lighter | Text on surface, icons |
+| `--ply-{color}-2` | Darker | Medium | Emphasis |
+| `--ply-{color}-3` | Darkest | Lightest | Subtle accent |
+
+```css
+/* Theme-aware colored card */
+.card-info {
+  background: var(--ply-blue-surface);
+  border: 1px solid var(--ply-blue-border);
+  color: var(--ply-blue-1);
+}
+
+.card-danger {
+  background: var(--ply-red-surface);
+  border: 1px solid var(--ply-red-border);
+  color: var(--ply-red-1);
+}
+```
+
 ## Philosophy: Start Semantic
 
 ply automatically styles semantic HTML elements — tables, code blocks, blockquotes, navs, details/summary, dialogs, progress bars, meters, forms, and more. Before reaching for a `<div>` with a custom class, check if a semantic element already does what you need. Custom styling is fine when you need it, but start with what HTML and ply give you for free.
@@ -640,7 +667,7 @@ Ready-to-use HTML examples are in the `snippets/` directory:
 
 | Bundle | Includes | Size (gzip) |
 |--------|----------|-------------|
-| `ply.min.css` | Everything | 18.5KB |
+| `ply.min.css` | Everything | ~21KB |
 | `ply-core.min.css` | Grid, buttons, forms, nav, alerts, tables, typography, essential helpers | ~17KB |
-| `ply-essentials.min.css` | Grid, helpers, alignments, blocks only | ~6KB |
-| `ply-helpers.min.css` | Helper utilities only | ~4KB |
+| `ply-essentials.min.css` | Grid, helpers, alignments, blocks only | ~7KB |
+| `ply-helpers.min.css` | Helper utilities only | ~5KB |

package/README.md

@@ -2,7 +2,7 @@
 
 A ratio-based, AI-ready CSS framework with dark mode, accessibility, and a small footprint.
 
-**18.5KB gzipped. No JavaScript. No build step. One `<link>` tag.**
+**~21KB gzipped. No JavaScript. No build step. One `<link>` tag.**
 
 ## Install
 
@@ -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** — 18.5KB gzipped (full), ~15KB (core). No JavaScript runtime, no build step, no tree-shaking.
+- **Small footprint** — ~21KB gzipped (full), ~17KB (core). No JavaScript runtime, no build step, no tree-shaking.
 - **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.
 

package/dist/css/ply-core.css

@@ -70,6 +70,26 @@
   --ply-bg-yellow: #f1c21b;
   --ply-bg-yellow-hover: #d2a106;
   --ply-bg-yellow-active: #b28600;
+  --ply-blue-surface: #d3e3fb;
+  --ply-red-surface: #f8d5d8;
+  --ply-green-surface: #d5ecd9;
+  --ply-yellow-surface: #fff4cc;
+  --ply-indigo-surface: #e0e7ff;
+  --ply-purple-surface: #ede9fe;
+  --ply-pink-surface: #fce7f3;
+  --ply-orange-surface: #ffedd5;
+  --ply-teal-surface: #ccfbf1;
+  --ply-cyan-surface: #cffafe;
+  --ply-blue-border: #92baf6;
+  --ply-red-border: #ef969d;
+  --ply-green-border: #96cfa1;
+  --ply-yellow-border: #ffe480;
+  --ply-indigo-border: #a5b4fc;
+  --ply-purple-border: #c4b5fd;
+  --ply-pink-border: #f9a8d4;
+  --ply-orange-border: #fdba74;
+  --ply-teal-border: #5eead4;
+  --ply-cyan-border: #67e8f9;
   --ply-blue-1: #0f62fe;
   --ply-blue-2: #0043ce;
   --ply-blue-3: #002d9c;
@@ -164,6 +184,26 @@
     --ply-shadow-2: 0 2px 8px rgba(0, 0, 0, 0.3);
     --ply-shadow-3: 0 4px 24px rgba(0, 0, 0, 0.4);
     --ply-bg-glass: rgba(38, 38, 38, 0.25);
+    --ply-blue-surface: #1a2744;
+    --ply-red-surface: #3b1c1e;
+    --ply-green-surface: #1a2e1e;
+    --ply-yellow-surface: #332b10;
+    --ply-indigo-surface: #1e1b4b;
+    --ply-purple-surface: #2e1065;
+    --ply-pink-surface: #3b0a2a;
+    --ply-orange-surface: #331a08;
+    --ply-teal-surface: #132f2e;
+    --ply-cyan-surface: #133040;
+    --ply-blue-border: #1a52a5;
+    --ply-red-border: #b2232f;
+    --ply-green-border: #237f35;
+    --ply-yellow-border: #cca000;
+    --ply-indigo-border: #3730a3;
+    --ply-purple-border: #5b21b6;
+    --ply-pink-border: #9d174d;
+    --ply-orange-border: #c2410c;
+    --ply-teal-border: #0f766e;
+    --ply-cyan-border: #0e7490;
     --ply-bg-blue: #0f62fe;
     --ply-bg-blue-hover: #0043ce;
     --ply-bg-blue-active: #002d9c;
@@ -260,6 +300,26 @@
   --ply-shadow-2: 0 2px 8px rgba(0, 0, 0, 0.3);
   --ply-shadow-3: 0 4px 24px rgba(0, 0, 0, 0.4);
   --ply-bg-glass: rgba(38, 38, 38, 0.25);
+  --ply-blue-surface: #1a2744;
+  --ply-red-surface: #3b1c1e;
+  --ply-green-surface: #1a2e1e;
+  --ply-yellow-surface: #332b10;
+  --ply-indigo-surface: #1e1b4b;
+  --ply-purple-surface: #2e1065;
+  --ply-pink-surface: #3b0a2a;
+  --ply-orange-surface: #331a08;
+  --ply-teal-surface: #132f2e;
+  --ply-cyan-surface: #133040;
+  --ply-blue-border: #1a52a5;
+  --ply-red-border: #b2232f;
+  --ply-green-border: #237f35;
+  --ply-yellow-border: #cca000;
+  --ply-indigo-border: #3730a3;
+  --ply-purple-border: #5b21b6;
+  --ply-pink-border: #9d174d;
+  --ply-orange-border: #c2410c;
+  --ply-teal-border: #0f766e;
+  --ply-cyan-border: #0e7490;
   --ply-bg-blue: #0f62fe;
   --ply-bg-blue-hover: #0043ce;
   --ply-bg-blue-active: #002d9c;