@moldable-ai/ui 0.2.26 → 0.2.31

package/src/tokens/macos-27/web-adaptations.css

@@ -0,0 +1,98 @@
+/*
+ * Intentional macOS 27 adaptations for browser and native-webview rendering.
+ *
+ * Convention:
+ * - Source extraction remains unchanged in source/*.generated.css.
+ * - Every override is tagged with a stable M27-WEB-{AREA}-{NNN} ID.
+ * - Every tagged override has a matching entry in web-adaptations.json.
+ * - The full macOS 27 platform pack includes these effective values.
+ * - The /platforms/macos-27/source export remains source-faithful.
+ */
+
+/* @m27-divergence M27-WEB-COLOR-001 */
+[data-ui-platform='macos'][data-ui-platform-version='27'],
+[data-ui-platform='macos'][data-ui-platform-version='27']
+  [data-ui-appearance='light'] {
+  --m27-source-color-vibrant-label-primary: #000000e0;
+  --m27-source-color-vibrant-label-secondary: #000000a3;
+  --m27-source-color-vibrant-label-tertiary: #0000007a;
+  --m27-source-color-vibrant-label-quaternary: #0000004a;
+  --m27-source-color-vibrant-label-quinary: #0000002e;
+  --m27-web-adaptation-count: 5;
+}
+
+/* @m27-divergence M27-WEB-COLOR-001 */
+[data-ui-platform='macos'][data-ui-platform-version='27']
+  [data-ui-appearance='dark'],
+[data-ui-platform='macos'][data-ui-platform-version='27'][data-ui-appearance='dark'] {
+  --m27-source-color-vibrant-label-primary: #fffffff0;
+  --m27-source-color-vibrant-label-secondary: #ffffffb8;
+  --m27-source-color-vibrant-label-tertiary: #ffffff8a;
+  --m27-source-color-vibrant-label-quaternary: #ffffff59;
+  --m27-source-color-vibrant-label-quinary: #ffffff38;
+  --m27-web-adaptation-count: 5;
+}
+
+/*
+ * The light source window uses a transparent border because AppKit supplies
+ * its perimeter through the native window compositor. Embedded web windows
+ * have no compositor-owned edge, so preserve that perceived boundary with a
+ * single semantic hairline. The dark source already contains a visible edge.
+ */
+/* @m27-divergence M27-WEB-EFFECT-002 */
+[data-ui-platform='macos'][data-ui-platform-version='27'],
+[data-ui-platform='macos'][data-ui-platform-version='27']
+  [data-ui-appearance='light'] {
+  --m27-source-chrome-window-border: #00000024;
+}
+
+/*
+ * Native Liquid Glass uses separately blended contour, side-light, inner
+ * refraction, and cast-shadow layers. CSS box-shadow cannot assign a blend
+ * mode per shadow, so preserve the source geometry and depth with a
+ * normal-composited multi-edge highlight instead of a flat 1px border.
+ */
+/* @m27-divergence M27-WEB-EFFECT-001 */
+[data-ui-platform='macos'][data-ui-platform-version='27'],
+[data-ui-platform='macos'][data-ui-platform-version='27']
+  [data-ui-appearance='light'] {
+  --m27-source-effect-liquid-glass-medium:
+    inset 0 1px 0 #ffffffd9, inset 0 -1px 0 #ffffff8c, inset 1px 0 0 #ffffff4d,
+    inset -1px 0 0 #ffffff4d, 0 0 0 0.5px #00000059, 0 18px 48px #00000040;
+  --m27-source-effect-liquid-glass-large:
+    inset 0 1px 0 #ffffffd9, inset 0 -1px 0 #ffffff8c, inset 1px 0 0 #ffffff4d,
+    inset -1px 0 0 #ffffff4d, 0 0 0 0.5px #00000059, 0 18px 48px #00000040;
+}
+
+/* @m27-divergence M27-WEB-EFFECT-001 */
+[data-ui-platform='macos'][data-ui-platform-version='27']
+  [data-ui-appearance='dark'],
+[data-ui-platform='macos'][data-ui-platform-version='27'][data-ui-appearance='dark'] {
+  --m27-source-effect-liquid-glass-medium:
+    inset 0 1px 0 #ffffff3d, inset 0 -1px 0 #ffffff1f, inset 1px 0 0 #ffffff17,
+    inset -1px 0 0 #ffffff17, 0 0 0 0.5px #a6a6a6, 0 18px 48px #00000073;
+  --m27-source-effect-liquid-glass-large:
+    inset 0 1px 0 #ffffff3d, inset 0 -1px 0 #ffffff1f, inset 1px 0 0 #ffffff17,
+    inset -1px 0 0 #ffffff17, 0 0 0 0.5px #a6a6a6, 0 18px 48px #00000073;
+}
+
+/*
+ * Native menu highlights inherit a softened mask from the surrounding glass
+ * material. A flat browser fill at the extracted 8px radius reads visibly
+ * squarer, so the effective web radius tracks the 12px menu silhouette.
+ */
+/* @m27-divergence M27-WEB-GEOMETRY-001 */
+[data-ui-platform='macos'][data-ui-platform-version='27'] {
+  --m27-source-chrome-menu-item-radius: 12px;
+}
+
+/*
+ * The extracted block inset includes optical breathing room supplied by the
+ * native material edge. With the web's explicit border and shadow, 5px reads
+ * as a second visible gutter. Keep the horizontal inset intact while reducing
+ * only the first/last row distance from the menu shell.
+ */
+/* @m27-divergence M27-WEB-GEOMETRY-002 */
+[data-ui-platform='macos'][data-ui-platform-version='27'] {
+  --m27-source-chrome-menu-padding-block: 2px;
+}

