reflex-hairline

Hairline's twenty-seven isometric line figures that answer the pointer, as Reflex components.

Each figure is an SVG drawing that reacts to the mouse: pillars rise around it, a vault dial turns, a drawer slides out. They are useful as hero art, as section illustrations and, at 160–240px, as empty states. This package wraps @lucasmarkes/hairline v0.3.0 (MIT, by Lucas Marques) and adds a few things the React entry does not have: figures picked by a state var, figures made with the hairline-create agent skill, and theming from Python.

pip install reflex-hairline
# or
uv add reflex-hairline

Reflex installs the npm package (@lucasmarkes/hairline@0.3.0) on the next reflex run; there is nothing else to set up.

Quick start

import reflex as rx
from reflex_hairline import hairline


class State(rx.State):
    caption: str = "rest"

    @rx.event
    def set_caption(self, text: str):
        self.caption = text


def index() -> rx.Component:
    return rx.vstack(
        hairline.terrain(
            intensity=0.7,  # 0 (subtle) … 1 (strong), default 0.5
            theme="auto",  # "auto" | "light" | "dark"
            label="A field of pillars",  # accessible name
            on_read=State.set_caption,  # the figure's caption, each time it changes
            width="480px",
        ),
        rx.text(State.caption),
    )


app = rx.App()
app.add_page(index)

A figure renders one <div> that fills its parent's width at a 5:4 aspect ratio. Size it with width= (or its parent). Every other style prop, id, class_name, on_click, etc. passes through to the div.

The figures

All 27 are available three ways: hairline.<id>(...), a snake_case factory (from reflex_hairline import terrain) and a component class (Terrain.create(...)).

The same data is available in Python as FIGURES / BY_ID (FigureInfo with name, summary, stronger, default label, rest caption, and the internal parameter, unit and range that intensity maps onto).

Options

All props accept state vars.

Picking a figure at runtime

hairline.figure(figure=State.figure_id, fallback="terrain", intensity=State.intensity)
# hairline(figure=...) is the same thing

Changing figure remounts the drawing; an unknown id draws fallback.

Theming

Hairline reads six CSS custom properties. Set them from Python with keyword shortcuts on any figure:

hairline.vault(plate="#0b1020", hi="#e2e8f0", edge="#64748b", mid="#334155", lo="#1e293b", stroke=1.1)

or build a style dict with tokens() and put it on any ancestor (they inherit):

from reflex_hairline import tokens

rx.grid(*figures, style=tokens(palette="radix"))

Palettes for palette=: "light" and "dark" (Hairline's own), "radix" (mapped to Radix Themes gray tokens, so figures follow rx.theme and color mode) and "radix-accent" (lit strokes in your accent colour). Explicit shortcuts win over the palette, and a style= you pass wins over both. The dicts are exported as LIGHT, DARK, RADIX_TOKENS, RADIX_ACCENT_TOKENS and PALETTES.

Empty states

hairline.empty_state(
    "sieve",
    "No results match these filters",
    "Try removing a filter.",
    rx.button("Clear filters", on_click=State.clear),
    width="200px",
)

Hairline recommends 160–240px above a heading and one action; the rest pose is the picture, the pointer is a bonus. loupe, sieve, rail, plug, query, drawer, basket and plot were drawn for this.

Figures made with the hairline-create skill

hairline-create is Hairline's skill for coding agents (npx skills add lucasmarkes/hairline, then /hairline-create a sales funnel). It outputs hairline-<name>.html, one file drawn on the same kernel as the packaged figures. hairline.custom mounts it natively, with the same options:

# put hairline-funnel.html in your app's assets/ folder
hairline.custom(
    src="/hairline-funnel.html",  # or the figure's .js file, or code="..."
    intensity=State.intensity,
    theme="auto",
    on_read=State.set_caption,
    on_load=State.loaded,  # {name, means, rules, range}
    on_error=State.failed,  # str
)

intensity is mapped onto the figure's declared range, exactly as the packaged figures map theirs. The figure's script runs in the page, so only load files you trust.

Notes

• Accessibility. A figure is an image (role="img") with a description you can replace with label. Riffle is a focusable group whose arrow keys walk the cards.
• Reduced motion. With prefers-reduced-motion, Phosphor and Slow hold still; every figure still answers the pointer.
• Performance. All figures on a page share one requestAnimationFrame loop; a figure off screen or at rest does no work.
• SSR. On the server a figure is an empty 5:4 box, so nothing shifts when it draws.

Demo

git clone https://github.com/ecrespo/reflex-hairline
cd reflex-hairline
uv sync
cd hairline_demo
uv run reflex run

Pages: Gallery (all 27 with live on_read captions), Playground (every option and generated code), Theming, Empty states, Skill figures, and an API Reference.

Development

uv sync                          # editable install + dev tools
uv run pytest                    # unit tests
uv run reflex component build    # .pyi stubs + sdist/wheel in dist/

CI and releases

• CI (code quality): ruff lint/format, pytest on Python 3.10–3.13, demo reflex compile, build + twine check.
• Security: gitleaks, bandit, pip-audit, dependency review (PRs) and CodeQL; also weekly.
• Release: push a tag vX.Y.Z matching version in pyproject.toml. It re-runs both suites, builds, checks the tag is on main, publishes to PyPI, installs it back from PyPI and creates the GitHub Release. Pre-release versions (X.Y.ZrcN, aN, bN, .devN) go to PyPI as pre-releases. Trusted Publishing, environment pypi (no tokens).

Credits and license

Hairline, its figures and the hairline-create kernel (hairline_kernel.js, shipped unchanged apart from an ES module export) are © Lucas Marques, MIT; see LICENSE.hairline. The demo includes four example figures from hairline.lucasmarkes.com/skill. This Reflex wrapper is © Ernesto Crespo, MIT.