@almadar/std 16.241.0 → 16.243.0

package/behaviors/lolo/ui/core/atoms/std-doc-page.lolo

@@ -0,0 +1,153 @@
+app std-doc-page "1.0.0"
+"std-doc-page — one page of a documentation site: a section sidebar with the current page marked, a breadcrumb, the page title and lede, an \"on this page\" contents list, the page's own content (a render slot the call site fills, live behaviors included) and previous/next links. Supports right-to-left pages. Pick for docs sites, handbooks, reference manuals and knowledge bases."
+type DocNavItem = { label : string!, href : string, items : [DocNavItem], active : boolean }
+type DocCrumb = { label : string!, href : string }
+type DocTocEntry = { id : string!, label : string!, level : number! }
+type DocLink = { label : string!, href : string!, category : string }
+orbital DocPageOrbital {
+
+  entity DocPageView [runtime] {
+    id : string!
+  }
+
+  trait DocPageRender -> @rebindable DocPageView [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          type: box
+          paddingY: lg
+          fullWidth: true
+          dir: @config.direction
+          children: [{
+            type: container
+            size: xl
+            maxWidth: xl
+            padding: lg
+            children: [{
+              type: split
+              ratio: "1:4"
+              gap: xl
+              children: [{
+                type: stack
+                direction: vertical
+                gap: sm
+                className: "lg:sticky lg:top-6 self-start"
+                children: [{
+                  type: typography
+                  content: @config.sidebarLabel
+                  variant: label
+                  weight: semibold
+                  className: (if (== @config.sidebarLabel "") hidden "px-3")
+                }, {
+                  type: doc-sidebar
+                  items: @config.navItems
+                  aria-label: @config.sidebarLabel
+                }]
+              }, {
+                type: stack
+                direction: vertical
+                gap: lg
+                className: "min-w-0"
+                children: [{
+                  type: doc-breadcrumb
+                  items: @config.crumbs
+                  className: (if (== (array/len @config.crumbs) 0) hidden "")
+                }, {
+                  type: stack
+                  direction: vertical
+                  gap: sm
+                  children: [{
+                    type: typography
+                    content: @config.title
+                    variant: h1
+                    weight: bold
+                    className: "tracking-tight text-balance"
+                  }, {
+                    type: typography
+                    content: @config.lede
+                    variant: large
+                    color: muted
+                    className: (if (== @config.lede "") hidden "max-w-3xl text-pretty")
+                  }]
+                }, {
+                  type: box
+                  bg: muted
+                  padding: md
+                  rounded: lg
+                  className: (if (== (array/len @config.toc) 0) hidden "")
+                  children: [{
+                    type: stack
+                    direction: vertical
+                    gap: xs
+                    children: [{
+                      type: typography
+                      content: @config.tocLabel
+                      variant: label
+                      weight: semibold
+                    }, {
+                      type: doc-toc
+                      items: @config.toc
+                      aria-label: @config.tocLabel
+                    }]
+                  }]
+                }, @config.content, {
+                  type: divider
+                }, {
+                  type: doc-pagination
+                  prev: (if (== (object/get @config.prev href "") "") null @config.prev)
+                  next: (if (== (object/get @config.next href "") "") null @config.next)
+                }]
+              }]
+            }]
+          }]
+        })
+    }
+
+    config {
+      title : string = "Untitled page"
+        @label "Title"
+        @tier "presentation"
+      lede : string = ""
+        @label "Lede"
+        @description "One or two sentences under the title; empty hides it"
+        @tier "presentation"
+      content : render-ui = { type: stack, direction: vertical, gap: lg, children: [] }
+        @label "Content"
+        @description "The page body: markdown, code and live behaviors (trait references) in reading order"
+        @tier "presentation"
+      navItems : [DocNavItem] = []
+        @label "Sidebar"
+        @description "The documentation tree; mark the current page active"
+        @tier "presentation"
+      sidebarLabel : string = "Documentation"
+        @label "Sidebar label"
+        @tier "presentation"
+      crumbs : [DocCrumb] = []
+        @label "Breadcrumb"
+        @description "Ancestors first, the current page last without a link; empty hides it"
+        @tier "presentation"
+      toc : [DocTocEntry] = []
+        @label "On this page"
+        @description "Anchors of the page's sections (each section declares the same id); empty hides it"
+        @tier "presentation"
+      tocLabel : string = "On this page"
+        @label "Contents label"
+        @tier "presentation"
+      prev : DocLink = { label: "", href: "" }
+        @label "Previous page"
+        @description "Empty href hides it"
+        @tier "presentation"
+      next : DocLink = { label: "", href: "" }
+        @label "Next page"
+        @description "Empty href hides it"
+        @tier "presentation"
+      direction : "ltr" | "rtl" = "ltr"
+        @label "Direction"
+        @tier "presentation"
+    }
+  }
+
+  page "/doc" as DocPage -> DocPageRender
+}

