@hugocxl/design-system DESIGN.md Source

@hugocxl/design-system

My signature, across every project I make

This is how my projects look and read. Large reading type leads every page, line vectors and rounded icons give it an engineered feel, and one orange accent appears at most twice. This page is the complete definition: every token, component and rule a person or an agent needs to build a site with the system is here, and nothing outside it is part of the system.

Read the principles, then color, type, space and layout. Build with the components, icons and vectors and page recipes, check the rules, and brief an agent or install the files.

Product launchAn open interface panel is suspended above a crate with loose lid, with two dashed guides marking its position.
Fig. 01 / Product launch

Principles

  1. 01

    Text leads

    Reading type is 21 px at desktop widths and carries the page. Nothing is set larger than the title.

  2. 02

    Figures explain

    Vectors from @hugocxl/vectors show the subject, and icons from @hugocxl/icons label actions. Neither is ever decoration.

  3. 03

    One accent

    Orange marks at most two things on a page: one phrase in the statement and one status dot. Hues and status colors mark only icons and dots.

  4. 04

    Closed vocabulary

    Pages use the thirteen components below in a recipe’s order. Anything else is a proposal, not part of the system.

  5. 05

    Every rule is checkable

    Each value is a token, and each token is checked in a browser test.

Color

The paper and the orange come from Superlogical. The ink and greys are neutral, with no tint. Muted text is dark enough for supporting copy to meet WCAG AA. Superlogical’s lighter grey survives as faint, for placeholders only.

TokenLightDarkUse
canvas#f5f5f4#111111Page background
ink#171717#edededText, filled button
muted#6e6e6e#7d7d7dByline, headings, labels, supporting text
faint#b3b3b3#737373Placeholder text only
rule#1717171f#ededed24Hairlines, borders
surface#ebebea#1c1c1cMedia and code backgrounds
accent#fe9369#fe9369Status dot
accent-text#ce7755#fe9369One phrase at title size

Use the accent at most twice per page: once as .ds-accent on the last two or three words of the statement, and once as the .ds-dot before a status label. On paper the orange reaches 3:1 only at title size, so it never colors body text, links, buttons, backgrounds or rules.

Hues

Eleven hues color marks: colored icons and status dots, never text or fills. They take after the diffs.com icon palette. The dark values are the reference’s own, with violet and purple lifted for contrast. The light values are deeper versions of the same hues. Each one reaches 3:1 on the canvas and the surface in its theme.

HueLightDarkFor example
red#c43d3d#c43d3dnpm, Ruby, YAML, errors
orange#bb702f#c77b3bHTML, Rust, Swift, RSS
yellow#a08005#ceab3cJavaScript, folders, archives
green#419445#4b9d4eShell, tables, Vue
teal#378f99#4da3adPrettier, formatters
sky#388cb0#4c9fc3Go, React, servers
blue#3f83ce#3f83ceTypeScript, C, Docker, code
violet#633cc7#7350dcCSS, ESLint, WebAssembly
purple#993ab8#9e3fbdVite, Astro, fonts, MCP
pink#c23b62#c23b62GraphQL, Sass, images
brown#8f6d53#8f6d53Bun

A hue names a kind of thing, the same one everywhere: a language, a tool, a file type or a brand. Grey is not a hue, because an uncolored icon takes the text color. The hues are not the accent and don’t count toward its budget.

Status

Five roles give a hue a meaning. Set data-status on a .ds-dot, a .ds-icon or the form feedback and it takes the role’s color. A dot without data-status stays the accent, for the page’s own status such as Beta.

RoleHueLightDarkMeans
successgreen#419445#4b9d4eDone, live, passing
warningyellow#a08005#ceab3cNeeds attention soon
errorred#c43d3d#c43d3dFailed, down, invalid
infoblue#3f83ce#3f83ceScheduled, planned
neutralmuted#6e6e6e#7d7d7dDraft, paused, archived
  • Operational
  • Degraded
  • Down
  • Scheduled
  • Paused
  • Passing
  • Expiring
  • Failed
  • Maintenance
<li class="ds-label"><span class="ds-dot" data-status="success" aria-hidden="true"></span>Operational</li>
<li class="ds-label"><svg class="ds-icon" data-icon="circle-x" data-status="error" …>…</svg>Failed</li>
  • The words always name the status. The dot or icon goes before them, and color never says it alone.
  • Only the mark takes the color. Status text stays ink, or muted where the component already uses it.
  • Use one mark per status, a dot or an icon, in a meta label, an index label, a table cell or the form feedback.

Type

