@deskhero/dh_ui 2.58.0 → 2.59.1

package/.ai/CSS-CLASSES-GUIDE.md

@@ -0,0 +1,317 @@
+# CSS utility classes – AI development guide
+
+This guide documents the utility classes and **color tokens** from the design system. Use these classes and variables in templates and components instead of writing one-off CSS or hardcoded hex colors. The guide is **exportable**: use it in other codebases that consume the same `colors.scss` (or equivalent `:root` variables).
+
+**Source files:**
+- `src/styles/flex.scss` – flexbox layout
+- `src/styles/colorize.scss` – text/background color classes (design tokens)
+- `src/styles/colors.scss` – color palette variables (all `--dh-*` shades and filters)
+- `src/styles/spacing.scss` – margin, padding, gap, width, height
+
+---
+
+## 1. Flex utilities (`flex.scss`)
+
+Tailwind-inspired flexbox classes. Combine with spacing classes (e.g. `gap-spacer-2`, `m-spacer-2`) for layout.
+
+### Display
+| Class          | Effect            |
+|----------------|-------------------|
+| `flex`         | `display: flex`   |
+| `inline-flex`  | `display: inline-flex` |
+
+### Direction
+| Class                | Effect                    |
+|----------------------|---------------------------|
+| `flex-row`           | `flex-direction: row`     |
+| `flex-row-reverse`   | `flex-direction: row-reverse` |
+| `flex-column`        | `flex-direction: column`  |
+| `flex-column-reverse`| `flex-direction: column-reverse` |
+
+### Wrap
+| Class             | Effect                 |
+|-------------------|------------------------|
+| `flex-wrap`       | `flex-wrap: wrap`      |
+| `flex-nowrap`     | `flex-wrap: nowrap`    |
+| `flex-wrap-reverse` | `flex-wrap: wrap-reverse` |
+
+### Flex (grow/shrink/basis)
+| Class         | Effect           |
+|---------------|------------------|
+| `flex-1`      | `flex: 1 1 0%`   |
+| `flex-auto`   | `flex: 1 1 auto` |
+| `flex-initial`| `flex: 0 1 auto` |
+| `flex-none`   | `flex: none`     |
+
+### Justify content
+| Class           | Effect                      |
+|-----------------|-----------------------------|
+| `justify-start` | `justify-content: flex-start` |
+| `justify-end`   | `justify-content: flex-end`   |
+| `justify-center`| `justify-content: center`     |
+| `justify-between` | `justify-content: space-between` |
+| `justify-around`  | `justify-content: space-around`  |
+| `justify-evenly`  | `justify-content: space-evenly`  |
+
+### Align items
+| Class          | Effect                   |
+|----------------|--------------------------|
+| `items-start`  | `align-items: flex-start` |
+| `items-end`    | `align-items: flex-end`   |
+| `items-center` | `align-items: center`     |
+| `items-baseline` | `align-items: baseline`   |
+| `items-stretch`  | `align-items: stretch`    |
+
+### Align self
+| Class          | Effect                  |
+|----------------|-------------------------|
+| `self-auto`    | `align-self: auto`      |
+| `self-start`   | `align-self: flex-start`|
+| `self-end`     | `align-self: flex-end`  |
+| `self-center`  | `align-self: center`    |
+| `self-stretch` | `align-self: stretch`   |
+| `self-baseline`| `align-self: baseline`  |
+
+### Order
+| Class        | Effect      |
+|--------------|-------------|
+| `order-first`| `order: -9999` |
+| `order-last` | `order: 9999`  |
+| `order-none` | `order: 0`    |
+| `order-1` … `order-12` | `order: 1` … `order: 12` |
+
+**Example:**
+```html
+<div class="flex flex-row items-center justify-between gap-spacer-2">
+  <span>Left</span>
+  <span>Right</span>
+</div>
+<div class="flex flex-column flex-wrap gap-spacer-4">
+  <!-- stacked, wrapping column -->
+</div>
+```
+
+---
+
+## 2. Color utilities (`colorize.scss`)
+
+Uses design tokens (`--dh-*`). Prefer these over hardcoded colors.
+
+### Color attribute (on any element)
+Set the `color` **attribute** (not class) for semantic text color:
+
+| Attribute value       | Maps to variable      |
+|-----------------------|------------------------|
+| `color="primary"`     | `--dh-primary`         |
+| `color="secondary"`   | `--dh-text-secondary`  |
+| `color="secondary-lighter"` | `--dh-text-secondary-lighter` |
+| `color="danger"`      | `--dh-danger`          |
+| `color="success"`     | `--dh-success`         |
+| `color="warning"`     | `--dh-warning`         |
+| `color="purple"`      | `--dh-purple`          |
+
+**Example:** `<span color="danger">Error message</span>`
+
+### Text color classes (`.text-*`)
+| Class                  | Maps to variable           |
+|------------------------|----------------------------|
+| `text-primary`         | `--dh-text-primary`        |
+| `text-secondary`       | `--dh-text-secondary`      |
+| `text-secondary-lighter` | `--dh-text-secondary-lighter` |
+| `text-disabled`        | `--dh-text-disabled`       |
+| `text-warning`        | `--dh-warning`             |
+| `text-purple`          | `--dh-purple`              |
+| `text-success`         | `--dh-success`             |
+| `text-danger`          | `--dh-danger`              |
+
+### Background color classes (`.bg-color-*`)
+| Class                 | Maps to variable            |
+|-----------------------|-----------------------------|
+| `bg-color-primary`    | `--dh-bg-primary`           |
+| `bg-color-secondary`  | `--dh-text-secondary`       |
+| `bg-color-secondary-lighter` | `--dh-text-secondary-lighter` |
+| `bg-color-disabled`   | `--dh-text-disabled`        |
+| `bg-color-warning`    | `--dh-warning-lighter`      |
+| `bg-color-purple`     | `--dh-purple-lighter`       |
+| `bg-color-success`    | `--dh-success-lighter`      |
+| `bg-color-danger`     | `--dh-danger-lighter`       |
+
+**Example:**
+```html
+<p class="text-secondary">Hint text</p>
+<div class="bg-color-success text-primary">Success state</div>
+```
+
+---
+
+## 3. Color tokens (`colors.scss`) – full reference
+
+Base color scales are defined as CSS variables in `src/styles/colors.scss`. Each scale has **10 steps**: **-1** = darkest, **-10** = lightest. Use these variables in any codebase that consumes the design system; do not hardcode hex.
+
+**Source:** `src/styles/colors.scss` (ensure this file or its compiled output is loaded so `:root` variables are available.)
+
+### 3.1 Palette scales (variable → hex)
+
+| Variable | Hex | Variable | Hex | Variable | Hex | Variable | Hex | Variable | Hex |
+|----------|-----|----------|-----|----------|-----|----------|-----|----------|-----|
+| **Burgundy** | | | | | | | | | |
+| `--dh-burgundy-1` | #660033 | `--dh-burgundy-2` | #944c70 | `--dh-burgundy-3` | #c299a9 | `--dh-burgundy-4` | #f0e5eb | `--dh-burgundy-5` | #f9f2f5 |
+| `--dh-burgundy-6` | #fcf5f8 | `--dh-burgundy-7` | #fefafd | `--dh-burgundy-8` | #fff5f9 | `--dh-burgundy-9` | #fffbfe | `--dh-burgundy-10` | #ffffff |
+| **Pink** | | | | | | | | | |
+| `--dh-pink-1` | #ff668f | `--dh-pink-2` | #ff7fa7 | `--dh-pink-3` | #ff95af | `--dh-pink-4` | #ffdbe0 | `--dh-pink-5` | #ffc3d1 |
+| `--dh-pink-6` | #ffeaeb | `--dh-pink-7` | #fff1f2 | `--dh-pink-8` | #f0e5eb | `--dh-pink-9` | #ffffff | `--dh-pink-10` | #ffffff |
+| **Gray** | | | | | | | | | |
+| `--dh-gray-1` | #808080 | `--dh-gray-2` | #999999 | `--dh-gray-3` | #b3b3b3 | `--dh-gray-4` | #cccccc | `--dh-gray-5` | #dddddd |
+| `--dh-gray-6` | #e5e5e5 | `--dh-gray-7` | #f0f0f0 | `--dh-gray-8` | #f2f2f2 | `--dh-gray-9` | #f5f5f5 | `--dh-gray-10` | #ffffff |
+| **Yellow** | | | | | | | | | |
+| `--dh-yellow-1` | #e1a400 | `--dh-yellow-2` | #e6b000 | `--dh-yellow-3` | #ebbc00 | `--dh-yellow-4` | #f0c800 | `--dh-yellow-5` | #f5d300 |
+| `--dh-yellow-6` | #FCDE02 | `--dh-yellow-7` | #ffcf56 | `--dh-yellow-8` | #ffda79 | `--dh-yellow-9` | #ffe59c | `--dh-yellow-10` | #fff1c2 |
+| **Red** | | | | | | | | | |
+| `--dh-red-1` | #c32f27 | `--dh-red-2` | #d9332e | `--dh-red-3` | #ef3835 | `--dh-red-4` | #f53c3b | `--dh-red-5` | #fb4040 |
+| `--dh-red-6` | #ff4444 | `--dh-red-7` | #ff4848 | `--dh-red-8` | #ff4c4c | `--dh-red-9` | #ff5050 | `--dh-red-10` | #ff8e88 |
+| **Blue** | | | | | | | | | |
+| `--dh-blue-1` | #0a4f7f | `--dh-blue-2` | #0f71b4 | `--dh-blue-3` | #177fc2 | `--dh-blue-4` | #1e8bd6 | `--dh-blue-5` | #3497de |
+| `--dh-blue-6` | #5ea9e5 | `--dh-blue-7` | #8cc4f0 | `--dh-blue-8` | #c2e0f7 | `--dh-blue-9` | #e3f0fb | `--dh-blue-10` | #f5f9ff |
+| **Green** | | | | | | | | | |
+| `--dh-green-1` | #146233 | `--dh-green-2` | #18753c | `--dh-green-3` | #1d8245 | `--dh-green-4` | #289b54 | `--dh-green-5` | #37b866 |
+| `--dh-green-6` | #5fd287 | `--dh-green-7` | #9de9b5 | `--dh-green-8` | #dcf5e0 | `--dh-green-9` | #f1fbf3 | `--dh-green-10` | #ffffff |
+| **Orange** | | | | | | | | | |
+| `--dh-orange-1` | #8a5707 | `--dh-orange-2` | #a36508 | `--dh-orange-3` | #cd7f0a | `--dh-orange-4` | #e2910d | `--dh-orange-5` | #f2a836 |
+| `--dh-orange-6` | #f6b75e | `--dh-orange-7` | #f8c887 | `--dh-orange-8` | #f3cca8 | `--dh-orange-9` | #ffe6cf | `--dh-orange-10` | #fff7eb |
+| **Purple** | | | | | | | | | |
+| `--dh-purple-1` | #5f2a9b | `--dh-purple-2` | #7633c0 | `--dh-purple-3` | #8642cf | `--dh-purple-4` | #9b51e0 | `--dh-purple-5` | #a968e4 |
+| `--dh-purple-6` | #bc84ea | `--dh-purple-7` | #d8b6f4 | `--dh-purple-8` | #f0e0fb | `--dh-purple-9` | #fff5f4 | `--dh-purple-10` | #ffffff |
+| **Surface** (dark → light neutrals) | | | | | | | | | |
+| `--dh-surface-1` | #121212 | `--dh-surface-2` | #2b2a2a | `--dh-surface-3` | #333333 | `--dh-surface-4` | #444444 | `--dh-surface-5` | #555555 |
+| `--dh-surface-6` | #666666 | `--dh-surface-7` | #777777 | `--dh-surface-8` | #888888 | `--dh-surface-9` | #999999 | `--dh-surface-10` | #aaaaaa |
+| **Surface contrast** (dark → light; use on dark UIs) | | | | | | | | | |
+| `--dh-surface-contrast-10` | #555555 | `--dh-surface-contrast-9` | #666666 | `--dh-surface-contrast-8` | #777777 | `--dh-surface-contrast-7` | #888888 | `--dh-surface-contrast-6` | #999999 |
+| `--dh-surface-contrast-5` | #aaaaaa | `--dh-surface-contrast-4` | #bbbbbb | `--dh-surface-contrast-3` | #cccccc | `--dh-surface-contrast-2` | #dddddd | `--dh-surface-contrast-1` | #eeeeee |
+
+### 3.2 Filter variables (for SVG/icons)
+
+Use as `filter: var(--dh-*);` to tint icons or images. Values are CSS `filter()` functions.
+
+| Variable | Use case |
+|----------|----------|
+| `--dh-white-filter` | Icon as white (e.g. on dark background) |
+| `--dh-burgundy-filter` | Icon in burgundy |
+| `--dh-filter-blue` | Icon in primary blue |
+| `--dh-filter-red` | Icon in danger/red |
+| `--dh-filter-gray` | Icon in gray |
+| `--dh-filter-yellow` | Icon in yellow |
+| `--dh-filter-pink` | Icon in pink |
+| `--dh-filter-light` | Slightly brighter |
+| `--dh-filter-lighter` | Much brighter |
+| `--dh-filter-white` | Force white |
+
+### 3.3 Quick lookup by intent
+
+| Intent | Prefer these variables |
+|--------|-------------------------|
+| Primary / links / focus | `--dh-primary` (or `--dh-blue-2`, `--dh-blue-4`, `--dh-blue-6`) |
+| Success / positive | `--dh-success` (or `--dh-green-3`, `--dh-green-8`, `--dh-green-9`) |
+| Danger / error | `--dh-danger` (or `--dh-red-1`, `--dh-red-10`) |
+| Warning | `--dh-warning` (or `--dh-orange-3`, `--dh-orange-8`, `--dh-orange-10`) |
+| Purple accent | `--dh-purple` (or `--dh-purple-4`, `--dh-purple-9`) |
+| Body text | `--dh-text-primary` (or `--dh-surface-5`), `--dh-text-secondary` (or `--dh-gray-1`) |
+| Disabled / borders | `--dh-text-disabled` (or `--dh-gray-6`) |
+| White / light bg | `--dh-white` (or `--dh-gray-10`), `--dh-bg-primary` (or `--dh-blue-10`) |
+| Dark text on light | `--dh-dark`, `--dh-surface-1` … `--dh-surface-5` |
+| Light text on dark | `--dh-surface-contrast-1` … `--dh-surface-contrast-10` |
+
+### 3.4 Usage guidelines (AI & other codebases)
+
+- **Do not hardcode hex** in components or styles; use `var(--dh-*)` so theming and exports stay consistent.
+- **Semantic tokens** (e.g. `--dh-primary`, `--dh-danger`, `--dh-success`) are defined in theme files (e.g. `variables.css` / `variables.light.css`) and point at the palette above; prefer them when the meaning is “primary”, “danger”, etc.
+- **Palette steps** (`--dh-blue-4`, `--dh-gray-7`, etc.) are for custom UI that needs a specific shade.
+- **Exporting this guide:** Copy this section (and the colorize section) into another repo; ensure the consuming app loads the same `colors.scss` (or equivalent `:root` definitions) so the variable names resolve.
+
+```css
+/* Prefer semantic tokens when meaning matches */
+color: var(--dh-primary);
+background-color: var(--dh-success-lighter);
+
+/* Use palette steps for custom shades */
+border-color: var(--dh-gray-4);
+background-color: var(--dh-blue-9);
+```
+
+---
+
+## 4. Spacing utilities (`spacing.scss`)
+
+Margin, padding, gap, and size use a shared scale. Values use `!important` by default.
+
+### Spacing scale (size names)
+
+Use these as the **suffix** for margin, padding, gap, width, and height classes:
+
+| Size name   | Value   | Size name   | Value   |
+|-------------|---------|-------------|---------|
+| `spacer-0`  | 0       | `spacer-12` | 3rem    |
+| `spacer-half` | 0.125rem | `spacer-14` | 3.5rem  |
+| `spacer-1`  | 0.25rem | `spacer-16` | 4rem    |
+| `spacer-2`  | 0.5rem  | `spacer-20` | 5rem    |
+| `spacer-3`  | 0.75rem | `spacer-24` | 6rem    |
+| `spacer-4`  | 1rem    | … up to `spacer-86` (24rem) |
+| `spacer-5`  | 1.25rem |             |
+| `spacer-6`  | 1.5rem  |             |
+| `spacer-8`  | 2rem    |             |
+| `spacer-10` | 2.5rem  |             |
+
+Full list of keys: `spacer-0`, `spacer-half`, `spacer-1` … `spacer-10`, `spacer-12`, `spacer-14`, `spacer-16`, `spacer-20`, `spacer-24`, `spacer-28`, `spacer-32`, `spacer-36`, `spacer-40`, `spacer-44`, `spacer-48`, `spacer-52`, `spacer-56`, `spacer-60`, `spacer-64`, `spacer-72`, `spacer-80`, `spacer-86`.
+
+### Gap
+- **Class pattern:** `gap-<size>` (size from spacing scale only)
+- **Examples:** `gap-spacer-2`, `gap-spacer-4`, `gap-spacer-0`
+
+### Margin
+- **Pattern:** `m-<size>`, `mx-<size>`, `my-<size>`, `mt-<size>`, `mr-<size>`, `mb-<size>`, `ml-<size>`
+- **Examples:** `m-spacer-2`, `mx-spacer-4`, `mt-spacer-1`, `mb-spacer-3`
+- **Special (auto):** `mx-auto`, `ml-auto`, `mr-auto` (no `m-auto` or `my-auto`)
+
+### Padding
+- **Pattern:** `p-<size>`, `px-<size>`, `py-<size>`, `pt-<size>`, `pr-<size>`, `pb-<size>`, `pl-<size>`
+- **Examples:** `p-spacer-4`, `px-spacer-2`, `py-spacer-3`
+
+### Width and height (rem-based)
+- **Pattern:** `w-<size>`, `h-<size>` with spacing scale
+- **Examples:** `w-spacer-40`, `h-spacer-8`
+- **Special:** `w-auto`, `h-auto`
+
+### Width and height (percentage)
+| Class   | Effect         |
+|---------|----------------|
+| `w-100` | width: 100%    |
+| `w-75`  | width: 75%     |
+| `w-50`  | width: 50%     |
+| `w-25`  | width: 25%     |
+| `w-0`   | width: 0%      |
+| `h-100` | height: 100%   |
+| `h-75`  | height: 75%    |
+| `h-50`  | height: 50%    |
+| `h-25`  | height: 25%    |
+| `h-0`   | height: 0%     |
+
+**Examples:**
+```html
+<div class="flex flex-column gap-spacer-4 p-spacer-4">
+  <div class="flex flex-row items-center justify-between mb-spacer-2">
+    <span class="text-primary">Title</span>
+    <button class="ml-auto">Action</button>
+  </div>
+  <div class="w-100 h-100">Full size content</div>
+</div>
+```
+
+---
+
+## 5. Quick reference for AI
+
+- **Layout:** Prefer `flex` + direction + align/justify + `gap-*` from this guide before adding custom flex CSS.
+- **Colors:** Use `text-*` and `bg-color-*` (or `color="..."` attribute) for semantic colors. For any other color, use **Section 3** variables only: `var(--dh-<scale>-<1-10>)` (e.g. `--dh-blue-4`, `--dh-gray-7`). All available palette variables and hex values are listed in **Section 3.1**; do not invent or hardcode hex.
+- **Spacing:** Use `m-*`, `p-*`, `gap-*` with the `spacer-*` scale; use `mx-auto` for horizontal centering when appropriate.
+- **Sizes:** Use `w-*` / `h-*` with the spacing scale for fixed sizes, or `w-100` / `h-100` for 100%.
+- **Combining:** e.g. `flex flex-row items-center justify-between gap-spacer-2 p-spacer-4` is a valid and preferred pattern.
+- **No new one-off CSS:** If a layout or spacing need is covered by these classes, use the classes instead of new rules in the component.

