@vttforge/styles 0.3.2 → 0.4.0

package/index.css

@@ -1,16 +1,33 @@
 /*!
  * @vttforge/styles
  *
- * One-line import for consumers that want everything VTTForge ships, in the right
- * cascade-layer order.
+ * One-line import for consumers that want everything VTTForge ships:
  *
  *   @import '@vttforge/styles';
  *
- * Layer order matches Foundry v13's outer layer: tokens → reset → base → components → themes.
- * Foundry's own runtime wraps system CSS in its top-level `system` layer.
+ * Only tokens and the reset sit in a cascade layer. Base, components and the
+ * theme are deliberately unlayered.
+ *
+ * Foundry has already put this file in a layer by the time you see it. A
+ * system's stylesheet goes in `@layer system` and a module's in
+ * `@layer modules`; the manifest's `styles` entry takes an optional `layer`,
+ * and leaving it out lets the server fill one in. So the question here is
+ * never whether these rules are layered. It is how they sort against the rest
+ * of what is in that same layer, which is your own CSS.
+ *
+ * An unlayered rule beats every layered one in the same layer, whatever the
+ * specificity. Sub-layer the components and a bare `button { }` of yours beats
+ * `.vttf-btn`, and nothing you write can lose. That sounds convenient until a
+ * broad selector meant for one corner restyles every component. Leaving them
+ * unlayered puts the two on the same footing, where specificity decides.
+ *
+ * Tokens and the reset stay layered on purpose, and lose on purpose. Tokens are
+ * custom properties a consumer must be able to override with one plain
+ * declaration. The reset touches bare elements inside `.vttf-app`, so keeping it
+ * layered means it never outranks a real rule from the system around it.
  */
 
-@layer vttforge.tokens, vttforge.reset, vttforge.base, vttforge.components, vttforge.themes;
+@layer vttforge.tokens, vttforge.reset;
 
 @import "./dist/tokens.css";
 @import "./reset.css";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vttforge/styles",
-  "version": "0.3.2",
-  "description": "VTTForge base CSS layer: design tokens, reset, base, components, opt-in themes (CSS Cascade Layers).",
+  "version": "0.4.0",
+  "description": "VTTForge design system as CSS: tokens, reset, base, components and opt-in themes over cascade layers.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/vttforge/vttforge#readme",

package/styles.layer.css

@@ -1,13 +1,20 @@
 /*!
  * @vttforge/styles — styles.layer.css
  *
- * Mantine-style variant: wraps `index.css` inside an explicit `@layer vttforge`
- * for consumers that want a single namespaced layer instead of the five
- * sub-layers (`vttforge.tokens`, `vttforge.reset`, `vttforge.base`,
- * `vttforge.components`, `vttforge.themes`).
+ * The opt-in variant: everything VTTForge ships, wrapped in one `@layer
+ * vttforge` you can order against layers of your own.
  *
- * Use this entry when you need to control VTTForge's cascade position relative
- * to your own layers; use the default `index.css` otherwise.
+ *   @layer vttforge, my-system;
+ *   @import '@vttforge/styles/layer';
+ *
+ * Foundry has already placed this file in `@layer system` (or `modules`), so
+ * this nests a layer inside that one. The effect is that every rule here loses
+ * to your own CSS in the same layer, whatever the specificity, which is the
+ * behaviour the default entry deliberately does not have.
+ *
+ * That is the trade the variant exists to make: you give up composing on
+ * specificity in exchange for being able to order these styles as a block.
+ * Reach for `index.css` unless you need that.
  */
 
 @layer vttforge {

package/themes/forge.css

@@ -6,26 +6,24 @@
  * preference takes over. Explicit `data-theme="light"` and
  * `data-theme="foundry"` are handled by tokens.css.
  *
- * Imported by `index.css` and `styles.layer.css` after components, so theme
- * overrides win cleanly inside `@layer vttforge.themes`.
+ * Imported after components and, like them, unlayered, so theme overrides win
+ * on source order.
  */
 
-@layer vttforge.themes {
-  @media (prefers-color-scheme: light) {
-    :where([data-theme="auto"]) {
-      --vttf-bg: oklch(0.985 0.004 80);
-      --vttf-bg-elevated: oklch(0.972 0.006 78);
-      --vttf-bg-sunken: oklch(0.945 0.01 72);
-      --vttf-surface: oklch(0.962 0.008 75);
-      --vttf-surface-2: oklch(0.928 0.012 68);
-      --vttf-border: oklch(0.88 0.014 62);
-      --vttf-border-strong: oklch(0.76 0.016 58);
-      --vttf-text: oklch(0.215 0.02 42);
-      --vttf-text-muted: oklch(0.43 0.018 48);
-      --vttf-text-faint: oklch(0.595 0.014 55);
-      --vttf-ember: oklch(0.565 0.18 36);
-      --vttf-ember-deep: oklch(0.43 0.16 30);
-      --vttf-ember-glow: oklch(0.67 0.17 42);
-    }
+@media (prefers-color-scheme: light) {
+  :where([data-theme="auto"]) {
+    --vttf-bg: oklch(0.985 0.004 80);
+    --vttf-bg-elevated: oklch(0.972 0.006 78);
+    --vttf-bg-sunken: oklch(0.945 0.01 72);
+    --vttf-surface: oklch(0.962 0.008 75);
+    --vttf-surface-2: oklch(0.928 0.012 68);
+    --vttf-border: oklch(0.88 0.014 62);
+    --vttf-border-strong: oklch(0.76 0.016 58);
+    --vttf-text: oklch(0.215 0.02 42);
+    --vttf-text-muted: oklch(0.43 0.018 48);
+    --vttf-text-faint: oklch(0.595 0.014 55);
+    --vttf-ember: oklch(0.565 0.18 36);
+    --vttf-ember-deep: oklch(0.43 0.16 30);
+    --vttf-ember-glow: oklch(0.67 0.17 42);
   }
 }