package/src/tokens/macos-27/web-adaptations.json

@@ -0,0 +1,163 @@
+{
+  "source": "macOS 27",
+  "target": "web",
+  "schemaVersion": 1,
+  "idConvention": "M27-WEB-{AREA}-{NNN}",
+  "adaptations": [
+    {
+      "id": "M27-WEB-COLOR-001",
+      "area": "color",
+      "status": "intentional-divergence",
+      "summary": "Represent vibrant label colors with alpha compositing.",
+      "reason": "The source values rely on native macOS vibrancy and blend modes. Browser backdrop-filter does not reproduce that compositing pipeline, so opaque grayscale values lose or invert contrast over simulated materials.",
+      "sourceBehavior": "Opaque grayscale foreground combined with native vibrancy.",
+      "webBehavior": "Semantic black or white foreground with graduated alpha combined using normal browser compositing.",
+      "overrides": [
+        {
+          "appearance": "light",
+          "token": "--m27-source-color-vibrant-label-primary",
+          "sourceValue": "#1a1a1a",
+          "adaptedValue": "#000000e0"
+        },
+        {
+          "appearance": "light",
+          "token": "--m27-source-color-vibrant-label-secondary",
+          "sourceValue": "#727272",
+          "adaptedValue": "#000000a3"
+        },
+        {
+          "appearance": "light",
+          "token": "--m27-source-color-vibrant-label-tertiary",
+          "sourceValue": "#bfbfbf",
+          "adaptedValue": "#0000007a"
+        },
+        {
+          "appearance": "light",
+          "token": "--m27-source-color-vibrant-label-quaternary",
+          "sourceValue": "#d9d9d9",
+          "adaptedValue": "#0000004a"
+        },
+        {
+          "appearance": "light",
+          "token": "--m27-source-color-vibrant-label-quinary",
+          "sourceValue": "#e6e6e6",
+          "adaptedValue": "#0000002e"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-color-vibrant-label-primary",
+          "sourceValue": "#f5f5f5",
+          "adaptedValue": "#fffffff0"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-color-vibrant-label-secondary",
+          "sourceValue": "#8a8a8a",
+          "adaptedValue": "#ffffffb8"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-color-vibrant-label-tertiary",
+          "sourceValue": "#404040",
+          "adaptedValue": "#ffffff8a"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-color-vibrant-label-quaternary",
+          "sourceValue": "#262626",
+          "adaptedValue": "#ffffff59"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-color-vibrant-label-quinary",
+          "sourceValue": "#111111",
+          "adaptedValue": "#ffffff38"
+        }
+      ]
+    },
+    {
+      "id": "M27-WEB-GEOMETRY-001",
+      "area": "geometry",
+      "status": "intentional-divergence",
+      "summary": "Round menu selection and hover fills to preserve the native glass silhouette.",
+      "reason": "The native menu highlight is softened by the surrounding Liquid Glass mask. A flat browser background at the extracted radius reads visibly squarer, so the web radius is increased to match the perceived macOS silhouette.",
+      "sourceBehavior": "An 8px item radius rendered inside the native material and glass mask.",
+      "webBehavior": "A 12px item radius rendered as a flat CSS highlight inside the 12px menu shell.",
+      "overrides": [
+        {
+          "token": "--m27-source-chrome-menu-item-radius",
+          "sourceValue": "8px",
+          "adaptedValue": "12px"
+        }
+      ]
+    },
+    {
+      "id": "M27-WEB-GEOMETRY-002",
+      "area": "geometry",
+      "status": "intentional-divergence",
+      "summary": "Reduce the menu shell's vertical inset without changing row height.",
+      "reason": "The native material edge supplies optical breathing room around the first and last rows. In the browser, the explicit border and shadow make the extracted 5px inset read as a second gutter.",
+      "sourceBehavior": "A 5px block inset softened by native material compositing.",
+      "webBehavior": "A 2px block inset inside the explicit CSS border and shadow.",
+      "overrides": [
+        {
+          "token": "--m27-source-chrome-menu-padding-block",
+          "sourceValue": "5px",
+          "adaptedValue": "2px"
+        }
+      ]
+    },
+    {
+      "id": "M27-WEB-EFFECT-001",
+      "area": "effect",
+      "status": "intentional-divergence",
+      "summary": "Translate the native Liquid Glass contour into layered CSS edge lighting.",
+      "reason": "The source effect assigns Linear Dodge, Linear Burn, and other blend modes to individual contour and inner-shadow layers. CSS box-shadow cannot assign a blend mode per shadow, and a flat border loses the bright refractive rim.",
+      "sourceBehavior": "A native glass effect with independently blended top, bottom, side, contour, and cast-shadow layers.",
+      "webBehavior": "A normal-composited stack of directional inset highlights, a half-pixel outer contour, and the source cast shadow.",
+      "overrides": [
+        {
+          "appearance": "light",
+          "token": "--m27-source-effect-liquid-glass-medium",
+          "sourceValue": "0 18px 48px #00000040, 0 0 0 0.5px #dbdbdb",
+          "adaptedValue": "inset 0 1px 0 #ffffffd9, inset 0 -1px 0 #ffffff8c, inset 1px 0 0 #ffffff4d, inset -1px 0 0 #ffffff4d, 0 0 0 0.5px #00000059, 0 18px 48px #00000040"
+        },
+        {
+          "appearance": "light",
+          "token": "--m27-source-effect-liquid-glass-large",
+          "sourceValue": "0 18px 48px #00000040, 0 0 0 0.5px #dbdbdb",
+          "adaptedValue": "inset 0 1px 0 #ffffffd9, inset 0 -1px 0 #ffffff8c, inset 1px 0 0 #ffffff4d, inset -1px 0 0 #ffffff4d, 0 0 0 0.5px #00000059, 0 18px 48px #00000040"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-effect-liquid-glass-medium",
+          "sourceValue": "0 18px 48px #00000073, 0 0 0 0.5px #a6a6a6",
+          "adaptedValue": "inset 0 1px 0 #ffffff3d, inset 0 -1px 0 #ffffff1f, inset 1px 0 0 #ffffff17, inset -1px 0 0 #ffffff17, 0 0 0 0.5px #a6a6a6, 0 18px 48px #00000073"
+        },
+        {
+          "appearance": "dark",
+          "token": "--m27-source-effect-liquid-glass-large",
+          "sourceValue": "0 18px 48px #00000073, 0 0 0 0.5px #a6a6a6",
+          "adaptedValue": "inset 0 1px 0 #ffffff3d, inset 0 -1px 0 #ffffff1f, inset 1px 0 0 #ffffff17, inset -1px 0 0 #ffffff17, 0 0 0 0.5px #a6a6a6, 0 18px 48px #00000073"
+        }
+      ]
+    },
+    {
+      "id": "M27-WEB-EFFECT-002",
+      "area": "effect",
+      "status": "intentional-divergence",
+      "summary": "Supply the light window perimeter normally rendered by the native compositor.",
+      "reason": "The source light window border is transparent because AppKit and the macOS window compositor provide the visible edge. An embedded browser window has no compositor-owned perimeter, leaving edge-to-edge sidebars and the outer shell visually open.",
+      "sourceBehavior": "A transparent CSS-equivalent border with the visible perimeter supplied outside the view hierarchy.",
+      "webBehavior": "A single 14% black hairline around the embedded window; dark appearance retains its extracted 20% white edge.",
+      "overrides": [
+        {
+          "appearance": "light",
+          "token": "--m27-source-chrome-window-border",
+          "sourceValue": "transparent",
+          "adaptedValue": "#00000024"
+        }
+      ]
+    }
+  ]
+}

