Sklent's design system¶
Sklent wears the design system of Kist 2.0 (a self-hosted library for the images and files you
collect), so the two apps read as one suite, plus a small
drafting layer of its own (the "truth rule": every line either carries a real value or
separates two real things). The web UI is plain files: native ES modules and per-area CSS
under sklent/web/, with no bundler and no build step.
The decisions behind it are in the 0.2 review (U1 "Suite system", U2 "Drafting overlay"); the options built are UI 1–17 with 9a (label strip), 11a (schedule sidebar), 12a (drawing sheet), 15a (sheet-style gate plus the first-run screen), 16a, later replaced (2026-11-19) by the "Section" mark (see Brand below) (the S-in-a-ring mark on Kist's #3A3A3A tile, Instrument Serif wordmark) and 17a (no Sklent-side background keying).
Layers¶
| layer | file | what it may contain |
|---|---|---|
| Kist tokens | css/kist-tokens.css |
Generated. Kist's web/src/styles.css :root scale (type, motion, floats, corners, controls) and web/src/themes.css (dark, light, gallery), verbatim, with the Kist tag and commit in its header. Never edit by hand. |
| Pin | css/kist-tokens.lock.json |
The Kist tag, commit and the copy's sha256. |
| Sklent tokens | css/sk-tokens.css |
Only --sk-* names, each a Kist token or a color-mix of one: the canvas grid, the spec (mono) voice, hairline tones, the drawing sheet, dimension-line offsets, the title block. No colour values. |
| Areas | css/base.css … css/phone.css |
Rules only. Colours come from tokens; no hex, rgb() or named colours (tested). |
Theme: html[data-theme] is gallery (default), dark or light; the Appearance menu also
offers System. theme-init.js sets it from localStorage['sk.theme'] before the stylesheets
load, so the first frame is already the right colour, and js/theme.js keeps
<meta name="theme-color"> equal to the theme's --chrome.
Refreshing Kist's tokens¶
python scripts/sync_kist_tokens.py ~/src/kist # a checkout at the tag you want
python scripts/sync_kist_tokens.py ~/src/kist --check # exit 1 if the copy differs
The script rewrites kist-tokens.css and its lock and prints the token names added and
removed. Then run the tests: a removed or renamed token fails test_tokens.py, and a theme
change that breaks a text/surface pair fails test_contrast.py.
Ownership¶
| file | owner | notes |
|---|---|---|
sklent/web/index.html |
design system | markup for the shell, gate, sheet, dialogs |
sklent/web/theme-init.js |
design system | first-paint theme (classic script) |
sklent/web/manifest.webmanifest, icons (favicon.*, icon-*, apple-touch-icon.png) |
design system | built by scripts/build_icons.py |
sklent/web/fonts/ |
design system | Inter, Instrument Serif, JetBrains Mono (latin woff2) + OFL licences |
sklent/web/css/kist-tokens.css, .lock.json |
Kist (generated) | scripts/sync_kist_tokens.py only |
sklent/web/css/sk-tokens.css |
design system | the drafting overlay tokens |
sklent/web/css/base.css |
design system | fonts, reset, type roles, controls, focus, reduced motion |
sklent/web/css/shell.css |
design system | top bar, sidebar, job log, progress rule |
sklent/web/css/grid.css |
design system | canvas grid, grid header, tiles, empty states |
sklent/web/css/detail.css |
design system | drawing sheet, schedule, title block, dimension lines |
sklent/web/css/floats.css |
design system | dialogs, settings spec sheet, confirm, Appearance menu, toast |
sklent/web/css/gate.css |
design system | token gate |
sklent/web/css/phone.css |
design system | everything under 760 px |
sklent/web/js/api.js |
design system (seam) | api(path, opts) |
sklent/web/js/store.js |
design system | state, poll loop, onChange / emit |
sklent/web/js/ctx.js |
design system | the object handed to every seam callback |
sklent/web/js/detail.js |
design system (seam) | registerDetailSection, registerTitleBlockField |
sklent/web/js/sidebar.js |
design system (seam) | registerSidebarSection, registerSourceAction (added by specs) |
sklent/web/js/tiles.js |
design system (seam) | registerTileBadge, registerTileFigure |
sklent/web/js/settings.js |
design system (seam) | registerSettingsGroup (field types incl. checklist; optional render) |
sklent/web/js/grid.js, theme.js, toast.js, confirm.js, format.js, icons.js, dom.js, main.js |
design system | |
sklent/web/js/features.js |
feature builders | one import './features/<name>.js'; line per feature |
sklent/web/js/features/*.js |
feature builders | feature UI, using only the seams below: revisions.js, inputs-access.js, inputs-sources.js, inputs-classes.js, views.js, specs.js, outputs.js |
sklent/web/css/features/<area>.css |
feature builders | one sheet per area, classes prefixed sk-<area>- (tested), tokens only |
docs/design.md, scripts/sync_kist_tokens.py, scripts/build_icons.py |
design system |
Feature code doesn't edit design-system files; it calls the seams. If a seam is missing something, extend the seam.
Seams for feature work¶
A feature module lives in sklent/web/js/features/ and is imported from js/features.js
(main.js imports that before the first render). Every callback gets ctx
(js/ctx.js): { state, api, refresh, schedule, emit, toast, confirm, activeJobFor, icon,
esc, $, $$, format }. Treat ctx.state as read-only; escape anything from the server with
ctx.esc.
api(path, opts) — js/api.js¶
import { api } from '../api.js';
const job = await api(`/designs/${id}/render`, { method: 'POST', body: { force: true } });
path is under /api; opts.body is sent as JSON with the bearer token. Returns the parsed
JSON; throws Error(detail) on a non-2xx; a 401 sends the user to the token gate.
registerDetailSection({ id, title, order, render(container, design, ctx), sheet, when, group }) — js/detail.js¶
Extra content in the drawing sheet.
sheet: false(the default): a section in the side column between the schedule and the title block, under a ruled caps labeltitle(a spec card, a BOM, a files pack).sheet: true: a numbered row in the schedule after the files, under the labelgroup(defaultMore); choosing it renders the section into the viewer, in place of a media file (compare, filmstrip, an engineering sheet).when(design) -> boolhides it for designs it doesn't apply to.ordersorts sections (default 100). Re-registering anidreplaces it.renderruns when the sheet opens and whenever that design's data changes (each poll that changes it), into a fresh container. Keep it idempotent.
import { registerDetailSection } from '../detail.js';
registerDetailSection({
id: 'spec-card', title: 'Spec card', order: 10,
when: (d) => d.status === 'rendered',
render(el, d, ctx) { el.innerHTML = `<p class="sk-data">${ctx.esc(d.name)}</p>`; },
});
registerTitleBlockField({ id, label, order, wide, value(design, ctx) }) — js/detail.js¶
An extra cell in the title block. value returns a string (escaped for you) or null; a
cell with no data is not shown (ISO 7200: the block holds the minimum). wide spans both
columns.
The built-in cells read design.report (from the API: bodies, hidden_bodies,
bounds_mm, palette, frame_ms, processes, timings_s) and, when the API adds it,
design.spec, whose values win: spec.title, spec.bounds_mm, spec.bodies,
spec.palette, and two cells shown only when present, spec.mass_g (or spec.mass_kg) as
Mass and spec.material as Material.
registerSidebarSection({ id, title, order, render(container, ctx), grow }) — js/sidebar.js¶
A section in the sidebar (the drawer on a phone). Built-ins: views (0), sources (10),
jobs (20, grow: true). title: '' draws no heading. render runs after every poll and
view change.
registerSourceAction({ id, icon, label, order, when, run }) — js/sidebar.js¶
An icon button (icon is a Lucide name from js/icons.js) on every source row, before Scan
and Remove, shown on hover (always on the phone). when(source) -> bool hides it;
run(source, ctx) may be async and its errors become a toast. Used by the contact sheet.
Files that aren't pictures or movies (PDF, CSV, Markdown) open in the viewer as a card with Open and Download, without dimension lines.
registerTileBadge(fn) — js/tiles.js¶
fn(design) -> { text, title } | null. Badges are small neutral mono chips at the right of a
tile's name line (--chip-bg / --chip-text); nothing is ever drawn over the render.
registerTileFigure(fn) — js/tiles.js¶
fn(design) -> url | null: a picture for a tile whose design has no social still yet (the
views area's quick-check still while a first render runs, or a quick-check-only set). The
first non-null wins; a design with a thumb_url never asks.
registerSettingsGroup({ id, title, order, fields }) — js/settings.js¶
A group in the render-settings spec sheet. Built-ins: palette (0), turntable (10), stills
(20), GIF (30), output (40). Each field is
{ name, label, type, unit, min, max, step, options, hint }; type is number (default),
select (options: values or { value, label }, the value's type is kept), checkbox,
text or checklist (a list value, one checkbox per option, e.g. the outputs list). Values load from GET /api/settings by name and are sent in the same
PUT /api/settings as the built-in fields, so the server must accept the new keys (add them
to its settings first; it rejects unknown ones). A group may also pass render(container, ctx) to draw rows it
manages itself under its heading (Settings → Tokens does); those aren't sent with Save.
Backend seams¶
The web seams above have server-side partners. Every feature area is a package in
sklent/features/ and plugs in through these; shared files only call them.
| seam | where | signature / contract |
|---|---|---|
| Feature registry | sklent/features/__init__.py |
MODULES (one line per area: revisions, inputs, views, specs, outputs); each module exposes SCHEMA (additive SQL), router (mounted at /api) and register_mcp(mcp) |
| Render steps | sklent/steps.py |
register_step(name, run, *, order, when); run(ctx: StepContext) with ctx.sc, ctx.add(...), ctx.guard, ctx.restore(), ctx.settings, ctx.enabled(key), ctx.info (world-placed bodies), ctx.box. A failing step never fails the render. Orders: views 10–48, specs 50–79, revisions 80, outputs 90. Skipped on a quick check (settings["quick_check"]) |
| Settings registry | sklent/jobs.py |
register_setting(key, default, validate); get_all_settings(design_id=None) and get_options(design_id=None) apply a repo's .sklent.yaml overrides |
| Render path | sklent/jobs.py _render |
download (inputs.links.fetch_design) → options (get_options(id), get_all_settings(id), then views.render_overrides(id, opts, settings)) → settings["design"] = the design row → render_set into a staging dir → Kist filing (rev:, ref: tags, version links) → sets.promote → keep policy |
| Render sets | sklent/sets.py (revisions owns it) |
latest_set(design_id), get_set(design_id, set_id), list_sets(design_id), read_json(folder, name), write_json(folder, name, data); one set per blob; commit_sha is always a commit |
| Framing | sklent/render.py |
world_bodies(sc, info) (measure's world boxes; extra placements in placed), placed_bounds(info); ortho_fit, shot_path, paint_style, plan(opts, settings) |
| Views | sklent/features/views |
render_overrides(design_id, opts, settings); steps.render_job(sc, path, w, h, cam, ...) |
| Specs | sklent/features/specs |
meta.design_row(ctx) (reads ctx.settings["design"]), ortho.register_sheet_backend(name, fn), ortho.drawing_support(sc) (SolidCraft, the open-source parametric CAD app, ≥ 0.45 drawing.*) |
| Repo config | sklent/repo_config.py |
get(design_id) -> dict, render_overrides(design_id), for_local(path), parse(bytes), resolve(path, files); read by views (highlight), specs (material, licence, bom, steps), outputs (title, licence) |
| Share links | sklent/features/outputs |
share_link(design_id) -> str \| None (never creates one); used by the inputs review comment |
| Viewer gate | sklent/auth.py, sklent/mcp_server.py |
viewers get GET under /api (not /api/tokens) and MCP tools (MCP is the protocol AI agents like Claude use to call tools) in mcp_server.READ_ONLY_TOOLS (annotated readOnlyHint); every tool must be in READ_ONLY_TOOLS or WRITE_TOOLS (tested) |
Vocabulary¶
| Faces | Inter (--font-ui) for every word; Instrument Serif (--font-display) for names and titles; JetBrains Mono (--sk-font-data, class .sk-data / .mono) for spec values: sizes, envelopes, hashes, paths, dates, frame counts. Counts a person reads stay Inter. |
| Sizes | --fs-1…--fs-6 (11/13/15/18/24/34). A raw size needs /* type-scale: allow */ (only the 16 px phone fields, so iOS doesn't zoom). |
| Controls | 28 px (--ctl-h), quiet by default; one primary per view (Render, Save, Continue; Re-render on the sheet uses Kist's preview pair). |
| Selection | --accent-soft fill + 1 px --selected-line outline; in the sheet --preview-soft + --preview-dim. |
| Lines | always 1 px (--sk-line). The frame is the one 3:1 line (--sk-sheet-frame); rules are decorative tones (--sk-rule, --sk-rule-float, --sk-sheet-rule). |
| Grid | 24 px cells on the canvas only, never behind a render or text, off on the phone and under prefers-contrast: more. Tiles are 280 px (--sk-tile) so gutters sit on grid lines. |
| Dimension lines | only on the media's edge, giving the file's true pixel size; never on a part. |
| Icons | Lucide (ISC), inlined in js/icons.js, 14/16/20 px, 1.5 stroke. Add a glyph there from lucide-static. |
| Motion | Kist's --dur-* / --ease-*; everything off under prefers-reduced-motion. |
| Floats | --bg-float, --float-line, --float-shadow, --dialog-radius / --float-radius, over --scrim. |
Tests¶
| test | guards |
|---|---|
tests/test_tokens.py |
the vendored copy matches its pinned hash; the sync script reproduces it; sk-tokens.css defines only --sk-* from known tokens; every var() in the CSS exists; no colours outside the token files; font sizes on the scale; font and icon licences ship |
tests/test_contrast.py |
a Python port of Kist's contrast.ts (maths, parser, its 80 pairs) plus Sklent's own text/surface pairs, in all three themes |
tests/test_web.py |
every asset index.html names is served; ES-module imports resolve; the seams are exported; code is served no-cache; the manifest and its icons |
tests/test_design_api.py |
blob and report on designs; job cancel; "1 body" |
When a feature adds text on a new surface pair, add the pair to SKLENT_PAIRS in
tests/test_contrast.py.
Brand: the Section mark (2026-11-19)¶
A square part cut open by three 45° hatch gaps (ISO 128 section hatch, "/" direction), in four solid pieces. It is Kist's sibling: Kist's Corners frame a square from outside, and Section shows the same square cut open.
- Grid: Kist's 64-unit grid. The part spans 8–56 for the bare mark, 16–48 on the app tile, and 12–52 on the tab tile.
- Gaps: 6 units measured along an edge.
- Radii: r2 on the square's outer corners, r0.5 on the cut corners.
- Colours: white on #3A3A3A for tiles. The bare mark uses ink #2B2B2B on light and #ECEAE4 on dark (favicon.svg switches with prefers-color-scheme). The app uses currentColor, inlined in index.html.
- Empty states: format.js OUTLINE_MARK draws the mark as 1.5 px outlines with the last piece solid in the accent.
- Rebuilding: python scripts/build_icons.py rebuilds every icon file and docs/brand/*.svg. After an icon change, bump ?v= in index.html and the manifest.