@wpmoo/ui 0.1.0 → 0.2.0

package/README.md

@@ -1,74 +1,201 @@
-# Moo UI
+<p align="center">
+  <img src="https://ui.wpmoo.org/assets/images/readme-hero.webp" alt="Moo UI catalog preview" width="760">
+</p>
+
+<p align="center">
+  <a href="https://github.com/wpmoo-org/ui/actions/workflows/ui-ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/wpmoo-org/ui/ui-ci.yml?branch=main&label=CI"></a>
+  <a href="https://github.com/wpmoo-org/ui"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@wpmoo/ui"><img alt="npm" src="https://img.shields.io/npm/v/@wpmoo/ui?label=npm&logo=npm&color=cb3837"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
+</p>
+
+<p align="center">
+  <strong>Bootstrap markup. shadcn feel.</strong>
+</p>
+
+<p align="center">
+  Keep your Bootstrap 5.3 HTML and behavior. Replace the stylesheet and give
+  your application a calmer, modern product interface without moving to React or
+  Tailwind.
+</p>
+
+<p align="center">
+  <a href="https://ui.wpmoo.org/"><strong>Explore Moo UI »</strong></a>
+</p>
+
+<p align="center">
+  <a href="#try-it-in-30-seconds">Try it in 30 seconds</a> ·
+  <a href="https://www.npmjs.com/package/@wpmoo/ui">View on npm</a> ·
+  <a href="https://github.com/wpmoo-org/ui/issues">Report bug</a>
+</p>
 
-**Bootstrap markup. shadcn feel.**
+# Moo UI
 
-![Moo UI catalog preview](static/images/readme-hero.webp)
+Moo UI is for teams that already like Bootstrap's durability, documented
+components, and server-rendered friendliness, but want their customer portals,
+admin screens, and business applications to feel more like modern SaaS
+software.
 
-Moo UI is a Bootstrap 5.3 component system for teams that want the calm,
-modern feel of shadcn/ui without leaving server-rendered HTML, Bootstrap
-classes, Bootstrap Sass, or Bootstrap JavaScript behind.
+It keeps Bootstrap as the public contract: familiar classes, `data-bs-*`
+behavior, CSS variables, Sass customization, and Bootstrap JavaScript plugins.
+Moo UI changes the visual language around that contract.
 
-It keeps Bootstrap as the public contract, then shapes the catalog, component
-examples, and composed blocks into a quieter product interface language.
+## Try It in 30 Seconds
 
-## Philosophy
+Drop the stylesheet into ordinary Bootstrap markup:
 
-- **Bootstrap is the contract.** Moo UI keeps Bootstrap markup, documented
-  behavior, `data-bs-*` APIs, Sass knobs, and `--bs-*` variables wherever
-  Bootstrap can express the need.
-- **shadcn is the visual language.** Moo UI studies shadcn/ui for restraint,
-  spacing, composition, and state language. It does not copy shadcn source,
-  React code, Tailwind code, Radix code, or example prose.
-- **HTML stays first-class.** Component examples are generated from Jinja
-  macros, so the preview and copyable source share one rendered output.
-- **No framework adoption tax.** The catalog can be browsed, built, and
-  shipped as static HTML without a SPA runtime.
-- **Product shells matter.** Moo UI includes primitives, utilities, and
-  composed blocks for Bootstrap applications that need to feel like modern
-  product software.
+```html
+<link rel="stylesheet"
+      href="https://unpkg.com/@wpmoo/ui@0.2.0/dist/assets/css/moo-ui.css">
 
-## Documentation
+<button type="button" class="btn btn-primary">Create workspace</button>
+```
 
