qss 0.6.0 → 0.7.0

data/docs/HOWTO.md

@@ -0,0 +1,269 @@
+# How to use QSS
+
+A step-by-step walkthrough from installing the gem to a fully audited layout with overlays and persistent chrome.
+For the pitch and a 60-second taste, see [README.md](../README.md). For *why* QSS looks the way it does — including
+the approaches that were tried and rejected — see [DESIGN_HISTORY.md](DESIGN_HISTORY.md).
+
+## Step 1: Install
+
+```ruby
+# Gemfile
+gem "qss"
+```
+
+The gem's Rails engine puts QSS's assets on your asset pipeline (`qss/qss_core.css`, `qss/qss_core.scss`,
+`qss/qss-engine.js`). Everything else in QSS — the auditors, configuration — works in plain Ruby too; Rails is only
+needed for the asset pipeline.
+
+## Step 2: Load the stylesheet
+
+The simplest path, QSS's neutral defaults:
+
+```erb
+<%= stylesheet_link_tag "qss/qss_core" %>
+```
+
+To use your own settings (your palette, a different portal id, and so on — see Step 5), set your values first and
+import core after; core's settings are `!default`, so yours win. Put `QSS.stylesheets_path` on your Sass load path
+so `qss/qss_core` resolves:
+
+```scss
+// app/assets/stylesheets/application.scss
+@import "qss_variables";   // generated from your config by qss-sync -- see Step 5
+@import "qss/qss_core";
+```
+
+```ruby
+Sass.compile("app/assets/stylesheets/application.scss",
+             load_paths: ["app/assets/stylesheets", QSS.stylesheets_path])
+```
+
+## Step 3: Write your first layout
+
+The canvas id is fixed: `#qss-canvas` is not configurable, so a document has exactly one top-level QSS canvas. Two
+independent QSS instances nested in the same page would collide on it; isolate them in separate documents (an
+`<iframe>`) instead. This is a known constraint, not something QSS will build support for.
+
+### The canvas, `<body>`, and everything else
+
+QSS resets `html, body` globally (`margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden;`), so the
+canvas's own `height: 100%` has something real, non-zero to measure against. That reset only reaches as far as
+`<body>` itself, though: if you nest the canvas inside other wrapper elements — a layout's own container divs,
+say — size those wrappers too (`height: 100%` down the chain), or just put `#qss-canvas` directly inside `<body>`,
+which is the common case and needs nothing extra. Both `<body>` and the canvas clip rather than scroll by
+default (`overflow: hidden`) — QSS assumes a full-bleed, app-style viewport, not a scrolling document. Opt into
+scrolling deliberately with `qss-scroll` or `qss-scroll-smooth` wherever you actually want it.
+
+Everything *outside* `#qss-canvas` (and outside the optional overlay portal, Step 7) is completely untouched by
+QSS. Every single rule QSS generates is scoped to being a descendant of one of those two roots, so anything else
+you put in `<body>` — a cookie banner, an analytics widget, a completely separate part of the page — renders under
+ordinary CSS exactly as if QSS weren't installed at all.
+
+The same is true one level down, *inside* the canvas: only elements that actually carry a QSS class (`qss`, or any
+`qss-` prefixed utility) are ever touched. QSS's reset specifically targets `.qss`-classed elements
+(`:where(.qss:not(.foreign *))` in the compiled CSS) — nothing broader — so a plain `<div>` with no QSS classes at
+all, dropped anywhere inside the canvas, renders however your own CSS or content framework says it should. For
+content you want to *guarantee* stays untouched even if it happens to collide with a `qss-`-prefixed class name
+from some third-party library, wrap it in `class="foreign"` (or mark the one offending element
+`qss-payload-override`) — QSS's explicit escape hatch, rather than relying on it simply never reaching there.
+
+Every element QSS positions carries class `qss` (an **actor**) and lives inside the canvas. An actor's id is its
+**noun** — its identity — and follows `{qualifier}-{baseObject}`: the base object is an HTML tag, the qualifier
+says which one. Declare each qualifier once, in a registry, recording what it adds to its base:
+
+```erb
+<div id="qss-canvas">
+  <nav id="main-nav" class="qss qss-relative qss-contain-layout qss-w[200] qss-h-full"> ... </nav>
+  <section id="content-section" class="qss qss-relative qss-contain-layout qss-w[800] qss-h-full"> ... </section>
+</div>
+```
+
+```yaml
+# config/qss_registry.yml (auditor.registry_path in your config, Step 5)
+types:
+  main-nav:
+    extends: nav
+  content-section:
+    extends: section
+```
+
+Structural frames (`nav`, `main`, and similar) carry `qss-contain-layout`, which both isolates their internal
+layout and clips their own overflow by default — a frame's content can't spill out and cover its neighbors. This
+example audits fully green (Step 4).
+
+Everything an actor needs to be addressable is a single explicit bracket value: `qss-w[200]` is 200 qnt wide —
+20% of the canvas, at any screen size, since 1 qnt is always `canvas width / 1000`, computed in pure CSS. The same
+pattern covers position (`qss-pos-x[N]`, `qss-pos-y[N]`, `qss-pos-r[N]`, `qss-pos-b[N]`), size (`qss-w[N]`,
+`qss-h[N]`, `qss-min-w[N]`, `qss-min-h[N]`), spacing (`qss-gap[N]`, `qss-p[N]`, `qss-px[N]`, `qss-py[N]`) and
+borders/radius. Percentage-of-parent variants exist too (`qss-w-pct[N]`, `qss-pos-y-pct[N]`, ...) for when you want
+a fraction of the *immediate* containing block instead of the canvas.
+
+An actor must always declare both its width and height, in one of these units — never left to shrink-to-fit. Every
+actor is also a CSS size container (`container-type: inline-size`, needed for qnt itself to resolve), and per the
+CSS Containment spec that rules out content-based `auto` sizing in either axis in any browser that implements
+container queries correctly. An actor with no size opts into this deliberately with `qss-content-driven`. See
+[DESIGN_HISTORY.md](DESIGN_HISTORY.md) #16 for why.
+
+## Step 4: Audit your views
+
+```ruby
+result = QSS::QssNativeAuditor.audit_file("app/views/layouts/application.html.erb")
+result[:status] # => "green", "orange" or "red"
+result[:issues] # => [{ type:, message:, severity: }, ...] (plus code: on most identity and unit findings)
+```
+
+RED means a rule is violated: fix the markup, or reconsider the rule. ORANGE is a judgment call. Rules include:
+every actor declares its width and height (or opts out with `qss-content-driven`); structure carries no raw CSS
+lengths (sizes are in qnt or canvas percentages); no `!important`; ids follow the `{qualifier}-{baseObject}`
+grammar; every class literally resolves to a rule in the compiled stylesheet, not just a known shape; a `qss`-marked
+actor carries no class (from a content framework such as Tailwind) that resolves, in `auditor.drywall_stylesheet_path`,
+to a rule setting a structural property (`display`, `position`, sizing, `flex*`/`grid*`, `gap`, `z-index`, `order`)
+— checked by CSS property, so it works for any content framework with no fork.
+
+`QSS::QssAuditor` is the older class-whitelist auditor: it predates the bracket vocabulary (it reports `qss-w[200]`
+as unknown) and is kept only for projects that still use its whitelist. Use `QssNativeAuditor`.
+
+**Three tiers of stylesheet.** Class resolution reads core's own `qss_core.css` (always, verified against the
+manifest shipped with the gem, raising `QSS::CoreIntegrityError` on a mismatch), any sealed tool stylesheets
+(`auditor.tool_stylesheets`, sealed by the tool's own build with `qss-seal`, raising `QSS::ToolIntegrityError` if
+unsealed or changed), and your own compiled output (`auditor.host_stylesheets`, `stylesheet_path`, or
+`QSS.configure(host_stylesheets: -> { ... })`; a Rails host defaults to `app/assets/builds/*.css`).
+
+Appearance classes (colors, type styling, shadows, filters) are **deprecated**: the auditor reports each as orange
+`deprecated_decorative`, since appearance belongs to whatever fills Drywall — your content framework, not QSS.
+QSS's own quantized bracket scale (`qss-border[2]`, `qss-text-size[14]`) is unaffected, since those are structural
+(a border's width, text's footprint), not decorative. A Drywall stylesheet compiled with the `qss` prefix is a red
+`drywall_prefix_collision` — every QSS class is prefixed `qss-` specifically so no content framework sharing the
+canvas can mistake its own unprefixed utility for QSS's.
+
+## Step 5: Configure QSS for your project
+
+QSS starts neutral. Declare your own settings in one YAML file and tell QSS where it is:
+
+```ruby
+# config/initializers/qss.rb
+QSS.configure(root: Rails.root, config: "config/qss_config.yml")
+```
+
+```yaml
+# config/qss_config.yml -- every key is optional; see the gem's config/grammar.yml for the defaults
+config:
+  portal_root: "#qss-portal"        # overlays and chrome render here (any one #id; default #qss-portal); "" = rules scoped to the canvas only
+  palette:
+    brand-main: "#0f1115"
+  group_names: [menu]               # named groups for group-*:hover style classes
+auditor:
+  id_prefix: "app-"                  # optional project id prefix
+  registry_path: "config/qss_registry.yml"
+sync_targets:
+  variables: app/assets/stylesheets/_qss_variables.scss
+```
+
+Relative paths resolve against the declared `root`, never the working directory.
+
+Generate your SCSS settings from that config whenever it changes:
+
+```sh
+QSS_CONSUMER_CONFIG=config/qss_config.yml bundle exec qss-sync
+```
+
+This writes `_qss_variables.scss` (the `sync_targets.variables` path, imported in Step 2). Without
+`QSS_CONSUMER_CONFIG` it reads `config/qss_config.yml` from the current directory.
+
+## Step 6: Add the optional JS engine (if you want it)
+
+The compiled CSS from Steps 2–3 is already fully functional with zero JavaScript. The engine adds three runtime
+conveniences on top:
+
+- Rules for bracket classes the compiled CSS doesn't precompute (there's no combinatorial way to precompile every
+  possible value of a composite blueprint like `qss-Button[200|80]` — see Step 8's note on why `qss-elastic-y`
+  took a different shape instead).
+- Exporting measured element edges as CSS variables.
+- Naming each actor's CSS container after its own id (`container-name`, inside both the canvas and the portal), so
+  Drywall content inside it can use a named container-query variant — Tailwind's `@sm/<frame-name>:`, for example
+  — to react to that specific frame's own width, independent of the canvas or any sibling.
+
+```erb
+<%= javascript_include_tag "qss/qss-engine", defer: true %>
+<script>
+  document.addEventListener("DOMContentLoaded", () => { QSSEngine.startPulse(); QSSEngine.startObserver(); });
+</script>
+```
+
+While developing, `QSSEngine.auditPositioning()` lists every element that is `position: fixed` or `sticky` without
+QSS owning it — a loophole no static check can see, since a Drywall `fixed` utility only becomes a position once a
+stylesheet resolves it. Frames, the overlay portal, `foreign` content and the browser's native top layer are
+exempt. It runs only when you call it; `QSSEngine.setPortal("#qss-overlays")` tells it where your portal root is if
+it isn't `#qss-portal`.
+
+## Step 7: Overlays — modals, dropdowns, toasts
+
+A modal, dialog, menu or popover belongs outside the canvas entirely, in the **overlay portal root**: the element
+whose id is your configured `portal_root` (any one `#id` selector; `#qss-portal` when none is set), matched
+exactly — no prefix or substring guessing. Core gives it its own geometry automatically (a fixed, viewport-sized
+layer, `pointer-events: none` on the root and `auto` on its direct children, its own `--qnt` resolved the same way
+as the canvas's), so write no QSS classes on the root element itself — they match nothing there — and place it
+after the canvas in the document so it paints above it with no `z-index` at all.
+
+Prefer the browser's native top layer: a `<dialog>` opened with `showModal()`, or any element carrying the
+`popover` attribute. The browser then renders it above everything, genuinely with no `z-index`. A plain element
+placed directly in the portal root (the fallback path) is allowed, but the auditor reports it as orange
+`top_layer_preferred` until you mark it `qss-overlay-fallback`. A `z-index` is permitted only on the portal root
+and inside it (to order one fallback overlay above another, or rely on DOM order alone); anywhere else, Portal
+Integrity makes it red.
+
+## Step 8: Persistent chrome — nav bars, toolbars, sidebars
+
+Global nav, a file-tree explorer, a toolbar pinned to a screen edge — anything genuinely edge-docked and
+load-bearing that must never crop as the viewport reshapes — isn't canvas content, and shouldn't use canvas
+position classes (`qss-pos-y[N]` and friends). Dock it as a direct child of the same portal root from Step 7:
+
+```html
+<div id="qss-portal">
+  <nav id="chrome-sidebar" class="qss qss-w[64]" style="left: 0; top: 0; height: 100vh;"> ... </nav>
+</div>
+```
+
+Three rules, used together:
+
+1. **The chrome element's own placement uses real CSS edges** (`top: 0; left: 0; height: 100vh;`), never a qnt
+   position class — it's always exactly at the true edge by definition, at any viewport shape.
+2. **Each element's own size still uses qnt** (`qss-w[N]`/`qss-h[N]`), scaling proportionally with the real
+   viewport, visually consistent with the rest of the UI at any resolution.
+3. **Position *within* the chrome** (a button cluster sitting 70–80% down a nav bar) uses `qss-elastic-y-*`
+   (Step 9) or `*-pct[N]` plus ordinary flexbox, nested one level deeper.
+
+There is deliberately no second, separate root for this: persistent chrome and ephemeral overlays share
+`#qss-portal`, because stacking there is pure DOM paint order with no `z-index` (Step 7) — a native top-layer
+overlay always paints above everything regardless of which root anything lives in, and a modal or popover is
+meant to take over the user's entire attention, so chrome floating above it is never the right default. The one
+contract this depends on: **always append** new overlays to the portal, never insert at a fixed index, so
+later-added overlays keep painting over earlier, static chrome. See
+[DESIGN_HISTORY.md](DESIGN_HISTORY.md) #17.3.
+
+## Step 9: Elastic spacing — gaps that flex, without breaking proportion
+
+Most spacing should stay rigidly proportional to the canvas (`qss-pos-y[N]`, Step 3) — that's the default, and
+it's what keeps a whole composition moving together as one image at any screen size. But some gaps are more like
+a margin than a structural relationship: the headroom above a centered cluster, say, which can reasonably grow or
+shrink a bit as the frame's shape changes, the way a video's headroom above a subject's head is allowed to vary
+with the frame shape while the subject's own position stays fixed (the rule-of-thirds analogy this is named for).
+
+For those, stack four classes on one element — three value-setters plus a trigger:
+
+```html
+<div class="qss qss-elastic-y-min[20] qss-elastic-y-pct[100] qss-elastic-y-max[80] qss-elastic-y"> ... </div>
+```
+
+This computes `top: clamp(20 * qnt, 10%, 80 * qnt)` against the element's immediate containing block: it tracks
+10% of the parent's actual height, but never drops below 20 qnt or rises above 80 qnt, however that parent
+reshapes. (It's four classes rather than one `qss-elastic-y[min|pct|max]` bracket because a three-parameter
+bracket can't be precompiled — it would need every min×pct×max combination generated in advance. Composing single-
+value classes, the same idiom the rest of the grammar already uses, keeps this working with zero JavaScript.) See
+[DESIGN_HISTORY.md](DESIGN_HISTORY.md) #17.2 for the full reasoning.
+
+## Where to go from here
+
+- [QSS-MANIFESTO.md](../QSS-MANIFESTO.md) — the full grammar: nouns, adjectives, parametric blueprints.
+- [DESIGN_HISTORY.md](DESIGN_HISTORY.md) — why QSS looks the way it does, including what was tried and discarded.
+- [CHANGELOG.md](../CHANGELOG.md) — what changed, release by release.

data/exe/qss-core-render-check

@@ -41,10 +41,14 @@ HTML = <<~HTML
     <div id="host" class="qss host-static"></div>
     <div class="foreign"><div id="in-foreign" class="qss"></div></div>
     <div id="nearer-container" class="qss qss-w[100] qss-h[10]" style="container-type: inline-size"><div id="deep" class="qss"></div></div>
+    <div id="elastic-parent" class="qss qss-w[400] qss-h[300]" style="position: relative;">
+      <div id="elastic-actor" class="qss qss-w[50] qss-h[50] qss-elastic-y-min[20] qss-elastic-y-pct[100] qss-elastic-y-max[80] qss-elastic-y"></div>
+    </div>
   </div>
   <div id="qss-portal" class="qss-absolute qss-inset-0">
     <div id="portal-actor" class="qss qss-w[640] qss-h[420] qss-pos-r[16] qss-pos-b[52]"></div>
     <div id="portal-plain" class="host-static"></div>
+    <div id="chrome-sidebar" class="qss qss-w[64]" style="left: 0; top: 0; height: 100vh;"></div>
   </div>
   </body></html>
 HTML
@@ -145,6 +149,25 @@ Dir.mktmpdir do |dir|
       puts format("%-4s %-56s %s", ok ? "ok" : "FAIL", label, detail)
     end
 
+    # Persistent chrome docked in the portal (DESIGN_HISTORY #17.3, the README "Persistent chrome" convention):
+    # real-edge placement (left:0, top:0, height:100vh), qnt-sized width, at two very different viewport heights --
+    # proving it stays pinned with zero cropping and its width tracks the real viewport, not a fixed root.
+    [ [ 1400, 1000 ], [ 1400, 500 ] ].each do |w, h|
+      driver.manage.window.resize_to(w, h)
+      sidebar = driver.execute_script(<<~JS)
+        const el = document.getElementById('chrome-sidebar');
+        const b = el.getBoundingClientRect();
+        return { l: b.left, t: b.top, w: b.width, h: b.height,
+                 qnt: parseFloat(getComputedStyle(el).getPropertyValue('--qnt')),
+                 vh: window.innerHeight };
+      JS
+      ok = near.(sidebar["l"], 0) && near.(sidebar["t"], 0) && near.(sidebar["h"], sidebar["vh"]) && near.(sidebar["w"], 64 * sidebar["qnt"])
+      total += 1
+      failures += 1 unless ok
+      puts format("%-4s %-56s %s", ok ? "ok" : "FAIL", "docked chrome stays pinned full-height at viewport #{h}px",
+                   "l=#{sidebar['l'].round(1)} t=#{sidebar['t'].round(1)} h=#{sidebar['h'].round(1)} w=#{sidebar['w'].round(1)} (qnt #{sidebar['qnt']})")
+    end
+
     # The unit: one thousandth of the canvas width, from CSS alone, measured against the canvas even inside a nearer
     # size container; outside a canvas it approximates from the viewport.
     qnt = ->(id) { driver.execute_script("return getComputedStyle(arguments[0] ? document.getElementById(arguments[0]) : document.documentElement).getPropertyValue('--qnt').trim()", id) }
@@ -171,6 +194,21 @@ Dir.mktmpdir do |dir|
       failures += 1 unless ok
       puts format("%-4s %-56s %s", ok ? "ok" : "FAIL", "text-size-linear[3]/[96] scale linearly at #{vw}px", sizes.map { |v| v.round(3) }.inspect)
     end
+    # Clamped percentage-of-parent spacing (DESIGN_HISTORY #17.2): qss-elastic-y-min[20]/pct[100]/max[80] on a
+    # 400x300 actor's parent, canvas at 1000px (qnt=1px) so min=20px/max=80px exactly; pct[100] is 10% of the
+    # parent's actual height. Resizing the parent alone (not the canvas) proves the clamp tracks the immediate
+    # containing block's real size, floors below it, and caps above it -- not just that the middle value computes.
+    # Reset the canvas width first: the qnt sweep above leaves it at 5000px (qnt dampened to 3.2px).
+    driver.execute_script("document.getElementById('qss-canvas').style.width = '1000px'")
+    [ [ 100, 20 ], [ 300, 30 ], [ 1000, 80 ] ].each do |parent_h, expected_top|
+      driver.execute_script("document.getElementById('elastic-parent').style.height = arguments[0] + 'px'", parent_h)
+      actual = driver.execute_script("return parseFloat(getComputedStyle(document.getElementById('elastic-actor')).top)")
+      ok = near.(actual, expected_top)
+      total += 1
+      failures += 1 unless ok
+      puts format("%-4s %-56s top=%s%s", ok ? "ok" : "FAIL", "elastic-y clamp at parent height #{parent_h}px", actual, ok ? "" : " (expected #{expected_top})")
+    end
+
     viewport = driver.execute_script("return window.innerWidth")
     expected = "#{(viewport * 0.001).round(4).to_s.sub(/\.0\z/, '')}px"
     actual = qnt.(nil)

data/exe/qss-engine-render-check

@@ -29,7 +29,10 @@ HTML = <<~HTML
     <div class="foreign"><div id="foreign-fixed" style="position: fixed"></div></div>
   </div>
   <div id="body-fixed" style="position: fixed"></div>
-  <div id="qss-portal"><div id="portal-fixed" style="position: fixed"></div></div>
+  <div id="qss-portal">
+    <div id="portal-fixed" style="position: fixed"></div>
+    <div id="portal-auto-name" class="qss qss-w[200] qss-h[100]"></div>
+  </div>
   <dialog id="top-layer-modal"></dialog>
   </body></html>
 HTML
@@ -69,7 +72,10 @@ Dir.mktmpdir do |dir|
 
     [
       [ "the engine names an actor's container after its own id", "auto-name", "auto-name" ],
-      [ "the engine never overwrites a container-name already set by anything", "explicit-name", "custom-name" ]
+      [ "the engine never overwrites a container-name already set by anything", "explicit-name", "custom-name" ],
+      # DESIGN_HISTORY #17.3: the portal is where an entire layout's viewport-anchored chrome lives, not a
+      # secondary concern -- its actors need the same named container-query support canvas frames get.
+      [ "the engine also names an actor's container inside the portal root", "portal-auto-name", "portal-auto-name" ]
     ].each do |label, id, expected|
       actual = computed_name.(id)
       ok = actual == expected

data/lib/qss/qss_auditor.rb

@@ -33,6 +33,10 @@ module QSS
       'qss-cursor-pointer',
       'qss-cursor-row-resize',
       'qss-dev-border',
+      'qss-elastic-y',
+      'qss-elastic-y-max',
+      'qss-elastic-y-min',
+      'qss-elastic-y-pct',
       'qss-ergonomic-override',
       'qss-evenly',
       'qss-fixed',
@@ -114,7 +118,7 @@ module QSS
 
     PAYLOAD_TAGS = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "label", "blockquote", "li"].freeze
 