package/bin/ai-init.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const SOURCE_FILE = path.join(PACKAGE_ROOT, ".ai", "CSS-CLASSES-GUIDE.md");
+const DEST_DIR = path.join(process.cwd(), ".ai");
+const DEST_FILE = path.join(DEST_DIR, "DH-UI-USAGE.MD");
+
+function main() {
+  try {
+    if (!fs.existsSync(SOURCE_FILE)) {
+      console.error(
+        "[AI-INIT] Source guide '.ai/CSS-CLASSES-GUIDE.md' not found in '@deskhero/dh_ui' package."
+      );
+      process.exit(1);
+    }
+
+    if (!fs.existsSync(DEST_DIR)) {
+      fs.mkdirSync(DEST_DIR, { recursive: true });
+    }
+
+    if (fs.existsSync(DEST_FILE)) {
+      console.log(
+        "[AI-INIT] './ai/DH-UI-USAGE.MD' already exists. No changes made."
+      );
+      return;
+    }
+
+    const contents = fs.readFileSync(SOURCE_FILE, "utf8");
+    fs.writeFileSync(DEST_FILE, contents, "utf8");
+
+    console.log(
+      "[AI-INIT] Created './ai/DH-UI-USAGE.MD' from Deskhero UI CSS classes guide."
+    );
+  } catch (error) {
+    console.error("[AI-INIT] Failed to initialize AI guide:", error);
+    process.exit(1);
+  }
+}
+
+main();
+