@sublimee/surfaces 0.1.1 → 0.1.3

package/README.md

@@ -70,6 +70,28 @@ The `glass` variant creates a frosted glass effect using `backdrop-filter`. It's
 
 Browser support: Glass uses `backdrop-filter` which is supported in all modern browsers. In unsupported browsers, the surface will fall back to a solid semi-transparent background.
 
+#### Glass Dark Mode Behavior
+
+The glass surface automatically adapts its background color based on the theme:
+
+| Mode | Background | Use Case |
+|------|------------|----------|
+| **Light** | White translucent (`--sublime-color-overlay-light`) | Dark text on light backgrounds |
+| **Dark** | Black translucent (`--sublime-color-overlay-dark`) | Light text on dark backgrounds |
+
+This ensures the glass effect works correctly in both modes. In light mode, the white overlay provides a frosted look that darkens text for readability. In dark mode, the black overlay provides depth while keeping light text legible.
+
+```tsx
+// Automatic adaptation - no configuration needed
+<Surface variant="glass">
+  <p>This text is readable on any background</p>
+</Surface>
+```
+
+The glass effect uses these semantic tokens:
+- `--sublime-color-overlay-light`: `rgb(255 255 255 / 0.8)` in light mode
+- `--sublime-color-overlay-dark`: `rgb(0 0 0 / 0.5)` in dark mode
+
 ### Glass Utility Class
 
 For simple use cases, apply the glass effect directly with a CSS class:
@@ -88,6 +110,72 @@ This is the same glass styling as the Surface component, but without the additio
 
 Both `sublime-glassed` and `variant="glass"` respect dark mode automatically.
 