-    ADJECTIVE_CATEGORIES = {"positional"=>["qss-absolute", "qss-fixed", "qss-sticky", "qss-pos-x", "qss-pos-y", "qss-pos-r", "qss-pos-b", "qss-pos"], "flow_relative"=>["qss-relative"], "layout"=>["qss-flex-col", "qss-flex-row", "qss-centered", "qss-v-start", "qss-items-center", "qss-v-end", "qss-h-start", "qss-justify-center", "qss-h-end", "qss-justify-between", "qss-around", "qss-evenly", "qss-flex", "qss-flex-wrap", "qss-flex-nowrap", "qss-flex-1", "qss-flex-auto", "qss-flex-none", "qss-grid", "qss-table-fixed", "qss-contain-layout", "qss-w-full", "qss-h-full", "qss-w-f", "qss-h-f"], "typographic"=>["qss-italic", "qss-uppercase", "qss-lowercase", "qss-underline", "qss-nowrap", "qss-truncate", "qss-font-mono", "qss-font-sans", "qss-font-medium", "qss-font-bold", "qss-font-black", "qss-text-size", "qss-text-size-linear", "qss-leading", "qss-tracking", "qss-tracking-tighter", "qss-tracking-wide", "qss-tracking-wider", "qss-tracking-widest", "qss-icon-size"], "visual"=>["qss-border", "qss-border-t", "qss-border-b", "qss-border-l", "qss-border-r", "qss-rounded", "qss-rounded-full", "qss-shadow", "qss-opacity", "qss-blur", "qss-bright", "qss-contrast", "qss-grayscale", "qss-hue", "qss-invert", "qss-saturate", "qss-sepia", "qss-blend", "qss-contain", "qss-cover", "qss-visible", "qss-invisible", "qss-bg-alpha", "qss-border-alpha", "qss-text-alpha"], "interactive"=>["qss-cursor-pointer", "qss-transition-all", "qss-busy", "qss-ghost", "qss-unselectable", "qss-scroll-smooth", "qss-scroll", "qss-cursor-col-resize", "qss-cursor-row-resize", "qss-transition-colors", "qss-transition-none", "qss-ring", "qss-resize", "qss-outline-none"], "internal"=>["qss", "qss-dev-border", "group", "foreign", "qss-legibility-override", "qss-ergonomic-override", "qss-payload-override", "qss-paint-override", "qss-content-driven", "qss-overlay-fallback"]}.freeze
+    ADJECTIVE_CATEGORIES = {"positional"=>["qss-absolute", "qss-fixed", "qss-sticky", "qss-pos-x", "qss-pos-y", "qss-pos-r", "qss-pos-b", "qss-pos", "qss-elastic-y-min", "qss-elastic-y-pct", "qss-elastic-y-max", "qss-elastic-y"], "flow_relative"=>["qss-relative"], "layout"=>["qss-flex-col", "qss-flex-row", "qss-centered", "qss-v-start", "qss-items-center", "qss-v-end", "qss-h-start", "qss-justify-center", "qss-h-end", "qss-justify-between", "qss-around", "qss-evenly", "qss-flex", "qss-flex-wrap", "qss-flex-nowrap", "qss-flex-1", "qss-flex-auto", "qss-flex-none", "qss-grid", "qss-table-fixed", "qss-contain-layout", "qss-w-full", "qss-h-full", "qss-w-f", "qss-h-f"], "typographic"=>["qss-italic", "qss-uppercase", "qss-lowercase", "qss-underline", "qss-nowrap", "qss-truncate", "qss-font-mono", "qss-font-sans", "qss-font-medium", "qss-font-bold", "qss-font-black", "qss-text-size", "qss-text-size-linear", "qss-leading", "qss-tracking", "qss-tracking-tighter", "qss-tracking-wide", "qss-tracking-wider", "qss-tracking-widest", "qss-icon-size"], "visual"=>["qss-border", "qss-border-t", "qss-border-b", "qss-border-l", "qss-border-r", "qss-rounded", "qss-rounded-full", "qss-shadow", "qss-opacity", "qss-blur", "qss-bright", "qss-contrast", "qss-grayscale", "qss-hue", "qss-invert", "qss-saturate", "qss-sepia", "qss-blend", "qss-contain", "qss-cover", "qss-visible", "qss-invisible", "qss-bg-alpha", "qss-border-alpha", "qss-text-alpha"], "interactive"=>["qss-cursor-pointer", "qss-transition-all", "qss-busy", "qss-ghost", "qss-unselectable", "qss-scroll-smooth", "qss-scroll", "qss-cursor-col-resize", "qss-cursor-row-resize", "qss-transition-colors", "qss-transition-none", "qss-ring", "qss-resize", "qss-outline-none"], "internal"=>["qss", "qss-dev-border", "group", "foreign", "qss-legibility-override", "qss-ergonomic-override", "qss-payload-override", "qss-paint-override", "qss-content-driven", "qss-overlay-fallback"]}.freeze
 
     ILLEGAL_COMBOS = [{"tag_in"=>"payload_tags", "forbid_category"=>"positional", "severity"=>"red", "message"=>"Protocol Violation: Payload tags (<tag>) cannot carry flow-breaking positional adjectives. Use a wrapping <div> Frame.", "escape_hatch"=>"qss-payload-override"}].freeze
 

