@hanzo/design 0.5.1 → 0.5.2

package/dist/tokens.gen.d.ts

@@ -239,6 +239,13 @@ export declare const elevation: {
     readonly 'shadow-lg': "0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)";
     readonly 'shadow-xl': "0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)";
     readonly 'shadow-2xl': "var(--shadow-floating)";
+    readonly 'sheet-0': "var(--surface-page)";
+    readonly 'sheet-1': "var(--surface-card)";
+    readonly 'sheet-2': "var(--surface-card-emphasis)";
+    readonly 'shadow-sheet-1': "var(--edge-highlight),var(--shadow-md)";
+    readonly 'shadow-sheet-2': "var(--edge-highlight),var(--shadow-lg)";
+    readonly fold: "12px";
+    readonly 'fold-face': "linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))";
     readonly 'glow-hero': "radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)";
     readonly 'glow-hero-blur': "120px";
     readonly 'sheen-card': "radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)";
@@ -512,6 +519,13 @@ export declare const cssVars: {
     readonly '--shadow-lg': "0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)";
     readonly '--shadow-xl': "0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)";
     readonly '--shadow-2xl': "var(--shadow-floating)";
+    readonly '--sheet-0': "var(--surface-page)";
+    readonly '--sheet-1': "var(--surface-card)";
+    readonly '--sheet-2': "var(--surface-card-emphasis)";
+    readonly '--shadow-sheet-1': "var(--edge-highlight),var(--shadow-md)";
+    readonly '--shadow-sheet-2': "var(--edge-highlight),var(--shadow-lg)";
+    readonly '--fold': "12px";
+    readonly '--fold-face': "linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))";
     readonly '--glow-hero': "radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)";
     readonly '--glow-hero-blur': "120px";
     readonly '--sheen-card': "radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)";

package/dist/tokens.gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFT,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEb,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CV,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI;;;;;;;;;;;;CAYP,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;CAoBZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;CAaT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoQV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}
+{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFT,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEb,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CV,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI;;;;;;;;;;;;CAYP,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;CAaT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2QV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}

package/dist/tokens.gen.js

@@ -242,6 +242,13 @@ export const elevation = {
     'shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
     'shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
     'shadow-2xl': 'var(--shadow-floating)',
+    'sheet-0': 'var(--surface-page)',
+    'sheet-1': 'var(--surface-card)',
+    'sheet-2': 'var(--surface-card-emphasis)',
+    'shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+    'shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+    'fold': '12px',
+    'fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
     'glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     'glow-hero-blur': '120px',
     'sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -515,6 +522,13 @@ export const cssVars = {
     '--shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
     '--shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
     '--shadow-2xl': 'var(--shadow-floating)',
+    '--sheet-0': 'var(--surface-page)',
+    '--sheet-1': 'var(--surface-card)',
+    '--sheet-2': 'var(--surface-card-emphasis)',
+    '--shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+    '--shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+    '--fold': '12px',
+    '--fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
     '--glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     '--glow-hero-blur': '120px',
     '--sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',

package/guidelines/brand-paper.card.html

@@ -0,0 +1,22 @@
+<!-- @dsCard group="Brand" viewport="700x240" name="Paper" subtitle="Three sheets, one light, and a fold that means this opens" -->
+<!doctype html><html class="dark"><head><meta charset="utf-8"><title>Paper</title><link rel="stylesheet" href="../styles.css">
+<style>body{margin:0;padding:20px;background:var(--sheet-0);font-family:var(--font-sans);color:var(--foreground)}
+.n{font-size:10px;font-weight:600;letter-spacing:.06em;color:var(--neutral-300);font-family:var(--font-mono)}
+.v{font-size:9px;color:var(--neutral-600);font-family:var(--font-mono);margin-top:3px}
+.sheet{padding:14px;border-radius:var(--radius-lg);font-size:12px;color:var(--neutral-400)}
+.s1{background:var(--sheet-1);box-shadow:var(--shadow-sheet-1)}
+.s2{background:var(--sheet-2);box-shadow:var(--shadow-sheet-2)}
+.fold{background-image:var(--fold-face);border-bottom-right-radius:0}
+</style></head><body>
+<div style="display:flex;gap:16px;align-items:stretch">
+  <div class="sheet" style="flex:1">the workspace — no lift, no box<div class="n" style="margin-top:10px">--sheet-0</div><div class="v">the ground</div></div>
+  <div class="sheet s1" style="flex:1">an active tool<div class="n" style="margin-top:10px">--sheet-1</div><div class="v">+ --shadow-sheet-1</div></div>
+  <div class="sheet s2" style="flex:1">what opened<div class="n" style="margin-top:10px">--sheet-2</div><div class="v">+ --shadow-sheet-2</div></div>
+  <div class="sheet s1 fold" style="flex:1">this one expands<div class="n" style="margin-top:10px">--fold-face</div><div class="v">the only mark</div></div>
+</div>
+<div style="margin-top:18px;display:flex;gap:16px">
+  <div class="sheet s1" style="flex:1">a sheet on a sheet lands a step lighter
+    <div class="sheet s1" style="margin-top:10px">nested<div class="sheet s1" style="margin-top:10px">nested again</div></div>
+  </div>
+</div>
+</body></html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "packageManager": "pnpm@11.17.0",
   "description": "Hanzo Design System \u2014 monochrome, dark-default tokens + components + brand assets, the single source of truth for every Hanzo surface. CSS + typed programmatic tokens.",
   "license": "MIT OR Apache-2.0",

package/prompts/rules.md

@@ -33,7 +33,9 @@ token or pattern that makes the "do" trivial.
 |----|-------|
 | One primary (white) action per view; everything else outline or ghost. | Two competing primary buttons. |
 | Plain `<a>` / `<Link>` with className, or the shipped `<Button>`. | `<Button asChild>` — it breaks the build under React 18 strict children. |
-| Elevation as a hairline border + `--shadow-floating` only when floating. | Drop shadows on flat, in-flow cards. |
+| Separate two surfaces by RAISING one — `--sheet-1` + `--shadow-sheet-1`. | Outlining both, then raising one anyway. |
+| A level because the surface means something: workspace, tool, opened. | A drop shadow for looks, or a second lamp — every shadow drops straight down. |
+| A fold (`--fold-face`) only where the item expands. | A fold as ornament. |
 
 ## Motion
 

package/prompts/system.md

@@ -73,8 +73,14 @@ That is not Hanzo. Make it white-on-black and let the content carry it.
 
 - `--radius-sm` on buttons/inputs, `--radius-lg` on cards, `--radius-full` on
   pills and avatars. `--radius-composer` (28px) only for the chat composer.
-- Hanzo barely uses shadow. On black, elevation is a hairline border plus, for
-  truly floating surfaces, `--shadow-floating`. Heroes get one ambient
+- Depth is the hierarchy. Three levels of paper: `--sheet-0` is the workspace,
+  `--sheet-1` an active tool, `--sheet-2` what opened — each with the matching
+  `--shadow-sheet-*`, which carries the top edge-light and the drop together.
+  Raise a surface before you outline it, and never do both.
+- One light, above: every shadow in the system is `0 <y> …`. A sideways offset
+  is a second lamp, and the screen stops reading as one space.
+- `--fold-face` marks an item that expands, and nothing else. `--shadow-floating`
+  is for what actually floats — menus, dialogs. Heroes get one ambient
   `--glow-hero` radial, nothing more.
 
 ## Motion

package/scripts/check-tokens.mjs

@@ -302,5 +302,31 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
   }
 }
 
