Krzysztof kuhy Rudnicki
f7418969cf
dopamine-ux prompt 01. The token layer froze colour, spacing, radius and type, but every animation in every app picked its own duration and curve out of the air -- so "200ms ease-in-out" and "180ms ease-out" both existed and neither was wrong, because nothing said what right was. unified-design-system/motion.md is the freeze: four durations, three curves, a haptic vocabulary mapped onto Flutter's HapticFeedback, and three sound cues, each with its one-line rationale. Shipped as AppDuration/AppCurve in Dart and --duration-*/--ease-* in CSS, so a consumer imports the scale instead of transcribing it. Three things worth stating, because they are the parts easy to get wrong: - Reduced motion collapses the *tokens themselves* (CSS @media, Flutter disableAnimations), so no consumer has to remember to branch. - Haptics and sound are NOT motion and are deliberately left alone by that preference. Suppressing animation is not a request to lose confirmation that a tap landed; the sound opt-out is a separate, user-facing setting. - Reward the recording, never the number recorded. The haptic fires on logging a meal, not on hitting a calorie target -- the latter rewards eating less rather than recording honestly, and corrupts the app's own data. gatelock stays untouched: Tkinter has no animation framework, so motion there is marked `n/a (tk)` rather than shipping a dead constant that reads as a supported feature. Tests assert the frozen values on both sides, and that the reduced-motion block collapses every non-zero step -- verified by mutation: deleting one collapse line fails the suite. flutter analyze / tsc / eslint clean, 68 Dart and 88 TS tests pass, palette_check and the 250-line cap still exit 0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| dist | ||
| src | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| eslint.config.js | ||
| package.json | ||
| pnpm-lock.yaml | ||
| README.md | ||
| tsconfig.json | ||
| tsconfig.lint.json | ||
| vitest.config.ts | ||
@kuhyx/web-ui
The shared token + component layer for kuhy's web apps — the web counterpart to
~/utils/design_system (Dart). Owns the frozen palette, the spacing/radius/type
scales, and the components that were each reimplemented in two or more repos.
Consumers import the tokens rather than transcribing the token table by hand.
Source of truth for the values is ~/utils/unified-design-system/tokens.md;
this package is its executable form for the web.
Install
// package.json — pnpm only, see "Why the &path: suffix" below.
"dependencies": {
"@kuhyx/web-ui": "github:kuhyx/utils#web_ui-v0.3.1&path:/web_ui"
}
import "@kuhyx/web-ui/tokens.css"; // once, at the app entry point
import "@kuhyx/web-ui/range-slider.css"; // only if you use RangeSlider
import { RangeSlider, fuzzyMatch, quantileValue } from "@kuhyx/web-ui";
Why the &path:/web_ui suffix
utils is a monorepo with no root package.json, and npm cannot install from
a subdirectory of a git repo — github:user/repo#tag clones the root, looks
for package.json there, and fails with ENOENT (verified against npm 11.16).
pnpm supports the subdirectory via &path:/<dir>, which is why both consumers
are pnpm. This is the only difference from the Dart (git: {url, ref, path}) and
Python (#subdirectory=) conventions the rest of utils follows.
Why dist/ is committed
Vite does not transpile dependencies, so shipping raw .tsx would force
per-repo bundler config on every consumer. The tag carries a prebuilt dist/
(ESM + .d.ts, JSX already compiled, .ts specifiers rewritten to .js), so
consumers stay at zero config. pnpm build before tagging, always — a tag
whose dist/ is stale ships old code to every consumer with no error.
What's here
| Export | Notes |
|---|---|
tokens.css |
The :root block: palette, spacing, radius, type, shadows, focus ring. Also sets :focus-visible globally. |
RangeSlider |
Dual-thumb slider over a value distribution, not a linear ramp. |
range-slider.css |
Its styling, entirely in tokens. |
quantile.ts helpers |
nth, clamp01, quantileValue, valueQuantile, fractionFromPointer. |
fuzzyMatch |
Case-insensitive subsequence match. |
The categorical ramp
--cat-1 … --cat-6 are for charts, tags and category dots — N mutually
distinguishable colours with no inherent meaning. Never use them for
semantic state; --success/--warning/--danger own that.
They deliberately leave the warm wedge the rest of the palette sits in, because
hue separation is the whole point of a categorical scale. The values were chosen
by search under a ≥20 CIE ΔE floor across normal vision and deuteranopia,
protanopia and tritanopia, ≥3:1 contrast on both backgrounds, and a
monotonic lightness staircase so the ramp survives greyscale. Re-run the proof
with python3 ~/utils/unified-design-system/scripts/ramp_check.py — it exits
non-zero if an edit breaks any of it. A seventh hue is not available: the best
candidate reaches only ΔE 17.9. Group the tail into "other" instead.
fractionFromPointer is deliberately pure geometry: it makes the slider's
behaviour testable without layout, which jsdom does not implement.
RangeSlider is keyboard-operable
Both donor copies were pointer-only. The design system requires that every
action be reachable with the keyboard alone, and a role="slider" that ignores
arrow keys is an ARIA role that lies — so the shared version adds:
| Key | Effect |
|---|---|
← ↓ / → ↑ |
Step to the next distinct value |
PageDown / PageUp |
Step ten distinct values |
Home / End |
Jump to the distribution's bounds |
Pass label and format to get the built-in head (name + value readout);
omit them for a bare track when the caller draws its own chrome, as
dufs-cloud's SizeRange/DurationRange wrappers do.
Stepping targets the next distinct value, not the next index. Real
distributions are lumpy — ~1500 of awesome-mcp-explorer's ~2981 star counts are
0 — and an index step inside a run of equal values moves the index while
leaving the value, the thumb and the filter untouched. That reads as a dead
arrow key, and jsdom's evenly-spaced fixtures do not catch it.
Development
pnpm install
pnpm test # vitest
pnpm coverage # 100% branches/functions/lines/statements, enforced
pnpm lint # tsc --noEmit && eslint
pnpm build # tsc -b + copy CSS into dist/
The 100% bar matches Phase 1's design_system: a shared layer two repos depend
on does not get to be the least-tested code in the tree.
Releasing
pnpm test && pnpm build
git add web_ui && git commit -m "web_ui: <what changed>"
git tag web_ui-v<major>.<minor>.<patch> && git push origin main --tags
Then bump the tag in each consumer's package.json and re-run pnpm install.