@taprootio/espalier 3.7.0 → 3.9.0

package/dist/button/action-state-lightness.js

@@ -1 +1 @@
-const T=.9,N=.88,_=.8;export{_ as BUTTON_ICON_INTERACTION_LIGHTNESS_FACTOR,T as BUTTON_ICON_SPLIT_LIGHTNESS_FACTOR,N as BUTTON_INTERACTION_LIGHTNESS_FACTOR};
+const T=.88;export{T as BUTTON_INTERACTION_LIGHTNESS_FACTOR};

package/dist/button/esp-button.d.ts

@@ -1,5 +1,6 @@
 import { type TemplateResult } from "lit";
 import { EspalierElementBase } from "../shared/esp-element-base.js";
+export type ButtonIconPosition = "left" | "right";
 /**
  * Used to initiate a user action or link to another page.
  *
@@ -29,6 +30,27 @@ import { EspalierElementBase } from "../shared/esp-element-base.js";
  * </div>
  * ```
  *
+ * Use `icon-position="left"` for a leading icon. The default `"right"`
+ * position keeps the icon trailing; both positions follow writing direction
+ * and therefore mirror in RTL.
+ *
+ * ```html
+ * <div style="display: flex; gap: var(--esp-size-padding);">
+ *   <esp-button
+ *     collapsed
+ *     label="Save"
+ *     icon="save"
+ *     icon-position="left">
+ *   </esp-button>
+ *   <esp-button
+ *     collapsed
+ *     label="Next"
+ *     icon="arrow-big-right"
+ *     icon-position="right">
+ *   </esp-button>
+ * </div>
+ * ```
+ *
  * @customElement esp-button
  * @slot - Optional custom SVG icon. Slotted icons override the
  * generated SVG from the `icon` attribute.
@@ -180,6 +202,18 @@ export declare class EspalierButton extends EspalierElementBase {
      * @type {string}
      */
     icon: string;
