Riot’s Jolly Roger

The flag and surface system for RiotML: one voice across web, CLI, docs, packages, diagnostics, and releases.

Why Riot?

There are many OCaml stacks. This one is mine.

I wanted an ML-family language and ecosystem that felt beautiful and practical: actor-based, multi-core ready, type safe, and delightful to use end to end. Something built for shipping.

Riot is my take on what an ML stack should feel like in 2026: opinionated unified tooling, a modern packaging story with built-in docs, actor-oriented by default, a standard library for 80% of everything you'll ever need, and one flag over the whole thing.

Riot is about building software that works, shipping it quickly, making it beautiful when it proves itself useful, and enjoying the work along the way.

It is the most fun I've had programming in my entire career.

Jolly Roger is Riot’s design system, in many ways our very own pirate flag, and it describes the values this stack, and all the supporting systems around it, lives and dies by.

#01 - Optimize for Developer Joy

I get joy out of building good software. Especially when it works, but even more so when it looks beautiful and runs fast.

Every interaction with Riot should make information clear, feedback actionable, and iteration fast. Put commands near claims, examples near explanations, and recovery paths near failures.

Joy does not mean everything is soft, friendly, or simplified until it becomes useless. Riot can be sharp. It can be loud. It can be opinionated. It can say no.

Where it shows up

  • Package tables keep version, docs state, owner, and freshness close to the package name.
  • Command examples sit next to the prose that explains them.
  • Errors end with a concrete fix instead of a vague suggestion.

#02 - Design as One Piece

Riot is one piece, not many. The compiler, runtime, actor model, package manager, docs generator, registry, test runner, formatter, diagnostics, install scripts, standard library, and website should feel like parts of the same whole.

Make the preferred path obvious. A golden path is not a prison; it is the route designed, tested, documented, and supported end to end. The design system should make those paths visible: install this, run this, add this package, read these docs, fix this error, publish this way.

The core model is not up for committee redesign. Riot does not need formatter knobs, old-tool compatibility as identity, or every surface assembled from unrelated options.

Where it shows up

  • The same tokens drive the design-system page, component demos, docs mock, registry mock, and CLI surfaces.
  • The table of contents follows the same section order as the document.
  • The hero, footer, docs, and registry examples all use one voice and one visual grammar.

#03 - Build for Shipping

Riot exists so you can ship real software. The design system should help people understand, install, try, build, test, publish, debug, and keep going.

The Riot path is: make it work, learn whether it is the right thing, make it beautiful, make it fast where it needs to be fast, and keep shipping.

Do not reward performative complexity, academic posturing, elaborate setup rituals, or pages that brand and decorate without moving the builder forward.

Where it shows up

  • Buttons use imperative labels like Install, Read, Add, and Publish.
  • Copyable commands stay close to install, fix, and publish explanations.
  • Application rules name the task, required information, traps to avoid, and primary components.

#04 - Human-led, agent-ready

Riot is designed by humans. Taste matters. Authority matters. Judgment matters.

Use stable anchors, stable headings, stable field labels, package names, source paths, version numbers, error codes, copyable commands, structured metadata, explicit next steps, and short examples that agents can reuse safely.

AI-friendly does not mean vague chat UX, autopilot magic, generated slop, or letting the AI own the taste. The captain is human.

Where it shows up

  • The page rail exposes durable section anchors, not every tiny component variant.
  • Tables include captions and labels so the content degrades cleanly into text.
  • Agent-ready voice examples use stable fields like package, source, wanted, and fix.

#05 - Trust Builders With Power

Riot trusts you with powerful tools. The stack should be approachable, but it should not be timid.

Make power legible: show code, signatures, generated artifacts, runtime behavior, unsafe boundaries, platform caveats, what the tool did, and how to go deeper.

Do not hide powerful concepts behind soft language. Power tools need visible edges.

Where it shows up

  • Code blocks show real commands and structured output instead of decorative terminal chrome.
  • Callouts use explicit warning, danger, success, and note variants when the reader needs a stronger signal.
  • Docs examples expose signatures and module context instead of hiding the machinery.

