@kosko-app/design-tokens

Kosko's design system, for every repository that draws Kosko UI:

• TOKENS (@kosko-app/design-tokens): every colour role resolved to a literal, per surface (app, popup) and theme (light, dark), plus the scale (spacing, type, radius, icon sizes) and the fixed document / content colours. Deep-frozen.
• tokens.css (@kosko-app/design-tokens/tokens.css): the same roles as CSS custom properties, light and dark (prefers-color-scheme, with an explicit data-theme="light|dark" on :root winning).
• tokens.json: the resolved values as JSON, for a consumer that is not JavaScript.
• ICONS / ICON_PROFILES (@kosko-app/design-tokens/icons): every glyph by meaning (note, trash, move-to-notebook, …) as [[tag, attrs], …] on a 24 grid, and how each platform strokes it. Each glyph is also a standalone SVG: @kosko-app/design-tokens/icons/<meaning>.svg.

Every file under generated/ is produced from design/ in the content-vault repository by npm run tokens and npm run icons. Do not patch it: a change is an edit to design/ there, then a package release.

Use

import { TOKENS } from '@kosko-app/design-tokens';
const accent = TOKENS.app.light.acc;

@import '@kosko-app/design-tokens/tokens.css';
.button { background: var(--acc); color: var(--on-acc); padding: var(--space-2) var(--space-3); }

Pin it exactly ("@kosko-app/design-tokens": "0.1.0", never a range): a design change reaches a consumer only when that consumer bumps the pin.

The design-system check

kosko-ds-check keeps raw colours, font names, typed sizes and hand-drawn icons out of a repo's UI code. Describe the repo in a kosko-ds.config.json at its root:

{
  "channels": { "cli": { "dirs": ["src", "bin"], "extensions": [".mjs", ".html"], "platform": "web" } },
  "exempt": [{ "path": "src/vendor.mjs", "reason": "third-party code keeps its own look" }],
  "baseline": "design/system-baseline.json"
}

then run kosko-ds-check (the whole tree) or kosko-ds-check src/page.mjs (some files). Exit 0: clean. Exit 1: every new violation, with file, line, the literal and the token to use. Exit 2: a config or usage error. platform: "native" gives React Native rules and hints. The same check is importable from @kosko-app/design-tokens/check (loadConfig, createCheck, runGate).

Releases

Published from content-vault by GitHub Actions through npm's trusted publishing, staged and approved by the owner with 2FA. No provenance attestation: the source repository is private.

Requirements

Node 22 or later, ES modules. No runtime dependencies.

Licence

Apache-2.0. The utility glyphs are drawn by lucide (ISC); their notice is in generated/LICENSE-lucide.txt.