data/lib/qss/version.rb

@@ -3,7 +3,7 @@
 module QSS
   # The gem's version. QSS::VERSION is the usual spelling; QSS::Version::STRING the same value.
   module Version
-    STRING = "0.6.0"
+    STRING = "0.7.0"
   end
 
   VERSION = Version::STRING

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qss
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kraig Fairhurst
@@ -94,13 +94,15 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: |-
-  AI coding agents struggle with CSS. Asked to move a sidebar 10px, an agent edits a margin, then an order, then a flex-basis, and something else moves. It then reports the change as done while the page is broken. Flex and grid have no single "left" property, so the agent has to guess which one to touch.
+  Ask an AI coding agent to move a button 10 pixels left, and watch it struggle. CSS gives it five or six different ways to control position: margin, padding, a flex order, a grid column, a transform. Nothing says which one is actually in charge on this particular page, so the agent guesses, edits the wrong one, and something else quietly shifts. It reports the change as done. The page is now broken.
 
-  QSS makes layout addressable. Every structural value is an explicit, single-purpose quantity on a 1000-unit canvas grid (1 qnt = canvas width / 1000, computed in pure CSS), so each edit has one target and the same numbers hold at any screen size. Frames sit flat on one canvas, isolate their layout, and overlays portal to the document root.
+  QSS removes the guessing by removing the choice. Every element's position and size is one explicit number, not a tug-of-war between properties. Those numbers are written in a single unit, a "qnt" (1/1000th of the layout's own width), so the same edit holds its exact proportion at any screen size -- a phone, a laptop, a 4K display -- with no breakpoints, no media queries, and no separate rules to keep in sync. Move something once and it stays put, everywhere.
 