Voice and writing

Direct, useful, joyful.

Riot’s Jolly Roger sounds direct, opinionated, useful, technical, and joyful. It does not sound corporate, academic, generic, or clever when a clear label helps more.

Direct

Say the thing.

Do not wrap every claim in hedging language. Do not make the reader decode vague platform words. Do not hide the action behind narrative.

Useful

Every sentence should help.

A page can be joyful, opinionated, or expressive, but it still has to help the reader install Riot, find a package, fix an error, understand a module, compare options, or keep moving.

Joyful

Joy means momentum.

Joy does not mean childish. The writing should make the reader feel that Riot is on their side: beautiful code, fast feedback, good defaults, visible power, and the pleasure of building useful software.

Errors

Clear, structured, recoverable.

Error copy starts with the problem. Name what failed before explaining how the system works, then give the reader enough context to recover without guessing.

A useful Riot error names the package, source, requested thing, expected or available thing, and the reason it happened when that reason is known. It ends with one concrete command, edit, or docs link. The same diagnostic should still make sense as plain text.

Agents

Stable labels. No guessing.

Agent-ready voice is still human voice. It just refuses to hide important state in loose prose. When a surface describes a package, command, file, error, or generated report, name the stable facts directly so a person can scan them and a tool can parse them.

Prefer labels such as package, source, wanted, found, and fix when those facts matter. Make examples reusable without hidden setup. Avoid copy that forces the reader to infer the package, file, requested symbol, or next command.

Example

Vague copy names no object, no source, and no recovery path. It leaves both humans and agents guessing.

Vague
Something went wrong while resolving dependencies.

Better copy names the package, explains the failure, and gives the next command.

Better
Riot could not resolve Krasny because riot-cli does not depend on the package that exposes it.

Run riot add krasny.

When the output is meant for tools too, expose the same facts as stable fields.

Preferred structure
package: riot-cli
source:  src/publish.ri
wanted:  Krasny
fix:     riot add krasny

Foundations

Visible decisions, not decoration.

These are the tangibles: mark, color, typography, spacing, edges, density, layout, code, and terminal output. They follow the principles. They are not arbitrary styling choices.

/01 · Mark and flag

A black flag with a white λ.

The Jolly Roger is the flag of Riot: simple, reproducible, and useful as a clear signature across the stack.

Use as identityLet the mark sign a surface. Do not use it as repeated decoration.
High contrastPrefer simple placements where the mark survives at small sizes.

/02 · Color

Cream, coal, ink, and one red.

Riot Red is identity and action. Paper is reading. Coal is terminal and gravity. Ink is text. Mint, amber, and blue are functional colors.

Color clarifies what kind of information the reader is looking at. Paper carries reading, ink carries structure, coal carries code and terminal gravity, and Riot Red marks identity or action.

Paper #FFF8ED · Default reading surface
Paper-2 #F5ECDC · Recessed surface
Ink #151317 · Text, borders, structure
Coal #0E0D10 · Terminal and code gravity
Riot #EF233C · Flag, identity, primary action
Mint #24C08D · Success state
Amber #F0B429 · Warning state
Blue #2777FF · References and links
PrimaryRiot Red, paper, ink, and coal define identity, reading, structure, and terminal gravity.
SecondaryMint, amber, and blue are functional state colors for success, caution, and references.
Deliberate redUse Riot Red for identity, action, danger, and real emphasis.
Never color aloneState must also have labels, text, or structure.

/03 · Typography

Technical, authored, readable.

Use Martian Mono for headings, navigation, labels, and data chrome; a readable sans for explanations; and a regular mono for code and terminal output.

Typography has three jobs. Display type gives Riot its authored voice. Body type makes longer explanations comfortable. Code type keeps commands, paths, signatures, and numeric metadata precise.

DisplayMartian Mono · 900
Hoist the λ

Programming ecosystem. Headings, navigation, labels, data chrome.

BodyAtkinson Hyperlegible · 400

Long explanations should be comfortable enough to read without making dense technical pages feel padded.

Human explanation. Long docs prose. Editorial surfaces.

