css-is-awesome 1.1.0

package/public/themes/terminal-dark/theme.css

@@ -0,0 +1,229 @@
+@charset "UTF-8";
+/* ============================================================
+   THEME — Terminal (VT100 CRT Phosphor)
+   -----------------------------------------------------------
+   This is the ONE FILE users swap to reskin their site.
+   Replace this file with any other theme.css to change the
+   entire look & feel. Tokens only — no component CSS lives here.
+
+   TOKEN CONTRACT
+   -----------------------------------------------------------
+   Every theme MUST declare every variable in this file, even
+   if it sets it to a neutral value (e.g. --blur-md: none;).
+   That's what guarantees a clean one-file swap.
+
+   Slots:
+     Surfaces : --paper, --paper-raised, --paper-sunk, --paper-glass
+     Ink      : --ink, --ink-soft, --ink-faint, --graphite, --muted
+     Lines    : --guide, --guide-soft, --hair, --hair-soft
+     Primary  : --ai, --ai-ink, --ai-wash           (cyan — terminal links)
+     Seal     : --shu, --shu-wash                    (error red)
+     Accent   : --ochre, --ochre-wash                (warning amber)
+     Code     : --code-bg/ink/muted/accent/green/blue
+     Type     : --font-display/script/serif/sans/mono
+     Radius   : --r-sm, --r-md, --r-lg
+     Shadow   : --shadow-sm, --shadow-md, --shadow-lg
+     Blur     : --blur-sm, --blur-md, --blur-lg     (glass only; else 'none')
+     Glow     : --glow-sm, --glow-md, --glow-lg     (emphasis / rim / phosphor)
+     Motion   : --duration-fast, --duration-normal, --duration-slow, --ease
+
+   FONT NOTE
+   -----------------------------------------------------------
+   A terminal has no serif and no handwritten script. To keep
+   the contract intact without breaking the mood, every font
+   slot — display, script, serif, sans, mono — points at
+   --font-mono. The contract survives; the CRT stays pure.
+   ============================================================ */
+@import 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=IBM+Plex+Mono:wght@400;500;700&display=swap';
+:root, :root[data-theme=terminal-dark] {
+  color-scheme: dark;
+  /* Surfaces — deep warm black chassis + phosphor haze */
+  --paper: #0A0E0A;
+  --paper-raised: #0F140F;
+  --paper-sunk: #070A07;
+  --paper-glass: rgba(79, 224, 120, 0.06);
+  /* Ink — phosphor green on the tube */
+  --ink: #4FE078;
+  --ink-soft: #2A8B42;
+  --ink-faint: #3DAF4F;
+  --graphite: #1A3D22;
+  --muted: #2A8B42;
+  /* Scanlines / rule lines */
+  --guide: #1E5E2F;
+  --guide-soft: #143618;
+  --hair: #2A8B42;
+  --hair-soft: #1E5E2F;
+  /* Primary accent — cyan (interactive links in a terminal) */
+  --ai: #7FDBFF;
+  --ai-ink: #5AB3D4;
+  --ai-wash: rgba(127, 219, 255, 0.10);
+  /* Seal — error red */
+  --shu: #FF5A5A;
+  --shu-wash: rgba(255, 90, 90, 0.10);
+  /* Accent — warning amber */
+  --ochre: #F0A030;
+  --ochre-wash: rgba(240, 160, 48, 0.10);
+  /* Code surface */
+  --code-bg: #070A07;
+  --code-ink: #4FE078;
+  --code-muted: #2A8B42;
+  --code-accent: #F0A030;
+  --code-green: #8FFCA8;
+  --code-blue: #7FDBFF;
+  /* Typography — mono everywhere (see FONT NOTE in header) */
+  --font-mono: 'JetBrains Mono', 'IBM Plex Mono', 'Fira Code', ui-monospace, Consolas, Menlo, 'Courier New', monospace;
+  --font-sans: var(--font-mono);
+  --font-serif: var(--font-mono);
+  --font-display: var(--font-mono);
+  --font-script: var(--font-mono);
+  /* Radius — a CRT has hard pixel corners */
+  --r-sm: 0;
+  --r-md: 0;
+  --r-lg: 0;
+  /* Shadows — a CRT doesn't cast, it emits. Keep subtle. */
+  --shadow-sm: 0 0 0 1px rgba(79, 224, 120, 0.20);
+  --shadow-md: 0 0 0 1px rgba(79, 224, 120, 0.30), 0 0 12px rgba(79, 224, 120, 0.15);
+  --shadow-lg: 0 0 0 1px rgba(79, 224, 120, 0.40), 0 0 24px rgba(79, 224, 120, 0.25);
+  --shadow-xl: 0 0 0 1px rgba(79, 224, 120, 0.50), 0 0 36px rgba(79, 224, 120, 0.30);
+  --shadow-2xl: 0 0 0 1px rgba(79, 224, 120, 0.60), 0 0 56px rgba(79, 224, 120, 0.40);
+  /* Blur — terminal has no frosted glass; declared so swap stays lossless */
+  --blur-sm: none;
+  --blur-md: none;
+  --blur-lg: none;
+  /* Glow — phosphor halo (this is where the theme sings) */
+  --glow-sm: 0 0 4px rgba(79, 224, 120, 0.25);
+  --glow-md: 0 0 8px rgba(79, 224, 120, 0.35);
+  --glow-lg: 0 0 16px rgba(79, 224, 120, 0.45);
+  /* Motion — terminals are instant */
+  --duration-fast: 100ms;
+  --duration-normal: 140ms;
+  --duration-slow: 220ms;
+  --ease: cubic-bezier(0.2, 0.0, 0.2, 1);
+  /* ----------------------------------------------------------
+     SEMANTIC ALIASES
+     -----------------------------------------------------------
+     Bridge the library's expected names to this theme's native
+     palette. Components can now write m.color(surface-default)
+     or var(--surface-default) and reskin with the theme
+     automatically.
+     ---------------------------------------------------------- */
+  /* Backgrounds (page-level) */
+  --background-default: var(--paper);
+  --background-subtle: var(--paper-sunk);
+  --background-navbar: var(--paper-raised);
+  /* Surfaces */
+  --surface-default: var(--paper);
+  --surface-raised: var(--paper-raised);
+  --surface-sunk: var(--paper-sunk);
+  --surface-muted: var(--paper-sunk);
+  --surface-subtle: var(--paper-raised);
+  --surface-emphasis: var(--ink);
+  --surface-glass: var(--paper-glass);
+  /* Text */
+  --text-primary: var(--ink);
+  --text-secondary: var(--ink-soft);
+  --text-muted: var(--ink-faint);
+  --text-tertiary: var(--muted);
+  --text-inverse: var(--paper);
+  --text-link: var(--ai);
+  --text-link-hover: var(--ai-ink);
+  /* Borders */
+  --border-default: var(--hair);
+  --border-subtle: var(--hair-soft);
+  --border-emphasis: var(--ink);
+  --border-focus: var(--ai);
+  /* Interactive (hover / active wash layers) — phosphor-green translucent overlays */
+  --interactive-hover: rgba(79, 224, 120, 0.08);
+  --interactive-active: rgba(79, 224, 120, 0.15);
+  /* Brand (identity — action-primary usually references these) */
+  --brand-primary: var(--ai);
+  --brand-primary-hover: var(--ai-ink);
+  /* Action (primary / secondary / tertiary) */
+  --action-primary-default: var(--ai);
+  --action-primary-hover: var(--ai-ink);
+  --action-primary-active: var(--ai-ink);
+  --action-primary-wash: var(--ai-wash);
+  --action-secondary-default: var(--shu);
+  --action-secondary-hover: var(--shu);
+  --action-secondary-active: var(--shu);
+  --action-secondary-wash: var(--shu-wash);
+  --action-tertiary-default: var(--ochre);
+  --action-tertiary-hover: var(--ochre);
+  --action-tertiary-active: var(--ochre);
+  --action-tertiary-wash: var(--ochre-wash);
+  /* Feedback / status (high-level semantic) */
+  --feedback-info: var(--ai);
+  --feedback-success: var(--code-green);
+  --feedback-warning: var(--ochre);
+  --feedback-error: var(--shu);
+  /* Status — info (three-part: default / subtle / text) — cyan */
+  --info-default: var(--ai);
+  --info-subtle: rgba(127, 219, 255, 0.12);
+  --info-text: #7FDBFF;
+  /* Status — success — bright phosphor */
+  --success-default: #8FFCA8;
+  --success-subtle: rgba(143, 252, 168, 0.12);
+  --success-text: #8FFCA8;
+  /* Status — warning — amber */
+  --warning-default: var(--ochre);
+  --warning-subtle: rgba(240, 160, 48, 0.12);
+  --warning-text: var(--ochre);
+  /* Status — error — red */
+  --error-default: var(--shu);
+  --error-subtle: rgba(255, 90, 90, 0.12);
+  --error-text: #FF7A7A;
+  /* ----------------------------------------------------------
+     LIBRARY SCALES (space / radius / type / motion / z)
+     -----------------------------------------------------------
+     The library mixins emit var(--space-<key>), var(--radius-<key>),
+     var(--font-primary), var(--font-size-<key>), var(--z-<key>), …
+     Themes declare the slots so those mixins always resolve.
+     ---------------------------------------------------------- */
+  /* Space scale (rem for accessibility — natural scale, same as Sketchbook) */
+  /* Spacing rhythm — THE knob for how dense or airy this theme feels.
+     The numbered scale is the source of truth: every component reads
+     var(--space-N), and the t-shirt aliases (--space-md, --space-lg …)
+     are emitted by the library as references to these, so they follow
+     automatically. Change a value here and the whole page re-proportions.
+     Halve them for a compact UI; raise 4/5/6 for an airy editorial feel. */
+  --space-0: 0; /* flush            */
+  --space-1: 0.5rem; /* tight inner gap  */
+  --space-2: 0.75rem; /* control padding  */
+  --space-3: 0.875rem; /* (no t-shirt)     */
+  --space-4: 1rem; /* default rhythm   */
+  --space-5: 1.5rem; /* section gap      */
+  --space-6: 2rem; /* block gap        */
+  --space-7: 3rem; /* major gap        */
+  --space-8: 4rem; /* page section     */
+  --space-9: 6rem; /* hero rhythm      */
+  /* Radius alias — CRT has hard pixel corners, so every slot is 0 */
+  --radius-sm: 0;
+  --radius-md: 0;
+  --radius-lg: 0;
+  --radius-xl: 0;
+  --radius-full: 0;
+  /* Typography — mono body + key scale slots (15px matches CRT body setting) */
+  --font-primary: var(--font-mono);
+  --font-size-base: 15px;
+  --line-height-normal: 1.5;
+  --font-weight-medium: 500;
+  /* Z-index layers (layering is universal) */
+  --z-sticky: 1020;
+  --z-dropdown: 1030;
+  --z-backdrop: 1040;
+  --z-modal: 1050;
+  --z-popover: 1060;
+  --z-tooltip: 1070;
+  /* ----------------------------------------------------------
+     OPTIONAL COMPONENT OVERRIDES (Feature 1.3)
+     -----------------------------------------------------------
+     Terminal-specific component expressions: zero radii on
+     buttons/cards/inputs and a subtle phosphor glow on cards
+     instead of a drop shadow.
+     ---------------------------------------------------------- */
+  --btn-radius: 0;
+  --card-radius: 0;
+  --input-radius: 0;
+  --card-shadow: var(--glow-sm);
+  --card-border: 1px solid var(--ink-faint);
+}

