Installation

Add the stylesheet and script to your page. Both are served from this site with CORS enabled, so any domain can use them. Everything under /v1/ stays backwards compatible; breaking changes ship as /v2/.

<link rel="stylesheet" href="{{DS_URL}}/ds.css">
<script type="module" src="{{DS_URL}}/ds.js"></script>

Prefer a classic script (no modules)? Use ds.iife.js instead. Both expose the same API on window.DS.

In a Vite app

Keep the URL in an env variable so local development can point at a local copy of the design system:

<!-- index.html -->
<link rel="stylesheet" href="%VITE_DS_URL%/ds.css">
<script type="module" src="%VITE_DS_URL%/ds.js"></script>

# .env
VITE_DS_URL={{DS_URL}}

# .env.localds (vite --mode localds, with the design system running on :5174)
VITE_DS_URL=http://localhost:5174/v1

Starter page

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>My app</title>
    <script>
      // Apply the saved theme before first paint to avoid a flash of the wrong theme.
      try {
        const t = localStorage.getItem('theme');
        if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t;
      } catch {}
    </script>
    <link rel="stylesheet" href="{{DS_URL}}/ds.css">
    <script type="module" src="{{DS_URL}}/ds.js"></script>
  </head>
  <body>
    <main class="container">
      <h1>Hello</h1>
      <button class="btn btn-primary">Get started</button>
    </main>
  </body>
</html>

Theming

Colors are defined with light-dark(), so the whole system follows the OS theme by default. Set data-theme="light" or data-theme="dark" on <html> to force one. Any button with data-theme-value switches and remembers the theme.

To rebrand an app, override tokens after loading ds.css:

