Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 63 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ installs it back.
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src/ui/` | Desktop's primitives, on `@base-ui/react`: button, dialog, menus, select, tooltip, popover, segmented, switch, slider, command, colour picker… |
| `src/components/` | Components only the old `standards` gallery had (avatar, toast, table, tag, sheet, tabs…, plus `patterns/`, `blocks/` and `shell/`), restyled to desktop's language. |
| `src/styles/` | `styles.css` (the entry), `tokens.css`, `utilities.css`, and the generated `themes.css` |
| `src/styles/` | `styles.css` (the entry), `styles-core.css` (the entry minus themes), `tokens.css`, `utilities.css`, and the generated `themes.css` |
| `src/theme/` | The theme engine's pure half: the resolver, the colour maths, the generated key registry |
| `src/ratchet/` | The design-system ratchet, as rules and a runner |
| `keys.toml` | **The one hand-edited source of every derived colour** |
Expand Down Expand Up @@ -53,8 +53,10 @@ Without a provider, links are plain `<a href>` and nothing is "active".
".": "components, lib helpers (cn, motion, LinkProvider…)",
"./variants": "the server-safe subset: the cva recipes (buttonVariants…), Icon, cn",
"./styles.css": "the stylesheet",
"./styles-core.css": "the stylesheet without the built-in theme blocks, for an app that applies themes itself",
"./theme": "resolveTheme, resolveBase, themeFromToml, the registry, colour utils",
"./ratchet": "runRatchet, formatViolations, RULES, ATLAS_PREFIX_RULE",
"./ratchet": "runRatchet, formatViolations, RULES, ATLAS_PREFIX_RULE, TRANSITION_ALL_RULE",
"./animations": "INFINITE_ANIMATIONS, INFINITE_ANIMATION_FPS_VAR, infiniteAnimationFps (no React, no DOM at import)",
"./timeline-calendar": "TimelineCalendar, which needs @tanstack/react-virtual",
"./keys.toml": "the derivation source",
"./themes/*": "the built-in theme files, e.g. ./themes/dracula.toml",
Expand Down Expand Up @@ -139,8 +141,11 @@ them through `utilities.css`, so you write `bg-element-hover`, never the
variable. A test fails if two names would write the same variable.

The palette's eight hues are identities (a label, a project), not
statuses, and reach Tailwind as `bg-hue-red`, `text-hue-blue`… through the
key that is a plain alias of each hue, plus `hue-grey` for no hue.
statuses, and reach Tailwind as `bg-hue-red`, `text-hue-blue`… through
their own keys, `hue.red` … `hue.pink`, plus `hue-grey` (the theme's
`muted-foreground`) for no hue. Each key derives from the palette hue of the
same name, so an "orange" chip is the theme's orange; a theme that wants its
chips to differ from its palette sets the key.

To change a rule or a built-in theme, edit `keys.toml` or `themes/`, run
`bun run theme`, and commit what it writes. `bun run theme:check` (and the
Expand All @@ -161,6 +166,14 @@ brings Geist and Geist Mono (via `@fontsource-variable`, so they work
offline in Tauri) and an `@source` for the package's compiled files, so your
Tailwind keeps the classes only the package uses.

An app that applies themes itself — resolving a theme with `resolveTheme`
and writing its `cssVars` onto `<html>`, as desktop does — imports
`@tryatlas/design/styles-core.css` instead. It is `styles.css` without
`themes.css`: the same tokens, utilities, fonts and `@source`, minus the
`[data-theme][data-appearance]` blocks, which are most of the bytes and never
match in such an app. Nothing in it gives a theme variable a value, so apply a
theme before first paint.

- **Desktop** imports components and styles from the package and pins an
exact version. `bun run theme:keys` copies `keys.toml`, the built-in themes
and the Rust tables from `node_modules` into `crates/atlas-theme/`, so the
Expand All @@ -173,19 +186,44 @@ Tailwind keeps the classes only the package uses.
The ratchet, from any consumer's tests:

```ts
import { formatViolations, runRatchet } from "@tryatlas/design/ratchet";
import { TRANSITION_ALL_RULE, formatViolations, runRatchet } from "@tryatlas/design/ratchet";