+// ── 5. one light, from one direction ─────────────────────────────────────
+// The paper ramp reads as one space only while every edge and every drop in
+// the system agrees where the light is. A single `2px 4px` — the spelling
+// every other library ships — puts a second lamp in the room, and the failure
+// is not visible on any one component: the panel with the offset shadow looks
+// fine, and it is the SCREEN that stops making sense. So the rule is checked
+// on the values instead of trusted to whoever writes the next one: the light
+// is directly above, so a shadow moves down and never sideways.
+//
+// Structural, not by name — a layer counts as a shadow when its first two
+// lengths are lengths, which is what a shadow is and what a size is not.
+{
+  const css = strip(read(join(tokensDir, 'elevation.css')))
+  const LEN = /^-?[\d.]+(px|rem|em)?$/
+  const offenders = []
+  for (const [, name, value] of css.matchAll(/--([A-Za-z0-9-]+)\s*:\s*([^;]+);/g))
+    for (const layer of value.split(',')) {
+      const t = layer.trim().replace(/^inset\s+/, '').split(/\s+/)
+      if (LEN.test(t[0]) && LEN.test(t[1] ?? '') && parseFloat(t[0]) !== 0)
+        offenders.push(`--${name} (${layer.trim()})`)
+    }
+  offenders.length
+    ? offenders.forEach((o) => fail(`${o} is offset sideways — the light is above, so every shadow is \`0 <y> …\``))
+    : pass('one light direction — every shadow in elevation.css drops straight down')
+}
+
 console.log(failures ? `\n${failures} check(s) failed` : '\nall token checks passed')
 process.exit(failures ? 1 : 0)

