JK Tools Design System

A shared, no-build design layer for the tools in this repo — a baseline set of design tokens plus a hand-authored component library. Pure vanilla CSS: no framework, no bundler, no dependencies. Works in both the vanilla-JS tools and the CDN-React tool.

This folder is shared infrastructure, not a tool. It is excluded from the generated landing page (see IGNORE_DIRS in build.js).

Files

File	Purpose
`tokens.css`	CSS custom properties (colors, spacing, radii, shadows, typography). Colors are stored as HSL channel triplets so translucency composes via `hsl(var(--token) / .9)`. Light/dark/system theming.
`components.css`	Class-based components: button, input/textarea/select, field, switch, card, badge, table, tabs, dialog, toast, plus utilities. Requires `tokens.css`.
`index.html`	A living gallery of every token and component, with a light/dark toggle. Open it in a browser as the reference.

Usage

From a tool folder one level below the repo root:

<link rel="stylesheet" href="../design-system/tokens.css">
<link rel="stylesheet" href="../design-system/components.css">

Then use the component classes:

<button class="btn">Primary</button>
<button class="btn btn-outline btn-sm">Secondary action</button>
<span class="badge badge-success">Published</span>

<label class="field">
  <span>Handle</span>
  <input type="text" placeholder="you.bsky.social">
</label>

<div class="card card-padded"> … </div>

Theming

The theme is driven by the data-theme attribute on <html>:

data-theme="light" / data-theme="dark" — forced.
No attribute, or data-theme="system" — follows the OS via prefers-color-scheme.

Tools that resolve the theme in JS (e.g. a System/Light/Dark setting) should set data-theme to the resolved light/dark value.

Conventions

Don't redefine component styles in a tool. Tool stylesheets should only add app-specific layout (page header, grids, bespoke cards) and should reference tokens via hsl(var(--token)) so they track the theme.
Component classes are global. Keep names stable; if a tool needs a one-off, prefer a tool-scoped class over overriding a .btn/.card rule.
No emoji or decorative symbols in tool UI. Keep labels textual (e.g. "Refresh Feeds", "Open tool", "Saved") rather than ↻/↗/✓/📡. Functional navigation glyphs are fine where they read as controls — ← for back and × for close. For anything pictorial, use an inline SVG icon, not an emoji.
Consistent header. Every tool and README page uses the same .tool-header (← Back · centered title · action) so moving between a tool and its docs feels continuous.
Adopting a new component? Add it to components.css and showcase it in index.html so the gallery stays complete.

Status

Early/prototype. Pilot adopter: syndicate-elsewhere. Not yet rolled out to audiolog-episode-creator or other tools.