package/public/themes/terminal-light/theme.css

@@ -0,0 +1,152 @@
+@charset "UTF-8";
+@import 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=IBM+Plex+Mono:wght@400;500;700&display=swap';
+:root, :root[data-theme=terminal-light] {
+  color-scheme: light;
+  /* Surfaces — clear light gray paper */
+  --paper: #E8E8E8;
+  --paper-raised: #F5F5F5;
+  --paper-sunk: #D8D8D8;
+  --paper-glass: rgba(232, 232, 232, 0.85);
+  /* Ink — near-black mono */
+  --ink: #1A1A1A;
+  --ink-soft: #404040;
+  --ink-faint: #666;
+  --graphite: #0A0A0A;
+  --muted: #7C7C7C;
+  /* Hairlines — medium gray */
+  --guide: #B8B8B8;
+  --guide-soft: #C8C8C8;
+  --hair: #C0C0C0;
+  --hair-soft: #D8D8D8;
+  /* Primary accent — VS Code keyword blue */
+  --ai: #0451A5;
+  --ai-ink: #023268;
+  --ai-wash: rgba(4, 81, 165, 0.10);
+  /* Seal — error red */
+  --shu: #B91C1C;
+  --shu-wash: rgba(185, 28, 28, 0.10);
+  /* Accent — warning amber */
+  --ochre: #B45309;
+  --ochre-wash: rgba(180, 83, 9, 0.10);
+  /* Code surface */
+  --code-bg: #DDD;
+  --code-ink: #1A1A1A;
+  --code-muted: #5B5B5B;
+  --code-accent: #934407;
+  --code-green: #006A28;
+  --code-blue: #0451A5;
+  /* Typography — mono everywhere */
+  --font-mono: 'JetBrains Mono', 'IBM Plex Mono', 'Fira Code', ui-monospace, Consolas, Menlo, 'Courier New', monospace;
+  --font-sans: var(--font-mono);
+  --font-serif: var(--font-mono);
+  --font-display: var(--font-mono);
+  --font-script: var(--font-mono);
+  /* Radius — terminals are square */
+  --r-sm: 0;
+  --r-md: 0;
+  --r-lg: 0;
+  /* Shadows — hairline rings */
+  --shadow-sm: 0 0 0 1px rgba(26, 26, 26, 0.08);
+  --shadow-md: 0 0 0 1px rgba(26, 26, 26, 0.10), 0 1px 2px rgba(26, 26, 26, 0.06);
+  --shadow-lg: 0 0 0 1px rgba(26, 26, 26, 0.12), 0 2px 4px rgba(26, 26, 26, 0.08);
+  --shadow-xl: 0 0 0 1px rgba(26, 26, 26, 0.14), 0 4px 8px rgba(26, 26, 26, 0.10);
+  --shadow-2xl: 0 0 0 1px rgba(26, 26, 26, 0.16), 0 8px 16px rgba(26, 26, 26, 0.12);
+  /* Blur / glow — daylight, no emission */
+  --blur-sm: none;
+  --blur-md: none;
+  --blur-lg: none;
+  --glow-sm: 0 0 0 transparent;
+  --glow-md: 0 0 0 transparent;
+  --glow-lg: 0 0 0 transparent;
+  /* Motion — instant */
+  --duration-fast: 100ms;
+  --duration-normal: 140ms;
+  --duration-slow: 220ms;
+  --ease: cubic-bezier(0.2, 0.0, 0.2, 1);
+  /* Semantic aliases */
+  --background-default: var(--paper);
+  --background-subtle: var(--paper-sunk);
+  --background-navbar: var(--paper-raised);
+  --surface-default: var(--paper);
+  --surface-raised: var(--paper-raised);
+  --surface-sunk: var(--paper-sunk);
+  --surface-muted: var(--paper-sunk);
+  --surface-subtle: var(--paper-raised);
+  --surface-emphasis: var(--ink);
+  --surface-glass: var(--paper-glass);
+  --text-primary: var(--ink);
+  --text-secondary: var(--ink-soft);
+  --text-muted: var(--ink-faint);
+  --text-tertiary: var(--muted);
+  --text-inverse: var(--paper);
+  --text-link: var(--ai);
+  --text-link-hover: var(--ai-ink);
+  --border-default: var(--hair);
+  --border-subtle: var(--hair-soft);
+  --border-emphasis: var(--ink);
+  --border-focus: var(--ai);
+  --interactive-hover: rgba(26, 26, 26, 0.05);
+  --interactive-active: rgba(26, 26, 26, 0.10);
+  --brand-primary: var(--ai);
+  --brand-primary-hover: var(--ai-ink);
+  --action-primary-default: var(--ai);
+  --action-primary-hover: var(--ai-ink);
+  --action-primary-active: var(--ai-ink);
+  --action-primary-wash: var(--ai-wash);
+  --action-secondary-default: var(--shu);
+  --action-secondary-hover: var(--shu);
+  --action-secondary-active: var(--shu);
+  --action-secondary-wash: var(--shu-wash);
+  --action-tertiary-default: var(--ochre);
+  --action-tertiary-hover: var(--ochre);
+  --action-tertiary-active: var(--ochre);
+  --action-tertiary-wash: var(--ochre-wash);
+  --feedback-info: var(--ai);
+  --feedback-success: #083;
+  --feedback-warning: var(--ochre);
+  --feedback-error: var(--shu);
+  --info-default: var(--ai);
+  --info-subtle: rgba(4, 81, 165, 0.10);
+  --info-text: var(--ai-ink);
+  --success-default: #083;
+  --success-subtle: rgba(0, 136, 51, 0.10);
+  --success-text: #062;
+  --warning-default: var(--ochre);
+  --warning-subtle: rgba(180, 83, 9, 0.10);
+  --warning-text: #92400E;
+  --error-default: var(--shu);
+  --error-subtle: rgba(185, 28, 28, 0.10);
+  --error-text: #7F1D1D;
+  /* Library scales */
+  /* Spacing rhythm — THE knob for how dense or airy this theme feels.
+     The numbered scale is the source of truth: every component reads
+     var(--space-N), and the t-shirt aliases (--space-md, --space-lg …)
+     are emitted by the library as references to these, so they follow
+     automatically. Change a value here and the whole page re-proportions.
+     Halve them for a compact UI; raise 4/5/6 for an airy editorial feel. */
+  --space-0: 0; /* flush            */
+  --space-1: 0.5rem; /* tight inner gap  */
+  --space-2: 0.75rem; /* control padding  */
+  --space-3: 0.875rem; /* (no t-shirt)     */
+  --space-4: 1rem; /* default rhythm   */
+  --space-5: 1.5rem; /* section gap      */
+  --space-6: 2rem; /* block gap        */
+  --space-7: 3rem; /* major gap        */
+  --space-8: 4rem; /* page section     */
+  --space-9: 6rem; /* hero rhythm      */
+  --radius-sm: 0;
+  --radius-md: 0;
+  --radius-lg: 0;
+  --radius-xl: 0;
+  --radius-full: 0;
+  --font-primary: var(--font-mono);
+  --font-size-base: 15px;
+  --line-height-normal: 1.5;
+  --font-weight-medium: 500;
+  --z-sticky: 1020;
+  --z-dropdown: 1030;
+  --z-backdrop: 1040;
+  --z-modal: 1050;
+  --z-popover: 1060;
+  --z-tooltip: 1070;
+}