package/behaviors/lolo/ui/learning/atoms/std-learn-arrangement.lolo

@@ -31,6 +31,11 @@ orbital LearnArrangementOrbital {
     fill : string
     lineWidth : number
     opacity : number
+    tone : string
+    fillTone : string
+    stroke : string
+    textSize : string
+    fillStyle : string
   }
   type LearnArrangementItem = {
     id : string!
@@ -75,8 +80,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -87,23 +92,30 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
+                  ] },
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
 
+      MODE_SELECTED -> idle when (and (not (== @config.matchMode "")) (not (== ?mode @config.matchMode)))
+        (set @entity.active false)
+        (render-ui main null)
+
       MODE_SELECTED -> idle when (== ?mode @config.matchMode)
         (set @entity.active true)
         (set @entity.title @config.title)
@@ -124,8 +136,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -136,19 +148,22 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
+                  ] },
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
@@ -170,8 +185,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -182,19 +197,22 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
+                  ] },
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
@@ -216,8 +234,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -228,19 +246,22 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
+                  ] },
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
@@ -272,8 +293,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -284,19 +305,22 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
+                  ] },
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
@@ -320,8 +344,8 @@ orbital LearnArrangementOrbital {
                     (bx (+ @config.slotLeft (* @i @config.slotSpacing)))
                   )
                   [
-                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, color: @config.slotBorderColor, fill: @fillColor },
-                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), fontSize: @config.slotFontSize, align: "center", color: @config.slotTextColor }
+                    { type: "rect", id: (str/concat "slot-" @i), x: @bx, y: @config.slotY, width: @config.slotWidth, height: @config.slotHeight, tone: @config.slotBorderColor, fillTone: @fillColor, fillStyle: "tint" },
+                    { type: "text", id: (str/concat "slot-label-" @i), x: (+ @bx (/ @config.slotWidth 2)), y: (+ @config.slotY (/ @config.slotHeight 2) 5), text: (if @filled @label (str/concat "" (+ @i 1))), textSize: @config.slotFontSize, align: "center", tone: @config.slotTextColor }
                   ]
                 )))))
           )
@@ -332,19 +356,22 @@ orbital LearnArrangementOrbital {
           padding: md
           children: [
             { type: stack, direction: vertical, gap: md, children: [
-                { type: typography, variant: h4, content: @entity.title },
-                { type: typography, variant: body, content: "Tap items below to build the sequence in order, then press Check." },
-                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate },
-                { type: stack, direction: horizontal, gap: xs, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: sm })) },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: button, action: UNDO, label: @config.undoLabel, variant: ghost, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
-                    { type: button, action: CHECK, label: @config.checkLabel, variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
-                    { type: button, action: RETRY, label: @config.retryLabel, variant: ghost }
+                { type: stack, direction: horizontal, justify: between, align: start, gap: md, children: [
+                    { type: stack, direction: vertical, gap: xs, children: [
+                        { type: typography, variant: h4, content: @entity.title },
+                        (if (== @config.summary "") null { type: typography, variant: body2, color: muted, content: @config.summary })
+                      ] },
+                    { type: badge, label: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "Correct" (str/concat @entity.correctCount " / " @entity.totalItems " correct")) (str/concat (array/len @entity.placedIds) " / " @entity.totalItems " placed")), variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "error") "neutral") }
                   ] },