+    /**
+     * Places the optional icon on the logical leading (`"left"`) or trailing
+     * (`"right"`) side of the label. Logical placement mirrors in RTL.
+     *
+     * ```html
+     * <esp-button label="Save" icon="save" icon-position="left"></esp-button>
+     * <esp-button label="Next" icon="arrow-big-right" icon-position="right"></esp-button>
+     * ```
+     *
+     * @type {"left" | "right"}
+     */
+    iconPosition: ButtonIconPosition;
     /**
      * The label of the button.
      *

package/dist/button/esp-button.js

@@ -1,4 +1,4 @@
-var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnPropertyDescriptor(t,i):e,c;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")r=Reflect.decorate(h,t,i,e);else for(var d=h.length-1;d>=0;d--)(c=h[d])&&(r=(a<3?c(r):a>3?c(t,i,r):c(t,i))||r);return a>3&&r&&Object.defineProperty(t,i,r),r};import{css as f,html as p,nothing as l}from"lit";import{customElement as m,eventOptions as v,property as s,state as y}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{ref as k}from"lit/directives/ref.js";import{getIconHrefForHost as x}from"../shared/intent-values.js";import{SlottedIconController as T}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as w}from"../shared/svgs/render-sprite-icon.js";import{BUTTON_ICON_INTERACTION_LIGHTNESS_FACTOR as S,BUTTON_ICON_SPLIT_LIGHTNESS_FACTOR as g,BUTTON_INTERACTION_LIGHTNESS_FACTOR as $}from"./action-state-lightness.js";const N=p`<svg
+var n=function(h,t,r,o){var a=arguments.length,i=a<3?t:o===null?o=Object.getOwnPropertyDescriptor(t,r):o,d;if(typeof Reflect=="object"&&typeof Reflect.decorate=="function")i=Reflect.decorate(h,t,r,o);else for(var c=h.length-1;c>=0;c--)(d=h[c])&&(i=(a<3?d(i):a>3?d(t,r,i):d(t,r))||i);return a>3&&i&&Object.defineProperty(t,r,i),i};import{css as f,html as p,nothing as l}from"lit";import{customElement as g,eventOptions as m,property as s,state as v}from"lit/decorators.js";import{classMap as u}from"lit/directives/class-map.js";import{EspalierElementBase as b}from"../shared/esp-element-base.js";import{ref as y}from"lit/directives/ref.js";import{getIconHrefForHost as w}from"../shared/intent-values.js";import{SlottedIconController as x}from"../shared/slotted-icon-controller.js";import{renderSpriteIcon as k}from"../shared/svgs/render-sprite-icon.js";import{BUTTON_INTERACTION_LIGHTNESS_FACTOR as T}from"./action-state-lightness.js";const S=p`<svg
   xmlns="http://www.w3.org/2000/svg"
   viewBox="0 0 24 24"
   fill="none"
@@ -10,40 +10,40 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
 >
   <path stroke="none" d="M0 0h24v24H0z" fill="none" />
   <path d="M4.05 11a8 8 0 1 1 .5 4m-.5 5v-5h5" />
-</svg>`;let o=class extends b{constructor(){super(...arguments),this.iconSlot=new T(this),this.innerTabindex=null,this.neutralizingTabindex=!1,this.buttonType="button",this.collapsed=!1,this.disabled=!1,this.href="",this.iconOnly=!1,this.incognito=!1,this.icon="",this.label="",this.loading=!1,this.target="",this.rel="",this.formNoValidate=!1,this.buildIcon=t=>this.loading?p` <span>${N}</span> `:p`
+</svg>`;let e=class extends b{constructor(){super(...arguments),this.iconSlot=new x(this),this.innerTabindex=null,this.neutralizingTabindex=!1,this.buttonType="button",this.collapsed=!1,this.disabled=!1,this.href="",this.iconOnly=!1,this.incognito=!1,this.icon="",this.iconPosition="right",this.label="",this.loading=!1,this.target="",this.rel="",this.formNoValidate=!1,this.buildIcon=t=>this.loading?p` <span>${S}</span> `:p`
       <span>
-        <slot ${k(this.iconSlot.slotRef)} @slotchange=${this.iconSlot.handleSlotChange}></slot>
-        ${!this.iconSlot.hasSlottedIcon(":scope > *")&&t?w(t):l}
+        <slot ${y(this.iconSlot.slotRef)} @slotchange=${this.iconSlot.handleSlotChange}></slot>
+        ${!this.iconSlot.hasSlottedIcon(":scope > *")&&t?k(t):l}
       </span>
-    `}static get observedAttributes(){return[...super.observedAttributes,"tabindex","aria-pressed"]}attributeChangedCallback(t,i,e){if(super.attributeChangedCallback(t,i,e),t==="aria-pressed"){this.requestUpdate();return}if(t!=="tabindex"||this.neutralizingTabindex)return;const a=e===null?null:Number(e),r=a===null||Number.isNaN(a)?null:a;r!==null&&r>=0?(this.innerTabindex=r,this.writeHostTabindex(null)):r===null&&e!==null?(this.innerTabindex=null,this.writeHostTabindex(null)):this.innerTabindex=r}writeHostTabindex(t){this.getAttribute("tabindex")!==t&&(this.neutralizingTabindex=!0,t===null?this.removeAttribute("tabindex"):this.setAttribute("tabindex",t),this.neutralizingTabindex=!1)}removeAttribute(t){super.removeAttribute(t),t==="tabindex"&&!this.neutralizingTabindex&&(this.innerTabindex=null)}focus(t){this.focusShadowElementAfterUpdate("button, a",t)}handleClick(t){if(this.dispatchEvent(new CustomEvent("clicked",{detail:{},bubbles:!0,composed:!0})),this.buttonType==="submit"){const i=this.closest("form");if(i){const e=document.createElement("button");e.type="submit",e.hidden=!0,this.formNoValidate&&(e.formNoValidate=!0),i.appendChild(e),i.requestSubmit(e),e.remove()}}else this.buttonType==="reset"&&this.closest("form")?.reset()}render(){const t=x(this.icon,this),i=this.loading||this.iconSlot.hasSlottedIcon(":scope > *")||t.length>0,{collapsed:e,iconOnly:a}=this,r=a?this.getAttribute("aria-label")||this.label||l:l,c=this.getAttribute("aria-pressed")||l,d={"esp-field":!0,"icon-only":a,incognito:this.incognito,"is-collapsed":e,"has-icon":i};return this.href.length?p`
-          <div part="wrapper" class=${u(d)}>
+    `}static get observedAttributes(){return[...super.observedAttributes,"tabindex","aria-pressed"]}attributeChangedCallback(t,r,o){if(super.attributeChangedCallback(t,r,o),t==="aria-pressed"){this.requestUpdate();return}if(t!=="tabindex"||this.neutralizingTabindex)return;const a=o===null?null:Number(o),i=a===null||Number.isNaN(a)?null:a;i!==null&&i>=0?(this.innerTabindex=i,this.writeHostTabindex(null)):i===null&&o!==null?(this.innerTabindex=null,this.writeHostTabindex(null)):this.innerTabindex=i}writeHostTabindex(t){this.getAttribute("tabindex")!==t&&(this.neutralizingTabindex=!0,t===null?this.removeAttribute("tabindex"):this.setAttribute("tabindex",t),this.neutralizingTabindex=!1)}removeAttribute(t){super.removeAttribute(t),t==="tabindex"&&!this.neutralizingTabindex&&(this.innerTabindex=null)}focus(t){this.focusShadowElementAfterUpdate("button, a",t)}handleClick(t){if(this.dispatchEvent(new CustomEvent("clicked",{detail:{},bubbles:!0,composed:!0})),this.buttonType==="submit"){const r=this.closest("form");if(r){const o=document.createElement("button");o.type="submit",o.hidden=!0,this.formNoValidate&&(o.formNoValidate=!0),r.appendChild(o),r.requestSubmit(o),o.remove()}}else this.buttonType==="reset"&&this.closest("form")?.reset()}render(){const t=w(this.icon,this),r=this.loading||this.iconSlot.hasSlottedIcon(":scope > *")||t.length>0,{collapsed:o,iconOnly:a}=this,i=a?this.getAttribute("aria-label")||this.label||l:l,d=this.getAttribute("aria-pressed")||l,c={"esp-field":!0,"icon-only":a,incognito:this.incognito,"is-collapsed":o,"has-icon":r,"icon-left":r&&!a&&this.iconPosition==="left"};return this.href.length?p`
+          <div part="wrapper" class=${u(c)}>
             <a
               ?disabled=${this.disabled}
               href=${this.href}
               target=${this.target}
               rel=${this.rel||l}
               tabindex=${this.innerTabindex??l}
-              aria-label=${r}
+              aria-label=${i}
             >
               <span>${this.label??""}</span>
               ${this.buildIcon(t)}
             </a>
           </div>
         `:p`
-          <div part="wrapper" class=${u(d)}>
+          <div part="wrapper" class=${u(c)}>
             <button
               ?disabled=${this.disabled||this.loading}
               @click=${this.handleClick}
               type=${this.buttonType}
               tabindex=${this.innerTabindex??l}
-              aria-label=${r}
-              aria-pressed=${c}
+              aria-label=${i}
+              aria-pressed=${d}
             >
               <span>${this.label??""}</span>
               ${this.buildIcon(t)}
             </button>
           </div>
-        `}};o.styles=[...b.styles,f`
+        `}};e.styles=[...b.styles,f`
       :host {
         --_esp-button-radius: var(--esp-size-border-radius);
       }
@@ -81,15 +81,8 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
           }
 
           > span:nth-child(2) {
-            background-color: oklch(
-              from var(--esp-color-action-background)
-                calc(l * ${g}) c h
-            );
             display: none;
             place-content: center;
-            border-left: 1px dotted var(--esp-color-border);
-            border-bottom-right-radius: max(0px, calc(var(--_esp-button-radius) - 0.1rem));
-            border-top-right-radius: max(0px, calc(var(--_esp-button-radius) - 0.1rem));
             padding: var(--esp-button-padding, var(--esp-size-padding));
 
             .generated-icon,
@@ -101,6 +94,17 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
           }
         }
 
+        &.icon-left {
+          button,
+          a {
+            grid-template-columns: min-content auto;
+
+            > span:nth-child(2) {
+              order: -1;
+            }
+          }
+        }
+
         &.has-icon {
           button,
           a {
@@ -123,7 +127,6 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
             }
 
             > span:nth-child(2) {
-              background-color: var(--esp-color-action-background);
               border: none;
               border-radius: var(--_esp-button-radius);
             }
@@ -136,24 +139,12 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
         &:hover,
         &:focus-within {
           background-color: oklch(
-            from var(--esp-color-action-background) calc(l * ${$})
+            from var(--esp-color-action-background) calc(l * ${T})
               c h
           );
-
-          button,
-          a {
-            > span:nth-child(2) {
-              background-color: oklch(
-                from var(--esp-color-action-background)
-                  calc(l * ${S}) c h
-              );
-              border-color: oklch(from var(--esp-color-border) calc(l * 1.2) c h);
-            }
-          }
         }
 
         &.incognito {
-          grid-template-columns: min-content auto;
           background-color: transparent;
           border-color: transparent;
           color: var(--esp-color-text);
@@ -162,17 +153,27 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
           button,
           a {
             > span:nth-child(1) {
-              grid-column: 2;
-              justify-content: left;
+              justify-content: start;
               padding: var(--esp-button-incognito-padding, var(--esp-size-tiny)) 0;
-              padding-right: calc(2 * var(--esp-button-incognito-padding, var(--esp-size-tiny)));
+              padding-inline-end: calc(
+                2 * var(--esp-button-incognito-padding, var(--esp-size-tiny))
+              );
             }
 
             > span:nth-child(2) {
-              grid-row: 1;
-              grid-column: 1;
               background-color: transparent;
-              border-color: transparent;
+            }
+          }
+
+          &.icon-left {
+            button,
+            a {
+              > span:nth-child(1) {
+                padding-inline-start: calc(
+                  2 * var(--esp-button-incognito-padding, var(--esp-size-tiny))
+                );
+                padding-inline-end: 0;
+              }
             }
           }
 
@@ -193,17 +194,6 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
         &:has(button:disabled):hover,
         &:has(button:disabled):focus-within {
           background-color: var(--esp-color-action-background);
-
-          button,
-          a {
-            > span:nth-child(2) {
-              background-color: oklch(
-                from var(--esp-color-action-background)
-                  calc(l * ${g}) c h
-              );
-              border-color: var(--esp-color-border);
-            }
-          }
         }
 
         svg.rotate {
@@ -223,4 +213,4 @@ var n=function(h,t,i,e){var a=arguments.length,r=a<3?t:e===null?e=Object.getOwnP
           transform: rotate(360deg);
         }
       }
-    `],n([y()],o.prototype,"innerTabindex",void 0),n([s({attribute:"button-type",type:String})],o.prototype,"buttonType",void 0),n([s({type:Boolean})],o.prototype,"collapsed",void 0),n([s({type:Boolean,reflect:!0})],o.prototype,"disabled",void 0),n([s({type:String})],o.prototype,"href",void 0),n([s({attribute:"icon-only",type:Boolean})],o.prototype,"iconOnly",void 0),n([s({type:Boolean,reflect:!0})],o.prototype,"incognito",void 0),n([s({type:String})],o.prototype,"icon",void 0),n([s({type:String})],o.prototype,"label",void 0),n([s({type:Boolean,reflect:!0})],o.prototype,"loading",void 0),n([s({type:String})],o.prototype,"target",void 0),n([s({type:String})],o.prototype,"rel",void 0),n([s({attribute:"formnovalidate",type:Boolean})],o.prototype,"formNoValidate",void 0),n([v({capture:!1,passive:!0})],o.prototype,"handleClick",null),o=n([m("esp-button")],o);export{o as EspalierButton};
+    `],n([v()],e.prototype,"innerTabindex",void 0),n([s({attribute:"button-type",type:String})],e.prototype,"buttonType",void 0),n([s({type:Boolean})],e.prototype,"collapsed",void 0),n([s({type:Boolean,reflect:!0})],e.prototype,"disabled",void 0),n([s({type:String})],e.prototype,"href",void 0),n([s({attribute:"icon-only",type:Boolean})],e.prototype,"iconOnly",void 0),n([s({type:Boolean,reflect:!0})],e.prototype,"incognito",void 0),n([s({type:String})],e.prototype,"icon",void 0),n([s({attribute:"icon-position",type:String})],e.prototype,"iconPosition",void 0),n([s({type:String})],e.prototype,"label",void 0),n([s({type:Boolean,reflect:!0})],e.prototype,"loading",void 0),n([s({type:String})],e.prototype,"target",void 0),n([s({type:String})],e.prototype,"rel",void 0),n([s({attribute:"formnovalidate",type:Boolean})],e.prototype,"formNoValidate",void 0),n([m({capture:!1,passive:!0})],e.prototype,"handleClick",null),e=n([g("esp-button")],e);export{e as EspalierButton};

package/dist/index.d.ts

@@ -73,7 +73,7 @@ export * from "./shared/events.js";
 export { getImageDetails, releasePreviewUrl, type EspalierUploadImage, type ImageDetailsOptions, type SelectedUploadImage, type ExistingUploadImage, type ExistingImage, type ResponsiveImageUrl, type UploadCallbacks, type UploadEventDetail, } from "./image-upload/image-helpers.js";
 export { calculatePhotoLayout, type LayoutImage, type PhotoRow, } from "./shared/justified-layout.js";
 export { type TypeaheadFetchItems } from "./pickers/types.js";
-export { type EspalierTheme, type PartialTheme, type PartialThemeContexts, type ThemeContext, type ThemeContexts, type VariantColorSource, encodeTheme, parseTheme, mergePartials, layerThemes, validateThemePair, resolveContextTheme, buildTaprootLightTheme, buildTaprootDarkTheme, NESTED_THEME_KEYS, } from "./shared/theme.js";
+export { type EspalierTheme, type LightnessKey, type LightnessReference, type PartialTheme, type PartialThemeContexts, type PartialThemeTones, type ThemeContext, type ThemeContexts, type ThemeTones, type ToneReference, type VariantColorSource, encodeTheme, parseTheme, mergePartials, layerThemes, validateThemePair, resolveContextTheme, buildTaprootLightTheme, buildTaprootDarkTheme, NESTED_THEME_KEYS, } from "./shared/theme.js";
 export { auditDataPalette, generateSequentialRamp, generateDivergingRamp, COLOR_VISION_SIMULATIONS, DATA_SERIES_KEYS, DEFAULT_DATA_PALETTE, DEFAULT_DATA_RAMP_STEPS, DEFAULT_DIVERGING_NEUTRAL, MAX_DATA_RAMP_STEPS, MIN_DATA_COLOR_DISTANCE, MIN_DATA_RAMP_LIGHTNESS_STEP, MIN_DATA_RAMP_STEPS, type ColorVisionSimulation, type DataPalette, type DataPaletteIssue, type DataRamp, type DataRamps, type DataSeriesKey, type DivergingDataRamp, type DivergingRampOptions, type PartialDataRamp, type PartialDataRamps, type SequentialDataRamp, type SequentialRampOptions, } from "./shared/data-colors.js";
 export { WEIGHT_LABELS, extractWeights, normalizeWeight, bestAvailableWeight, extractFamily, getFallbackFont, } from "./shared/font-helpers.js";
 export { getGoogleFonts } from "./font-picker/esp-font-picker.js";

package/dist/root/helpers/compute-semantic-properties.js

@@ -1 +1 @@
-import{deriveSemantic as O,deriveSemanticWithContrast as k,serializeOklch as C}from"../../shared/color-engine.js";import{SEMANTIC_COLOR_NAMES as M,TOKEN_PAIRINGS as R,semanticToCSS as y}from"../../shared/theme.js";import{resolveMappingSource as A}from"./compute-variants.js";function E(s,u,r,n,i,g){return[s.l,s.c,s.h,u,r,n,i.l,i.c,i.h,g].join("|")}function q(s,u,r={}){const n={},i={},g=new Map,h=(e,o)=>{const t=r.effectiveSource?.(e,o)??o,c=A(t,u,s.anchors);return c||r.onUnresolvedSource?.(t),{color:c??u.primary,resolved:c!==null,source:t}};for(const e of M){if(R[e])continue;const o=s.semanticMappings[e],t=s.chroma[e],c=h(e,o.source),a=s.lightness[o.lightness],m=O(c.color,a,t.min,t.max),l=y(e);i[e]=m,n[l]=C(m),r.trace&&r.trace.push({token:e,property:l,resolved:n[l],source:c.source,lightness:o.lightness,sourceResolved:c.resolved,base:c.color})}for(const e of M){const o=R[e];if(!o)continue;const t=s.semanticMappings[e],c=s.chroma[e],a=h(e,t.source),m=s.lightness[t.lightness],l=i[o.bg],v=E(a.color,m,c.min,c.max,l,o.targetLc);let f=g.get(v);if(!f){let S;const x=k(a.color,m,c.min,c.max,l,o.targetLc,r.trace&&(N=>{S=N}));f={requested:S,semantic:x},g.set(v,f)}const{requested:L,semantic:d}=f,p=y(e);i[e]=d,n[p]=C(d),r.trace&&r.trace.push({token:e,property:p,resolved:n[p],source:a.source,lightness:t.lightness,sourceResolved:a.resolved,base:a.color,requested:L,contrast:{against:o.bg,background:l,targetLc:o.targetLc}})}return n}export{q as computeSemanticProperties};
+import{deriveSemantic as k,deriveSemanticWithContrast as A,serializeOklch as R}from"../../shared/color-engine.js";import{SEMANTIC_COLOR_NAMES as C,TOKEN_PAIRINGS as L,resolveLightnessReference as M,semanticToCSS as y}from"../../shared/theme.js";import{resolveMappingSource as E}from"./compute-variants.js";function I(o,g,r,t,i,m){return[o.l,o.c,o.h,g,r,t,i.l,i.c,i.h,m].join("|")}function K(o,g,r={}){const t={},i={},m=new Map,h=(e,s)=>{const n=r.effectiveSource?.(e,s)??s,c=E(n,g,o.anchors);return c||r.onUnresolvedSource?.(n),{color:c??g.primary,resolved:c!==null,source:n}};for(const e of C){if(L[e])continue;const s=o.semanticMappings[e],n=o.chroma[e],c=h(e,s.source),a=M(o.lightness,o.tones,s.lightness),u=k(c.color,a,n.min,n.max),l=y(e);i[e]=u,t[l]=R(u),r.trace&&r.trace.push({token:e,property:l,resolved:t[l],source:c.source,lightness:s.lightness,sourceResolved:c.resolved,base:c.color})}for(const e of C){const s=L[e];if(!s)continue;const n=o.semanticMappings[e],c=o.chroma[e],a=h(e,n.source),u=M(o.lightness,o.tones,n.lightness),l=i[s.bg],v=I(a.color,u,c.min,c.max,l,s.targetLc);let f=m.get(v);if(!f){let S;const N=A(a.color,u,c.min,c.max,l,s.targetLc,r.trace&&(O=>{S=O}));f={requested:S,semantic:N},m.set(v,f)}const{requested:x,semantic:d}=f,p=y(e);i[e]=d,t[p]=R(d),r.trace&&r.trace.push({token:e,property:p,resolved:t[p],source:a.source,lightness:n.lightness,sourceResolved:a.resolved,base:a.color,requested:x,contrast:{against:s.bg,background:l,targetLc:s.targetLc}})}return t}export{K as computeSemanticProperties};

package/dist/shared/theme-fit-report.d.ts

@@ -48,7 +48,7 @@
  * report.adjustedTokens;                // ['linkHover']
  * ```
  */
