mocha-ui-themes 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+Copyright (c) 2026 Noel C (theme additions)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,20 @@
+# Upstream attribution
+
+This is an independent, opinionated distribution derived from Tailwind CSS 4.3.3.
+It is not an official Tailwind Labs product.
+
+`vendor/tailwindcss/` contains the unmodified published Tailwind CSS distribution,
+including its compiler, types, CSS, package metadata, and original MIT license.
+The exact source version, npm archive integrity, and individual file hashes are
+recorded in `UPSTREAM.json`. Original source is available at:
+https://github.com/tailwindlabs/tailwindcss/tree/v4.3.3
+
+Our changes are the package identity, additive semantic theme layer, opt-in base
+styles, and compatibility tooling. The upstream compiler is intentionally retained
+to preserve existing utility syntax and plugin behavior. `npm run check:upstream`
+checks the vendored distribution before release.
+
+To upgrade: obtain the new upstream release, verify its registry integrity, replace
+the vendor directory and hash manifest, review its export map, align integration
+dependency versions, and run the complete compatibility suite. Do not hand-edit
+the compiled upstream bundles.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# mocha-ui-themes
+
+[![npm version](https://img.shields.io/npm/v/mocha-ui-themes.svg)](https://www.npmjs.com/package/mocha-ui-themes)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](#requirements)
+
+Semantic color themes for Tailwind CSS 4. Keep every utility you already
+use, and add coordinated palettes with light, dark, and system modes, plus
+optional scoped base styling. This initial release derives from
+**Tailwind CSS 4.3.3** and retains its unmodified compiler and public entry
+points (see [NOTICE.md](./NOTICE.md) and [UPSTREAM.json](./UPSTREAM.json)).
+
+## Highlights
+
+- Six coordinated palettes: `ocean` (default), `forest`, `ember`, `gruvbox`,
+  `dracula`, and `catppuccin`.
+- One attribute switches light, dark, or system mode; no utility rewrites.
+- Semantic tokens (`bg-primary`, `text-muted`, `border-danger`, ...) that
+  work with ordinary Tailwind modifiers and opacity.
+- Text/background pairings checked for a 4.5:1 contrast ratio.
+- Optional base styling for buttons, fields, and headings, scoped behind an
+  opt-in attribute.
+- Zero runtime JavaScript; plain CSS custom properties, generated at build
+  time and shipped ready to use.
+
+## Requirements
+
+- Tailwind CSS **4.3.3** and its matching `@tailwindcss/postcss` adapter.
+  Other versions and Vite/CLI integrations are not yet verified.
+- Node.js >= 20 to build or develop the kit; consumers need no build step.
+
+## Install
+
+### Alongside upstream (reversible)
+
+Keep Tailwind as-is and layer the themes on top:
+
+```sh
+npm install -D mocha-ui-themes
+```
+
+```css
+@import "tailwindcss";
+@import "mocha-ui-themes/themes.css";
+```
+
+Only the `--twt-*` custom properties are added by the second import; remove it
+to return to stock Tailwind.
+
+### Drop-in replacement
+
+Install the kit under the `tailwindcss` dependency name to keep existing
+imports, JavaScript plugin imports, and PostCSS configuration untouched:
+
+```sh
+npm install -D tailwindcss@npm:mocha-ui-themes
+```
+
+```css
+@import "tailwindcss";
+```
+
+Keep `@tailwindcss/postcss` at version `4.3.3`. Its compiler dependency may
+install a separate upstream copy; your app's CSS import still resolves to this
+package.
+
+## Usage
+
+Choose a palette and mode on the document root:
+
+```html
+<html data-theme="forest" data-mode="dark">
+```
+
+The default palette is `ocean`. `data-mode="light"` and `data-mode="dark"`
+are explicit overrides; omit `data-mode` to follow the operating system. A
+nested theme island should specify both `data-theme` and `data-mode`
+explicitly.
+
+```html
+<section class="rounded-xl border border-border bg-surface p-6 text-foreground">
+  <p class="text-muted">Your theme changes; these classes stay the same.</p>
+  <button class="rounded-lg bg-primary px-4 py-2 text-primary-foreground hover:bg-primary-hover">
+    Save changes
+  </button>
+</section>
+```
+
+Available color tokens:
+
+| Purpose | Tokens |
+| --- | --- |
+| Surfaces | `background`, `surface`, `surface-raised` |
+| Text and borders | `foreground`, `muted`, `border`, `ring` |
+| Main action | `primary`, `primary-hover`, `primary-foreground` |
+| Secondary action | `secondary`, `secondary-foreground` |
+| Feedback | `success`, `warning`, `danger`, each with a `-foreground` companion |
+
+Tokens work with ordinary Tailwind modifiers, including `hover:bg-primary`,
+`md:text-muted`, and `bg-primary/50`. App-level `@theme` declarations can
+override semantic colors. The common misspelling `catpuccin` is accepted as
+an alias for the Catppuccin palette.
+
+**Theming and Tailwind's `dark:` variant are separate.** `data-mode` switches
+semantic values. The existing `dark:` variant keeps its upstream media-query
+behavior, preserving compatibility.
+
+## Optional base styling
+
+```css
+@import "mocha-ui-themes/base.css";
+```
+
+```html
+<body data-twt-ui>
+  <button>Uses the theme's action styles</button>
+</body>
+```
+
+This opts into heading, button, field, focus, and page defaults. The styles
+live in the base layer, so utility classes can override them. Remove this
+import before switching back to upstream, which does not export `base.css`.
+
+## Compatibility contract
+
+- Existing utility names, palettes, spacing, typography, breakpoints, and
+  Preflight retain their upstream behavior. Default imports add custom
+  properties only.
+- Themes add `bg-primary`, `text-muted`, `border-danger`, and related
+  utilities. They do not redefine classes such as `bg-teal-600` or
+  `rounded-xl`.
+- Base element styling requires both a separate CSS import and `data-twt-ui`.
+- CSS generation is verified against upstream Tailwind 4.3.3: standard
+  variants, palettes, arbitrary values, and utilities generate identical CSS,
+  excluding the new `--twt-*` custom properties.
+
+## Local development
+
+```sh
+npm ci
+npm test
+npm run check:upstream
+npm run demo:build
+```
+
+Open `examples/playground/index.html` after building the demo to switch
+between all six palettes in light, dark, or system mode.
+`npm run demo:check` verifies computed theme colors and controls in a headless
+browser, including system dark mode (set `CHROME_PATH` for a non-default
+Chrome/Chromium installation).
+
+`src/themes.mjs` is the source of truth for palettes; `npm run build`
+regenerates `themes.css`. Generated CSS is included in the npm package, so
+consumers need no theme-generation step.
+
+## Provenance
+
+The compiler is vendored from the verified upstream npm distribution so the
+package is self-contained. See [NOTICE.md](./NOTICE.md) for third-party
+notices and [UPSTREAM.json](./UPSTREAM.json) for provenance and upgrade
+instructions. This is a theme kit release, not a separate compiler
+implementation, and is not affiliated with Tailwind Labs.
+
+## License
+
+MIT. Original Tailwind Labs notices are preserved, with attribution for the
+additional theme work.

package/UPSTREAM.json

@@ -0,0 +1,43 @@
+{
+  "name": "tailwindcss",
+  "version": "4.3.3",
+  "source": "https://github.com/tailwindlabs/tailwindcss/tree/v4.3.3",
+  "tarball": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.3.tgz",
+  "integrity": "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ==",
+  "files": {
+    "dist/chunk-5JIJA4QV.mjs": "c24e6bf22af878f559ed55bf81c6023d0413abd0e7854286944088cb44473149",
+    "dist/chunk-C2OYBFIH.mjs": "4b15bfa07f438749d3512e4e0decfa2acdb4c3268e3293853af51bdf1b0535f4",
+    "dist/chunk-DCG7AFIE.mjs": "b162bd2089f644e13bbd7138a5efe678f837b55e513b51bc9ed0002d64ddd85b",
+    "dist/colors-C__qRT83.d.ts": "dd0d82b8bd458da790d190a58fda615ce8afb4e015ccfafda27765c2639298d1",
+    "dist/colors.d.mts": "ed6ef11fe4001f6089f47361e0574567857514703825ac05872bcaa752df02f1",
+    "dist/colors.d.ts": "af45d2740e699977c3adbf47abb04ff45d3403021931599017b99258510bd567",
+    "dist/colors.js": "1bcf4a87977eb0dd5d97ebb3fa8f86a94960e04432b9bda11cc452680bb3a8a1",
+    "dist/colors.mjs": "7d8ab04dd25d73a352046154acf703317511d870ff9303d3724e09919ef0fd8b",
+    "dist/default-theme.d.mts": "b04171c8fd7a517cb5e6b479b1ca889ea1fdef98c844e32e128407e73e52340e",
+    "dist/default-theme.d.ts": "9804f3cc1f9a20e96f11e9bd08f8ba3b058169f258f9f58acc5d84698e626fe7",
+    "dist/default-theme.js": "147be701807ff7342b81a4f2c8bf63f61515f3a85307d60e4b5a37c1145fe540",
+    "dist/default-theme.mjs": "49ae2de009d4cdaec3c37a09bde834ddbb4692814af448f2f1a52af725de145d",
+    "dist/flatten-color-palette.d.mts": "0cf62ae5406e942c2ec4d1c93c0388cebbbdc01812eb2fc69fd3f8a5fc328ed1",
+    "dist/flatten-color-palette.d.ts": "0cf62ae5406e942c2ec4d1c93c0388cebbbdc01812eb2fc69fd3f8a5fc328ed1",
+    "dist/flatten-color-palette.js": "fc677f08e9e4e7e1f24d580fa622aa11adabdc7a90e9322338ab56c5aabd8cb4",
+    "dist/flatten-color-palette.mjs": "62b5ba008d1566947ed5baa5b162f5d8dbf75f9a6deaba6b09cb79bfac00a359",
+    "dist/lib.d.mts": "cd9a12144f9364eeed4c40b44e2d30cd884467aa7154ab8f379425943e5d39fc",
+    "dist/lib.d.ts": "c3041279151dd9ae22f718f83cd52cbe069b8b994420444ef9fce1e4d0568be3",
+    "dist/lib.js": "934fd25eee4dc84b2bb168b751816bba4c29cc6ed665a86ef6d6594c54da80d8",
+    "dist/lib.mjs": "8ebfd51c44d6cca0ef675007e97e6aa918944df2b662c2d7bfa50fdfaa98bb64",
+    "dist/plugin.d.mts": "423f604a78916e33620f20942748a28ed43c41a968871c4fe41f896ee7a6afaf",
+    "dist/plugin.d.ts": "f9c7de1181bddfe5b8796d22a025e44ca7d4ae069b26b953460aa19fb5d24ef6",
+    "dist/plugin.js": "5564284a5af01cc76f2cfa4e32631ffd58368c167ecac60664b351f895732d19",
+    "dist/plugin.mjs": "3e62ce6dd41a0540dc04af03149fc30f65934c34dd10e3abc57eebc6e6acecb2",
+    "dist/resolve-config-B4yBzhca.d.ts": "171c8fc22d735433308be43d5a01887f3c07efa09b140867df1f331bca380b4d",
+    "dist/resolve-config-QUZ9b-Gn.d.mts": "397e0cbdbbdc4341e7841c3c63d8507c177119abf07532cf276f81fad1da7442",
+    "dist/types-DWdTiksJ.d.mts": "6a4f90e26876d82510869f5c55b6d24fd0fdb69a6b3fe6d53efa35f8f559dae6",
+    "index.css": "175f88737ecb7e033059eac4a3b22a3b5f971d5a05d9fd50811610a0714633b2",
+    "LICENSE": "60e0b68c0f35c078eef3a5d29419d0b03ff84ec1df9c3f9d6e39a519a5ae7985",
+    "package.json": "3dc86b46c511947ca00838aa3f1776243abe923ac347c092e60a0cbc7ae68559",
+    "preflight.css": "ace8310eed6dc5568a56fc16e1d695cf58da7528d81d66d81649e93cce644df6",
+    "README.md": "a7db79d5cd483c6f6d1a51f4042e32598ec39e2391a5dd5be62a71d59299cda8",
+    "theme.css": "443d7af364200f8ec8352dc78e39485a118a1840d498c97967bf0ae402b39167",
+    "utilities.css": "0e5844ec75de2fb4a76097b26bb624bf8f9d9cf59f6d947855b743dd25f920fb"
+  }
+}

package/base.css

@@ -0,0 +1,46 @@
+/* Optional defaults. Import after tailwindcss; opt in with data-twt-ui. */
+@layer base {
+  :where([data-twt-ui]) {
+    color: var(--twt-foreground);
+    background-color: var(--twt-background);
+    accent-color: var(--twt-primary);
+  }
+
+  :where([data-twt-ui]) :is(h1, h2, h3, h4) {
+    font-weight: 700;
+    line-height: 1.2;
+    letter-spacing: -0.025em;
+  }
+
+  :where([data-twt-ui]) :is(button, input, select, textarea) {
+    border-radius: 0.75rem;
+  }
+
+  :where([data-twt-ui]) :is(input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not([type="file"]), select, textarea) {
+    border: 1px solid var(--twt-border);
+    background-color: var(--twt-surface);
+    color: var(--twt-foreground);
+    padding: 0.625rem 0.875rem;
+  }
+
+  :where([data-twt-ui]) button {
+    background-color: var(--twt-primary);
+    color: var(--twt-primary-foreground);
+    padding: 0.625rem 1rem;
+    font-weight: 600;
+  }
+
+  :where([data-twt-ui]) button:not(:disabled):hover {
+    background-color: var(--twt-primary-hover);
+  }
+
+  :where([data-twt-ui]) :is(a, button, input, select, textarea):focus-visible {
+    outline: 2px solid var(--twt-ring);
+    outline-offset: 3px;
+  }
+
+  :where([data-twt-ui]) button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}