-                { type: stack, direction: horizontal, gap: sm, children: [
-                    { type: badge, variant: (if @entity.checked (if (== @entity.correctCount @entity.totalItems) "success" "danger") "neutral"), label: (if @entity.checked @entity.verdict "Not checked yet") },
-                    { type: stat-display, label: "Score", value: @entity.correctCount, max: @entity.totalItems }
-                  ] }
+                { type: math-canvas, width: @config.width, height: @config.height, xMin: 0, xMax: @config.width, yMin: 0, yMax: @config.height, showAxes: false, showGrid: false, gridStep: 1, curves: [], points: [], vectors: [], shapes: @entity.slotShapes, interactive: @config.interactive, animate: @config.animate, keyMap: { Space: CHECK, Backspace: UNDO, KeyR: RETRY } },
+                { type: stack, direction: vertical, gap: sm, children: (array/map (array/filter @config.items (fn it (not (array/includes @entity.placedIds (object/get @it id))))) (fn it { type: button, action: PLACE, actionPayload: { itemId: (object/get @it id) }, label: (if (!= (object/get @it hint "") "") (str/concat (object/get @it label) " — " (object/get @it hint "")) (object/get @it label)), variant: secondary, size: lg, disabled: @entity.checked })) },
+                { type: stack, direction: horizontal, align: center, gap: sm, wrap: true, children: [
+                    { type: button, action: CHECK, label: @config.checkLabel, icon: "check", variant: primary, disabled: (if (>= (array/len @entity.placedIds) @entity.totalItems) false true) },
+                    { type: button, action: UNDO, label: @config.undoLabel, icon: "chevron-left", variant: secondary, disabled: (if (> (array/len @entity.placedIds) 0) false true) },
+                    { type: button, action: RETRY, label: @config.retryLabel, icon: "rotate-ccw", variant: ghost },
+                    { type: typography, variant: caption, color: muted, content: (str/concat "Placed " (array/len @entity.placedIds) " of " @entity.totalItems) }
+                  ] },
+                { type: typography, variant: body, content: (if @entity.checked @entity.verdict "Tap items to build the sequence in order, then press Check.") }
               ] }
           ]
         })
@@ -407,6 +434,10 @@ orbital LearnArrangementOrbital {
         @label "Title"
         @description "Title shown above the instrument."
         @tier "presentation"
+      summary : string = ""
+        @label "Concept"
+        @description "One line under the title saying what is being ordered (keep it under ~65 characters). Empty shows no line."
+        @tier "presentation"
       width : number = 640
         @label "Width"
         @description "Canvas width in pixels."
@@ -434,19 +465,19 @@ orbital LearnArrangementOrbital {
         @description "Roster of items to order; each carries its label, its zero-based correct position in the finished sequence, and an optional hint shown beneath its button while unplaced."
         @synonyms "item, step, stage, sequence, order, ranking, procedure"
         @tier "domain"
-      correctColor : string = "#16a34a"
+      correctColor : string = "success"
         @label "Correct Slot Color"
         @description "Fill color for a filled slot whose item matches its correct position, once graded."
         @tier "presentation"
-      incorrectColor : string = "#dc2626"
+      incorrectColor : string = "error"
         @label "Incorrect Slot Color"
         @description "Fill color for a filled slot whose item does not match its correct position, once graded."
         @tier "presentation"
-      pendingColor : string = "#94a3b8"
+      pendingColor : string = "series-2"
         @label "Pending Slot Color"
         @description "Fill color for a filled slot before grading."
         @tier "presentation"
-      emptySlotColor : string = "#e2e8f0"
+      emptySlotColor : string = "fill"
         @label "Empty Slot Color"
         @description "Fill color for a slot with no item placed yet."
         @tier "presentation"
@@ -465,13 +496,14 @@ orbital LearnArrangementOrbital {
       slotY : number = 70
         @label "Slot Row Y (px)"
         @tier "presentation"
-      slotFontSize : number = 13
-        @label "Slot Font Size"
+      slotFontSize : string = "sm"
+        @label "Slot Text Size"
+        @description "Slot label size role: xs, sm, base or lg."
         @tier "presentation"
-      slotBorderColor : string = "#334155"
+      slotBorderColor : string = "ink"
         @label "Slot Border Color"
         @tier "presentation"
-      slotTextColor : string = "#0f172a"
+      slotTextColor : string = "label"
         @label "Slot Text Color"
         @tier "presentation"
       undoLabel : string = "Undo"