slabkit 0.1.0__tar.gz

slabkit-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+examples/out/
+dist/
+*.egg-info/

slabkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sverre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slabkit-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: slabkit
+Version: 0.1.0
+Summary: SVG panel system for GitHub profile READMEs — OKLCH palettes with asserted contrast, superellipse corners, one motion idea per panel.
+Project-URL: Homepage, https://github.com/hellosverre/slab
+Project-URL: Source, https://github.com/hellosverre/slab
+Project-URL: Issues, https://github.com/hellosverre/slab/issues
+Author-email: Sverre <sverresig@proton.me>
+License: MIT License
+        
+        Copyright (c) 2026 Sverre
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: design-system,generative,github,oklch,profile,readme,svg
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Stubs Only
+Requires-Python: >=3.9
+Provides-Extra: fonts
+Requires-Dist: fonttools>=4.0; extra == 'fonts'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img alt="slab — SVG panels for GitHub READMEs" width="100%"
+       src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/hero.svg">
+</div>
+
+<div align="center">
+  <a href="https://pypi.org/project/slabkit/"><img alt="PyPI" src="https://img.shields.io/pypi/v/slabkit?style=flat-square&color=76D5A1&labelColor=081A10&label=pypi"></a>
+  &nbsp;
+  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-081A10?style=flat-square&logo=python&logoColor=76D5A1&labelColor=081A10">
+  &nbsp;
+  <img alt="No runtime dependencies" src="https://img.shields.io/badge/runtime%20deps-none-081A10?style=flat-square&labelColor=081A10">
+  &nbsp;
+  <img alt="MIT" src="https://img.shields.io/badge/licence-MIT-76D5A1?style=flat-square&labelColor=081A10">
+</div>
+
+<br>
+
+A small Python library that generates the panels on a GitHub profile: a hero banner, a
+stack grid, a status strip, a system diagram, a contact footer. Everything comes out as a
+self-contained animated SVG with no external requests.
+
+Every image above and below was generated by this library. If it could not document
+itself it would not be worth publishing.
+
+## Why this exists
+
+GitHub is a hostile rendering target, and most of the rules only announce themselves once
+something silently breaks:
+
+| Constraint | Consequence |
+|---|---|
+| `<style>` is escaped to plain text | No CSS. No `:target`, no `:hover`, no CSS-only toggles. |
+| JavaScript is stripped | Nothing is interactive. |
+| Images are proxied through camo | **Webfonts never load.** A `font-family` pointing at one silently falls back. |
+| SVG is served as `<img>` | Pointer events never reach it, so links inside an SVG are dead. |
+| `id` is rewritten to `user-content-id` | Anchor tricks lose their handle. |
+
+What *does* survive is SMIL animation, filters, masks, gradients, and system fonts. slab
+is built entirely inside that envelope, which is why it uses `<animate>` rather than CSS
+keyframes and outlines display type to vector paths rather than linking a font.
+
+## Install
+
+```bash
+pip install slabkit
+```
+
+The distribution is `slabkit` because `slab` was already taken on PyPI by a DSP library,
+and sharing an import name with it would break anyone who has both installed.
+
+No runtime dependencies — the whole library is string formatting and arithmetic.
+`fonttools` is an optional extra, needed only for `outline()`, which converts a wordmark
+to paths so a non-system typeface survives camo:
+
+```bash
+pip install "slabkit[fonts]"
+```
+
+## Quickstart
+
+```python
+from slabkit import Theme, banner, chips, footer, write
+
+t = Theme(158)                      # one hue derives the entire ramp
+
+write("banner.svg", banner(
+    t, "SVERRE", "building AI systems, fundamentals first",
+    meta="TypeScript · Python · Next.js · Postgres",
+    note="Ski · Norway"))
+
+write("stack.svg", chips(t, [
+    ("WRITE", ["TypeScript", "Python"]),
+    ("RUN",   ["Linux", "Docker"]),
+]))
+```
+
+Reference the result from your README by its `raw.githubusercontent.com` URL. Relative
+paths are risky on profile READMEs, which render outside the repo's base path.
+
+## Theming
+
+`Theme(hue)` derives ink, surface, text, muted, dim and accent in OKLCH from a single hue,
+varying almost entirely in lightness. It then **asserts the contrast ratios and raises if
+any role falls below 4.5:1**, so an unreadable palette fails at build time rather than
+shipping.
+
+<div align="center">
+  <img alt="The same ramp at five hues" width="100%"
+       src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/hues.svg">
+</div>
+
+```python
+Theme(158).report()     # audit any hue before committing to it
+Theme(250, accent="#81C3FF")    # override individual roles when you must
+```
+
+## Panels
+
+#### `banner(theme, wordmark, tagline, meta, note, font=...)`
+
+Pass `font=` a `.ttf`/`.otf` to outline the wordmark to paths. Any typeface works, because
+the glyphs ship as geometry rather than as a font reference.
+
+#### `chips(theme, groups)`
+
+<img alt="chips panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-chips.svg">
+
+A raking light crosses the grid, brightening each chip as it passes. Two copies of the
+grid, the lit one revealed through a soft gradient **mask** — a clip would give a hard
+edge, which reads as a wipe rather than as light.
+
+#### `status(theme, label, state, word, headline, detail, right, stamp)`
+
+<img alt="status panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-status.svg">
+
+`state` is `ok` / `warn` / `bad`. Those colours are semantic rather than brand, which is
+why they are exempt from the one-accent rule — but they are derived at the accent's OKLCH
+lightness so they still belong to the same band.
+
+**Always pass `stamp`.** A committed SVG behind camo is stale by design, and a status
+panel implying real-time is simply lying.
+
+#### `diagram(theme, title, subtitle, nodes, edges, caption)`
+
+<img alt="diagram panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-diagram.svg">
+
+Nodes are dicts, edges are index pairs. A request relays along the edges and responses
+return, staggered by graph depth so parallel branches fire together instead of in series.
+Useful when the code is private and the shape is the only thing you can show.
+
+#### `footer(theme, headline, sub, right)` · `pill(theme, label, on)`
+
+<img alt="footer panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-footer.svg">
+
+`pill()` renders one small standalone pill — a language toggle, nav, a tag. One image per
+pill on purpose: markdown hangs a single `href` off an `<img>`, so a combined toggle would
+send both halves to the same place.
+
+## Design rules
+
+These are the constraints the panels are built to, and they are the actual product. Most
+generated READMEs look identical because they all make the same handful of colour
+decisions; each rule below exists to refuse one of them.
+
+- **One accent.** Hierarchy comes from lightness, not chroma. `Theme` keeps the accent
+  under 80% HSL saturation.
+- **Never the default dark.** Slate-indigo ink around `#0c0e15` is the night-mode twin of
+  the blue-to-purple gradient. Pick a hue and commit to it.
+- **No gradient-clipped headline text.** Solid ink; weight and size do the work.
+- **No coloured glow, no glow blobs.** Depth is one hairline border and a rim light.
+- **Grain on every surface.** A perfectly smooth gradient is the giveaway that nothing
+  physical made it.
+- **Superellipse corners, not `border-radius`.** A radius corner has discontinuous
+  curvature where the arc meets the edge; a superellipse does not.
+- **One motion idea per panel**, and stagger the timings across panels. Elements pulsing
+  in unison is what makes motion look cheap.
+
+## Releasing
+
+Publishing runs on [Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so
+there is no API token anywhere in this repo — GitHub mints a short-lived credential for
+the `publish` workflow and PyPI verifies it.
+
+One-time setup on PyPI (Account → Publishing → add a pending publisher):
+
+| Field | Value |
+|---|---|
+| PyPI project name | `slabkit` |
+| Owner | `hellosverre` |
+| Repository name | `slab` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+After that, bump `version` in `pyproject.toml` and publish a GitHub release. The workflow
+builds, runs `twine check`, installs the wheel into a clean venv and renders every panel
+before it uploads anything.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

slabkit-0.1.0/README.md

@@ -0,0 +1,180 @@
+<div align="center">
+  <img alt="slab — SVG panels for GitHub READMEs" width="100%"
+       src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/hero.svg">
+</div>
+
+<div align="center">
+  <a href="https://pypi.org/project/slabkit/"><img alt="PyPI" src="https://img.shields.io/pypi/v/slabkit?style=flat-square&color=76D5A1&labelColor=081A10&label=pypi"></a>
+  &nbsp;
+  <img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-081A10?style=flat-square&logo=python&logoColor=76D5A1&labelColor=081A10">
+  &nbsp;
+  <img alt="No runtime dependencies" src="https://img.shields.io/badge/runtime%20deps-none-081A10?style=flat-square&labelColor=081A10">
+  &nbsp;
+  <img alt="MIT" src="https://img.shields.io/badge/licence-MIT-76D5A1?style=flat-square&labelColor=081A10">
+</div>
+
+<br>
+
+A small Python library that generates the panels on a GitHub profile: a hero banner, a
+stack grid, a status strip, a system diagram, a contact footer. Everything comes out as a
+self-contained animated SVG with no external requests.
+
+Every image above and below was generated by this library. If it could not document
+itself it would not be worth publishing.
+
+## Why this exists
+
+GitHub is a hostile rendering target, and most of the rules only announce themselves once
+something silently breaks:
+
+| Constraint | Consequence |
+|---|---|
+| `<style>` is escaped to plain text | No CSS. No `:target`, no `:hover`, no CSS-only toggles. |
+| JavaScript is stripped | Nothing is interactive. |
+| Images are proxied through camo | **Webfonts never load.** A `font-family` pointing at one silently falls back. |
+| SVG is served as `<img>` | Pointer events never reach it, so links inside an SVG are dead. |
+| `id` is rewritten to `user-content-id` | Anchor tricks lose their handle. |
+
+What *does* survive is SMIL animation, filters, masks, gradients, and system fonts. slab
+is built entirely inside that envelope, which is why it uses `<animate>` rather than CSS
+keyframes and outlines display type to vector paths rather than linking a font.
+
+## Install
+
+```bash
+pip install slabkit
+```
+
+The distribution is `slabkit` because `slab` was already taken on PyPI by a DSP library,
+and sharing an import name with it would break anyone who has both installed.
+
+No runtime dependencies — the whole library is string formatting and arithmetic.
+`fonttools` is an optional extra, needed only for `outline()`, which converts a wordmark
+to paths so a non-system typeface survives camo:
+
+```bash
+pip install "slabkit[fonts]"
+```
+
+## Quickstart
+
+```python
+from slabkit import Theme, banner, chips, footer, write
+
+t = Theme(158)                      # one hue derives the entire ramp
+
+write("banner.svg", banner(
+    t, "SVERRE", "building AI systems, fundamentals first",
+    meta="TypeScript · Python · Next.js · Postgres",
+    note="Ski · Norway"))
+
+write("stack.svg", chips(t, [
+    ("WRITE", ["TypeScript", "Python"]),
+    ("RUN",   ["Linux", "Docker"]),
+]))
+```
+
+Reference the result from your README by its `raw.githubusercontent.com` URL. Relative
+paths are risky on profile READMEs, which render outside the repo's base path.
+
+## Theming
+
+`Theme(hue)` derives ink, surface, text, muted, dim and accent in OKLCH from a single hue,
+varying almost entirely in lightness. It then **asserts the contrast ratios and raises if
+any role falls below 4.5:1**, so an unreadable palette fails at build time rather than
+shipping.
+
+<div align="center">
+  <img alt="The same ramp at five hues" width="100%"
+       src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/hues.svg">
+</div>
+
+```python
+Theme(158).report()     # audit any hue before committing to it
+Theme(250, accent="#81C3FF")    # override individual roles when you must
+```
+
+## Panels
+
+#### `banner(theme, wordmark, tagline, meta, note, font=...)`
+
+Pass `font=` a `.ttf`/`.otf` to outline the wordmark to paths. Any typeface works, because
+the glyphs ship as geometry rather than as a font reference.
+
+#### `chips(theme, groups)`
+
+<img alt="chips panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-chips.svg">
+
+A raking light crosses the grid, brightening each chip as it passes. Two copies of the
+grid, the lit one revealed through a soft gradient **mask** — a clip would give a hard
+edge, which reads as a wipe rather than as light.
+
+#### `status(theme, label, state, word, headline, detail, right, stamp)`
+
+<img alt="status panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-status.svg">
+
+`state` is `ok` / `warn` / `bad`. Those colours are semantic rather than brand, which is
+why they are exempt from the one-accent rule — but they are derived at the accent's OKLCH
+lightness so they still belong to the same band.
+
+**Always pass `stamp`.** A committed SVG behind camo is stale by design, and a status
+panel implying real-time is simply lying.
+
+#### `diagram(theme, title, subtitle, nodes, edges, caption)`
+
+<img alt="diagram panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-diagram.svg">
+
+Nodes are dicts, edges are index pairs. A request relays along the edges and responses
+return, staggered by graph depth so parallel branches fire together instead of in series.
+Useful when the code is private and the shape is the only thing you can show.
+
+#### `footer(theme, headline, sub, right)` · `pill(theme, label, on)`
+
+<img alt="footer panel" width="100%" src="https://raw.githubusercontent.com/hellosverre/slab/main/assets/panel-footer.svg">
+
+`pill()` renders one small standalone pill — a language toggle, nav, a tag. One image per
+pill on purpose: markdown hangs a single `href` off an `<img>`, so a combined toggle would
+send both halves to the same place.
+
+## Design rules
+
+These are the constraints the panels are built to, and they are the actual product. Most
+generated READMEs look identical because they all make the same handful of colour
+decisions; each rule below exists to refuse one of them.
+
+- **One accent.** Hierarchy comes from lightness, not chroma. `Theme` keeps the accent
+  under 80% HSL saturation.
+- **Never the default dark.** Slate-indigo ink around `#0c0e15` is the night-mode twin of
+  the blue-to-purple gradient. Pick a hue and commit to it.
+- **No gradient-clipped headline text.** Solid ink; weight and size do the work.
+- **No coloured glow, no glow blobs.** Depth is one hairline border and a rim light.
+- **Grain on every surface.** A perfectly smooth gradient is the giveaway that nothing
+  physical made it.
+- **Superellipse corners, not `border-radius`.** A radius corner has discontinuous
+  curvature where the arc meets the edge; a superellipse does not.
+- **One motion idea per panel**, and stagger the timings across panels. Elements pulsing
+  in unison is what makes motion look cheap.
+
+## Releasing
+
+Publishing runs on [Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so
+there is no API token anywhere in this repo — GitHub mints a short-lived credential for
+the `publish` workflow and PyPI verifies it.
+
+One-time setup on PyPI (Account → Publishing → add a pending publisher):
+
+| Field | Value |
+|---|---|
+| PyPI project name | `slabkit` |
+| Owner | `hellosverre` |
+| Repository name | `slab` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+After that, bump `version` in `pyproject.toml` and publish a GitHub release. The workflow
+builds, runs `twine check`, installs the wheel into a clean venv and renders every panel
+before it uploads anything.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

slabkit-0.1.0/examples/profile.py

@@ -0,0 +1,67 @@
+"""Builds a full profile panel set. This is the real config behind github.com/hellosverre.
+
+    python examples/profile.py
+"""
+import datetime as dt
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from slabkit import Theme, banner, chips, diagram, footer, pill, status, write
+
+OUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "out")
+os.makedirs(OUT, exist_ok=True)
+
+theme = Theme(158)
+
+# Set this to a .ttf/.otf to outline the wordmark; None falls back to the mono stack.
+# Any typeface works because the glyphs ship as paths, not as a font reference.
+WORDMARK_FONT = None
+
+STACK = [
+    ("WRITE", ["TypeScript", "JavaScript", "Python"]),
+    ("BUILD", ["Next.js", "React", "Hono", "Tailwind", "Tauri"]),
+    ("STORE", ["Postgres", "libSQL", "Redis", "Drizzle"]),
+    ("RUN",   ["Linux", "Docker", "Cloudflare Tunnel", "Vercel", "Proxmox"]),
+]
+
+NODES = [
+    dict(x=56,  w=118, cy=142, label="browser",    sub=""),
+    dict(x=214, w=168, cy=142, label="Vercel",     sub="Next.js 15"),
+    dict(x=422, w=176, cy=142, label="Cloudflare", sub="Tunnel"),
+    dict(x=638, w=150, cy=142, label="VM",         sub="Hono + Drizzle"),
+    dict(x=828, w=126, cy=100, label="Postgres",   sub=""),
+    dict(x=828, w=126, cy=184, label="Redis",      sub=""),
+]
+EDGES = [(0, 1), (1, 2), (2, 3), (3, 4), (3, 5)]
+
+stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+built = [
+    ("banner.svg", banner(
+        theme, "SVERRE", "building AI systems, fundamentals first",
+        meta="TypeScript  ·  Python  ·  Next.js  ·  Hono  ·  Postgres  ·  Docker  ·  Linux",
+        note="Ski · Norway", font=WORDMARK_FONT)),
+    ("stack.svg", chips(theme, STACK)),
+    ("architecture.svg", diagram(
+        theme, "AETHER", "request path", NODES, EDGES,
+        caption="No inbound ports open on the VM — the tunnel dials out to Cloudflare.")),
+    ("status.svg", status(
+        theme, "HOME SERVER", "warn", "MAINTENANCE", "storage pool rebuild",
+        "Box is down on purpose while I rebuild the storage pool.",
+        right="down since 2026-08-24", stamp="generated " + stamp)),
+    ("footer.svg", footer(
+        theme, "sverresig@proton.me",
+        "Building an AI system that has to survive contact with real users?",
+        right="open to apprenticeship · aug 2027")),
+    ("lang-en-on.svg",  pill(theme, "English", True)),
+    ("lang-en-off.svg", pill(theme, "English", False)),
+    ("lang-no-on.svg",  pill(theme, "Norsk", True)),
+    ("lang-no-off.svg", pill(theme, "Norsk", False)),
+]
+
+print(theme.report(), "\n")
+for name, svg in built:
+    p = write(os.path.join(OUT, name), svg)
+    print("  %-20s %6d bytes" % (name, os.path.getsize(p)))

slabkit-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "slabkit"
+version = "0.1.0"
+description = "SVG panel system for GitHub profile READMEs — OKLCH palettes with asserted contrast, superellipse corners, one motion idea per panel."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Sverre", email = "sverresig@proton.me" }]
+keywords = ["svg", "github", "readme", "profile", "design-system", "oklch", "generative"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Documentation",
+    "Typing :: Stubs Only",
+]
+# Nothing at runtime on purpose: the whole library is string formatting and arithmetic.
+dependencies = []
+
+[project.optional-dependencies]
+# Only outline() needs this, and only when you want a wordmark in a non-system typeface.
+fonts = ["fonttools>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/hellosverre/slab"
+Source = "https://github.com/hellosverre/slab"
+Issues = "https://github.com/hellosverre/slab/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["slabkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["slabkit", "examples", "tools", "README.md", "LICENSE"]

slabkit-0.1.0/slabkit/__init__.py

@@ -0,0 +1,20 @@
+"""slabkit -- an SVG panel system for GitHub profile READMEs.
+
+    from slabkit import Theme, banner, chips, footer, write
+
+    t = Theme(158)
+    write("banner.svg", banner(t, "SVERRE", "building AI systems, fundamentals first"))
+
+Everything renders to a self-contained SVG with no external requests, because GitHub
+serves README images through a proxy that blocks them.
+"""
+from .palette import Theme, contrast, hsl_saturation, oklch_to_hex
+from .material import MONO, Slab, mono_width, outline, squircle, write
+from .panels import banner, chips, diagram, footer, pill, status
+
+__version__ = "0.1.0"
+__all__ = [
+    "Theme", "contrast", "hsl_saturation", "oklch_to_hex",
+    "MONO", "Slab", "mono_width", "outline", "squircle", "write",
+    "banner", "chips", "diagram", "footer", "pill", "status",
+]

slabkit-0.1.0/slabkit/material.py

@@ -0,0 +1,147 @@
+"""The surface every panel is cut from.
+
+A slab is: a two-stop lightness ramp, a superellipse outline, film grain, a rim light
+along the top edge, a hairline border, and one slow specular band crossing it. Nothing
+glows, nothing blurs coloured light, and the only motion is the band.
+
+Text is either a system monospace stack or outlined to paths. GitHub proxies README
+images through camo, which blocks webfont requests -- a `font-family` pointing at a
+webfont silently falls back to something else on the reader's machine.
+"""
+import io
+
+__all__ = ["MONO", "mono_width", "squircle", "outline", "Slab"]
+
+MONO = "ui-monospace, SFMono-Regular, 'JetBrains Mono', Menlo, Consolas, monospace"
+
+# A monospace advance is a fixed fraction of the font size. This is the only reason chip
+# and label widths can be laid out without shaping text at build time. Measured against
+# rendered output, not assumed.
+MONO_ADVANCE = 0.601
+
+
+def mono_width(text, size):
+    """Rendered width of `text` in the monospace stack at `size` px."""
+    return len(text) * size * MONO_ADVANCE
+
+
+def squircle(w, h, r, n=4.5, seg=18):
+    """Rounded rect whose corners are superellipse quadrants (|x|^n + |y|^n = r^n).
+
+    A border-radius corner has discontinuous curvature where the arc meets the straight
+    edge. A superellipse does not, which is why Apple's shapes use one and why this
+    reads as considered next to every `rounded-2xl` card on the page.
+    """
+    def quad(cx, cy, sx, sy):
+        return [(cx + sx * (r * i / seg),
+                 cy + sy * (max(r ** n - (r * i / seg) ** n, 0.0)) ** (1.0 / n))
+                for i in range(seg + 1)]
+
+    d = ["M %.2f %.2f" % (r, 0)]
+    for pts in (quad(w - r, r, 1, -1),               # top-right
+                quad(w - r, h - r, 1, 1)[::-1],      # bottom-right
+                quad(r, h - r, -1, 1),               # bottom-left
+                quad(r, r, -1, -1)[::-1]):           # top-left
+        d += ["L %.2f %.2f" % pt for pt in pts]
+    d.append("Z")
+    return " ".join(d)
+
+
+def outline(font_path, text, cap_height, tracking_em=0.02):
+    """Glyph outlines as one SVG path, y-flipped into user space, sitting on y=0.
+
+    Returns (path_d, width, scale). Requires fonttools. Use this for a wordmark in a
+    typeface the reader will not have -- outlines survive camo, font references do not.
+    """
+    from fontTools.ttLib import TTFont
+    from fontTools.pens.svgPathPen import SVGPathPen
+    from fontTools.pens.transformPen import TransformPen
+    from fontTools.misc.transform import Identity
+
+    font = TTFont(font_path, fontNumber=0)
+    cmap, gs = font.getBestCmap(), font.getGlyphSet()
+    upem = font["head"].unitsPerEm
+    cap = getattr(font["OS/2"], "sCapHeight", 0) if "OS/2" in font else 0
+    scale = cap_height / float(cap or upem * 0.7)
+
+    pen = SVGPathPen(gs, ntos=lambda v: "%.1f" % v)
+    x, track = 0.0, tracking_em * upem
+    for ch in text:
+        gname = cmap.get(ord(ch))
+        if gname is None:
+            raise ValueError("no glyph for %r in %s" % (ch, font_path))
+        gs[gname].draw(TransformPen(pen, Identity.translate(x, 0).scale(1, -1)))
+        x += gs[gname].width + track
+    return pen.getCommands(), (x - track) * scale, scale
+
+
+class Slab:
+    """One panel's surface. Compose content between `open_()` and `close()`.
+
+    ids are namespaced per panel: GitHub inlines several of these images into a single
+    document, and colliding gradient ids would let the last panel win everywhere.
+    """
+
+    def __init__(self, theme, uid, w, h, radius=30, sweep=13, sweep_delay=0, band=360):
+        self.t, self.uid, self.w, self.h = theme, uid, w, h
+        self.radius, self.sweep, self.sweep_delay, self.band = radius, sweep, sweep_delay, band
+        self.shape = squircle(w, h, radius)
+
+    def defs(self):
+        t, u, w, h = self.t, self.uid, self.w, self.h
+        return f'''
+    <linearGradient id="{u}-slab" x1="0" y1="0" x2="0.35" y2="1">
+      <stop offset="0" stop-color="{t.surface}"/><stop offset="1" stop-color="{t.ink}"/>
+    </linearGradient>
+    <linearGradient id="{u}-rim" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.02"/>
+      <stop offset="0.35" stop-color="#FFFFFF" stop-opacity="0.16"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0.03"/>
+    </linearGradient>
+    <linearGradient id="{u}-sheen" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0"/>
+      <stop offset="0.25" stop-color="#FFFFFF" stop-opacity="0.018"/>
+      <stop offset="0.5" stop-color="#FFFFFF" stop-opacity="0.075"/>
+      <stop offset="0.75" stop-color="#FFFFFF" stop-opacity="0.018"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0"/>
+    </linearGradient>
+    <filter id="{u}-grain" x="0" y="0" width="100%" height="100%">
+      <feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="3" stitchTiles="stitch" result="n"/>
+      <feColorMatrix in="n" type="saturate" values="0"/>
+    </filter>
+    <clipPath id="{u}-clip"><path d="{self.shape}"/></clipPath>'''
+
+    def background(self):
+        """Gradient, travelling specular band, grain. A perfectly smooth gradient is the
+        giveaway that nothing physical made it, so the grain is not optional."""
+        u, w, h, b = self.uid, self.w, self.h, self.band
+        return f'''
+    <rect width="{w}" height="{h}" fill="url(#{u}-slab)"/>
+    <g transform="translate({-b - 100},0)">
+      <rect x="0" y="{-h}" width="{b}" height="{h * 3}" fill="url(#{u}-sheen)"
+            transform="rotate(14 {b/2} {h/2})"/>
+      <animateTransform attributeName="transform" type="translate"
+                        values="{-b - 100},0; {w + b},0" dur="{self.sweep}s"
+                        begin="{self.sweep_delay}s" repeatCount="indefinite"/>
+    </g>
+    <rect width="{w}" height="{h}" filter="url(#{u}-grain)" opacity="0.055"/>'''
+
+    def render(self, body, label="", extra_defs=""):
+        """Wrap panel content in the full slab. `label` becomes the aria-label."""
+        u, w, h = self.uid, self.w, self.h
+        return f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {w} {h}" width="{w}" height="{h}" role="img" aria-label="{label}">
+  <defs>{self.defs()}{extra_defs}</defs>
+  <g clip-path="url(#{u}-clip)">
+    {self.background()}
+    {body}
+    <rect width="{w}" height="1.25" fill="url(#{u}-rim)"/>
+  </g>
+  <path d="{self.shape}" fill="none" stroke="#FFFFFF" stroke-opacity="0.07" stroke-width="1"/>
+</svg>
+'''
+
+
+def write(path, svg):
+    with io.open(path, "w", encoding="utf-8") as f:
+        f.write(svg)
+    return path

slabkit-0.1.0/slabkit/palette.py

@@ -0,0 +1,109 @@
+"""Palettes authored in OKLCH, converted to sRGB, with contrast checked rather than hoped for.
+
+The whole point of deriving a theme from a single hue is that hierarchy then comes from
+lightness instead of chroma. That is the difference between a palette that looks designed
+and the blue-to-purple gradient every generated UI reaches for.
+"""
+import math
+
+__all__ = ["oklch_to_hex", "contrast", "hsl_saturation", "Theme"]
+
+
+def _lin_to_srgb(c):
+    return 12.92 * c if c <= 0.0031308 else 1.055 * (c ** (1 / 2.4)) - 0.055
+
+
+def _srgb_to_lin(c):
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def oklch_to_hex(L, C, H):
+    """OKLCH -> sRGB hex. Returns (hex, clipped) so callers can notice gamut overflow."""
+    a, b = C * math.cos(math.radians(H)), C * math.sin(math.radians(H))
+    l_, m_, s_ = (L + 0.3963377774 * a + 0.2158037573 * b,
+                  L - 0.1055613458 * a - 0.0638541728 * b,
+                  L - 0.0894841775 * a - 1.2914855480 * b)
+    l, m, s = l_ ** 3, m_ ** 3, s_ ** 3
+    rgb = (+4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+           -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+           -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s)
+    out, clipped = [], False
+    for v in rgb:
+        v = _lin_to_srgb(v)
+        if v < -0.001 or v > 1.001:
+            clipped = True
+        out.append(max(0.0, min(1.0, v)))
+    return "#%02X%02X%02X" % tuple(round(v * 255) for v in out), clipped
+
+
+def _luminance(hex_):
+    r, g, b = (_srgb_to_lin(int(hex_[i:i + 2], 16) / 255) for i in (1, 3, 5))
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast(a, b):
+    """WCAG contrast ratio between two hex colours."""
+    la, lb = _luminance(a), _luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def hsl_saturation(hex_):
+    r, g, b = (int(hex_[i:i + 2], 16) / 255 for i in (1, 3, 5))
+    mx, mn = max(r, g, b), min(r, g, b)
+    if mx == mn:
+        return 0.0
+    l, d = (mx + mn) / 2, mx - mn
+    return d / (2 - mx - mn) if l > 0.5 else d / (mx + mn)
+
+
+# L and C per role. Only the hue moves between themes, which is what keeps a theme
+# coherent no matter which hue you hand it.
+_ROLES = {
+    "ink":     (0.145, 0.024),   # bottom of the surface ramp
+    "surface": (0.200, 0.032),   # top of the surface ramp
+    "text":    (0.965, 0.008),
+    "muted":   (0.740, 0.012),
+    "dim":     (0.585, 0.012),
+    "accent":  (0.800, 0.118),
+}
+
+# Status hues are semantic rather than brand, so they are exempt from the one-accent
+# rule -- but they are pinned to the accent's lightness so they still belong.
+_STATUS = {"ok": 158, "warn": 78, "bad": 25}
+
+
+class Theme:
+    """A full surface ramp derived from one hue.
+
+    >>> t = Theme(158)
+    >>> t.accent
+    '#76D5A1'
+    >>> round(contrast(t.text, t.ink))
+    18
+    """
+
+    def __init__(self, hue=158, min_contrast=4.5, **overrides):
+        self.hue = hue
+        for name, (L, C) in _ROLES.items():
+            setattr(self, name, overrides.get(name) or oklch_to_hex(L, C, hue)[0])
+        for name, h in _STATUS.items():
+            L, C = (0.700, 0.150) if name == "bad" else _ROLES["accent"]
+            setattr(self, name, overrides.get(name) or oklch_to_hex(L, C, h)[0])
+
+        # Fail at build time rather than shipping unreadable text.
+        for role in ("text", "muted", "dim", "accent"):
+            got = contrast(getattr(self, role), self.ink)
+            if got < min_contrast:
+                raise ValueError(
+                    "theme hue %s: %s on ink is %.2f:1, below the %.1f:1 floor"
+                    % (hue, role, got, min_contrast))
+
+    def report(self):
+        """Human-readable audit of the theme -- handy when picking a hue."""
+        lines = ["hue %d" % self.hue]
+        for role in ("ink", "surface", "text", "muted", "dim", "accent", "ok", "warn", "bad"):
+            c = getattr(self, role)
+            lines.append("  %-8s %s  sat=%3.0f%%  contrast on ink %5.2f:1"
+                         % (role, c, hsl_saturation(c) * 100, contrast(c, self.ink)))
+        return "\n".join(lines)

slabkit-0.1.0/slabkit/panels.py

@@ -0,0 +1,221 @@
+"""The panels themselves. Each takes a Theme and its content, and returns SVG text.
+
+Every panel gets exactly one motion idea. More than one and it reads as a screensaver.
+"""
+from .material import MONO, Slab, mono_width, outline, squircle
+
+__all__ = ["banner", "chips", "status", "footer", "pill", "diagram"]
+
+PAD = 56
+
+
+def banner(theme, wordmark, tagline, meta="", note="", font=None, cap=54,
+           tracking=0.022, motif=None, w=1000, h=288, uid="b"):
+    """Hero panel. `font` outlines the wordmark; without it the monospace stack is used.
+
+    Motion: the specular band, plus whatever `motif` contributes.
+    """
+    s = Slab(theme, uid, w, h, sweep=13)
+    if font:
+        d, _, scale = outline(font, wordmark, cap, tracking)
+        mark = (f'<g transform="translate({PAD},112) scale({scale:.5f})">'
+                f'<path d="{d}" fill="{theme.text}"/></g>')
+    else:
+        mark = (f'<text x="{PAD}" y="112" font-family="{MONO}" font-size="{cap}" '
+                f'font-weight="700" fill="{theme.text}" letter-spacing="3">{wordmark}</text>')
+
+    body = [motif(theme) if motif else "", mark,
+            f'<rect x="{PAD + 2}" y="128" width="62" height="3" rx="1.5" fill="{theme.accent}"/>',
+            f'<text x="{PAD}" y="180" font-family="{MONO}" font-size="19.5" fill="{theme.accent}">&#8250;</text>',
+            f'<text x="{PAD + 22}" y="180" font-family="{MONO}" font-size="19.5" fill="{theme.muted}">{tagline}</text>']
+    if meta:
+        body.append(f'<text x="{PAD}" y="240" font-family="{MONO}" font-size="13" '
+                    f'fill="{theme.dim}" letter-spacing="0.3">{meta}</text>')
+    if note:
+        body.append(f'<text x="{w - PAD}" y="240" text-anchor="end" font-family="{MONO}" '
+                    f'font-size="12.5" fill="{theme.dim}">{note}</text>')
+    return s.render("".join(body), "%s - %s" % (wordmark, tagline))
+
+
+def chips(theme, groups, w=1000, uid="s", chip_h=36, fs=15, pad=16, gap=10,
+          row_step=60, row_first=66, label_col=168, divider=146):
+    """Labelled rows of chips.
+
+    Motion: a raking light crosses the grid, brightening each chip as it passes. Done
+    with two copies of the grid, the lit one revealed through a soft gradient mask --
+    a clip would give a hard edge, which reads as a wipe rather than as light.
+    """
+    h = row_first + (len(groups) - 1) * row_step + chip_h // 2 + 36
+    s = Slab(theme, uid, w, h, sweep=17, sweep_delay=2)
+    band = 300
+
+    def grid(lit):
+        stroke, sop = (theme.accent, "0.55") if lit else ("#FFFFFF", "0.09")
+        fop = "0.05" if lit else "0.025"
+        colour = theme.accent if lit else theme.muted
+        out = []
+        for gi, (name, items) in enumerate(groups):
+            mid = row_first + gi * row_step
+            if not lit:
+                out.append(f'<text x="{PAD}" y="{mid + 4}" font-family="{MONO}" font-size="10.5" '
+                           f'fill="{theme.dim}" letter-spacing="1.6">{name}</text>')
+            x = label_col
+            for item in items:
+                cw = mono_width(item, fs) + pad * 2
+                out.append(
+                    f'<rect x="{x:.1f}" y="{mid - chip_h/2}" width="{cw:.1f}" height="{chip_h}" rx="9" '
+                    f'fill="#FFFFFF" fill-opacity="{fop}" stroke="{stroke}" stroke-opacity="{sop}" stroke-width="1"/>'
+                    f'<text x="{x + cw/2:.1f}" y="{mid + 5}" text-anchor="middle" font-family="{MONO}" '
+                    f'font-size="{fs}" fill="{colour}">{item}</text>')
+                x += cw + gap
+        return "".join(out)
+
+    extra = f'''
+    <linearGradient id="{uid}-rakeg" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#000000"/><stop offset="0.5" stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#000000"/>
+    </linearGradient>
+    <mask id="{uid}-rake">
+      <rect width="{w}" height="{h}" fill="#000000"/>
+      <g transform="translate({-band},0)">
+        <rect width="{band}" height="{h}" fill="url(#{uid}-rakeg)"/>
+        <animateTransform attributeName="transform" type="translate"
+                          values="{-band},0; {w},0" dur="9s" repeatCount="indefinite"/>
+      </g>
+    </mask>'''
+    body = (f'<line x1="{divider}" y1="{row_first - 30}" x2="{divider}" y2="{h - 36}" '
+            f'stroke="#FFFFFF" stroke-opacity="0.06" stroke-width="1"/>'
+            + grid(False) + f'<g mask="url(#{uid}-rake)">{grid(True)}</g>')
+    label = "; ".join("%s: %s" % (n, ", ".join(i)) for n, i in groups)
+    return s.render(body, label, extra)
+
+
+def status(theme, label, state, word, headline, detail, right="", stamp="",
+           w=1000, h=168, uid="st"):
+    """Service status.
+
+    `state` picks the semantic colour: ok / warn / bad. Those are exempt from the
+    one-accent rule because they carry meaning rather than decoration -- but they are
+    derived at the accent's lightness so they still sit in the same band.
+
+    Motion: the status dot pulses a ring.
+
+    Always pass `stamp`. A committed SVG behind camo is stale by design, and a status
+    panel that implies real-time is simply lying.
+    """
+    colour = {"ok": theme.ok, "warn": theme.warn, "bad": theme.bad}[state]
+    s = Slab(theme, uid, w, h, sweep=19, sweep_delay=7)
+    body = f'''
+    <text x="{PAD}" y="48" font-family="{MONO}" font-size="10.5" fill="{theme.dim}" letter-spacing="1.6">{label}</text>
+    <circle cx="{PAD + 6}" cy="86" r="5" fill="{colour}"/>
+    <circle cx="{PAD + 6}" cy="86" r="5" fill="none" stroke="{colour}" stroke-width="1">
+      <animate attributeName="r" values="5;16;16" keyTimes="0;0.7;1" dur="3s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.65;0;0" keyTimes="0;0.7;1" dur="3s" repeatCount="indefinite"/>
+    </circle>
+    <text x="{PAD + 26}" y="94" font-family="{MONO}" font-size="24" fill="{colour}" letter-spacing="1.5">{word}</text>
+    <text x="{PAD + 34 + mono_width(word, 24)}" y="94" font-family="{MONO}" font-size="15" fill="{theme.muted}">{headline}</text>
+    <text x="{PAD}" y="128" font-family="{MONO}" font-size="12.5" fill="{theme.dim}">{detail}</text>
+    <text x="{w - PAD}" y="86" text-anchor="end" font-family="{MONO}" font-size="12.5" fill="{theme.muted}">{right}</text>
+    <text x="{w - PAD}" y="107" text-anchor="end" font-family="{MONO}" font-size="11" fill="{theme.dim}">{stamp}</text>'''
+    return s.render(body, "%s: %s - %s" % (label, word, headline))
+
+
+def footer(theme, headline, sub, right="", w=1000, h=140, uid="f"):
+    """Contact bookend. Motion: a ring pulses out of the right-hand dot."""
+    s = Slab(theme, uid, w, h, sweep=15, sweep_delay=5)
+    dot = w - PAD - mono_width(right, 12.5) - 20
+    body = f'''
+    <text x="{PAD}" y="62" font-family="{MONO}" font-size="24" fill="{theme.accent}">{headline}</text>
+    <text x="{PAD}" y="94" font-family="{MONO}" font-size="13" fill="{theme.muted}">{sub}</text>'''
+    if right:
+        body += f'''
+    <circle cx="{dot:.1f}" cy="72" r="4" fill="{theme.accent}"/>
+    <circle cx="{dot:.1f}" cy="72" r="4" fill="none" stroke="{theme.accent}" stroke-width="1">
+      <animate attributeName="r" values="4;13;13" keyTimes="0;0.7;1" dur="2.6s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.7;0;0" keyTimes="0;0.7;1" dur="2.6s" repeatCount="indefinite"/>
+    </circle>
+    <text x="{w - PAD}" y="77" text-anchor="end" font-family="{MONO}" font-size="12.5" fill="{theme.dim}">{right}</text>'''
+    return s.render(body, headline)
+
+
+def pill(theme, label, on, fs=13, h=36, uid="p"):
+    """A small standalone pill -- language toggles, nav, tags.
+
+    One image per pill on purpose: markdown hangs a single href off an <img>, so a
+    combined toggle would send both halves to the same place.
+    """
+    w = int(mono_width(label, fs) + 38)
+    stroke, sop = (theme.accent, "0.55") if on else ("#FFFFFF", "0.10")
+    colour = theme.accent if on else theme.muted
+    shape = squircle(w, h, 10)
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {w} {h}" width="{w}" height="{h}" role="img" aria-label="{label}{' (current)' if on else ''}">
+  <defs>
+    <linearGradient id="{uid}-slab" x1="0" y1="0" x2="0.35" y2="1">
+      <stop offset="0" stop-color="{theme.surface}"/><stop offset="1" stop-color="{theme.ink}"/>
+    </linearGradient>
+    <clipPath id="{uid}-clip"><path d="{shape}"/></clipPath>
+  </defs>
+  <g clip-path="url(#{uid}-clip)">
+    <rect width="{w}" height="{h}" fill="url(#{uid}-slab)"/>
+    <text x="{w/2}" y="{h/2 + 4.5}" text-anchor="middle" font-family="{MONO}"
+          font-size="{fs}" fill="{colour}" letter-spacing="0.4">{label}</text>
+  </g>
+  <path d="{shape}" fill="none" stroke="{stroke}" stroke-opacity="{sop}" stroke-width="1"/>
+</svg>
+'''
+
+
+def diagram(theme, title, subtitle, nodes, edges, caption="", w=1000, h=268,
+            box_h=56, uid="a"):
+    """System diagram with a request relaying along the edges and responses returning.
+
+    `nodes` are dicts of x/w/cy/label/sub; `edges` are (from_index, to_index) pairs.
+    Useful when the code is private and the shape is the only thing you can show.
+    """
+    s = Slab(theme, uid, w, h, sweep=21, sweep_delay=3)
+    parts = []
+    for a_i, b_i in edges:
+        a, b = nodes[a_i], nodes[b_i]
+        parts.append(f'<path d="M {a["x"]+a["w"]} {a["cy"]} L {b["x"]} {b["cy"]}" fill="none" '
+                     f'stroke="{theme.accent}" stroke-width="1" opacity="0.26"/>')
+    for n in nodes:
+        cx, top = n["x"] + n["w"] / 2, n["cy"] - box_h / 2
+        parts.append(f'<rect x="{n["x"]}" y="{top}" width="{n["w"]}" height="{box_h}" rx="10" '
+                     f'fill="#FFFFFF" fill-opacity="0.028" stroke="#FFFFFF" stroke-opacity="0.10" stroke-width="1"/>')
+        if n.get("sub"):
+            parts.append(f'<text x="{cx}" y="{n["cy"] - 2}" text-anchor="middle" font-family="{MONO}" '
+                         f'font-size="13" fill="{theme.text}">{n["label"]}</text>'
+                         f'<text x="{cx}" y="{n["cy"] + 15}" text-anchor="middle" font-family="{MONO}" '
+                         f'font-size="10.5" fill="{theme.dim}">{n["sub"]}</text>')
+        else:
+            parts.append(f'<text x="{cx}" y="{n["cy"] + 5}" text-anchor="middle" font-family="{MONO}" '
+                         f'font-size="13" fill="{theme.text}">{n["label"]}</text>')
+
+    def hop(a, b, begin, back):
+        x1, y1, x2, y2 = a["x"] + a["w"], a["cy"], b["x"], b["cy"]
+        if back:
+            x1, y1, x2, y2 = x2, y2, x1, y1
+        r, op = (1.6, 0.5) if back else (2.1, 0.95)
+        return (f'<circle r="{r}" fill="{theme.accent}" opacity="0">'
+                f'<animate attributeName="cx" values="{x1};{x2}" dur="0.9s" repeatCount="indefinite" begin="{begin}s"/>'
+                f'<animate attributeName="cy" values="{y1};{y2}" dur="0.9s" repeatCount="indefinite" begin="{begin}s"/>'
+                f'<animate attributeName="opacity" values="0;{op};{op};0" keyTimes="0;0.15;0.75;1" '
+                f'dur="0.9s" repeatCount="indefinite" begin="{begin}s"/></circle>')
+
+    # depth from the first node, so parallel branches fire together rather than in series
+    depth = {0: 0}
+    for a_i, b_i in edges:
+        depth[b_i] = depth.get(a_i, 0) + 1
+    for a_i, b_i in edges:
+        t = depth[a_i] * 0.75
+        parts.append(hop(nodes[a_i], nodes[b_i], t, False))
+        parts.append(hop(nodes[a_i], nodes[b_i], t + 3.2, True))
+
+    body = (f'<text x="{PAD}" y="46" font-family="{MONO}" font-size="10.5" fill="{theme.dim}" '
+            f'letter-spacing="1.6">{title}</text>'
+            f'<text x="{PAD + mono_width(title, 10.5) + 26}" y="46" font-family="{MONO}" font-size="10.5" '
+            f'fill="{theme.accent}" letter-spacing="1.2">{subtitle}</text>' + "".join(parts))
+    if caption:
+        body += (f'<text x="{PAD}" y="{h - 28}" font-family="{MONO}" font-size="12" '
+                 f'fill="{theme.muted}">{caption}</text>')
+    return s.render(body, "%s %s" % (title, subtitle))

slabkit-0.1.0/tools/build_docs.py

@@ -0,0 +1,77 @@
+"""Builds the images in slab's own README, using slab.
+
+If the library cannot document itself, it is not ready to document anyone else.
+
+    python tools/build_docs.py
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from slabkit import (MONO, Slab, Theme, banner, chips, diagram, footer, mono_width,
+                  status, write)
+
+OUT = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "assets")
+os.makedirs(OUT, exist_ok=True)
+
+t = Theme(158)
+
+HUES = [(158, "jade"), (200, "cyan"), (250, "blue"), (30, "coral"), (110, "moss")]
+
+
+def hue_strip(w=1000, h=132):
+    """Low-level API demo: the same ramp at five hues, drawn straight onto a Slab.
+
+    Every swatch here is generated, not picked -- which is the argument for deriving a
+    palette instead of choosing hexes by eye.
+    """
+    s = Slab(t, "h", w, h, sweep=16)
+    parts = [f'<text x="56" y="46" font-family="{MONO}" font-size="10.5" fill="{t.dim}" '
+             f'letter-spacing="1.6">Theme(hue)</text>']
+    x, box = 56, 168
+    for hue, name in HUES:
+        th = Theme(hue)
+        parts.append(
+            f'<rect x="{x}" y="66" width="{box - 14}" height="40" rx="9" fill="{th.surface}" '
+            f'stroke="{th.accent}" stroke-opacity="0.5" stroke-width="1"/>'
+            f'<circle cx="{x + 22}" cy="86" r="7" fill="{th.accent}"/>'
+            f'<text x="{x + 40}" y="83" font-family="{MONO}" font-size="11.5" fill="{t.text}">{name}</text>'
+            f'<text x="{x + 40}" y="96" font-family="{MONO}" font-size="9.5" fill="{t.dim}">{hue}° {th.accent}</text>')
+        x += box
+    return s.render("".join(parts), "Theme accents at hues %s" % ", ".join(str(h) for h, _ in HUES))
+
+
+DEMO_NODES = [
+    dict(x=56,  w=150, cy=132, label="client",  sub=""),
+    dict(x=266, w=180, cy=132, label="edge",    sub="cache"),
+    dict(x=506, w=170, cy=132, label="api",     sub="your service"),
+    dict(x=736, w=160, cy=132, label="storage", sub=""),
+]
+
+built = [
+    ("hero.svg", banner(
+        t, "SLAB", "SVG panels for GitHub READMEs",
+        meta="python  ·  no runtime deps  ·  MIT",
+        note="generated by slab")),
+    ("panel-chips.svg", chips(t, [
+        ("WRITE", ["Python", "TypeScript"]),
+        ("BUILD", ["anything", "you", "like"]),
+    ])),
+    ("panel-status.svg", status(
+        t, "SERVICE", "ok", "UP", "all checks passing",
+        "Flip state to warn or bad and the colour follows.",
+        right="since 2026-08-01", stamp="generated 2026-08-26 19:00 UTC")),
+    ("panel-diagram.svg", diagram(
+        t, "EXAMPLE", "request path", DEMO_NODES, [(0, 1), (1, 2), (2, 3)],
+        caption="Nodes are dicts, edges are index pairs. The relay animates itself.",
+        h=248)),
+    ("panel-footer.svg", footer(
+        t, "you@example.com", "One accent, one motion idea, no glow.",
+        right="available")),
+    ("hues.svg", hue_strip()),
+]
+
+for name, svg in built:
+    p = write(os.path.join(OUT, name), svg)
+    print("  %-20s %6d bytes" % (name, os.path.getsize(p)))