CodeMonospace stack · 500
$ riot add std
→ resolved 12 packages in 84ms

Code is product UI. Commands, paths, signatures, table numerics.

SizesUse the token scale for headings, labels, body text, compact metadata, and code.
RuleDo not use display mono for long code snippets.

/04 · Spacing

5px base unit. Memorable scale.

Use 5px increments for spacing and component rhythm. The common scale is 5, 10, 15, 20, 25, 30, 40, 50.

The 5px unit is small enough to tune dense interfaces without inventing one-off values, and large enough to stay memorable.

It keeps Riot surfaces rhythmic: rows, gutters, controls, and examples snap to the same cadence, so dense pages feel authored instead of arbitrary.

Typography can still be optical. The grid does its work in spacing, sizing, rhythm, and repeated structure.

u1 5px
u2 10px
u3 15px
u4 20px
u5 25px
u6 30px
u8 40px
u10 50px
UnitThe base spacing unit is 5px.
SizesControls, rows, icons, and marks follow named size tokens.
SpacersThe common rhythm is 5, 10, 15, 20, 25, 30, 40, and 50.
BordersUse 1px borders. Borders do not need to become grid units.

/05 · Edges

Crisp, not inflated.

Use small radii, quiet borders, and restrained shadows. Riot should feel scrappy and precise, not boxed-in or aggressively stamped.

crisp

Default geometry keeps docs, tables, panels, and command surfaces clean without turning every block into a sign.

5px

Small radius softens controls and shells while staying inside the 5px rhythm.

lift

Soft lift is enough for emphasis. The page should not look like a stack of posters.

focus

Use stronger emphasis only when a surface needs focus or hierarchy.

DefaultUse crisp 5px corners for cards, tables, docs shells, commands, and controls.
RuleUse borders for structure and shadows for focus, not decoration.

/06 · Density

Clean compression.

Riot surfaces carry packages, modules, types, versions, dependencies, diagnostics, reports, and docs. Density is a feature when hierarchy is clear.

Use tablesComparison belongs in rows, not decorative cards.
Use sidebarsLong references need orientation and anchors.
Keep metadata closeVersions, dates, owners, and docs status sit near the thing they describe.
Hierarchy firstReach for labels, rules, alignment, and type before adding empty air.

/07 · Layout

Chapter, body, anchors.

Use the shell to orient the reader, chapters to create long-page structure, and compact metadata to keep decisions local.

ShellPage frame plus flexible main column.
ContentReadable width with tokenized gutters.
ChapterMarker column plus body column.
SectionTokenized vertical padding and rule.

/08 · Code and terminal

Code is product UI.

Commands, output, signatures, diagnostics, and copy affordances are first-class surfaces.

The terminal is not a screenshot. It is where install, build, test, publish, debug, and recovery happen. Code and output need the same care as navigation and prose.

Terminal
λ riot fmt --check
ok 128 files formatted
json: {"event":"fmt.checked","files":128}
riot add krasny http postgres

Components

Reusable primitives with Riot judgment.

Components are repeated decisions. Buttons, tables, forms, inputs, badges, callouts, cards, and code should look like the same system and carry the same voice.

Buttons

Direct, compact, imperative actions.

Button variant rules
Variant Use for Example
Primary One main action on the surface.
Default A secondary action with normal weight.
Dark A technical or source-adjacent action.
Ghost A quiet command-shaped action.
Small Compact toolbars and dense forms.

Tables

Let users scan and compare dense structured information.

Package metadata comparison
Package Version Docs Owner Updated
std0.6.0readycoretoday
kernel0.0.18readycore2d
krasny0.2.1partialweb1d
Benchmark comparison
Run Mean P95 Delta
baseline42 ms68 ms0%
current37 ms54 ms-12%

Forms

Group controls by the decision they support.

Fields keep labels close to values so compact forms still scan cleanly.

Version values stay mono and exact.

Short fields read like configuration, not marketing copy.

Inputs

Compact, labeled, bordered in ink.

Use placeholders for examples, not hidden labels.

Textareas follow the same border, type, and spacing rules as inputs.

Badges

