designmd

A plain HTML/CSS extension of Picasso, Toptal's production design system, built so Operationalize can prototype quickly and hand over something that translates.

Picasso is the source of truth. Its Storybook and packages/base/<Component>/src/ define what a component is and what a token is worth. designmd re-expresses those foundations as three stylesheets a browser can load directly — no React, no build step — so a screen can exist in hours rather than days.

Every token here is either Picasso's, name and value verbatim, or marked extension with a reason in its own comment. Where the two disagree, Picasso is right and this is a bug.

tokens.css           primitives — Picasso's palette, scale and shadows
semantic.css         intent aliases — --color-bg, --type-h1
components.css       the component classes
icons.svg            the icon sprite — <use href="#i-{slug}">
example.html         the showcase: every token and component, live
DESIGN.md            the full written reference
data/figma-map.json  binds each class to its Picasso React component

Building with an AI tool

Point it at AGENTS.md — the rules, the traps, and how to build and check a prototype, in about 1,300 tokens. Cursor, Copilot, Windsurf and Cline each get a generated copy at the path they look for, so whichever you use already has it.

AGENTS.md       the rules. Start here.
llms-full.txt   AGENTS.md + the worked markup + the complete class and
                token inventory, ~9k tokens.
                Paste this into a chat that has no access to the repo.
llms.txt        a short index of everything here.
dist/kit.json   every class, grouped — plus the attribute-driven components, the
                behaviour hooks, and the showcase-only classes to reject.
dist/tokens.json  every token, value and usage note, light and dark.
lint.py         checks a prototype; exits non-zero on errors.

CI runs `tools/build-packages.py --check` and `tools/smoke_test.py` on every
push and pull request, so the generated files and the documented workflow
cannot drift unnoticed.

Two rules carry most of the weight: never invent a class — if it is not in kit.json it does not exist, and a class nothing defines renders as nothing — and never copy markup out of example.html, because 88 of the classes in it are the showcase's own chrome and look identical to kit classes.

Everything under dist/, plus llms*.txt and the per-tool rule files, is generated by tools/build-packages.py. Edit the stylesheets or AGENTS.md and re-run it; --check fails when they fall behind.

Open example.html to browse the system, or DESIGN.md to read it. Prototypes live in the sibling features/ folder and are shipped as single self-contained HTML files — inline.py bakes the stylesheets, the icon sprite and the fonts into each one.