Geist Sans for everything people read and Geist Mono for labels, dates and code. Both are bundled. There are six styles and three weights: 300 for reading, 400 for headings and controls, 500 for the title and emphasis. The wordmark alone uses 600.

  1. Title

    Public testing is beginning

    1.4 × reading · 500 · 1.15 · −0.02em

  2. Reading

    Text leads the composition, and figures follow it.

    min(1rem + 0.36vw, 1.54rem) · 300 · 1.3 · −0.01em

  3. Heading

    What is available

    Reading size · 400 · muted

  4. Small

    Captions for grid items and table cells.

    0.8 × reading · 300 · 1.4

  5. Label

    5 October 2026

    Mono 13px · 400 · 0.08em · uppercase

  6. Mono

    Press kit

    Mono 15px · 400 · footer links

Space

Ten steps. Every margin, padding and gap uses one of them. The named roles are the ones you reach for most.

TokenValueRoleScale
space-14px
space-28pxList items, label gaps
space-312pxCaption offset, cell padding
space-416pxHeading to text
space-520pxParagraph
space-632pxTitle to meta, grid gutter
space-740pxSection
space-856pxWide figure, meta to lead
space-980pxFooter
space-10128pxOpening, maximum

Radii are 6px for controls and code, 12px for media and the field, and a full pill for the pager. Every interactive target is at least 44px. Nothing has a shadow.

Layout

Every page uses plain, centered, unless it is a personal home page. Set the layout with data-layout on the body. Text sits in a 30em column, about 65 characters. Wide figures and grids extend to 80rem.

Components

Thirteen components make up the whole vocabulary. Each one is shown live with its exact markup. Copy the markup, change only the text, links and vector and icon names, and keep every class and attribute.

masthead

Wordmark, up to three text links, and the theme button. It is always the first element in the body.

title

The page name in ink with a muted byline beneath it. Use it on every page except home.

Public testing is beginning

Fieldwork team

statement

One sentence for the home page, at title size. It may end with a single accent phrase of two or three words.

Field notes for teams that ship every day.

meta

One to three mono labels under the title: date, version, status. Only a status label takes the dot.

  • Beta

section

A muted heading followed by paragraphs, lists, code or table. The first section after the title has no heading and acts as the lead.

What is available

Initially, testing is limited to the macOS application. Linux and Windows follow once the first wave is stable.

Read the documentation for setup.

figure-wide

One vector or screenshot on the surface at 3:2, with a mono caption. A pager is added only when the figure cycles. The opening figure on this page is the live example.

How it worksA stepped gauge, a stamping press, and a notched sample block occupy consecutive stations.
Fig. 01 / How it works

figure-grid

Two to four vectors side by side, divided by hairlines, each with a figure label, a short title and one sentence. It stacks below 34rem.

  • Fig 0.1 Modular designFour independent modules fit into one assembly.

    Purpose-built

    Shaped by the practices of teams who ship daily.

  • Fig 0.2 HandoffA document travels between two stations.

    Shared by people and agents

    From the first draft to the merged change.

  • Fig 0.3 Fast performanceA tightly spaced pulse rises through a bank of thin fins.

    Designed for speed

    Less noise, more momentum, every release.

index

Numbered or dated rows divided by hairlines, for changelogs, steps, plans and principles. The label is a number, a date or a price.

  1. Persistent sessions

    Sessions survive restarts and reconnect where you left them.

  2. Remote hosts

    Connect to any machine running the server.

table

Comparisons and specifications. Mono column headings, row headings in ink, hairline rows, tabular figures.

PlanPriceHosts
PersonalFree3
Team€12 per seat / monthUnlimited

button

The one filled action on a page. Use an anchor for navigation and a button for an action. Every other action is an underlined text link.

form

A visible label, an underlined input with an icon submit, help text and a live feedback line. Entered values are kept when validation fails. On an error or a success, data-status on the feedback puts a status dot before its sentence.

We’ll let you know when the beta is available.

code

A command or snippet on the surface, with a Copy button.

brew install fieldwork

Icons and vectors

Pages draw with two companion libraries and nothing else. @hugocxl/icons label actions, and @hugocxl/vectors illustrate ideas. Both draw in the color of the text around them, so they follow the theme and leave the accent alone. No other icon set, illustration, emoji or symbol character may stand in for them.

npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors

@hugocxl/icons

Use the Stroke style. An icon either goes before the words of a link, the button or a meta label, or it is the whole content of an icon button with an aria-label. Give the SVG class="ds-icon" and data-icon with its name. It takes the size and color of its text and keeps a small gap before the words.

Read the icon guide

Browse icons

  • Version 0.2
<!-- Before words: a link, the button or a meta label -->
<a href="/docs"><svg class="ds-icon" data-icon="book-open" viewBox="0 0 16 16" fill="none" aria-hidden="true">…</svg>Read the guide</a>