-import { type EspalierTheme, type LightnessKey, type MappingSource, type PartialTheme, type SemanticColorName } from "./theme.js";
+import { type EspalierTheme, type LightnessReference, type MappingSource, type PartialTheme, type SemanticColorName } from "./theme.js";
 /** What APCA enforcement did to one token. */
 export interface ThemeFitApcaAction {
     /** The requested value, as an `oklch()` string. */
@@ -75,8 +75,8 @@ export interface ThemeFitAnchor {
     /**
      * ΔE-OK between the declared anchor and the emitted token. Expect a
      * non-zero number even on a perfect fit: lightness always comes from
-     * the mapping's ramp stop, so a swatch used as a source is re-lit by
-     * design (ADR-015).
+     * the mapping's built-in stop or custom tone, so a swatch used as a
+     * source is re-lit by design (ADR-015, ADR-020).
      */
     deltaE: number;
 }
@@ -88,8 +88,8 @@ export interface ThemeFitToken {
     property: string;
     /** The mapping's declared source. */
     source: MappingSource;
-    /** The lightness ramp stop the mapping selected. */
-    lightness: LightnessKey;
+    /** The built-in ramp stop or custom tone reference the mapping selected. */
+    lightness: LightnessReference;
     /** The value the mapping asked for, before contrast enforcement. */
     requested: string;
     /** The value actually emitted. */

package/dist/shared/theme.d.ts

@@ -35,6 +35,14 @@ import { type DataPalette, type DataRamps, type PartialDataRamps } from "./data-
 export type LightnessKey = "surface" | "raised1" | "raised2" | "raised3" | "raised4" | "accent" | "muted" | "text" | "border" | "ink" | "shadow";
 /** Lightness values (0–1) for every ramp position. */
 export type LightnessMap = Record<LightnessKey, number>;
+/** A named, opt-in lightness value outside the engine-owned ramp. */
+export type ToneReference = `tone:${string}`;
+/** A built-in ramp stop or an explicitly declared custom tone. */
+export type LightnessReference = LightnessKey | ToneReference;
+/** Named custom lightness values. They are inert until a mapping references one. */
+export type ThemeTones = Record<string, number>;
+/** Tone declarations while partial themes are being layered. */
+export type PartialThemeTones = Record<string, number | undefined>;
 /**
  * A geometric color-theory variant **or** a fixed status family.
  *
@@ -110,11 +118,11 @@ export type ThemeAnchors = Record<string, ThemeAnchor>;
  * base color, `anchor:<name>.<slot>` for a sub-slot.
  *
  * An anchor source contributes its own hue **and chroma**; lightness
- * always comes from the mapping's ramp stop, and APCA enforcement
- * applies unchanged. Anchors are absolute sources rather than seed
- * rotations — a brand color is a color, not a relationship to the
- * seed — so they hold steady while contexts rebind roles around them
- * and intents replace the filled-action source.
+ * comes from the mapping's built-in stop or custom tone, and APCA
+ * enforcement applies unchanged. Anchors are absolute sources rather
+ * than seed rotations — a brand color is a color, not a relationship
+ * to the seed — so they hold steady while contexts rebind roles around
+ * them and intents replace the filled-action source.
  */
 export type MappingSource = ColorSource | `anchor:${string}`;
 /** Anchor names and slot names share one slug grammar. */
@@ -167,8 +175,8 @@ export interface SemanticMapping {
      * declared anchor as `anchor:<name>` / `anchor:<name>.<slot>`.
      */
     source: MappingSource;
-    /** The lightness ramp position to apply. */
-    lightness: LightnessKey;
+    /** A built-in ramp stop, or a named custom tone as `tone:<name>`. */
+    lightness: LightnessReference;
 }
 /** Full mapping table — one entry per semantic color token. */
 export type SemanticMappings = Record<SemanticColorName, SemanticMapping>;
@@ -229,14 +237,14 @@ export type ThemeRoles = {
  * cannot make a dark zone inside a light scheme because semantic derivation
  * deliberately takes lightness from the ramp rather than from an anchor.
  *
- * A context may also carry token-level `semanticMappings` (ESP0175).
- * Root-level explicit mappings survive into every context by design —
- * they are deliberate token pins — so a zone that needs a different
- * value for one of them declares its own mapping here, which layers over
- * the inherited pin exactly as a root-level mapping layers over roles.
+ * A context may also carry custom `tones` and token-level
+ * `semanticMappings` (ESP0175, ESP0180). Root-level tones and explicit
+ * mappings survive into every context by design, while a zone may add or
+ * override a tone and pin a token locally. Each record layers by name.
  */
 export type ThemeContext = ThemeRoles & {
     lightness?: Partial<LightnessMap>;
+    tones?: PartialThemeTones;
     semanticMappings?: Partial<SemanticMappings>;
 };
 /** Named role-rebinding zones available to `context` attributes. */
@@ -279,6 +287,8 @@ export declare const ROLE_PAIRED_INK: Readonly<Record<string, {
 interface CompileRoleOptions {
     /** Token mappings declared explicitly at this merge boundary. */
     explicitMappings?: Partial<SemanticMappings>;
+    /** Custom tones available to explicit surface mappings. */
+    tones?: ThemeTones;
     /** Exact maximum paired-ink contrast of an action surface candidate. */
     actionSurfaceContrast?: (source: MappingSource, stop: LightnessKey) => number;
     /** ΔE-OK between an action surface candidate and the theme's background. */
@@ -458,6 +468,14 @@ export interface EspalierTheme {
     variantChroma: Partial<Record<VariantColorSource, number>>;
     /** Lightness values (0–1) for the eleven ramp positions. */
     lightness: LightnessMap;
+    /**
+     * Named custom lightness values for explicit semantic mappings.
+     *
+     * Refer to one as `tone:<name>` from `semanticMappings`. Tones do not
+     * become built-in ramp stops, emit `--esp-l-*` properties, or participate
+     * in automatic role and action-stop selection.
+     */
+    tones: ThemeTones;
     /** Per-semantic-token chroma min / max. */
     chroma: Record<SemanticColorName, ChromaRange>;
     /** Maps each semantic token to its color source + lightness. */
@@ -515,10 +533,11 @@ export interface EspalierTheme {
  * carry slot-only anchor overrides, which the resolved
  * {@link ThemeAnchor} deliberately does not permit.
  */
-export type PartialTheme = Omit<DeepPartial<EspalierTheme>, "anchors" | "contexts" | "dataRamps"> & {
+export type PartialTheme = Omit<DeepPartial<EspalierTheme>, "anchors" | "contexts" | "dataRamps" | "tones"> & {
     anchors?: PartialThemeAnchors;
     contexts?: PartialThemeContexts;
     dataRamps?: PartialDataRamps;
+    tones?: PartialThemeTones;
 };
 /** Validation result returned by {@link validateTheme}. */
 export interface ThemeValidationResult {
@@ -566,6 +585,19 @@ export declare const STATUS_COLOR_SOURCES: readonly StatusColorSource[];
 export declare const VARIANT_COLOR_SOURCES: readonly VariantColorSource[];
 /** Valid keys for the lightness ramp. */
 export declare const LIGHTNESS_KEYS: readonly LightnessKey[];
+/** Return the custom tone name carried by a valid `tone:<slug>` reference. */
+export declare function toneReferenceName(reference: unknown): string | null;
+/** True when a string names one of the eleven engine-owned ramp stops. */
+export declare function isLightnessKey(reference: unknown): reference is LightnessKey;
+/**
+ * Resolve the lightness an explicit semantic mapping requested.
+ *
+ * Custom tones are a lookup namespace only: this function never adds them to
+ * {@link LIGHTNESS_KEYS}, so automatic role and action-stop algorithms continue
+ * to consider exactly the built-in eleven. An invalid runtime reference falls
+ * back to `surface`; validation reports the authoring error before mounting.
+ */
+export declare function resolveLightnessReference(lightness: LightnessMap, tones: ThemeTones | undefined, reference: LightnessReference): number;
 /**
  * Default lightness ramp for the **light** scheme.
  *
@@ -660,7 +692,7 @@ export declare function explicitMappingTokens(theme: EspalierTheme): Set<Semanti
  * Deep-merge a {@link PartialTheme} over a set of defaults.
  *
  * Primitive fields are replaced; nested objects (`angles`,
- * `semanticHues`, `lightness`, `chroma`, `semanticMappings`, `contexts`)
+ * `semanticHues`, `lightness`, `tones`, `chroma`, `semanticMappings`, `contexts`)
  * are merged key-by-key.  Arrays (`stylesheets`) are replaced
  * wholesale.
  *
@@ -675,10 +707,10 @@ export declare function mergeTheme(defaults: EspalierTheme, overrides: PartialTh
  *
  * This is the same compilation `esp-element-base` performs for a zone
  * host, exported so a check script or the fit report can inspect a
- * context surface without a DOM: role rebindings and the partial
- * lightness ramp merge over the root theme, and any context-level
- * `semanticMappings` layer on top as explicit token pins. Returns `null`
- * when the theme does not define the context.
+ * context surface without a DOM: role rebindings, the partial lightness ramp,
+ * and custom tones merge over the root theme, and any context-level
+ * `semanticMappings` layer on top as explicit token pins. Returns `null` when
+ * the theme does not define the context.
  *
  * @param theme A resolved theme (as `mergeTheme` returns).
  * @param name  The context name a zone would set in its attribute.
@@ -711,7 +743,7 @@ export declare function validateThemePair(lightBase64: string, darkBase64: strin
  * and therefore need key-by-key merging instead of wholesale
  * replacement when combining two {@link PartialTheme} objects.
  */
-export declare const NESTED_THEME_KEYS: readonly ["anchors", "angles", "contexts", "dataPalette", "dataRamps", "intents", "roles", "chroma", "lightness", "semanticHues", "semanticMappings", "variantChroma"];
+export declare const NESTED_THEME_KEYS: readonly ["anchors", "angles", "contexts", "dataPalette", "dataRamps", "intents", "roles", "chroma", "lightness", "tones", "semanticHues", "semanticMappings", "variantChroma"];
 /**
  * Deep-merge two {@link PartialTheme} objects.
  *