package/skills/design-system/SKILL.md

@@ -43,7 +43,9 @@ Then reach for a **name**, never a value:
 | You want | Use | Never |
 |---|---|---|
 | a page / text | `--background`, `--foreground`, `--text-secondary` | `#000`, `#fff`, `rgb(…)` |
-| a card, a panel | `--surface-card`, `--border-hairline` | a hand-mixed grey |
+| a card, a panel | `--surface-card`, `--border` | a hand-mixed grey |
+| depth — a tool over the workspace | `--sheet-1` + `--shadow-sheet-1` | a box round both, or your own `box-shadow` |
+| "this expands" | `--fold-face` | a fold as ornament |
 | rank / emphasis | the ladder `--white-05 … --white-80` | an off-ladder 12% or 37% |
 | a size | `--type-body`, `--type-h2`, `--text-sm` | `font-size: 13px` |
 | space | `--space-*`, `--gutter*`, `--container-max` | `padding: 13px` |

package/src/tokens.gen.ts

@@ -248,6 +248,13 @@ export const elevation = {
   'shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
   'shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
   'shadow-2xl': 'var(--shadow-floating)',
+  'sheet-0': 'var(--surface-page)',
+  'sheet-1': 'var(--surface-card)',
+  'sheet-2': 'var(--surface-card-emphasis)',
+  'shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+  'shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+  'fold': '12px',
+  'fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
   'glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
   'glow-hero-blur': '120px',
   'sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -528,6 +535,13 @@ export const cssVars = {
   '--shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
   '--shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
   '--shadow-2xl': 'var(--shadow-floating)',
+  '--sheet-0': 'var(--surface-page)',
+  '--sheet-1': 'var(--surface-card)',
+  '--sheet-2': 'var(--surface-card-emphasis)',
+  '--shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+  '--shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+  '--fold': '12px',
+  '--fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
   '--glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
   '--glow-hero-blur': '120px',
   '--sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',

package/styles.css

@@ -588,6 +588,41 @@
   --shadow-lg:0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55);
   --shadow-xl:0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60);
   --shadow-2xl:var(--shadow-floating);
+
+  /* ——— the paper ——— */
+  /* Depth carries STATE, not decoration: which sheet is the workspace, which is
+     the tool in use, which one opened. Reach for a level before a border — if
+     two surfaces need separating, RAISE one rather than outline both, and a
+     surface that is already raised does not also need a box drawn round it.
+
+     A level is a tint AND the light on it, published as a pair, because the
+     alternative — every component composing its own `--edge-highlight,
+     --shadow-*` — is how two panels on one screen end up lit from two
+     directions. Every rung here is pure vertical: a 1px inset line along the
+     top edge, a drop straight down. One origin, above and slightly in front.
+
+     The tints are the surface recipes rather than new values, so sheets stack
+     the way paper does: each is an alpha-white wash, one laid on another lands
+     a step lighter, and the stack converges on #262626 instead of blowing out.
+
+     Nothing here is restated in `.light`, deliberately: every part defers to a
+     token that already flips, so the ramp inverts with the theme for free. */
+  --sheet-0:var(--surface-page);            /* the workspace ground             */
+  --sheet-1:var(--surface-card);            /* an active tool                   */
+  --sheet-2:var(--surface-card-emphasis);   /* what opened, or what is inside   */
+  --shadow-sheet-1:var(--edge-highlight),var(--shadow-md);
+  --shadow-sheet-2:var(--edge-highlight),var(--shadow-lg);
+
+  /* The fold — a corner turned back, and the one mark that means THIS OPENS.
+     Ornament nowhere: a sheet that does not expand does not wear one.
+     It is a background-image, so it costs no element and no pseudo-element —
+     paint it on the sheet itself and square that corner
+     (`border-bottom-right-radius:0`), because a folded corner is not round.
+     The flap catches the light like every other surface; the crease is the
+     hairline; both defer, so both invert. */
+  --fold:12px;
+  --fold-face:linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold)); /* @kind color */
+
   /* Ambient hero glow — a single white radial, blurred 120px, low opacity. */
   --glow-hero:radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%); /* @kind color */
   --glow-hero-blur:120px;