<!-- Alone: an icon button names itself with aria-label -->
<button class="ds-theme" type="button" data-ds-theme aria-label="Switch theme"><svg class="ds-icon" data-icon="contrast" …>…</svg></button>

// React
import { BookOpenIcon } from '@hugocxl/icons/react/stroke';
<a href="/docs"><BookOpenIcon className="ds-icon" />Read the guide</a>
PlaceIcon
Theme buttoncontrast
Pagerarrow-left, arrow-right
Form submitcorner-down-left to send, arrow-right to go
Searchsearch
External linkarrow-up-right
  • One icon per element. Before words it never replaces a word; alone it needs an aria-label.
  • Use icons in links, the button, meta labels and icon buttons, plus colored icons in index labels and table cells. Keep them out of headings, the statement, body sentences and the footer.
  • Hide icons from assistive technology with aria-hidden="true". The React components do this unless they receive an aria-label.
  • Never color an icon with the accent, and never draw arrows, ◐ or other symbols as text instead.

Colored icons

An icon takes a color only when the color means something. data-color with a hue marks what an item is, and data-status with a role marks its state. Use the hue the icon library assigns, so the same thing has the same color everywhere. Colored icons label items in lists, index labels and table cells, in the Stroke or Duotone style.

NameKindChecks
componentsFolderPassing
install.shShell scriptTwo warnings
index.tsTypeScriptFailed
<!-- Kind: what the item is -->
<th scope="row"><svg class="ds-icon" data-icon="folder" data-color="yellow" viewBox="0 0 16 16" fill="none" aria-hidden="true">…</svg>components</th>

<!-- Status: the state, named by the words after it -->
<td><svg class="ds-icon" data-icon="circle-check" data-status="success" viewBox="0 0 16 16" fill="none" aria-hidden="true">…</svg>Passing</td>
  • Action icons in links, the button and icon buttons are never colored. They take the text color.
  • Use one color per icon, from the tokens: never a hex value, a gradient or the accent.
  • The words beside a colored icon always say what it means.

@hugocxl/vectors

Every figure is a vector. It fills figure-wide and each figure-grid item, drawn in ink on the surface at its own 4:3 proportions. Inline the SVG from the package, replace its root xmlns with class="ds-vector" and data-vector with its name, and remove its color attribute.

Modular designFour independent modules fit into one assembly.
Fig. 02 / Modular design
<figure class="ds-wide">
  <div class="ds-media"><svg class="ds-vector" data-vector="modular-design" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" …><title>Modular design</title><desc>…</desc>…</svg></div>
  <figcaption class="ds-caption"><span class="ds-label">Fig. 02 / Modular design</span></figcaption>
</figure>

// React
import { ModularDesignVector } from '@hugocxl/vectors/react/modular-design';
<div className="ds-media"><ModularDesignVector className="ds-vector" /></div>
  • Choose a vector for what it means. The vectors browser lists all 2,000 by use case. Name it in the caption.
  • Keep the SVG’s title and desc: they are its accessible name.
  • Use screenshots as <img> only when the subject is the product itself.
  • Never crop a vector, color it with the accent or place it on the field.
  • Use the field layout only on a personal home page.

Page recipes

A recipe fixes the layout and the order of components. ? means optional, + one or more, * zero or more and | one of. Leave out an optional component when the brief has no content for it.

RecipeLayoutSequence
homeplain (field on a personal site)masthead statement meta? section (figure-wide | figure-grid) section* (button | form)? footer
articleplainmasthead title meta section figure-wide? section+ form? footer
docsplainmasthead title meta? section (section | figure-wide)* footer
changelogplainmasthead title section? index footer
pricingplainmasthead title section index table? section* button footer
contactplainmasthead title section form footer

The example below is a complete home page built only from the components above. Use it as the reference output: a generated home page should differ from it only in its words, links and figure names.

Fieldwork Changelog Docs

Field notes for teams that ship every day.

  • Beta
  • Version 0.9

Fieldwork turns every deploy into a short note your team can read in a minute. It reads the diff, the tests and the incident channel, then writes what changed and why.

  • Fig 0.1Version controlA branch leaves the main track and rejoins it downstream.

    Reads the diff

    Every merged change, summarised in a sentence.

  • Fig 0.2MonitoringThree offset traces show a pulse across a bank of channels.

    Watches the release

    Errors and latency beside the note.

  • Fig 0.3ChangelogA folded sheet sits in front of and above a notched selector wheel.

    Keeps the record

    A searchable history of every deploy.

How it works

Connect a repository and a deploy target. The first note arrives with your next release.

Rules

These hold on every page. A result that breaks one is wrong, whatever else it gets right.

