The Jolly Roger · foundation first
A pragmatic design system for the RiotML ecosystem, migrated in the same order it asks other surfaces to follow: tokens first, typography second, layout third, components after that.
Language ecosystems accumulate dense surfaces: package indexes, generated API docs, changelogs, diagnostics, install flows, examples, and reference pages.
Use strong hierarchy, square geometry, exact spacing, visible structure, and real code. Prefer useful density over decoration.
Tokens first
Tokens are the first migration layer. Every later decision pulls from these variables: color, type families, spacing, borders, and shadows. If a page needs an off-system value, the system probably needs a new token first.
/01 · Color
Paper carries reading. Ink carries structure. Riot Red is identity and urgent action. Mint, amber, and blue are semantic states, not decoration.
/02 · Typography
Martian Mono is the system voice. JetBrains Mono is the code voice. Atkinson Hyperlegible carries longer prose.
Riot ships a single tool, a modern package registry, a multi-core actor runtime, and a standard library designed for real systems.
/03 · Spacing
Layout snaps to the 5px scale. Type can be optical when it needs to be, but spacing should stay boring.
/04 · Edges and shadows
Depth comes from ink borders and solid offsets. Radius is an exception for inputs, not the house shape.
/05 · Layout
The documentation shell uses a persistent left rail, a sticky chapter marker, and a constrained content column. Dense pages stay readable because the grid is predictable.
/06 · Elevation
Elevation is a drawing rule, not atmosphere. Primary surfaces use solid ink offsets. Soft shadows stay out of product UI.
/07 · Code
Diagnostics, commands, package names, paths, and numeric output use the mono channel. Color always means state.
λ riot fmt --check ok 128 files formatted json: {"event":"fmt.checked","files":128}
/08 · Accessibility
The system can be compact because text, borders, focus, and state colors remain legible on every supported surface.
Rules for judgment
These are the rules every Riot surface has to live by: the website, registry, docs, CLI output, README badge, and release notes.
Riot surfaces carry package lists, version matrices, error logs, and dependency trees. Density is respect for an expert reader when hierarchy is clear.
Install, build, test, publish, and debug happen in the terminal. CLI output and copyable commands are first-class design surfaces.
Excellent means the obvious path is polished: first search, first install, first error, first generated doc page, and first copy-pasted example.
Riot can have an edge without becoming noisy. Red is a signal. Structure does most of the talking.
The flag
The lambda ties Riot to ML and functional programming. The flag gives the ecosystem its edge. On cream, the red offset is part of the mark, not a decorative shadow.
Black flag with red offset is the default. On dark surfaces the flag inverts to paper. On red, the offset flips to paper so the silhouette stays crisp.
Built from tokens and type
Components are repeated decisions. Buttons, tables, diagnostics, pills, and callouts use the same token contract documented above.
Square, command-shaped, imperative.
Compact cards for recently published packages.
Datatypes, collections, IO, time, formats, crypto.
↓ 1.2M · todayWeb framework on top of httpaf and the actor runtime.
↓ 98K · 1dCompiler errors are product surfaces.
error[R0087] Type mismatch in fold accumulator ┌─ src/main.ri:42:13 42 │ let total = items |> List.fold (+) "zero" │ ^^^^^^ expected int, found string help: change "zero" to 0
The natural form for registries and version matrices.
| Package | Version | Category | Downloads |
|---|---|---|---|
| std | 0.6.0 | core | 1,247K |
| http | 0.7.1 | net | 840K |
| krasny | 0.2.1 | web | 98K |
Inputs are compact, labeled, and bordered in ink.
Copyable command strips for docs and install flows.
curl -sSL https://get.riot.ml | sh riot add krasny http postgres A dense row for generated docs and registry APIs.
Result.map('a -> 'b) -> ('a, 'e) t -> ('b, 'e) tstablePackage.searchquery:string -> package list promisebetaDocs.renderartifact -> html resultstableA left rule, one label, one useful note.
Use riot fmt. There is one style, and the formatter is part of the product surface.
Module indexes should scan like a map, not a grid of teasers.
Version, date, and exactly what changed.
In the wild
RiotML is declarative. pkgs.ml is table-first. docs.pkgs.ml is long-form reference. The flag and tokens make them feel like one ecosystem.
riot.ml
One tool, a modern package registry, an actor runtime, and a stdlib that ships the common path.
Standard library surface for system work.
published todayCore abstractions shared across Riot.
updated 6h ago| Package | Version | Description | Category | Downloads | Updated |
|---|---|---|---|---|---|
| std | 0.4.0 | Standard library. Datatypes, collections, IO, time, formats. | core | 1,247,890 | today |
| httpaf | 0.7.1 | Fast, low-allocation HTTP/1.1 server and client. | net | 840,221 | 2d |
| kernel | 0.0.18 | Core abstractions shared across the Riot ecosystem. | core | 620,498 | 6h |
| krasny | 0.2.1-rc | Web framework on top of httpaf and the actor runtime. | web | 98,114 | 1d |
module · Kernel.Result
Errors are values. Results carry them through pipelines, actor boundaries, and logs.
type ('a, 'e) t = Ok of 'a | Error of 'e val map : ('a -> 'b) -> ('a, 'e) t -> ('b, 'e) t
let* for chains. Stop nesting binds when the
next step can fail.
CLI
Prompts, aligned labels, diagnostic IDs, and fix commands should work without browser chrome.
λ riot publish --dry-run ok package checked package: krasny version: 0.2.1 next: run riot publish
How we sound
One piece of pirate flavor per page is plenty. The rest is straight engineering: name the function, show the command, explain the tradeoff, move on.
Do
Don't
Error voice
Agent-friendly voice
riot fmt.