+#### Glass Configuration API
+
+Customize the glass effect using CSS custom properties:
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--sublime-glass-blur` | `12px` | Blur intensity (higher = more frosted) |
+| `--sublime-glass-bg` | Semantic overlay* | Background color/opacity |
+| `--sublime-glass-border` | Semantic border* | Border color |
+| `--sublime-glass-shadow` | Semantic shadow* | Box shadow |
+
+\* Uses `--sublime-color-overlay-light/dark`, `--sublime-color-border-*`, and `--sublime-shadow-*` tokens based on theme.
+
+**Adjust blur and opacity:**
+```tsx
+// More opaque, heavier blur for busy backgrounds
+<Surface 
+  variant="glass" 
+  style={{ 
+    '--sublime-glass-blur': '20px',
+    '--sublime-glass-bg': 'rgba(255, 255, 255, 0.95)'
+  }}
+>
+  Content
+</Surface>
+
+// Or with utility class
+<div class="sublime-glassed" style="--sublime-glass-blur: 20px; --sublime-glass-bg: rgba(255,255,255,0.95)">
+  Content
+</div>
+```
+
+**Custom color tint:**
+```tsx
+// Blue-tinted glass
+<Surface 
+  variant="glass" 
+  style={{ '--sublime-glass-bg': 'rgba(59, 130, 246, 0.3)' }}
+>
+  Blue glass
+</Surface>
+```
+
+**Darker modifier for very dark backgrounds:**
+
+When the default dark mode glass is too subtle on near-black backgrounds, use the `sublime-glassed--darker` modifier:
+
+```html
+<!-- Default may be invisible on black -->
+<div class="sublime-glassed">Default</div>
+
+<!-- Lighter tint for visibility -->
+<div class="sublime-glassed sublime-glassed--darker">More visible</div>
+```
+
+This switches to `rgba(255, 255, 255, 0.15)` background with `rgba(255, 255, 255, 0.25)` border—subtle but visible on pure black.
+
+**Override per-element:**
+```css
+.my-glass-button {
+  /* Always use light glass, even in dark mode */
+  --sublime-glass-bg: rgba(255, 255, 255, 0.9);
+  --sublime-glass-border: rgba(255, 255, 255, 0.3);
+}
+```
+
 ## Theming
 
 For full theming support including dark mode, also import the tokens:

package/dist/surface.css

@@ -228,34 +228,76 @@
  * Usage: <div class="sublime-glassed">Content</div>
  * Or with Surface: <Surface variant="glass">Content</Surface>
  *
+ * Configuration API (CSS custom properties):
+ *   --sublime-glass-bg: Background color/opacity (default: semantic overlay)
+ *   --sublime-glass-blur: Blur amount (default: 12px)
+ *   --sublime-glass-border: Border color (default: semantic border)
+ *   --sublime-glass-shadow: Box shadow (default: semantic shadow)
+ *
+ * Examples:
+ *   // Increase blur and opacity
+ *   <div class="sublime-glassed" style="--sublime-glass-blur: 20px; --sublime-glass-bg: rgba(255,255,255,0.95)">
+ *
+ *   // Custom color tint
+ *   <div class="sublime-glassed" style="--sublime-glass-bg: rgba(59, 130, 246, 0.3)">
+ *
+ *   // Darker in dark mode
+ *   <div class="sublime-glassed dark-glass-darker">
+ *
  * Note: The Surface component applies additional padding, radius, and layout.
  * This utility is the raw glass styling only.
+ *
+ * Light mode: white translucent overlay (readable on light backgrounds)
+ * Dark mode: black translucent overlay (readable on dark backgrounds)
  */
 .sublime-glassed,
 .sublime-surface--glass {
-  background: rgba(255, 255, 255, 0.11);
+  /* Configurable properties - override these to customize */
+  --sublime-glass-blur: 12px;
+  --sublime-glass-bg: var(--sublime-color-overlay-light, rgba(255, 255, 255, 0.8));
+  --sublime-glass-border: var(--sublime-color-border-primary, rgba(0, 0, 0, 0.1));
+  --sublime-glass-shadow: var(--sublime-shadow-md, 0 4px 6px -1px rgba(0, 0, 0, 0.1));
+
+  /* Light mode: white glass for dark text on light backgrounds */
+  background: var(--sublime-glass-bg);
   border-radius: 16px;
-  box-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
-  backdrop-filter: blur(8.6px);
-  -webkit-backdrop-filter: blur(8.6px);
-  border: 1px solid rgba(255, 255, 255, 0.11);
+  box-shadow: var(--sublime-glass-shadow);
+  backdrop-filter: blur(var(--sublime-glass-blur));
+  -webkit-backdrop-filter: blur(var(--sublime-glass-blur));
+  border: 1px solid var(--sublime-glass-border);
+  transition: var(--sublime-transition-button);
 }
 
+/* Hover state */
+.sublime-glassed:hover,
+.sublime-surface--glass:hover {
+  box-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.1));
+}
+
+/* Dark mode: switch to dark translucent overlay for light text */
 .dark .sublime-glassed,
 [data-theme="dark"] .sublime-glassed,
 .dark .sublime-surface--glass,
 [data-theme="dark"] .sublime-surface--glass {
-  background: rgba(255, 255, 255, 0.1);
-  border-color: rgba(255, 255, 255, 0.2);
-  box-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
+  --sublime-glass-bg: var(--sublime-color-overlay-dark, rgba(0, 0, 0, 0.5));
+  --sublime-glass-border: var(--sublime-color-border-surface, rgba(255, 255, 255, 0.2));
+  --sublime-glass-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.5));
+}
+
+/* Darker glass modifier - for very dark backgrounds where default isn't visible */
+.dark .sublime-glassed--darker,
+[data-theme="dark"] .sublime-glassed--darker,
+.sublime-glassed.sublime-glassed--darker {
+  --sublime-glass-bg: rgba(255, 255, 255, 0.15);
+  --sublime-glass-border: rgba(255, 255, 255, 0.25);
 }
 
 /* System preference dark mode */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]):not(.light) .sublime-glassed,
   :root:not([data-theme="light"]):not(.light) .sublime-surface--glass {
-    background: rgba(255, 255, 255, 0.1);
-    border-color: rgba(255, 255, 255, 0.2);
-    box-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
+    --sublime-glass-bg: var(--sublime-color-overlay-dark, rgba(0, 0, 0, 0.5));
+    --sublime-glass-border: var(--sublime-color-border-surface, rgba(255, 255, 255, 0.2));
+    --sublime-glass-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.5));
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublimee/surfaces",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Surface container components for Sublime",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -52,7 +52,7 @@
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@sublimee/tokens": "0.1.16"
+    "@sublimee/tokens": "0.1.18"
   },
   "peerDependenciesMeta": {
     "@sublimee/tokens": {

package/src/surface.css

@@ -228,34 +228,76 @@
  * Usage: <div class="sublime-glassed">Content</div>
  * Or with Surface: <Surface variant="glass">Content</Surface>
  *
+ * Configuration API (CSS custom properties):
+ *   --sublime-glass-bg: Background color/opacity (default: semantic overlay)
+ *   --sublime-glass-blur: Blur amount (default: 12px)
+ *   --sublime-glass-border: Border color (default: semantic border)
+ *   --sublime-glass-shadow: Box shadow (default: semantic shadow)
+ *
+ * Examples:
+ *   // Increase blur and opacity
+ *   <div class="sublime-glassed" style="--sublime-glass-blur: 20px; --sublime-glass-bg: rgba(255,255,255,0.95)">
+ *
+ *   // Custom color tint
+ *   <div class="sublime-glassed" style="--sublime-glass-bg: rgba(59, 130, 246, 0.3)">
+ *
+ *   // Darker in dark mode
+ *   <div class="sublime-glassed dark-glass-darker">
+ *
  * Note: The Surface component applies additional padding, radius, and layout.
  * This utility is the raw glass styling only.
+ *
+ * Light mode: white translucent overlay (readable on light backgrounds)
+ * Dark mode: black translucent overlay (readable on dark backgrounds)
  */
 .sublime-glassed,
 .sublime-surface--glass {
-  background: rgba(255, 255, 255, 0.11);
+  /* Configurable properties - override these to customize */
+  --sublime-glass-blur: 12px;
+  --sublime-glass-bg: var(--sublime-color-overlay-light, rgba(255, 255, 255, 0.8));
+  --sublime-glass-border: var(--sublime-color-border-primary, rgba(0, 0, 0, 0.1));
+  --sublime-glass-shadow: var(--sublime-shadow-md, 0 4px 6px -1px rgba(0, 0, 0, 0.1));
+
+  /* Light mode: white glass for dark text on light backgrounds */
+  background: var(--sublime-glass-bg);
   border-radius: 16px;
-  box-shadow: 0 4px 30px rgba(0, 0, 0, 0.1);
-  backdrop-filter: blur(8.6px);
-  -webkit-backdrop-filter: blur(8.6px);
-  border: 1px solid rgba(255, 255, 255, 0.11);
+  box-shadow: var(--sublime-glass-shadow);
+  backdrop-filter: blur(var(--sublime-glass-blur));
+  -webkit-backdrop-filter: blur(var(--sublime-glass-blur));
+  border: 1px solid var(--sublime-glass-border);
+  transition: var(--sublime-transition-button);
 }
 
+/* Hover state */
+.sublime-glassed:hover,
+.sublime-surface--glass:hover {
+  box-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.1));
+}
+
+/* Dark mode: switch to dark translucent overlay for light text */
 .dark .sublime-glassed,
 [data-theme="dark"] .sublime-glassed,
 .dark .sublime-surface--glass,
 [data-theme="dark"] .sublime-surface--glass {
-  background: rgba(255, 255, 255, 0.1);
-  border-color: rgba(255, 255, 255, 0.2);
-  box-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
+  --sublime-glass-bg: var(--sublime-color-overlay-dark, rgba(0, 0, 0, 0.5));
+  --sublime-glass-border: var(--sublime-color-border-surface, rgba(255, 255, 255, 0.2));
+  --sublime-glass-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.5));
+}
+
+/* Darker glass modifier - for very dark backgrounds where default isn't visible */
+.dark .sublime-glassed--darker,
+[data-theme="dark"] .sublime-glassed--darker,
+.sublime-glassed.sublime-glassed--darker {
+  --sublime-glass-bg: rgba(255, 255, 255, 0.15);
+  --sublime-glass-border: rgba(255, 255, 255, 0.25);
 }
 
 /* System preference dark mode */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]):not(.light) .sublime-glassed,
   :root:not([data-theme="light"]):not(.light) .sublime-surface--glass {
-    background: rgba(255, 255, 255, 0.1);
-    border-color: rgba(255, 255, 255, 0.2);
-    box-shadow: 0 4px 30px rgba(0, 0, 0, 0.3);
+    --sublime-glass-bg: var(--sublime-color-overlay-dark, rgba(0, 0, 0, 0.5));
+    --sublime-glass-border: var(--sublime-color-border-surface, rgba(255, 255, 255, 0.2));
+    --sublime-glass-shadow: var(--sublime-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.5));
   }
 }