package/src/tokens/macos-27/web-adaptations.md

@@ -0,0 +1,117 @@
+# macOS 27 web adaptations
+
+The macOS 27 token pack has two distinct responsibilities:
+
+1. Preserve the values extracted from the macOS 27 source specification.
+2. Produce the closest practical macOS 27 rendering in browsers and native
+   webviews.
+
+Those goals occasionally conflict. Native macOS rendering can use effects
+such as vibrancy, platform blend modes, material compositing, and font
+rendering that CSS cannot reproduce exactly. When an extracted value produces
+the wrong visual result on the web, add a documented web adaptation instead
+of changing a showcase or component locally.
+
+## File boundaries
+
+- `source/*.generated.css` contains the extracted reference values. Do not
+  hand-edit these files.
+- `source.css` exports the source-faithful reference pack without adaptations.
+- `web-adaptations.css` overrides reference variables with effective web
+  values.
+- `web-adaptations.json` records every intentional divergence in a
+  machine-readable manifest.
+- `index.css` exports the effective macOS 27 platform pack and imports the web
+  adaptations before aliases, compatibility mappings, and recipes.
+
+Components and showcases should consume the normal macOS 27 platform pack.
+They must not compensate for platform-wide translation issues with local
+colors or one-off CSS.
+
+## Adaptation IDs
+
+Every adaptation has a stable ID:
+
+```text
+M27-WEB-{AREA}-{NNN}
+```
+
+Examples:
+
+- `M27-WEB-COLOR-001`
+- `M27-WEB-MATERIAL-001`
+- `M27-WEB-TYPE-001`
+- `M27-WEB-EFFECT-001`
+
+Use one ID for one coherent rendering discrepancy. A single adaptation may
+cover multiple related tokens, appearances, or states when they form one
+semantic scale.
+
+## How to add or tune an adaptation
+
+1. Reproduce the discrepancy in the Moldable UI calibration or component
+   page in both light and dark appearances.
+2. Confirm that the mismatch comes from a browser or webview limitation, not
+   from application globals, Tailwind utilities, component CSS, or an
+   incorrect source extraction.
+3. Keep the extracted value unchanged in `source/*.generated.css`.
+4. Add or update the effective override in `web-adaptations.css`.
+5. Tag the CSS group with its adaptation ID:
+
+   ```css
+   /* @m27-divergence M27-WEB-COLOR-001 */
+   ```
+
+6. Add or update the matching entry in `web-adaptations.json`. Record:
+   - the stable adaptation ID;
+   - the affected area and appearance;
+   - every token name;
+   - the exact source value;
+   - the exact adapted value;
+   - why the source behavior cannot be reproduced directly;
+   - what web behavior replaces it.
+
+7. Compare the result across representative backgrounds and material
+   thicknesses. Check normal and increased-contrast contexts where relevant.
+8. Run the platform-contract test, UI package checks, and the Moldable UI app
+   checks.
+
+## Review criteria
+
+An adaptation is appropriate when it makes the effective web rendering more
+faithful to macOS 27, not merely more attractive.
+
+Prefer adaptations that:
+
+- preserve the semantic hierarchy of the source values;
+- work across both appearances and varied content backgrounds;
+- remain centralized at the platform-token layer;
+- use the smallest coherent set of overrides;
+- preserve readable contrast without flattening primary, secondary, and
+  tertiary distinctions;
+- can be removed cleanly if browser or webview capabilities improve.
+
+Do not use an adaptation to:
+
+- add Moldable branding;
+- change a component for product-specific taste;
+- hide a cascade or theme-isolation bug;
+- compensate for an incorrect component size or layout;
+- modify source artwork, symbols, vectors, image assets, or font files.
+
+Moldable-specific styling belongs in the Moldable theme layer above the
+platform pack.
+
+## Validation
+
+`platform-contract.test.ts` enforces that:
+
+- the effective macOS 27 pack imports `web-adaptations.css`;
+- the source-faithful entry point does not import adaptations;
+- adaptation IDs are unique;
+- every manifest entry has a matching CSS marker;
+- every recorded source value still exists in the generated source styles;
+- every recorded adapted value exists in the adaptation stylesheet.
+
+If an override is intentional, document it. If it is not documented, it does
+not belong in the macOS 27 platform pack.