Always

  • Load system/ds.css, system/theme.js in the head and system/ds.js as a module.
  • Set class="ds" and data-layout on the body, as the recipe specifies.
  • Follow the recipe’s component order. Copy component markup exactly and change only text, links, vector and icon names and IDs.
  • Write in sentence case. Keep the title to one line and the statement to one sentence.
  • Use the muted color for supporting sentences, inline after the main thought. Text on the surface is always ink.
  • Keep every vector’s title, give every icon button an aria-label and every field a visible label.
  • Check the page at 320, 760, 761 and 1440px wide in both themes.

Never

  • Never add a class, color, font, size, weight, radius or spacing value that is not a token.
  • Never use the accent more than twice, on body text, links, buttons, backgrounds or rules.
  • Never use a hue or status color on anything but an icon or a dot, or let color alone say what something is or what state it is in.
  • Never set text larger than the title or bolder than 500 (the wordmark is the exception).
  • Never use shadows, gradients, emoji, stock photography, symbol characters as icons, or icons and illustrations from outside @hugocxl/icons and @hugocxl/vectors.
  • Never place two filled buttons on one page.
  • Never center text other than the column itself, and never justify it.
  • Never invent copy, links, numbers, quotes or logos the brief does not supply.

Agent handoff

Give the agent this page and a page plan. Point it at DESIGN.md, which repeats this page in Markdown, at a pinned commit. Write the plan as JSON that validates against plan.schema.json. It names the recipe and lists the blocks in order with their copy.

{
  "designRevision": "<design-system commit SHA>",
  "recipe": "changelog",
  "layout": "plain",
  "blocks": [
    { "component": "masthead", "wordmark": "Fieldwork", "links": [{ "label": "Docs", "href": "/docs" }] },
    { "component": "title", "heading": "Changelog", "byline": "What shipped, newest first" },
    { "component": "index", "items": [
      { "label": "12 Nov 2026", "title": "Persistent sessions", "text": "Sessions survive restarts." }
    ] },
    { "component": "footer", "start": [{ "label": "Press kit", "href": "/press" }], "end": [] }
  ]
}

Make the build repeatable. The same prompt can produce different output, so keep the model’s freedom in the plan, not in the markup. Validate the plan against the schema and check that it follows the recipe. Then render each block by copying its component markup. The same plan and revision always give the same page.

Verify the result. Run the browser tests: computed tokens, column and figure widths, keyboard use, both themes and an axe WCAG 2.2 AA scan. To compare screenshots, fix the browser, viewport, scale, theme, locale and motion settings, and wait for fonts and figures.

Install

Install the package, or copy its system/ folder into the site. Fonts, the field texture and the theme script travel together, with ready-made entries for Tailwind, CSS, Sass and JavaScript. Install @hugocxl/icons and @hugocxl/vectors beside it.

npm install @hugocxl/design-system

Serve the folder with the site and add these lines. With a bundler, import @hugocxl/design-system/ds.css, /theme.js and /ds.js instead.

<link rel="stylesheet" href="system/ds.css">
<script src="system/theme.js"></script>
<script type="module" src="system/ds.js"></script>

Use it in any project. The package also ships the tokens on their own, generated from the stylesheet so they never drift. Pick the entry that fits the project. Every value is a --ds-* custom property, so light and dark keep working.

ProjectImport
Tailwind v4@hugocxl/design-system/tailwind
Tailwind v3@hugocxl/design-system/tailwind-preset and /tokens.css
Plain CSS@hugocxl/design-system/tokens.css and /fonts.css
Sasspkg:@hugocxl/design-system/scss
JavaScript@hugocxl/design-system/tokens or /tokens.json

Tailwind v4 gets the fonts, the tokens and a dark variant tied to the theme, as utilities like bg-canvas, text-ink, text-reading, p-space-5, rounded-media and max-w-measure.

/* app.css */
@import "tailwindcss";
@import "@hugocxl/design-system/tailwind";

Tailwind v3 takes the preset, with the tokens loaded once in the CSS.

// tailwind.config.js
module.exports = {
  presets: [require("@hugocxl/design-system/tailwind-preset")],
};

/* app.css, through your bundler or postcss-import */
@import "@hugocxl/design-system/tokens.css";
@import "@hugocxl/design-system/fonts.css";

Sass maps each token to a variable; load tokens.css once for the values. JavaScript gets the raw values for charts, canvas and native apps.

@use "pkg:@hugocxl/design-system/scss" as ds;
.card { padding: ds.$ds-space-5; color: ds.$ds-ink; }

// JavaScript
import { tokens } from "@hugocxl/design-system/tokens";
tokens.color.dark.canvas; // "#111111"

Before shipping, complete the main task with a keyboard and check reflow at 320px, text zoom at 200%, reduced motion and both themes.