package/scripts/README.md

@@ -0,0 +1,70 @@
+# scripts
+
+Small Node utilities that support the css-is-awesome workflow. No runtime deps.
+
+## theme-validator.js
+
+Checks a `theme.css` against the token contract **and** runs a WCAG 2.2 AA
+contrast audit on every theme. Every theme MUST declare every required custom
+property so the "swap one file, reskin the site" model stays lossless, and
+every audited contrast pair must meet AA so the system stays accessible by
+default.
+
+### Run
+
+```bash
+# Validate every theme (public/theme.css + public/themes/*/theme.css)
+npm run validate-themes
+
+# Validate a specific file
+node scripts/theme-validator.js public/themes/graphite-dark/theme.css
+```
+
+### Flags
+
+| Flag                  | Effect                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------- |
+| `--all`               | Validate every `theme.css` under `public/` (CI mode)                                            |
+| `--no-a11y`           | Skip the WCAG 2.2 AA contrast audit; contract check only                                        |
+| `--allow-a11y-fail`   | Run the audit and report a11y FAILs, but do not exit non-zero on them (downgrade to soft)        |
+| `--strict`            | Accepted as a **no-op** for backwards compatibility. A11y FAIL is now the default behaviour     |
+
+### Output
+
+```
+✓ public/theme.css passes (78 tokens declared)
+x public/themes/<name>/theme.css — 2 missing:
+     --text-link
+     --border-focus
+```
+
+The a11y audit prints a per-theme line with `pass / warn / info / fail`
+counts plus a one-liner per non-passing pair. Pairs flagged `decorative`
+(currently `--border-default`) are reported as `info` with their actual
+contrast ratio but never count as a FAIL — WCAG 2.2 SC 1.4.11 applies only to
+graphical objects essential for understanding content.
+
+### Exit codes
+
+| Code | Meaning                                                                                       |
+| ---- | --------------------------------------------------------------------------------------------- |
+| `0`  | Every file/block declares every required contract token AND all audited pairs meet WCAG 2.2 AA (or `--allow-a11y-fail` was passed) |
+| `1`  | One or more files/blocks missing tokens (always fatal), OR an a11y FAIL (default as of v0.7)  |
+| `2`  | Usage error (file not found, bad args)                                                        |
+
+### Contract
+
+The authoritative required-token list lives in `scripts/theme-contract.json`.
+It mirrors the `:root { ... }` block in `public/theme.css` (Sketchbook — the
+reference theme). When the contract changes, update that JSON file, not the
+validator.
+
+The audited contrast pairs live in `scripts/theme-a11y.js` (`AUDIT_PAIRS`).
+A pair carrying `decorative: true` is reported as `info` rather than `fail`
+when it dips below its target ratio.
+
+### CI
+
+Wired into `.github/workflows/ci.yml` via `npm run validate-themes`. A PR
+that introduces an incomplete theme **or** an AA contrast regression on any
+audited pair fails before merge.