package/src/tokens/moldable/brand.css

@@ -0,0 +1,48 @@
+/*
+ * Moldable uses the selected base platform for its general controls and
+ * chrome. Its floating sidebar is an explicit, independently versioned
+ * component recipe selected by ThemeProvider's `sidebarStyle` axis.
+ */
+[data-ui-theme='moldable'] {
+  --m-ui-theme-name: moldable;
+}
+
+/*
+ * Moldable's dark canvas stays close to the macOS window surface while
+ * carrying a subtle cool cast. Keep these product colors in the brand layer
+ * instead of changing the immutable platform source values.
+ */
+[data-ui-theme='moldable'][data-ui-appearance='dark'] {
+  --m-ui-surface-window: #1d1f1f;
+  --m-ui-surface-content: #1d1f1f;
+  --background: #1d1f1f;
+  --surface-canvas: #1d1f1f;
+}
+
+/*
+ * The macOS 26 source shadow has a 40px blur intended for a full-size native
+ * floating panel. At showcase scale that blur reads as an inset gradient on
+ * the neighboring content pane. Moldable keeps the sidebar lift while using a
+ * tighter web rendering that does not veil adjacent content.
+ */
+[data-ui-theme='moldable'][data-ui-sidebar-style='floating'] {
+  --m-ui-sidebar-shadow: 0 1px 2px rgb(0 0 0 / 5%), 0 4px 14px rgb(0 0 0 / 6%);
+}
+
+[data-ui-theme='moldable'][data-ui-sidebar-style='floating'][data-ui-appearance='dark'] {
+  --m-ui-sidebar-material-fill: #1b1d1e;
+  --m-ui-sidebar-border-width: 1px;
+  --m-ui-sidebar-border-color: #394043;
+  --m-ui-sidebar-selection-fill: color-mix(
+    in srgb,
+    var(--m-ui-color-accent) 14%,
+    transparent
+  );
+  --m-ui-sidebar-shadow:
+    0 1px 2px rgb(0 0 0 / 18%), 0 4px 14px rgb(0 0 0 / 16%);
+  --sidebar: var(--m-ui-sidebar-material-fill);
+  --sidebar-accent: var(--m-ui-sidebar-selection-fill);
+  --sidebar-accent-foreground: var(--m-ui-color-accent);
+  --sidebar-border: var(--m-ui-sidebar-border-color);
+  --surface-sidebar: var(--m-ui-sidebar-material-fill);
+}

package/src/tokens/moldable/index.css

@@ -0,0 +1 @@
+@import './brand.css';