package/tailwind.css

@@ -611,6 +611,41 @@
   --shadow-lg:0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55);
   --shadow-xl:0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60);
   --shadow-2xl:var(--shadow-floating);
+
+  /* ——— the paper ——— */
+  /* Depth carries STATE, not decoration: which sheet is the workspace, which is
+     the tool in use, which one opened. Reach for a level before a border — if
+     two surfaces need separating, RAISE one rather than outline both, and a
+     surface that is already raised does not also need a box drawn round it.
+
+     A level is a tint AND the light on it, published as a pair, because the
+     alternative — every component composing its own `--edge-highlight,
+     --shadow-*` — is how two panels on one screen end up lit from two
+     directions. Every rung here is pure vertical: a 1px inset line along the
+     top edge, a drop straight down. One origin, above and slightly in front.
+
+     The tints are the surface recipes rather than new values, so sheets stack
+     the way paper does: each is an alpha-white wash, one laid on another lands
+     a step lighter, and the stack converges on #262626 instead of blowing out.
+
+     Nothing here is restated in `.light`, deliberately: every part defers to a
+     token that already flips, so the ramp inverts with the theme for free. */
+  --sheet-0:var(--surface-page);            /* the workspace ground             */
+  --sheet-1:var(--surface-card);            /* an active tool                   */
+  --sheet-2:var(--surface-card-emphasis);   /* what opened, or what is inside   */
+  --shadow-sheet-1:var(--edge-highlight),var(--shadow-md);
+  --shadow-sheet-2:var(--edge-highlight),var(--shadow-lg);
+
+  /* The fold — a corner turned back, and the one mark that means THIS OPENS.
+     Ornament nowhere: a sheet that does not expand does not wear one.
+     It is a background-image, so it costs no element and no pseudo-element —
+     paint it on the sheet itself and square that corner
+     (`border-bottom-right-radius:0`), because a folded corner is not round.
+     The flap catches the light like every other surface; the crease is the
+     hairline; both defer, so both invert. */
+  --fold:12px;
+  --fold-face:linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold)); /* @kind color */
+
   /* Ambient hero glow — a single white radial, blurred 120px, low opacity. */
   --glow-hero:radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%); /* @kind color */
   --glow-hero-blur:120px;

package/tokens/elevation.css

@@ -53,6 +53,41 @@
   --shadow-lg:0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55);
   --shadow-xl:0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60);
   --shadow-2xl:var(--shadow-floating);
+
+  /* ——— the paper ——— */
+  /* Depth carries STATE, not decoration: which sheet is the workspace, which is
+     the tool in use, which one opened. Reach for a level before a border — if
+     two surfaces need separating, RAISE one rather than outline both, and a
+     surface that is already raised does not also need a box drawn round it.
+
+     A level is a tint AND the light on it, published as a pair, because the
+     alternative — every component composing its own `--edge-highlight,
+     --shadow-*` — is how two panels on one screen end up lit from two
+     directions. Every rung here is pure vertical: a 1px inset line along the
+     top edge, a drop straight down. One origin, above and slightly in front.
+
+     The tints are the surface recipes rather than new values, so sheets stack
+     the way paper does: each is an alpha-white wash, one laid on another lands
+     a step lighter, and the stack converges on #262626 instead of blowing out.
+
+     Nothing here is restated in `.light`, deliberately: every part defers to a
+     token that already flips, so the ramp inverts with the theme for free. */
+  --sheet-0:var(--surface-page);            /* the workspace ground             */
+  --sheet-1:var(--surface-card);            /* an active tool                   */
+  --sheet-2:var(--surface-card-emphasis);   /* what opened, or what is inside   */
+  --shadow-sheet-1:var(--edge-highlight),var(--shadow-md);
+  --shadow-sheet-2:var(--edge-highlight),var(--shadow-lg);
+
+  /* The fold — a corner turned back, and the one mark that means THIS OPENS.
+     Ornament nowhere: a sheet that does not expand does not wear one.
+     It is a background-image, so it costs no element and no pseudo-element —
+     paint it on the sheet itself and square that corner
+     (`border-bottom-right-radius:0`), because a folded corner is not round.
+     The flap catches the light like every other surface; the crease is the
+     hairline; both defer, so both invert. */
+  --fold:12px;
+  --fold-face:linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold)); /* @kind color */
+
   /* Ambient hero glow — a single white radial, blurred 120px, low opacity. */
   --glow-hero:radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%); /* @kind color */
   --glow-hero-blur:120px;