studio-engine 0.117.0 → 0.118.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27c8703c859ad0039101776ceeeee457d6f2bd47df12a5180ebc20aa1127ad8c
-  data.tar.gz: 6b05c69deb801b08c6d1f6b31012220bf07b43cebb06b22e8becbd14fab159b0
+  metadata.gz: 48ec929ff6a1178b1f5d031f591f3e6f90f4e3257feb303063e40dcd9b142eeb
+  data.tar.gz: c4215b12c48ac7dbcb829e53faca80412007f2da8c0d785641412d375f847f74
 SHA512:
-  metadata.gz: 92bb22f3f1c1e28d7b2606541f2880ff098f3ff18986f29476fdfe66a9713c8e7565c72059e684a66b1c82251b86f0984b95bea4e8b2640775ddb0401a02e03a
-  data.tar.gz: 81332763ef29a2ccb68ca9f143b3c828022b5a3f42e6d47b30c63334ed59363a6decabe7e611c9e471bc1b9e539ade2be5f0b8ce71373d54ccce7d86f607ef05
+  metadata.gz: 898cba360f134fbc33f800b329e0914a82ed6ecb2af4306dc907361a246845d7974f70f80b2f3740bace96bd2ea7d08ff93b3a4523e27e3a30c223445e442c95
+  data.tar.gz: df32d0a535175c62b3390e8cbbbbc1df96d1be5ac4479711ee388cdbb3643914ec37ca3b04a43c79d1a4d12279145baa2777143079a633f7ba844bb141d9a99c

data/CHANGELOG.md

@@ -4,6 +4,18 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.118.0 — 2026-10-28
+
+### Added
+
+- **The type scale: five text roles every app draws from.** `type-title` (6x),
+  `type-heading` (3x), `type-subhead` (1.5x), `type-body` (1x) and `type-fine`
+  (0.75x), each a multiple of `--type-base`, which the theme tag sets from
+  `Studio.type_base` (16). A `type-dense` container swaps in
+  `Studio.type_dense_base` (14) for admin and ops pages. Title and heading take
+  `Studio.type_display_weight` (800), the rest `Studio.type_text_weight` (400).
+  Nothing changes on a page until it uses a role. README "Type scale".
+
 ## 0.117.0 — 2026-10-28
 
 ### Changed

data/README.md

@@ -310,6 +310,47 @@ flag — it cannot know where the reader is sitting, so only the reader's machin
 may assert one. A host that omits the script still gets working stamps, just
 frozen in the app's timezone. Specimen: `/admin/style` → Tricks → Time stamps.
 
