@camtomlabs/malix-design-system 0.3.0 → 0.4.1

package/README.md

@@ -46,6 +46,27 @@ Layer cascade order:
 malix-reset  →  malix-tokens  →  malix-components  →  app
 ```
 
+### Using Malix alongside Bootstrap (or other unlayered frameworks)
+
+CSS spec: **unlayered styles always beat layered styles**, regardless of
+source order or specificity. Since Bootstrap, Tailwind Preflight, and most
+legacy CSS frameworks don't use `@layer`, their global `body` rules will
+override Malix's layered reset.
+
+Import the compatibility stylesheet **after** Bootstrap and Malix:
+
+```ts
+import 'bootstrap/dist/css/bootstrap.min.css';
+import '@camtomlabs/malix-design-system/reset.css';   // optional
+import '@camtomlabs/malix-design-system/styles.css';
+import '@camtomlabs/malix-design-system/compat-bootstrap.css'; // ← add this
+```
+
+This file is intentionally unlayered so it wins over Bootstrap's global
+`body { font-family }`, `a { color }`, and heading declarations. It only
+overrides properties where Bootstrap and Malix conflict — it is safe to
+import even if you later remove Bootstrap.
+
 ## Usage
 
 ```tsx
@@ -83,6 +104,13 @@ Sizes: `'xs'` (12px), `'sm'` (14px), `'md'` (16px), `'lg'` (20px), `'xl'` (24px)
 Malix ships an ESLint plugin that catches raw `<button>` and `<input>`
 elements and tells you to use `<Button>` / `<Input>` from the DS.
 
+Install the sibling plugin package alongside the main package so that
+classic ESLint config can resolve `@camtomlabs/malix` automatically:
+
+```bash
+pnpm add -D @camtomlabs/eslint-plugin-malix
+```
+
 ```js
 // .eslintrc.cjs
 module.exports = {
@@ -109,6 +137,11 @@ You can escape the rule with a standard disable comment when needed:
 
 The `no-raw-input` rule allows `type="hidden"` and `type="file"` by default.
 
+> **Legacy subpath export.** The `@camtomlabs/malix-design-system/eslint-plugin`
+> subpath export still works but is considered legacy — classic ESLint
+> configs can't resolve plugin names from subpath exports. Prefer installing
+> `@camtomlabs/eslint-plugin-malix` directly.
+
 ## Theme Provider
 
 Malix includes a React theme provider for managing dark mode:
@@ -232,11 +265,46 @@ import { tokenRegistry } from '@camtomlabs/malix-design-system';
 ### Overlays
 | Component | Description |
 |-----------|-------------|
+| `Dialog` | **Composable modal** with `Dialog.Header` / `Dialog.Body` / `Dialog.Footer` slots. Portal + focus trap + scroll lock + focus restore. Variants: `default \| danger \| warning \| info`. Sizes: `sm \| md \| lg`. **Prefer this for custom modal layouts.** |
+| `ConfirmDialog` | Preset confirm/cancel dialog with title + description + icon. Variants: `default \| danger \| warning \| info`. Use for simple binary confirmations. |
+| `Modal` | Opinionated glass-style modal with fixed header/body/footer preset. Legacy — prefer `Dialog` for new code. |
 | `GlassPopover` | Glassmorphism-styled popover |
-| `Modal` | Full-screen modal dialog |
 | `OnboardingPopover` | Guided onboarding popover |
 | `Overlay` | Backdrop overlay layer |
 
+#### Dialog usage
+
+```tsx
+import { Dialog, Button } from '@camtomlabs/malix-design-system';
+
+function DeleteCatalogDialog({ open, onClose, onDelete }) {
+  return (
+    <Dialog open={open} onClose={onClose} variant="danger" size="sm" role="alertdialog">
+      <Dialog.Header>Delete catalog?</Dialog.Header>
+      <Dialog.Body>
+        This action cannot be undone. All related glosas and flags will be
+        permanently removed.
+      </Dialog.Body>
+      <Dialog.Footer>
+        <Button hierarchy="secondary" onClick={onClose}>Cancel</Button>
+        <Button hierarchy="danger" onClick={onDelete}>Delete</Button>
+      </Dialog.Footer>
+    </Dialog>
+  );
+}
+```
+
+`Dialog` handles all the modal plumbing for you:
+
+- **Portal to `document.body`** — immune to `transform` / `overflow: hidden` ancestors
+- **Focus trap** — Tab cycles within the panel
+- **Escape to close** (disable via `closeOnEsc={false}`)
+- **Backdrop click to close** (disable via `closeOnBackdropClick={false}`)
+- **Body scroll lock** while open
+- **Focus restore** — returns focus to the trigger on close
+- **ARIA wiring** — `aria-labelledby` / `aria-describedby` auto-generated via `useId`
+- **`role="alertdialog"`** opt-in for urgent confirm flows
+
 ### Interactive / Composite
 | Component | Description |
 |-----------|-------------|