:root {
  --accent: light-dark(#7c3aed, #a78bfa);
  --accent-hover: light-dark(#6d28d9, #c4b5fd);
  --accent-soft: light-dark(rgb(124 58 237 / 0.08), rgb(167 139 250 / 0.16));
  --focus: light-dark(rgb(124 58 237 / 0.35), rgb(167 139 250 / 0.5));
  --radius-lg: 12px;
}

Colors

Use tokens, never raw hex values, so components adapt to both themes. Values below update when you switch theme.

Typography

System UI font first (SF Pro on Apple devices), Inter everywhere else. Base size is 14px with a 1.45 line height.

Heading 1 · 32px

Heading 2 · 24px

Heading 3 · 20px

Heading 4 · 17px

Heading 5 · 15px

Heading 6 · 13px

Body text at 14px. Links use the accent color, bold, inline code and ⌘ K.

Hint text: 12px muted, for help under fields.

Token	Size	Use
`--text-xs`	11px	Range labels, menu labels
`--text-sm`	12px	Hints, badges, meta
`--text-md`	13px	Buttons, labels, controls
`--text-base`	14px	Body
`--text-lg`	17px	Card and dialog titles
`--text-xl`	22px	Page titles
`--text-2xl` / `--text-3xl`	28px / 40px	Marketing headings

Spacing

A 4px grid. Use var(--space-*) for padding, margins and gaps.

Radius & elevation

Buttons

Pill-shaped buttons. The default is a tinted secondary button; add a modifier for other styles.

Sizes, icons and states

Link as button

Icon buttons

Square buttons for a single icon. Always give them an aria-label. Use aria-pressed for toggles.

Chips

Small pill buttons for presets and filters. Mark the active one with aria-pressed="true".

Badges

Neutral Accent −42% Beta +8% New Online

Alerts

Inline messages. Add a button with data-ds-dismiss to let people close it.

Heads up

Your images are processed on this device and never uploaded.

12 images converted, 4.2 MB saved.

Storage is almost full. Older history items will be removed.

Conversion failed

This file appears to be damaged.

Cards

Elevated containers. Use .surface alone for a plain panel with your own layout.

photo.webp

1920×1080 · 214 KB

Storage

Saved on this device

64% 320 MB of 500 MB used

Flat card

No shadow, for nesting inside a surface.

Navbar

Sticky, translucent app header. It is position: sticky, so place it as the first child of <body>.

Tabs

Add data-ds-tabs to a role="tablist". Each tab points at its panel with aria-controls. Arrow keys move between tabs.

General settings go here.

Dropdown

A .dropdown with a toggle (data-ds-toggle="dropdown") and a .menu. Closes on outside click, Esc or choosing an item. Use .dropdown-end to align right.

Dialog

Built on the native <dialog> element: focus trapping and Esc come for free. Open with data-ds-open="#id", close with data-ds-close. data-ds-dismissible also closes it on a backdrop click.

The returnValue of the dialog is the value of the data-ds-close button that closed it, so you can listen for close:

const dialog = document.querySelector('#demo-dialog');
dialog.addEventListener('close', () => {
  if (dialog.returnValue === 'confirm') clearHistory();
});

Toast

Short, non-blocking notifications, created from JavaScript.

DS.toast('Saved to history');
DS.toast('12 images converted', { variant: 'success' });
DS.toast('Image removed', {
  duration: 6000,
  action: { label: 'Undo', onClick: () => restore() },
});

Tooltip

CSS only: add data-tooltip. Keep the text short, and don't put essential information only in a tooltip.

Accordion

Native <details>, no JavaScript. Give items the same name to allow only one open at a time.

Are my images uploaded?

No. Everything runs in your browser.

Which formats are supported?

JPEG, PNG, WebP, AVIF, HEIC, TIFF, GIF, BMP, SVG and ICO.

Is there a file size limit?

Only your device's memory.

Progress & loading

40% Done

Table

Wrap in .table-wrap for rounded corners and horizontal scrolling on small screens. Use .num for right-aligned numbers.

File	Format	Before	After	Saved
beach.heic	WebP	3.4 MB	412 KB	−88%
logo.png	AVIF	96 KB	18 KB	−81%
icon.svg	PNG	4 KB	11 KB	+175%

List group

A Account Name, email, password
Save history on this device
Storage used 320 MB

Avatar

FR AL DS A B C

Empty state

No history yet

Converted images will appear here.

Text inputs

Wrap a label and control in .field. Add .input to text, number, email, password, search, select and textarea elements.

Email Longest side px Search

Select & textarea

Format Notes Optional. Max 500 characters.

Validation

Set aria-invalid="true" on the control (or .is-invalid on the field) and add a .field-error message linked with aria-describedby.

Width

Width must be at least 1 px.

Checkbox & radio

Keep metadata Strip color profile Disabled

Keep file name Add suffix

Switch

An iOS-style toggle: a checkbox with .switch, usually inside a .switch-row label.

Lossless Keep aspect ratio

Segmented control

A radio group styled as a single control. Use .segmented-grid (with --cols) to wrap many options.

Range

Native range input. ds.js fills the track as you drag; if you change value from code, call DS.syncRange(input).

Quality80

Smaller fileBetter quality

Color

Background for transparency

Drop zone

Styling for a file drop area. Toggle .is-dragover from your drag events; wire the click to a hidden file input.

Click or drag files here

PNG, JPEG or WebP, up to 50 MB

Scrollbars

Every scrollable area gets a thin, rounded scrollbar that follows the theme: no class needed. The thumb keeps a small gap from the edges, grows on hover and turns accent while dragged. Tune it with --scrollbar-size, --scrollbar-inset, --scrollbar-thumb, --scrollbar-thumb-hover and --scrollbar-thumb-active. Avoid setting scrollbar-width or scrollbar-color yourself: in Chrome that switches the custom style off.

.scroll-y

Scrolls vertically and keeps the scroll inside the box (no scroll chaining to the page).

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante venenatis dapibus posuere velit aliquet.

Cras mattis consectetur purus sit amet fermentum. Donec ullamcorper nulla non metus auctor fringilla.

.scrollbar-track

A slim scrollbar with a visible track and small arrow buttons at both ends. Use it on the main scroll area of a dialog or panel.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante venenatis dapibus posuere velit aliquet.

Cras mattis consectetur purus sit amet fermentum. Donec ullamcorper nulla non metus auctor fringilla.

.scrollbar-hover

The thumb only appears while the pointer is over the box. Good for sidebars and dense panels.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante venenatis dapibus posuere velit aliquet.

Cras mattis consectetur purus sit amet fermentum. Donec ullamcorper nulla non metus auctor fringilla.

Utilities

A small set of helpers. Layout helpers read --gap (and --min for the grid) so you can tune them inline.

Class	Does
`.container`	Centered page width (`--container`) with gutters
`.stack`	Vertical flex with gap
`.cluster`	Wrapping horizontal flex with gap
`.spread`	Horizontal flex, items pushed to both ends
`.grid-auto`	Responsive grid of columns at least `--min` wide
`.grow`	Take remaining space in a flex row
`.surface`	Card background, large radius and shadow
`.text-muted`, `.text-accent`, `.text-success`, `.text-warning`, `.text-danger`	Text colors
`.text-xs` … `.text-xl`, `.fw-medium`, `.fw-semibold`	Text size and weight
`.tabular`, `.mono`, `.truncate`	Tabular numbers, monospace, single-line ellipsis
`.m-0`, `.mt-2`, `.mt-4`, `.mb-2`, `.mb-4`, `.p-4`, `.p-5`	Common spacing
`.scroll-y`, `.scroll-x`	Scroll container that does not chain scrolling to the page
`.scrollbar-track`, `.scrollbar-hover`, `.scrollbar-none`	Scrollbar with a visible track, only on hover, or hidden while keeping scroll
`.checkerboard`	Transparency backdrop for image previews
`.visually-hidden`	Hide visually, keep for screen readers

JavaScript API

ds.js wires up behaviour through data attributes as soon as it loads; content added later works too. For anything else, use window.DS or import from the module:

import { toast, setTheme } from '{{DS_URL}}/ds.js';

setTheme('dark');
toast('Welcome back', { variant: 'success' });

// or, from any script
window.DS.openDialog('#settings');

Function	Description
`DS.setTheme(theme, persist = true)`	`'light'`, `'dark'` or `'system'`. Saved in `localStorage['theme']`.
`DS.getTheme()`	The current theme setting.
`DS.toast(message, options)`	Show a toast. Options: `variant`, `duration` (ms, 0 = sticky), `action`. Returns `{ dismiss }`.
`DS.openDialog(target)` / `DS.closeDialog(target, value)`	Open or close a `<dialog>` by selector or element.
`DS.selectTab(tab)`	Select a tab and show its panel.
`DS.syncRange(input?)`	Refresh the filled track of one range input, or all of them.
`DS.version`	Library version.

Data attributes

Attribute	Effect
`data-theme-value="light\|dark\|system"`	Click switches theme; gets `aria-pressed`.
`data-ds-open="#dialog"`	Click opens that dialog.
`data-ds-close="value"`	Click closes the surrounding dialog with that return value.
`data-ds-dismissible`	On a dialog: close on backdrop click.
`data-ds-dismiss`	Click removes the surrounding `.alert`.
`data-ds-toggle="dropdown"`	Toggle of a `.dropdown`.
`data-ds-tabs`	On a `role="tablist"`: click and keyboard tab switching.

Events

document.addEventListener('ds:themechange', (e) => console.log(e.detail.theme));
document.addEventListener('ds:tabchange', (e) => console.log(e.detail.tab.id));

Basis design system

Installation

In a Vite app

Starter page

Theming

Colors

Typography

Heading 1 · 32px

Heading 2 · 24px

Heading 3 · 20px

Heading 4 · 17px

Heading 5 · 15px

Heading 6 · 13px

Spacing

Radius & elevation

Buttons

Sizes, icons and states

Icon buttons

Chips

Badges

Alerts

Cards

photo.webp

Storage

Flat card

Navbar

Tabs

Dropdown

Dialog

Toast

Tooltip

Accordion

Progress & loading

Table

List group

Avatar

Empty state

Text inputs

Select & textarea

Validation

Checkbox & radio

Switch

Segmented control

Range

Color

Drop zone

Scrollbars

Utilities

JavaScript API

Data attributes

Events