@camtomlabs/malix-design-system 0.2.0 → 0.4.0

package/README.md

@@ -23,11 +23,29 @@ npm install react react-dom
 Import the bundled stylesheet once in your app's entry point (e.g. `main.tsx`, `layout.tsx`, or `_app.tsx`):
 
 ```ts
+// Optional: opt-in reset scoped to @layer malix-reset.
+// Import BEFORE styles.css so the layer order is established correctly.
+import '@camtomlabs/malix-design-system/reset.css';
+
 import '@camtomlabs/malix-design-system/styles.css';
 ```
 
 That's it. All components are styled and ready to use.
 
+### Why the reset is optional
+
+`reset.css` lives inside `@layer malix-reset`, which means **any style you
+write outside a layer will automatically win** — no specificity wars, no
+`:not()` hacks. Use it if your project has a hostile global reset that
+makes CSS Modules fight for background colors; skip it if you already
+have your own reset.
+
+Layer cascade order:
+
+```
+malix-reset  →  malix-tokens  →  malix-components  →  app
+```
+
 ## Usage
 
 ```tsx
@@ -43,6 +61,66 @@ export function MyPage() {
 }
 ```
 
+## Icons
+
+Malix ships a canonical `<Icon>` wrapper that accepts any icon component
+(lucide-react, phosphor-react, custom SVG) and enforces consistent
+sizing and theming via `currentColor`.
+
+```tsx
+import { Icon } from '@camtomlabs/malix-design-system';
+import { Plus, Search, Trash } from 'lucide-react';
+
+<Icon as={Plus} size="md" label="Add item" />       // 16px, aria-label
+<Icon as={Search} size="sm" />                       // decorative (aria-hidden)
+<Icon as={Trash} size="lg" />                        // 20px
+```
+
+Sizes: `'xs'` (12px), `'sm'` (14px), `'md'` (16px), `'lg'` (20px), `'xl'` (24px), or a raw number.
+
+## ESLint Plugin — enforce canonical components
+
+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 = {
+  plugins: ['@camtomlabs/malix'],
+  rules: {
+    '@camtomlabs/malix/no-raw-button': 'warn',
+    '@camtomlabs/malix/no-raw-input': 'warn',
+  },
+};
+```
+
+Or use the recommended preset:
+
+```js
+extends: ['plugin:@camtomlabs/malix/recommended']
+```
+
+You can escape the rule with a standard disable comment when needed:
+
+```tsx
+// eslint-disable-next-line @camtomlabs/malix/no-raw-button
+<button type="submit" form="external-form-id" />
+```
+
+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:
@@ -166,11 +244,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 |
 |-----------|-------------|