@mosaic-argos/tokens
v0.5.0
Published
Argos design tokens — colors, type, spacing, radii, shadows as Tailwind v4 @theme
Readme
@mosaic-argos/tokens
Design tokens for Argos — colors, typography, spacing, radii, and motion, expressed as Tailwind v4 @theme variables.
Install
pnpm add @mosaic-argos/tokensUse
Import Tailwind first, then Argos tokens, in your app's global stylesheet:
@import "tailwindcss";
@import "@mosaic-argos/tokens/styles.css";This adds the Argos @theme variables and base resets on top of Tailwind CSS v4. Utilities like bg-bg, text-fg, border-border, rounded-md, text-sm are now available.
Fonts
Argos uses two Google Fonts — Hanken Grotesk (the one sans: UI at 400–600, display moments at 700–800) and IBM Plex Mono (data and code). The tokens reference them by name but load nothing themselves; add this <link> to your app's HTML <head>:
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400;500;600;700;800&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet" />Next.js apps can instead bind next/font/google — Hanken Grotesk to --font-sans-next and --font-display-next, IBM Plex Mono to --font-mono-next.
Theme
Argos is light-first. To opt into dark mode, add class="dark" to <html>:
<html lang="en" className="dark">Token surfaces
| Kind | Example tokens |
| --- | --- |
| Surfaces | bg, bg-subtle, surface, surface-hover, surface-active |
| Text | fg, fg-muted, fg-subtle, fg-disabled |
| Borders | border-subtle, border, border-strong |
| Brand | primary, primary-hover, primary-fg, primary-subtle, ring |
| Status | success, warning, danger, info (each with -fg and -subtle) |
| Neutral scale | neutral-1 … neutral-12 (12-step Radix-style) |
| Accent scale | accent-1 … accent-12 |
Scale convention
Argos uses a 12-step perceptual scale (Radix UI Colors-inspired) — with one Ledger twist: surfaces sit above the page, so step 1 is the card and step 2 is the page wash:
| Step | Purpose | | --- | --- | | 1 | Card surface (white) | | 2 | Page wash | | 3 | Insets, table heads, soft tints | | 4 | Deeper inset / hovered UI element background | | 5 | Active / selected UI element background | | 6 | Subtle borders — the hairline | | 7 | UI element borders | | 8 | Hovered / strong borders | | 9 | Solid backgrounds (primary buttons — the azure) | | 10 | Hovered solid backgrounds | | 11 | Low-contrast text | | 12 | High-contrast text — the navy ink |
The same relationships hold in dark mode — hand-translated onto navy-dark surfaces.
Customizing
To tune the visual direction, edit src/theme.css in this package. Every component in @mosaic-argos/ui reads from these variables — no other files need to change.