Small status and metadata markers.

Badge variant rules
Variant Use for Example
Default Neutral categories and tags. stdlib
Solid Strong version or status metadata. v0.6.0
Riot Identity, risk, or attention. unstable
Mint Readiness, success, passing checks. stable
Amber Caution, beta state, review needed. beta

Callouts

Interrupt only when the information changes what the reader should do.

Cards

Use cards for one bounded object. Do not use cards to replace comparison tables.

Docs report

One object, one status, one next action. Cards frame a thing; they should not hide data that wants rows.

Build surface review

Use status cards for repeated summaries, settings groups, and focused previews.

Code

Code examples are product UI.

Code snippet
λ riot fmt --check
ok 128 files formatted
Structured output
package: std
source:  src/lib.ri
fix:     riot add std

In the wild

Real surfaces governed by the system.

Each application names the surface, the reader's task, the required information, the traps to avoid, and the components that carry it.

https://riot.ml
PurposeMake people think: this might be the ML stack I wanted.
Must showThe stack, a real command, real code, and the path to install, learn, and ship.
AvoidStartup SaaS air, vague positioning, and technical proof buried below chrome.
Primary componentsButtons, cards, code, and callouts.

riot.ml

Many OCaml stacks.
/ One flies a flag.

The Riot website makes the stack legible fast. Show the command, the stack, and the path to install, learn, and ship.

std@0.6.0

Standard library surface for system work.

published today
kernel@0.0.18

Core abstractions shared across Riot.

updated 6h ago
https://pkgs.ml
PurposeHelp users find, compare, evaluate, and install packages.
Must showName, version, docs status, freshness, owner, install command, and compatibility context.
AvoidDecorative cards when comparison is the task.
Primary componentsTables, badges, forms, inputs, and callouts.
pkgs.ml
1,247 packages
Total packages1,247
Downloads8.4M
Publishers309
Median publish1.8s
Registry package comparison
Package Version Description Category Downloads Updated
std 0.4.0 Standard library. Datatypes, collections, IO, time, formats. core 1,247,890 today
kernel 0.0.18 Core abstractions shared across the Riot ecosystem. core 840,221 2d
serde 0.3.0 Schema-driven serialization helpers for Riot data. format 620,498 6h
krasny 0.2.1-rc Web framework on top of Riot’s actor runtime. web 98,114 1d
https://docs.pkgs.ml/p/kernel/0.0.18/Kernel/Result
PurposeHelp readers understand generated API documentation without losing orientation.
Must showPackage, version, module, breadcrumbs, search, local navigation, signatures, examples, and stability markers.
AvoidDecorative chrome around generated reference material.
Primary componentsTables, cards, code, callouts, and badges.
Riot Docs kernel / Kernel / Result v0.0.18

module · Kernel.Result

Result

Errors are values. Results carry them through pipelines, actor boundaries, and logs.

Signature
type ('a, 'e) t = Ok of 'a | Error of 'e
val map : ('a -> 'b) -> ('a, 'e) t -> ('b, 'e) t
terminal surfaces
PurposeTell the user what happened and what to do next in plain text.
Must showStatus, package, version, source when relevant, diagnostic IDs, and copyable next commands.
AvoidNoisy success output, fake terminal theater, and prose that breaks scripts.
Primary componentsCode, badges, tables, and callouts.

CLI

Plain text still carries the brand.

Prompts, aligned labels, diagnostic IDs, and fix commands work without browser chrome.

CLI output
λ riot publish --dry-run
ok package checked
package: krasny
version: 0.2.1
next: run riot publish
https://pkgs.ml/not-found
PurposeTurn a dead end into a recovery path.
Must showProblem, context, possible cause, fix, and fallback.
AvoidCute dead ends, jokes instead of recovery, and errors with no next action.
Primary componentsCallouts, code, buttons, and badges.

Error pages

Useful dead ends.

Error pages are diagnostics in web form. Explain what failed, whether it is local or remote, and what the user can do next.

Anatomy
problem: package not found
context: registry search
possible cause: misspelled package name
fix: search for krasny
fallback: publish a new package