@stnd/workshop
Circle 3 — Specialized Satellite & Plumbing · Active · Utility
Role: In-browser design workshop (
]) and baseline rhythm/grid debug overlay (Shift+Cmd+D).When to use: Inspect live token values, switch themes on the fly, and verify vertical rhythm alignment during development.
Quick Start (TL;DR)
// Press Shift + Cmd/Ctrl + D in any Standard app to toggle the Workshop Inspector
The design workshop: a panel to edit a Standard site’s tokens — colours, type, scale, themes — live, in the browser.
ELI5
Press ] on a Standard site in development and a panel slides in from the right. Move a slider, pick a colour, change the theme: the whole page follows. When it looks right, Copy CSS gives you the overrides to paste into your theme. It is where you make the design, not where you test it.
How it loads
The Workshop is heavy (a Svelte panel, its state and styles, about 60 KB), so it is never loaded by default:
| In development | @stnd/modules/workshop is a Gold Standard module with environment: "dev": every @stnd/core app gets the launcher in dev, and only there. |
| In production | Nothing ships. A site that wants the Workshop opts in by importing the launcher: import "@stnd/workshop/launcher" (stnd.build does, in its Base layout). |
| The launcher | launcher.js, about 1.6 KB. It owns the global entry points and loads the panel (Svelte, component, styles) the first time one fires. A panel left open on the previous page is restored on load. |
A page can also mount the panel itself — the Studio (/studio) does:
---
import Workshop from "@stnd/workshop/Workshop.svelte";
---
<Workshop client:only="svelte" open pin />
| Prop | Default | Effect |
|---|---|---|
open |
false |
Opens the panel when it mounts |
pin |
false |
Keeps it open (no close on outside click or mouse leave) |
showHandler |
true |
Shows the floating trigger when the panel is closed |
There is one Workshop per page. A second instance renders nothing and asks the first to open or pin itself.
Talking to it: commands and state
There is no global instance. Send a command; listen for state. Both go through events (protocol.js):
import { sendCommand, COMMANDS, onState, currentState } from "@stnd/workshop";
sendCommand(COMMANDS.toggle); // open (pinned) or close
onState(({ state, pinned }) => {}); // "open" | "dormant"
currentState(); // also readable at <html data-workshop-state>
| Command | Effect |
|---|---|
open / close |
Slide the panel out / collapse it |
toggle |
Open pinned, or close |
pin / unpin |
Keep it open / back to hover-peek |
cycle |
What ] does: open and pin, then pin, then close |
toggle-debug |
The layout debug overlay (stnd-debug) |
compare-start / compare-end |
Show the page without your changes / bring them back (what holding [ does) |
Any [data-workshop-toggle] element toggles the panel when clicked. The launcher palette entry ::workshop opens and pins it, and the Astro dev toolbar has a Workshop button.
Shortcuts
| Key | Does |
|---|---|
] |
Cycle: open and pin → pin → close (ignored while typing) |
[ (hold) |
Before / after: see the page without your changes |
Shift + Cmd/Ctrl + D |
Toggle the debug overlay |
Esc |
Close the panel |
The Workshop no longer overrides Cmd/Ctrl + S or Cmd/Ctrl + D: they are the browser’s.
What it edits
Four tabs, in this order:
- Info — the page and the docs. The theme preset (choosing one clears the Workshop’s overrides and writes the same cookie / localStorage the theme system reads); page facts (viewport width and breakpoint, current scheme, theme, Standard version); the debug layer toggle (and Clear Preferences); and docs: a search box over the Standard manual (stnd.build’s
/api/search, results link to the pages) with links to the Manual and the Studio. - Type — font families, size, density, ratio, page gap, rhythm, radius. The family field takes any installed
@stnd/fontsfamily — or any Google Font: type “Lora” and it shows. That is the one thing the panel fetches for itself, only when you choose or hover a family it does not ship (lib/google-fonts.js); it previews, it does not publish. A page that wants the font declares it itself. - Layout — Page (page width, reading width, page padding, block rhythm, and a switch that puts
.lefton every.prosecontainer so the reading column hugs the left edge; Before and Reset give each container back as the page had it, and it is disabled on a page with no.prose), Shape (radius, small and large radii, stroke) and Motion (the three durations). Widths and radii are written in the token’s own unit (px,rem,ms); numbers that come from an expression (clamp(...),var(...)) are read as the browser resolves them. - Color — a light / dark / auto toggle for the scheme; a Contrast table (WCAG ratio and grade of the text, the accent and each palette hue against the background, in the scheme being shown); the three seeds (background, foreground, accent) and the whole palette (red, orange, yellow, green, cyan, blue, magenta, purple, pink, brown). Each colour opens an inline OKLCH picker (plane, sliders, eyedropper; the seeds also have presets). Edits go to the token of the scheme being shown, e.g.
--color-light-redor--color-dark-red.
The debug layer
The Debug layer switch (and Shift + Cmd/Ctrl + D) toggles .stnd-debug on <html>, styled in @stnd/styles (_standard-99-debug.scss), and a breakpoint tag (xs, sm, md, lg) bottom right. Under it, one switch per guide; a muted guide is named in data-debug-off on <html> (remembered for the tab). The stylesheet draws five, the measuring half (audit/, loaded only while the layer is on) draws six:
| Guide | Shows |
|---|---|
| Baseline grid | one root line, over the whole page |
| Rhythm | the gap of every .rhythm block, tagged by element |
| Columns & gutters | the columns of every .grid-N, gutters tinted, each child outlined |
| Type lines | baseline, x-height and cap-height of the text in .prose / .rhythm (exact where the text is trimmed) |
| Page margins | the page padding on both sides |
| Baseline snap | blocks whose baseline (trimmed text) or top edge is off the baseline grid, with the offset in px |
| Off-grid items | grid children that do not start and end on a column edge |
| Overflow | the outermost elements wider than the window |
| Line length | characters per line of the prose, green from 45 to 75 |
| Runts | a last line that holds a single word (rivers are not detected) |
| Token inspector | hover a block: margin and padding as rings, and its spacing and type named by the --space-* / --scale-* token that has that value |
The measuring half puts one marker per finding in .stnd-debug-audit (a child of <html>, document coordinates, no change to the page) and re-measures on resize, font load and DOM change. It is one switch shared with the Astro dev toolbar and the ::debug palette entry (@stnd/workshop/debug): the class is the source of truth, each change is announced as stnd:debug-layer ({ on, off }) so the three follow each other.
Overrides are inline custom properties on <html>; Reset removes only the Workshop’s own tokens and leaves the app’s inline styles alone. The last tab you used is remembered; the first visit opens on Info.
Before / after
Before (footer, or hold [) shows the page without your changes: the Workshop’s overrides, scheme and theme choice are taken off, the page’s own theme comes back, and everything returns the moment you let go. It never edits what is saved, and it is disabled until there is something to compare.
Taking your work out
- CSS — a
:root { … }block of the tokens you changed. - Frontmatter — the same changes as a note’s frontmatter (
theme:,color-light-accent:,font-header:,reading-width:…). The keys are exactly those the framework accepts (@stnd/utils/theme-tokens, “frontmatter key = CSS property minus--“); a token with no frontmatter key is kept as a YAML comment, so nothing is dropped silently.
Vanilla first
The panel is built from the framework’s own vocabulary, not a look of its own:
| Need | What it uses |
|---|---|
| The panel | .panel[data-position="right"], .panel-head, .panel-brand, .panel-scroll |
| Tabs | .btn-group with role="tablist" — icon-only, as in Reveal’s develop panel, named by aria-label |
| Collapsible groups | native <details> / <summary class="panel-group"> |
| Controls | <select>, <input type="range"> (track fill from --slider-value), <input type="search">, <input type="checkbox" role="switch">, .btn-group with aria-pressed for the scheme |
| Lists and results | .list, .item, .panel-label, .panel-count |
| Buttons | .small, .icon, .ghost, .secondary |
workshop.css (about 245 lines, namespaced .workshop-*) only places that and styles what the framework has no word for: the closed-state trigger, the label · control · value rows, the colour swatch and the picker. The panel’s width is --workshop-sidebar-w, which the framework also reads to push the page aside when the panel is pinned open.
Anatomy
launcher.js always loaded (~1.6 KB): entry points, lazy-loads the panel
protocol.js command / state events — the public contract
index.js public API (re-exports protocol)
Workshop.svelte the shell: trigger, panel frame, header, tabs, footer
state.svelte.js all state and behaviour, as runes; no markup
panels/ InfoPanel (+ ThemePanel), TypographyPanel, LayoutPanel, ColorsPanel (+ ColorPicker); Section (<details>), Slider (a range row), Glyph (inline icons)
workshop.css the stylesheet, injected when the panel mounts
lib/ tokens, roles (seeds + palette), layout (the Layout tab's controls), scale, presets (OKLCH), contrast (WCAG), frontmatter, catalog, dom, store, site-theme, color, styles, google-fonts, docs-search
tests/ the panel mounted in happy-dom (lifecycle, restore, editing, reset, structure)
State is saved in two namespaced records (lib/store.js): stnd:workshop in sessionStorage (panel, pin, scheme, theme, overrides, sections, debug) and stnd:workshop:prefs in localStorage (the active tab).
Adding a panel
- Write
panels/MyPanel.svelte; read the shared state withconst ws = getContext("workshop"), wrap your fields in<Section id="mine" title="Mine">and use plain elements — a<Slider>for a range row, a.workshop-rowfor the rest. - Add the state and handlers to
createWorkshopStateinstate.svelte.js(and return them). - Add a tab in
Workshop.svelteand a test intests/.
Reach for a framework class before writing CSS; what is left goes in workshop.css, namespaced .workshop-*. No hex or named colours (use OKLCH or a token), no !important. Third-party URLs stay in lib/google-fonts.js.