package/scripts/icon-contract.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "./icon-contract.schema (informal)",
+  "version": "1",
+  "description": "Canonical icon pack contract. Every pack must declare every glyph in its `glyphs` list. The icon-validator (scripts/icon-validator.js) enforces completeness.",
+  "packs": {
+    "core": {
+      "description": "UI essentials. Bundled with css-is-awesome under public/icons/core/. Source: Lucide (ISC + MIT, see LICENSE-third-party).",
+      "glyphs": [
+        "arrow-right",
+        "check",
+        "chevron-down",
+        "close",
+        "download",
+        "edit",
+        "menu",
+        "search",
+
+        "arrow-left",
+        "arrow-up",
+        "arrow-down",
+        "chevron-up",
+        "chevron-left",
+        "chevron-right",
+        "external-link",
+        "home",
+
+        "upload",
+        "copy",
+        "share",
+        "trash",
+        "save",
+        "refresh",
+        "settings",
+        "filter",
+        "sort",
+        "plus",
+        "minus",
+        "more-horizontal",
+
+        "info",
+        "warning",
+        "error",
+        "success",
+        "help",
+        "loading",
+
+        "mail",
+        "bell",
+        "calendar",
+        "clock",
+        "message",
+
+        "user",
+        "users",
+        "lock",
+        "unlock",
+        "eye",
+        "eye-off",
+
+        "play",
+        "pause",
+        "star",
+        "heart"
+      ]
+    }
+  }
+}