-Browse the catalog at [ui.wpmoo.org](https://ui.wpmoo.org/). Component pages,
-blocks, examples, local development notes, and implementation contracts belong
-in the documentation rather than this README.
+That is the point of Moo UI: your markup still says Bootstrap, but the surface
+feels quieter, sharper, and more product-ready.
 
-## Package
+## Install
 
-The canonical npm package is `@wpmoo/ui`:
+Use the published package when a bundler owns your build:
 
 ```bash
 npm install @wpmoo/ui
 ```
 
-For CDN usage, load the built CSS artifact from the canonical package:
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@wpmoo/ui/dist/assets/css/moo-ui.css">
-```
-
-Bundlers can import the same stylesheet from the package export:
-
 ```js
 import "@wpmoo/ui/moo-ui.css";
 ```
 
-If the shorter `@moo/ui` scope is available to WPMoo, it is reserved as a
-small alias package only. Use `@wpmoo/ui` in documentation, CDN examples, and
-production installs.
+If a page uses Bootstrap plugins such as Dropdown, Tooltip, Popover, Modal,
+Toast, or Offcanvas, load Bootstrap's JavaScript bundle separately through your
+application. Tooltip and Popover also need the initialization Bootstrap
+documents for those plugins.
+
+## Choose an Adoption Path
 
-## Build Outputs
+| Situation | Use | Contract |
+| --- | --- | --- |
+| New page or whole application | `moo-ui.css` | Complete Bootstrap CSS build with Moo UI defaults; use it instead of your existing Bootstrap stylesheet. |
+| Gradual adoption inside an existing Bootstrap app | `moo.css` | Scoped Moo component layer under a `.moo-ui` boundary for gradual adoption inside an existing Bootstrap app. |
 
-The static build emits three CSS artifacts under `dist/assets/css/`:
+## Why Bootstrap Teams Try It
 
-- `moo-ui.css` for the standalone catalog and examples.
-- `catalog.css` for documentation chrome.
-- `moo-core.css` for integrations that need the Moo component surface as an
-  opt-in native `@scope (.moo-ui)` layer.
+- **No frontend rewrite.** Keep server-rendered HTML, Bootstrap classes, and
+  the component behavior your team already knows.
+- **Modern product rhythm.** Buttons, forms, overlays, navigation, data
+  display, and app shells are tuned toward a restrained shadcn-inspired feel.
+- **Inspectable examples.** The catalog is static HTML. Every component page
+  shows rendered examples and copyable markup.
+- **Bootstrap-native customization.** Moo UI uses Bootstrap Sass knobs and
+  `--bs-*` variables wherever Bootstrap can express the need, adding Moo-owned
+  tokens only for gaps Bootstrap does not model.
+- **Practical migration surface.** Start with one page, one scoped area, or a
+  full stylesheet replacement after visual review.
+
+## Philosophy
+
+- **Bootstrap is the contract.** Moo UI keeps Bootstrap markup, documented
+  behavior, Sass knobs, and `--bs-*` variables wherever Bootstrap can express
+  the need.
+- **shadcn is the feeling.** Moo UI studies restraint, rhythm, and product UI
+  sensibility without adopting React, Tailwind, Radix, or shadcn source.
+- **HTML stays first-class.** The catalog is static, inspectable, and friendly
+  to server-rendered applications.
+- **Extensions stay honest.** Moo-owned classes and behavior are added only
+  when Bootstrap has no native component contract for the pattern.
+
+## What Is Included
+
+The live catalog is the source of truth for current coverage:
+
+- [Components](https://ui.wpmoo.org/components/) for actions, forms,
+  data display, feedback, disclosure, overlays, and navigation.
+- [Blocks](https://ui.wpmoo.org/blocks/) for composed application
+  surfaces such as sidebar layouts.
+- A static documentation site that can be inspected without a client-side app
+  runtime.
+
+Representative components include Button, Field, Table, Dialog, Toast, Sheet,
+and Sidebar. More components are being added as the catalog roadmap continues.
+
+## Designed, Not Just Restyled
+
+Moo UI uses original sketch-style previews to show the thinking behind each
+primitive: states, spacing, hierarchy, and the product UI feeling Bootstrap
+projects often need. The README wraps a few of those transparent assets in
+theme-aware surfaces so they stay legible on GitHub.
+
+<p align="center">
+  <a href="https://ui.wpmoo.org/components/button.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/button-dark.svg">
+      <img src="static/images/readme/button-light.svg" alt="Button preview" width="31%">
+    </picture>
+  </a>
+  <a href="https://ui.wpmoo.org/components/dialog.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/dialog-dark.svg">
+      <img src="static/images/readme/dialog-light.svg" alt="Dialog preview" width="31%">
+    </picture>
+  </a>
+  <a href="https://ui.wpmoo.org/components/sidebar.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/sidebar-dark.svg">
+      <img src="static/images/readme/sidebar-light.svg" alt="Sidebar preview" width="31%">
+    </picture>
+  </a>
+  <a href="https://ui.wpmoo.org/components/toast.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/toast-dark.svg">
+      <img src="static/images/readme/toast-light.svg" alt="Toast preview" width="31%">
+    </picture>
+  </a>
+  <a href="https://ui.wpmoo.org/components/sheet.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/sheet-dark.svg">
+      <img src="static/images/readme/sheet-light.svg" alt="Sheet preview" width="31%">
+    </picture>
+  </a>
+  <a href="https://ui.wpmoo.org/components/input.html">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/images/readme/input-dark.svg">
+      <img src="static/images/readme/input-light.svg" alt="Input preview" width="31%">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://ui.wpmoo.org/components/">Browse the full catalog →</a>
+</p>
+
+## Package Boundaries
+
+The npm package distributes compiled CSS and license/notice files. It does not
+ship the catalog's generated preview images, Jinja templates, Sass source, or
+Moo-owned catalog JavaScript.
+
+The source repository contains the static catalog, component templates, build
+tooling, tests, and documentation.
+
+## Development
+
+The catalog is intentionally small-tool friendly:
+
+```bash
+.venv/bin/python build.py
+.venv/bin/python dev.py
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+For developers who prefer npm scripts, the package also exposes:
+
+```bash
+npm run build
+npm run dev
+npm test
+```
 
-The npm package publishes only built component CSS, the optional Bootstrap
-bundle, and license/notice files. WPMoo-owned catalog and preview images are
-not included in the package.
+Browse the local catalog at `http://localhost:4173/` when `dev.py` is running.
 
 ## Licensing
 
@@ -79,5 +206,4 @@ are not covered by the MIT source code license and remain copyright WPMoo, all
 rights reserved.
 
 Vendored third-party material keeps its original license and attribution. See
-`LICENSE`, `LICENSE-MOO-CORE.txt`, `ASSET_LICENSE.md`, and
-`THIRD_PARTY_NOTICES.md`.
+`LICENSE`, `ASSET_LICENSE.md`, and `THIRD_PARTY_NOTICES.md`.