it("holds the design system at zero", () => {
const violations = runRatchet({
roots: ["src/features", "src/components"],
exemptFiles: {
"src/brand.tsx": "Shape 2. A third party's logo; a recoloured logo is wrong.",
},
// Optional: rules of your own, each { id, pattern (/g), instead, scope? }.
// `scope` replaces `roots` for that rule (directories or single files, read
// whatever `include` says), and a rule with a built-in's id replaces it.
rules: [{ ...TRANSITION_ALL_RULE, scope: ["src", "index.html"] }],
});
expect(violations, formatViolations(violations)).toEqual([]);
});
```

Exemptions and `ratchet-allow:` markers apply to a consumer's rules as to the
built-in ones.

### Endless animations

`@tryatlas/design/animations` lists every animation in the package that
never stops (`INFINITE_ANIMATIONS`), for an app that has to cap them — desktop
does on Linux, where WebKitGTK presents a frame per tick. A `css` entry gives
the `selector` to override and a `steps` count near 12 fps; a `js` entry (the
marquee, the globe's turn, the dither field) reads `--infinite-animation-fps`
when it starts:

```css
html.platform-linux {
--infinite-animation-fps: 12;
}
html.platform-linux [data-slot="globe-live-dot"] {
animation-timing-function: steps(24);
}
```

## Migrating from standards

The package replaced the old `standards` gallery (its last commit is
Expand Down Expand Up @@ -274,12 +312,31 @@ foundations page).
- The package sets no root font size; desktop and web both use 13px, so `rem`
spacing matches between them.

### Upgrading to 0.1.4

- **Identity hues are theme keys.** `hue.red` … `hue.pink` (variables
`--hue-red` … `--hue-pink`) are new, in a new "Identity hues" group, each
derived from the palette hue of its name. `--color-hue-*` reads them instead
of `syntax.number`, `syntax.escape` and the ANSI slots, so `orange` and
`pink` chips change colour in every theme whose syntax colours differ from
its palette (Atlas, Dracula, Mirage, Monokai, One Dark, Rosé Pine, Tokyo
Night, Vesper). The Atlas and Mirage palettes' `pink` is now a pink. A
consumer that copies the generated files (desktop's `bun run theme:keys`)
re-copies them; there is no fallback for themes written before the keys
existed, which simply derive them.
- **`styles-core.css`** is new; `styles.css` is unchanged.
- **The ratchet bans `transition-all`** (and `transition: all`) by default,
as rule `transition-all`. `runRatchet` takes `rules`, and
`TRANSITION_ALL_RULE` is exported to widen its scope.
- **`@tryatlas/design/animations`** is new. `SessionPipeline`'s running
spinner and `Globe`'s ping rings and live dot gained `data-slot`s for it.

## Installing

Until the `@tryatlas` npm scope is set up, install from a git tag:

```bash
bun add github:tryatlas/design#v0.1.3
bun add github:tryatlas/design#v0.1.4
```

Bun does not run a git dependency's build, so **a release tag carries the
Expand Down
16 changes: 16 additions & 0 deletions fixtures/consumer/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,12 @@ const toml = readFileSync(require.resolve("@tryatlas/design/themes/dracula.toml"
const resolved = theme.resolveTheme(theme.themeFromToml(parse(toml)), "dark");
assert.ok(resolved.cssVars["--element-hover"], "theme keys resolve to unprefixed variables");
assert.equal(typeof ratchet.runRatchet, "function");
assert.equal(ratchet.TRANSITION_ALL_RULE.id, "transition-all");

// The endless-animation list, importable without React or a DOM.
const animations = await import("@tryatlas/design/animations");
assert.ok(animations.INFINITE_ANIMATIONS.length > 0, "the endless animations are listed");
assert.equal(animations.INFINITE_ANIMATION_FPS_VAR, "--infinite-animation-fps");

for (const file of ["keys.toml", "theme-rules/theme-keys.txt", "theme-rules/base-rules.txt"]) {
assert.ok(readFileSync(require.resolve(`@tryatlas/design/${file}`), "utf8").length > 0, file);
Expand All @@ -64,4 +70,14 @@ assert.ok(
);
assert.ok(css.includes("Geist Variable"), "Geist is the sans face");

// The theme-less entry: the same package classes and fonts, no theme blocks.
const core = readFileSync("out/app-core.css", "utf8");
assert.ok(
core.includes(".aria-pressed\\:bg-element-selected"),
"package classes survive the consumer's build from styles-core.css",
);
assert.ok(core.includes("Geist Variable"), "styles-core.css brings Geist");
assert.ok(!core.includes("[data-theme="), "styles-core.css carries no theme blocks");
assert.ok(core.length < css.length / 2, "styles-core.css is the smaller entry");

console.log("consumer fixture: ok");
2 changes: 1 addition & 1 deletion fixtures/consumer/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"private": true,
"type": "module",
"scripts": {
"check": "tailwindcss -i src/app.css -o out/app.css && node check.mjs"
"check": "tailwindcss -i src/app.css -o out/app.css && tailwindcss -i src/app-core.css -o out/app-core.css && node check.mjs"
},
"dependencies": {
"@base-ui/react": "1.8.0",
Expand Down
4 changes: 4 additions & 0 deletions fixtures/consumer/src/app-core.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/* The same consumer on the theme-less entry, as desktop imports it: it applies
themes itself, so the built-in theme blocks must not be here. */
@import "tailwindcss" source("./");
@import "@tryatlas/design/styles-core.css";
82 changes: 82 additions & 0 deletions keys.toml
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,10 @@ description = "Added and removed regions, inline and side-by-side."
name = "Agents and indicators"
description = "The agent identity chip."

[[group]]
name = "Identity hues"
description = "The eight hues that name a thing — a label, a project dot — never a status."


# ── Borders ───────────────────────────────────────────────────────────────────

Expand Down Expand Up @@ -1131,6 +1135,84 @@ dark = "rgba(255,255,255,0.06)"
light = "rgba(0,0,0,0.06)"


# ── Identity hues ─────────────────────────────────────────────────────────────
#
# The `--color-hue-*` utilities (`bg-hue-orange`, `Tag`, `HueDot`) read these.
# They used to borrow other roles — orange was `syntax.number`, pink was
# `syntax.escape`, the rest the ANSI slots — and a theme that coloured those
# roles for code (Atlas's own syntax is Pierre's, where numbers are cyan) turned
# an "orange" label cyan. A hue now reads the theme's own palette hue of the same
# name, so it is whatever that theme means by orange, and a theme that wants a
# different chip colour from its palette sets the key. The defaults, for a
# theme that writes no palette, are the Atlas theme's palette — except dark
# yellow, where Atlas's palette has a terminal's pure #ffff00 and a label wants
# the softer yellow the ANSI default uses.

[[key]]
name = "hue.red"
group = "Identity hues"
description = "The red identity hue: labels, project dots, meters."
palette = "red"
dark = "#f44747"
light = "#c62828"

[[key]]
name = "hue.orange"
group = "Identity hues"
description = "The orange identity hue: labels, project dots, meters."
palette = "orange"
dark = "#e0b070"
light = "#b06000"

[[key]]
name = "hue.yellow"
group = "Identity hues"
description = "The yellow identity hue: labels, project dots, meters."
palette = "yellow"
dark = "#e5c07b"
light = "#8f7a00"

[[key]]
name = "hue.green"
group = "Identity hues"
description = "The green identity hue: labels, project dots, meters."
palette = "green"
dark = "#9ecf8a"
light = "#3f7f2f"

[[key]]
name = "hue.cyan"
group = "Identity hues"
description = "The cyan identity hue: labels, project dots, meters."
palette = "cyan"
dark = "#7fd1e8"
light = "#1f7f99"

[[key]]
name = "hue.blue"
group = "Identity hues"
description = "The blue identity hue: labels, project dots, meters."
palette = "blue"
dark = "#6796e6"
light = "#1f5fb0"

[[key]]
name = "hue.purple"
group = "Identity hues"
description = "The purple identity hue: labels, project dots, meters."
palette = "purple"
dark = "#c9a2f5"
light = "#7b3fb5"

[[key]]
name = "hue.pink"
group = "Identity hues"
description = "The pink identity hue: labels, project dots, meters."
palette = "pink"
dark = "#f0a0c8"
light = "#b03a6a"


# ── Derived variables ─────────────────────────────────────────────────────────
#
# Not theme keys. See the header for what belongs here.
Expand Down
7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@tryatlas/design",
"version": "0.1.3",
"version": "0.1.4",
"private": false,
"description": "Atlas's design system: primitives, tokens, themes and the ratchet, shared by desktop, web and docs.",
"license": "Apache-2.0",
Expand Down Expand Up @@ -31,6 +31,7 @@
"import": "./dist/variants.js"
},
"./styles.css": "./src/styles/styles.css",
"./styles-core.css": "./src/styles/styles-core.css",
"./theme": {
"types": "./dist/theme/index.d.ts",
"import": "./dist/theme/index.js"
Expand All @@ -39,6 +40,10 @@
"types": "./dist/components/blocks/timeline-calendar.d.ts",
"import": "./dist/components/blocks/timeline-calendar.js"
},
"./animations": {
"types": "./dist/lib/infinite-animations.d.ts",
"import": "./dist/lib/infinite-animations.js"
},
"./ratchet": {
"types": "./dist/ratchet/index.d.ts",
"import": "./dist/ratchet/index.js"
Expand Down
16 changes: 13 additions & 3 deletions scripts/release.sh
Original file line number Diff line number Diff line change
@@ -1,18 +1,28 @@
#!/usr/bin/env bash
# Cut a git-tag release that carries the built dist/ (bun does not build git
# dependencies). main never holds dist/; the tag points at a detached commit
# that does. Usage: bun run release (from a clean main; version from package.json)
# that does. Usage: bun run release (from a clean main, or a detached HEAD at
# <remote>/main such as a worktree's; version from package.json). The remote is
# RELEASE_REMOTE, default origin.
set -euo pipefail
version="v$(node -p "require('./package.json').version")"
remote="${RELEASE_REMOTE:-origin}"
[ -z "$(git status --porcelain)" ] || { echo "release: working tree is not clean" >&2; exit 1; }
[ "$(git branch --show-current)" = "main" ] || { echo "release: run from main" >&2; exit 1; }
branch="$(git branch --show-current)"
start="$(git rev-parse HEAD)"
if [ "$branch" != "main" ]; then
git fetch -q "$remote" main
if [ -n "$branch" ] || [ "$start" != "$(git rev-parse "$remote/main")" ]; then
echo "release: run from main, or a detached HEAD at $remote/main" >&2
exit 1
fi
fi
git rev-parse -q --verify "refs/tags/$version" >/dev/null && { echo "release: $version already exists" >&2; exit 1; }
bun run build
git switch --detach -q
git add -f dist
git commit -qm "Release $version"
git tag -a "$version" -m "Release $version"
git push -q "$remote" "$version"
git switch -q main
if [ -n "$branch" ]; then git switch -q "$branch"; else git switch -q --detach "$start"; fi
echo "release: pushed $version"
22 changes: 19 additions & 3 deletions src/components/blocks/globe.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from "react";
import createGlobe from "cobe";
import { cn } from "../../lib/utils.ts";

import { infiniteAnimationFps } from "../../lib/infinite-animations.ts";
import { resolveToken } from "../../lib/resolved-color.ts";
import { useTheme } from "../../lib/theme.tsx";

Expand All @@ -30,7 +31,9 @@ import { useTheme } from "../../lib/theme.tsx";
* colours are resolved from the token layer on mount. `useTheme()` is a
* dependency so switching appearance rebuilds the globe in the new ink.
* Under `prefers-reduced-motion` it stops turning on its own but can still
* be dragged.
* be dragged. Its turn redraws at most `--infinite-animation-fps` times a
* second when that is set (see `INFINITE_ANIMATIONS`), covering the same
* angle per second either way.
*/

export type GlobeMarker = {
Expand Down Expand Up @@ -178,6 +181,10 @@ function Globe({
let globe: ReturnType<typeof createGlobe> | null = null;
let frame = 0;
let phi = 0;
// Under a cap, skip frames and turn by the time that passed instead.
const fps = infiniteAnimationFps(canvas);
const minFrameMs = fps ? 1000 / fps : 0;
let last = 0;

function init(width: number) {
if (!canvas || globe) return;
Expand Down Expand Up @@ -205,8 +212,15 @@ function Globe({
opacity: dark ? 0.75 : 0.9,
});

const tick = () => {
if (!drag.current && !still) phi += speed;
const tick = (now = performance.now()) => {
const elapsed = last ? now - last : 1000 / 60;
if (minFrameMs && last && elapsed < minFrameMs && !drag.current) {
frame = requestAnimationFrame(tick);
return;
}
last = now;
// `speed` is per 60 Hz frame; scaled by the time that passed.
if (!drag.current && !still) phi += speed * (minFrameMs ? elapsed / (1000 / 60) : 1);
globe?.update({
phi: phi + offset.current.phi + dragDelta.current.phi,
theta: THETA + offset.current.theta + dragDelta.current.theta,
Expand Down Expand Up @@ -265,6 +279,7 @@ function Globe({
{[0, 0.5].map((lag) => (
<span
key={lag}
data-slot="globe-ping"
className="absolute inset-0 rounded-full motion-safe:animate-ping border-2 border-success/60"
style={{ animationDelay: `${m.delay + lag}s` }}
/>
Expand All @@ -290,6 +305,7 @@ function Globe({
>
<span
aria-hidden="true"
data-slot="globe-live-dot"
className="size-1.5 rounded-full bg-success motion-safe:animate-pulse"
/>
<span className="font-mono text-3xs font-medium tracking-widest text-success uppercase">
Expand Down
Loading
Loading