-  QSS also audits what can be checked statically. Two auditors flag violations such as !important, inline layout styles, undeclared sizes and raw viewport units. RED marks a rule violation and ORANGE a judgment call. Static checks can't prove a page renders, so QSS includes a render check for the compiled CSS alone, and its design history is explicit that only a real browser is real proof.
+  That is the whole idea, and it helps humans exactly as much as it helps agents: fewer rules to maintain, one obvious place to make a change, and layouts that stay consistent across devices by construction instead of by discipline.
 
-  QSS was extracted from a Rails development tool, which was its first consumer. Its early custom parser was a bug farm, and an invented syntax costs agents more than it buys. Structure moved to plain CSS custom properties; bracket values remain for content such as spacing and sizes. What was tried and dropped is in docs/DESIGN_HISTORY.md.
+  QSS backs that up with two automatic auditors that catch mistakes a human reviewer might miss (a RED finding is a broken rule, ORANGE is a judgment call) and a real-browser render check, because a passing lint rule is not proof a page actually displays correctly -- only watching it render is. It ships compiled, ready-to-use CSS plus its SCSS source, works with zero JavaScript, and offers an optional JS engine for a few conveniences on top. It stays out of the way of whatever you use for colors, type and visual polish (Tailwind or anything else) -- QSS only ever owns position, size and structure.
+
+  QSS was extracted from a real Rails development tool that still runs on it today, not built as a theoretical exercise. See docs/HOWTO.md to get started and docs/DESIGN_HISTORY.md for the full story of what was tried, what broke, and why each decision landed where it did.
 
   Status: 0.x. Expect names and APIs to change before 1.0.
 email:
@@ -125,6 +127,8 @@ files:
 - config/grammar.yml
 - config/integrity.json
 - config/qss-objects.json
+- docs/DESIGN_HISTORY.md
+- docs/HOWTO.md
 - exe/qss-core-render-check
 - exe/qss-engine-render-check
 - exe/qss-seal
@@ -144,7 +148,7 @@ metadata:
   source_code_uri: https://bitbucket.org/kmf2/qss
   bug_tracker_uri: https://bitbucket.org/kmf2/qss/issues
   changelog_uri: https://bitbucket.org/kmf2/qss/src/main/CHANGELOG.md
-  documentation_uri: https://bitbucket.org/kmf2/qss/src/main/docs/DESIGN_HISTORY.md
+  documentation_uri: https://bitbucket.org/kmf2/qss/src/main/docs/HOWTO.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -163,6 +167,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.13
 specification_version: 4
-summary: 'Quantized Spatial Styling: CSS layout that AI agents can read, edit and
-  check from source'
+summary: A CSS layout system built so AI agents (and the humans reviewing them) never
+  have to guess
 test_files: []