+### Type scale — `type-*`
+
+The one set of text sizes every Studio app uses (Alex McRitchie's standard,
+2026-10-28; the hub's `/logos/<brand>` Type Scale card shows it per brand).
+Each role is a multiple of one base:
+
+| Utility | Multiple | Public base (16 px) | Dense base (14 px) | Weight |
+|---|---|---|---|---|
+| `type-title` | 6x | 96 px | 84 px | display |
+| `type-heading` | 3x | 48 px | 42 px | display |
+| `type-subhead` | 1.5x | 24 px | 21 px | text |
+| `type-body` | 1x | 16 px | 14 px | text |
+| `type-fine` | 0.75x | 12 px | 10.5 px | text |
+
+```erb
+<h1 class="type-title text-heading">Winter Run 2026</h1>
+<p class="type-body text-body">Since 2016 ...</p>
+
+<%# an admin or ops page: everything inside takes the dense base %>
+<main class="type-dense">
+  <h1 class="type-heading text-heading">Releases</h1>
+</main>
+```
+
+- **Public pages** use the public base. **Admin and ops pages** put
+  `type-dense` on their container: the roles inside keep their ratios on the
+  dense base.
+- **Set the base and weights from the brand kit**, in
+  `config/initializers/studio.rb`: `Studio.type_base`,
+  `Studio.type_dense_base`, `Studio.type_display_weight`,
+  `Studio.type_text_weight`. The theme tag (`studio_theme_css_tag`) writes them
+  as `--type-base`, `--type-dense-base`, `--type-display-weight` and
+  `--type-text-weight`; a bad value raises, naming the setting.
+- **A role sets size, weight and line height only.** Colour stays with
+  `text-heading`, `text-body` and the rest, which are colour utilities, not
+  sizes.
+- **Nothing is smaller than `type-fine`.** A new page uses the roles, not
+  `text-xs` or `text-2xs`; existing pages move over app by app.
+- The multiples live in `Studio::TypeScale::ROLES` and in `engine.css`;
+  `test/lib/type_scale_contract_test.rb` keeps the two the same.
+
 ### Tints and shades — `.scrim`
 
 Text laid over media on a PAGE (a hero photo, a video, a banner) reads through

data/app/assets/tailwind/studio_engine/engine.css

@@ -179,6 +179,50 @@ body.modal-open .studio-app-banner {
   @apply bg-inset rounded-xl border border-subtle p-4 overflow-x-auto;
 }
 
+/* -- Type scale ------------------------------------------------------------
+   The one set of text sizes every app draws from (Studio::TypeScale, README
+   "Type scale"). Each role is a multiple of --type-base: title 6x, heading 3x,
+   subhead 1.5x, body 1x, fine print 0.75x. The theme tag sets the app's base
+   (Studio.type_base, 16px) and weights; `type-dense` swaps in the dense base
+   (Studio.type_dense_base, 14px) for everything inside it, for admin and ops
+   pages. The fallbacks are the engine defaults, for a page with no theme tag.
+   The multiples here must match Studio::TypeScale::ROLES
+   (test/lib/type_scale_contract_test.rb). */
+
+@utility type-dense {
+  --type-base: var(--type-dense-base, 14px);
+}
+
+@utility type-title {
+  font-size: calc(var(--type-base, 16px) * 6);
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.05;
+}
+
+@utility type-heading {
+  font-size: calc(var(--type-base, 16px) * 3);
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.1;
+}
+
+@utility type-subhead {
+  font-size: calc(var(--type-base, 16px) * 1.5);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.25;
+}
+
+@utility type-body {
+  font-size: calc(var(--type-base, 16px) * 1);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.5;
+}
+
+@utility type-fine {
+  font-size: calc(var(--type-base, 16px) * 0.75);
+  font-weight: var(--type-text-weight, 400);
+  line-height: 1.4;
+}
+
 /* -- Scrims: tints and shades ----------------------------------------------
    A scrim is the wash laid over media (a photo, a video) so text reads on it.
    It comes in two TONES, and the tone is a design decision, not a colour pick:

data/app/helpers/studio_theme_helper.rb

@@ -10,6 +10,6 @@ module StudioThemeHelper
       Studio::ThemeResolver.new(colors).to_css
     end
 
-    tag.style("#{css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
+    tag.style("#{css}\n#{Studio::TypeScale.css}\n#{Studio::UiPrimitives.css}".html_safe, nonce: content_security_policy_nonce)
   end
 end

data/lib/studio/type_scale.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Studio
+  # THE TYPE SCALE — the one set of text sizes every Studio app draws from
+  # (task engine-type-scale-roles). Alex McRitchie ruled it the standard for
+  # every app on 2026-10-28; the hub's /logos/<brand> Type Scale card shows the
+  # same multiples per brand.
+  #
+  # Each role is a multiple of one base: title 6x, heading 3x, subhead 1.5x,
+  # body 1x, fine print 0.75x. engine.css draws the roles as the utilities
+  # `type-title`, `type-heading`, `type-subhead`, `type-body` and `type-fine`
+  # (not `text-heading` / `text-body`: those are colour utilities).
+  #
+  # An app has TWO bases:
+  #   Studio.type_base        (16) public and marketing pages: 96/48/24/16/12
+  #   Studio.type_dense_base  (14) admin and ops pages, under a `type-dense`
+  #                                container: 84/42/21/14/10.5
+  # The ratios never change; a page picks its base by where it sits.
+  #
+  # This module emits the per-app variables the utilities read, in the theme
+  # tag (StudioThemeHelper#studio_theme_css_tag):
+  #
+  #   Studio::TypeScale.css
+  #   # => ":root {\n  --type-base: 16px;\n  --type-dense-base: 14px; ..."
+  module TypeScale
+    # [utility, multiple, weight] — weight :display or :text picks the app's
+    # Studio.type_display_weight or Studio.type_text_weight.
+    ROLES = [
+      ["type-title", 6, :display],
+      ["type-heading", 3, :display],
+      ["type-subhead", 1.5, :text],
+      ["type-body", 1, :text],
+      ["type-fine", 0.75, :text]
+    ].freeze
+
+    WEIGHTS = (100..900).step(100).to_a.freeze
+
+    def self.css
+      <<~CSS
+        :root {
+          --type-base: #{px(Studio.type_base, 'type_base')};
+          --type-dense-base: #{px(Studio.type_dense_base, 'type_dense_base')};
+          --type-display-weight: #{weight(Studio.type_display_weight, 'type_display_weight')};
+          --type-text-weight: #{weight(Studio.type_text_weight, 'type_text_weight')};
+        }
+      CSS
+    end
+
+    # The sizes a base gives, in pixels, largest first.
+    def self.sizes(base) = ROLES.to_h { |utility, multiple, _| [utility, base * multiple] }
+
+    def self.px(value, setting)
+      raise ArgumentError, "Studio.#{setting} must be a positive number of pixels, got #{value.inspect}" unless value.is_a?(Numeric) && value.positive?
+
+      "#{value.to_s.delete_suffix('.0')}px"
+    end
+
+    def self.weight(value, setting)
+      raise ArgumentError, "Studio.#{setting} must be one of #{WEIGHTS.join(', ')}, got #{value.inspect}" unless WEIGHTS.include?(value)
+
+      value.to_s
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.117.0"
+  VERSION = "0.118.0"
 end

data/lib/studio.rb

@@ -27,6 +27,7 @@ require "studio/color_scale"
 require "studio/environment_banner"
 require "studio/theme_resolver"
 require "studio/ui_primitives"
+require "studio/type_scale"
 require "studio/js_literal"
 require "studio/js_identifier"
 require "studio/hold_button"
@@ -1269,6 +1270,15 @@ module Studio
   mattr_accessor :theme_danger,   default: "#EF4444"
   mattr_accessor :theme_accent,   default: "#F72585"
 
+  # Type scale (Studio::TypeScale): the body size every type-* role multiplies.
+  # type_base for public pages, type_dense_base inside a `type-dense` container
+  # (admin and ops pages). Weights: title and heading take the display weight,
+  # subhead, body and fine print the text weight. Set them from the brand kit.
+  mattr_accessor :type_base,           default: 16
+  mattr_accessor :type_dense_base,     default: 14
+  mattr_accessor :type_display_weight, default: 800
+  mattr_accessor :type_text_weight,    default: 400
+
   # S3 / object storage — host apps MUST set s3_bucket_prefix explicitly in
   # config/initializers/studio.rb before any S3-touching code runs (ImageCache,
   # Studio::S3.upload, etc.). Default is nil so external users don't accidentally

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.117.0
+  version: 0.118.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -812,6 +812,7 @@ files:
 - lib/studio/survey/export.rb
 - lib/studio/tailwind_entry.rb
 - lib/studio/theme_resolver.rb
+- lib/studio/type_scale.rb
 - lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb
 - lib/studio/version.rb