@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Team of Silicons
+Copyright (c) 2026 Elia Kuratli (Arc, the original work this project is based on)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# Silicon UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components with calm motion, built on the Silicon design tokens. By Team of Silicons.
+Browse every component at [ui.teamofsilicons.com](https://ui.teamofsilicons.com).
+
+## Install
+
+```sh
+npm install @teamofsilicons/silicon-ui
+```
+
+Requires React 19.
+
+## Use
+
+Load the tokens once, in your root layout or entry file:
+
+```tsx
+import "@teamofsilicons/silicon-ui/styles.css";
+```
+
+Import each component from its own path:
+
+```tsx
+import { Button } from "@teamofsilicons/silicon-ui/button";
+import { Input } from "@teamofsilicons/silicon-ui/input";
+
+export function Example() {
+  return <Button variant="primary">Save</Button>;
+}
+```
+
+Components carry their own styles as CSS modules, so your bundler (Next.js, Vite) only loads the CSS of the
+components you use. Theme, accent and corners are set on `<html>`:
+
+```html
+<html data-theme="light" data-accent="neutral" data-corners="squircle">
+```
+
+`data-theme` is `light` or `dark`. `data-accent` is `neutral`, `violet`, `blue`, `green`, `amber`, `orange`,
+`coral` or `rose`. `data-corners` is `squircle` or `round`.
+
+Fonts: the tokens use `--font-geist` and `--font-inter` when set (for example by `next/font`), and fall back to
+Geist Variable, Inter Variable, then sans-serif.
+
+## Links and images
+
+Components render a plain `<a>` and `<img>` by default. To use your framework's, wrap the app once:
+
+```tsx
+import Link from "next/link";
+import Image from "next/image";
+import { SiliconProvider } from "@teamofsilicons/silicon-ui/provider";
+
+<SiliconProvider link={Link} image={Image}>{children}</SiliconProvider>
+```
+
+## Catalog
+
+`@teamofsilicons/silicon-ui/components.json` lists every component, its import path and its exports.
+
+
+## Guardrails
+
+Two checks keep an app on the system, so screens stay consistent however they are built (including by AI):
+
+```js
+// eslint.config.mjs: raw <button>, <input>, <select>, <textarea>, <dialog> and borrowed library CSS are errors
+import siliconUi from "@teamofsilicons/silicon-ui/eslint";
+export default [...yourConfig, ...siliconUi()];
+```
+
+```sh
+npx silicon-ui-check                    # raw spacing, radius, colour or font size in CSS modules fails
+npx silicon-ui-check --update-baseline  # tolerate today's legacy values; only new drift fails
+```
+
+Full guide, including the Claude Code hook: [docs/guardrails.md](https://github.com/teamofsilicons/silicon-ui/blob/main/docs/guardrails.md).
+
+## Licence
+
+MIT. Based on [Arc](https://github.com/kuratlielia/arc-library) by Elia Kuratli.

package/check.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * silicon-ui-check: keeps an app's CSS on Silicon UI's tokens.
+ *
+ * Fails a CSS file that sets spacing, a corner radius, a colour or a font size with a raw value instead of a token:
+ *
+ *   spacing    padding, margin, gap, inset, top/right/bottom/left, scroll-margin/padding → var(--space-*)
+ *   radius     border-radius and its corners                                           → var(--radius-*)
+ *   color      hex, rgb(), hsl(), oklch(), oklab(), lab(), lch(), color()              → var(--…)
+ *   font-size  px or rem                                                                → var(--text-*)
+ *
+ * Allowed everywhere: 0, auto, inherit and other keywords, anything inside var() (including fallbacks), and
+ * font-relative or layout-relative units (em, %, ch, vw, vh, cq*). Custom property definitions (--x: …) are not
+ * checked: tokens are defined that way, in the files you list under `ignore`. The visually hidden block (.srOnly,
+ * .visuallyHidden, .sr-only) and @keyframes are skipped.
+ *
+ * Configure it in package.json:
+ *
+ *   "siliconUi": {
+ *     "css": ["components/**\/*.module.css", "app/**\/*.module.css"],
+ *     "ignore": ["styles/tokens.css"],
+ *     "baseline": "silicon-ui-baseline.json"
+ *   }
+ *
+ * Usage:
+ *   silicon-ui-check                    check every configured file (fails only above the baseline)
+ *   silicon-ui-check a.css b.css        check these files
+ *   silicon-ui-check --update-baseline  record today's counts, so only new drift fails from now on
+ *   silicon-ui-check --hook             Claude Code PostToolUse hook: checks the edited file (CSS, and ESLint for
+ *                                       .ts/.tsx/.js/.jsx), exit 2 with the problems so the agent fixes them
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RULES = {
+  spacing: /^(?:padding|margin|gap|row-gap|column-gap|inset|top|right|bottom|left)(?:-[a-z-]+)?$|^scroll-(?:margin|padding)(?:-[a-z-]+)?$/,
+  radius: /^border(?:-[a-z]+(?:-[a-z]+)?)?-radius$/,
+  "font-size": /^font-size$/,
+};
+const LENGTH = /(?<![\w.#-])(-?(?:\d*\.)?\d+)(px|rem)\b/g;
+const COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\(/i;
+const HIDDEN = /\.(?:srOnly|visuallyHidden|sr-only|visually-hidden)\b/;
+const FIX = {
+  spacing: "use a spacing token: var(--space-tight|related|group|inset|comfort|section|block|page|stage|screen)",
+  radius: "use a radius token: var(--radius-detail|control|container|overlay|full)",
+  color: "use a colour token: var(--foreground), var(--text-secondary), var(--border), var(--accent) …",
+  "font-size": "use a type token: var(--text-xs|sm|base|lg|xl|2xl|3xl|4xl|5xl)",
+};
+
+/** Removes every var(...) (with nested parentheses), so tokens and their fallbacks are never flagged. */
+function withoutVars(value) {
+  let out = "";
+  for (let i = 0; i < value.length; i++) {
+    if (value.startsWith("var(", i)) {
+      let depth = 0;
+      for (; i < value.length; i++) {
+        if (value[i] === "(") depth++;
+        else if (value[i] === ")" && --depth === 0) break;
+      }
+      out += "var()";
+    } else out += value[i];
+  }
+  return out;
+}
+
+/** Declarations with their line, selector and whether they sit inside @keyframes. */
+function declarations(css) {
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, match => match.replace(/[^\n]/g, " "));
+  const found = [];
+  const stack = [];
+  let start = 0;
+  const lineAt = index => source.slice(0, index).split("\n").length;
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i];
+    if (char === "{") {
+      stack.push(source.slice(start, i).trim());
+      start = i + 1;
+    } else if (char === "}" || char === ";") {
+      const text = source.slice(start, i);
+      const colon = text.indexOf(":");
+      if (colon > 0 && stack.length && !/[{}]/.test(text)) {
+        const property = text.slice(0, colon).trim().toLowerCase();
+        const value = text.slice(colon + 1).trim();
+        const offset = start + text.length - text.trimStart().length;
+        if (/^[a-z-]+$/.test(property)) {
+          found.push({ property, value, line: lineAt(offset), selector: stack[stack.length - 1], keyframes: stack.some(p => /^@(-\w+-)?keyframes\b/.test(p)) });
+        }
+      }
+      if (char === "}") stack.pop();
+      start = i + 1;
+    }
+  }
+  return found;
+}
+
+export function checkCss(css) {
+  const problems = [];
+  for (const { property, value, line, selector, keyframes } of declarations(css)) {
+    if (keyframes || property.startsWith("--") || HIDDEN.test(selector)) continue;
+    const bare = withoutVars(value);
+    for (const [rule, pattern] of Object.entries(RULES)) {
+      if (!pattern.test(property)) continue;
+      const raw = [...bare.matchAll(LENGTH)].filter(match => Number(match[1]) !== 0).map(match => match[0]);
+      if (raw.length) problems.push({ rule, line, property, value, raw: raw.join(", ") });
+    }
+    const color = bare.match(COLOR);
+    if (color) problems.push({ rule: "color", line, property, value, raw: color[0] });
+  }
+  return problems;
+}
+
+/* ---------------------------------------------------------------- files and config ------------------------------------------------------------- */
+
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") { re += glob[i + 2] === "/" ? "(?:.*/)?" : ".*"; i += glob[i + 2] === "/" ? 2 : 1; }
+      else re += "[^/]*";
+    } else if (c === "?") re += "[^/]";
+    else if (c === "{") { const end = glob.indexOf("}", i); re += `(?:${glob.slice(i + 1, end).split(",").map(s => s.replace(/[.+^$()|[\]\\]/g, "\\$&")).join("|")})`; i = end; }
+    else re += c.replace(/[.+^$()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+const matches = (file, globs) => globs.some(glob => globToRegExp(glob).test(file));
+
+function walk(dir, root) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(full, root));
+    else out.push(path.relative(root, full).split(path.sep).join("/"));
+  }
+  return out;
+}
+
+function findProject(from) {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    const manifest = path.join(dir, "package.json");
+    if (fs.existsSync(manifest)) {
+      const config = JSON.parse(fs.readFileSync(manifest, "utf8")).siliconUi;
+      if (config) return { root: dir, config: { css: ["**/*.module.css"], ignore: [], baseline: "silicon-ui-baseline.json", ...config } };
+    }
+    if (path.dirname(dir) === dir) return { root: path.resolve(from), config: { css: ["**/*.module.css"], ignore: [], baseline: "silicon-ui-baseline.json" } };
+  }
+}
+
+const count = problems => problems.reduce((totals, { rule }) => ({ ...totals, [rule]: (totals[rule] ?? 0) + 1 }), {});
+const readBaseline = file => (fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")).files ?? {} : {});
+
+/** Problems in a file beyond what the baseline allows for it (all of them for a file the baseline does not list). */
+function overBaseline(problems, allowed = {}) {
+  const totals = count(problems);
+  return Object.keys(totals).filter(rule => totals[rule] > (allowed[rule] ?? 0)).flatMap(rule => problems.filter(problem => problem.rule === rule));
+}
+
+function report(file, problems, allowed = {}) {
+  const lines = [`${file}`];
+  for (const { rule, line, property, raw } of [...problems].sort((x, y) => x.line - y.line)) lines.push(`  ${line}  ${rule}: ${property} uses ${raw}; ${FIX[rule]}`);
+  const counted = count(problems);
+  const listed = Object.keys(counted).filter(rule => allowed[rule] && counted[rule] > allowed[rule]).map(rule => `${rule} ${counted[rule]}, baseline ${allowed[rule]}`);
+  if (listed.length) lines.push(`  (over the baseline: ${listed.join("; ")}. Older raw values are listed too; fix at least the new ones)`);
+  return lines.join("\n");
+}
+
+/* ---------------------------------------------------------------- modes ------------------------------------------------------------------------ */
+
+function runCli(args) {
+  const { root, config } = findProject(process.cwd());
+  const update = args.includes("--update-baseline");
+  const named = args.filter(arg => !arg.startsWith("--"));
+  const files = (named.length ? named.map(file => path.relative(root, path.resolve(file)).split(path.sep).join("/")) : walk(root, root).filter(file => matches(file, config.css)))
+    .filter(file => !matches(file, config.ignore));
+  const baselinePath = path.join(root, config.baseline);
+  const baseline = readBaseline(baselinePath);
+
+  if (update) {
+    const next = {};
+    for (const file of files) { const totals = count(checkCss(fs.readFileSync(path.join(root, file), "utf8"))); if (Object.keys(totals).length) next[file] = totals; }
+    fs.writeFileSync(baselinePath, `${JSON.stringify({ note: "Raw values that predate the Silicon UI checks. Counts may only go down: fix a file, then run silicon-ui-check --update-baseline.", files: next }, null, 2)}\n`);
+    const total = Object.values(next).reduce((sum, totals) => sum + Object.values(totals).reduce((a, b) => a + b, 0), 0);
+    console.log(`silicon-ui-check: baseline written to ${config.baseline}: ${total} raw values in ${Object.keys(next).length} files.`);
+    return 0;
+  }
+
+  let failed = 0, legacy = 0;
+  for (const file of files) {
+    const problems = checkCss(fs.readFileSync(path.join(root, file), "utf8"));
+    const over = overBaseline(problems, baseline[file]);
+    legacy += problems.length - over.length;
+    if (over.length) { failed++; console.error(report(file, problems.length > over.length ? problems : over, baseline[file])); }
+  }
+  if (failed) {
+    console.error(`\nsilicon-ui-check: ${failed} file${failed === 1 ? " uses" : "s use"} raw values where Silicon UI has tokens.`);
+    return 1;
+  }
+  console.log(`silicon-ui-check: ${files.length} files on tokens${legacy ? ` (${legacy} older raw values tolerated by the baseline; it only goes down)` : ""}.`);
+  return 0;
+}
+
+function runHook() {
+  let input = {};
+  try { input = JSON.parse(fs.readFileSync(0, "utf8") || "{}"); } catch { return 0; }
+  const target = input.tool_input?.file_path ?? input.tool_input?.path;
+  if (!target || !fs.existsSync(target)) return 0;
+  const { root, config } = findProject(path.dirname(target));
+  const file = path.relative(root, path.resolve(target)).split(path.sep).join("/");
+  const messages = [];
+
+  if (/\.css$/.test(file) && matches(file, config.css) && !matches(file, config.ignore)) {
+    const problems = checkCss(fs.readFileSync(target, "utf8"));
+    const allowed = readBaseline(path.join(root, config.baseline))[file];
+    if (overBaseline(problems, allowed).length) messages.push(report(file, problems, allowed));
+  }
+  if (/\.(?:[cm]?[jt]sx?)$/.test(file)) {
+    const eslint = path.join(root, "node_modules", ".bin", "eslint");
+    if (fs.existsSync(eslint)) {
+      const result = spawnSync(eslint, ["--no-warn-ignored", "--max-warnings=0", file], { cwd: root, encoding: "utf8" });
+      if (result.status) messages.push((result.stdout || result.stderr).trim());
+    }
+  }
+  if (!messages.length) return 0;
+  console.error(`Silicon UI check failed for ${file}. Fix these before moving on (docs: https://github.com/teamofsilicons/silicon-ui/tree/main/docs):\n\n${messages.join("\n\n")}`);
+  return 2;
+}
+
+// Run as a command (directly or through node_modules/.bin), not when imported.
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  process.exitCode = args.includes("--hook") ? runHook() : runCli(args);
+}

package/components/accordion/accordion.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+export interface AccordionItem {
+    title: string;
+    content: ReactNode;
+}
+export interface AccordionProps {
+    items: AccordionItem[];
+    defaultOpen?: number;
+    /** "lg" suits page-level FAQs: questions at the large text size, answers at body size. */
+    size?: "md" | "lg";
+}
+export declare function Accordion({ items, defaultOpen, size }: AccordionProps): import("react").JSX.Element;
+export default Accordion;

package/components/accordion/accordion.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import * as AccordionPrimitive from "@radix-ui/react-accordion";
+import { ChevronDown } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./accordion.module.css";
+/** Height follows the content on a spring that never overshoots; closed panels leave the accessibility tree once they finish collapsing. */
+const panelOpen = { height: "auto", opacity: 1, visibility: "visible" };
+const panelClosed = { height: 0, opacity: 0, transitionEnd: { visibility: "hidden" } };
+/** The answer settles down into place with a brief focus pull as the panel opens. */
+const contentOpen = { y: 0, filter: "blur(0px)", transitionEnd: { filter: "none" } };
+const contentClosed = { y: -6, filter: `blur(${motionTokens.blur.subtle}px)` };
+const panelMotion = {
+    open: { ...panelOpen, transition: { height: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] } } },
+    closed: { ...panelClosed, transition: { height: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } } },
+};
+const contentMotion = {
+    open: { ...contentOpen, transition: { y: motionTokens.spring.smooth, filter: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] } } },
+    closed: { ...contentClosed, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } },
+};
+/** Reduced motion: same end states in one step, so server and client render identical styles. */
+const panelStill = { open: { ...panelOpen, transition: { duration: 0 } }, closed: { ...panelClosed, transition: { duration: 0 } } };
+const contentStill = { open: { ...contentOpen, transition: { duration: 0 } }, closed: { ...contentClosed, transition: { duration: 0 } } };
+export function Accordion({ items, defaultOpen = 0, size = "md" }) {
+    const initialValue = defaultOpen >= 0 && defaultOpen < items.length ? String(defaultOpen) : "";
+    const [openValue, setOpenValue] = useState(initialValue);
+    const reduced = useReducedMotion();
+    return _jsx(AccordionPrimitive.Root, { className: [styles.accordion, size === "lg" ? styles.lg : ""].filter(Boolean).join(" "), type: "single", collapsible: true, value: openValue, onValueChange: setOpenValue, children: items.map((item, index) => {
+            const open = openValue === String(index);
+            return _jsxs(AccordionPrimitive.Item, { className: styles.item, value: String(index), children: [_jsx(AccordionPrimitive.Header, { className: styles.header, children: _jsxs(AccordionPrimitive.Trigger, { className: styles.trigger, children: [_jsx("span", { children: item.title }), _jsx(motion.span, { className: styles.icon, initial: false, animate: { rotate: open ? 180 : 0 }, transition: reduced ? { duration: 0 } : motionTokens.spring.snappy, children: _jsx(ChevronDown, { width: 17, height: 17, "aria-hidden": "true" }) })] }) }), _jsx(AccordionPrimitive.Content, { forceMount: true, asChild: true, children: _jsx(motion.div, { className: styles.panel, initial: false, animate: open ? "open" : "closed", variants: reduced ? panelStill : panelMotion, children: _jsx(motion.div, { className: styles.panelInner, variants: reduced ? contentStill : contentMotion, children: item.content }) }) })] }, `${item.title}-${index}`);
+        }) });
+}
+export default Accordion;

package/components/accordion/accordion.module.css

@@ -0,0 +1,15 @@
+.accordion { width: 100%; border-top: 1px solid var(--border); }
+.item { border-bottom: 1px solid var(--border); }
+.header { margin: 0; }
+.trigger { display: flex; width: 100%; min-height: var(--control-height-lg); align-items: center; justify-content: space-between; gap: var(--space-comfort); padding: var(--space-related) 0; border: 0; background: transparent; color: var(--foreground); font: inherit; font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); text-align: left; cursor: pointer; -webkit-tap-highlight-color: transparent; transition: color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .trigger:hover { color: var(--text-secondary); } .trigger:hover .icon { color: var(--foreground); } }
+/* Rotation is driven by a spring in accordion.tsx; CSS only handles color. */
+.icon { display: inline-flex; flex: 0 0 auto; color: var(--text-muted); transition: color var(--duration-fast) var(--ease-standard); }
+.trigger[data-state="open"] .icon { color: var(--foreground); }
+.panel { overflow: hidden; color: var(--text-secondary); font-size: var(--text-sm); line-height: var(--leading-body); }
+.panelInner { overflow-wrap: anywhere; padding: 0 var(--space-block) var(--space-comfort) 0; }
+.lg .trigger { min-height: 76px; gap: var(--space-block); padding-block: var(--space-comfort); font-size: var(--text-lg); letter-spacing: var(--tracking-body); }
+.lg .panel { font-size: var(--text-base); line-height: 1.65; }
+.lg .panelInner { max-width: 62ch; padding: 0 var(--space-page) var(--space-section) 0; }
+@media (max-width: 520px) { .lg .trigger { min-height: 68px; font-size: var(--text-base); } .lg .panel { font-size: var(--text-sm); } .lg .panelInner { padding-right: var(--space-section); } }
+@media (prefers-reduced-motion: reduce) { .trigger, .icon { transition: none; } }

package/components/action-button/action-button.d.ts

@@ -0,0 +1,11 @@
+import type { ButtonHTMLAttributes } from "react";
+export interface ActionButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart"> {
+    label: string;
+    successLabel?: string;
+    pendingLabel?: string;
+    onAction: () => void | Promise<void>;
+    resetAfterMs?: number;
+    onActionError?: (error: unknown) => void;
+}
+export declare function ActionButton({ label, successLabel, pendingLabel, onAction, resetAfterMs, onActionError, className, disabled, ...props }: ActionButtonProps): import("react").JSX.Element;
+export default ActionButton;

package/components/action-button/action-button.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { ArrowRight } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import { TextMorph } from "../text-morph/text-morph.js";
+import styles from "./action-button.module.css";
+const pressVariants = {
+    pressed: (button) => ({ scale: (button.current?.offsetWidth ?? 0) > 220 ? .985 : .97, transition: { duration: motionTokens.duration.instant, ease: [...motionTokens.ease.standard] } }),
+};
+const rest = { opacity: 1, y: 0, scale: 1, filter: "blur(0px)" };
+const iconIn = { opacity: 0, scale: .6, filter: `blur(${motionTokens.blur.subtle}px)` };
+const iconOut = { ...iconIn, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } };
+/** The arrow leaves in the direction of the action and returns from behind once the button resets. */
+const arrowIn = { opacity: 0, x: -6, filter: `blur(${motionTokens.blur.subtle}px)` };
+const arrowOut = { opacity: 0, x: 8, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } };
+const iconRest = { ...rest, x: 0 };
+const fadeIn = { ...rest, opacity: 0 };
+const fadeOut = { opacity: 0, transition: { duration: motionTokens.duration.instant } };
+/** Scale rides the spring; opacity and blur tween so blur never overshoots below zero. */
+const iconEnter = { ...motionTokens.spring.snappy, opacity: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.enter] }, filter: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.enter] } };
+/** The success tick draws itself from its short stroke, the way a hand would write it. */
+function DrawnCheck({ reduced }) {
+    return _jsx("svg", { className: styles.statusIcon, width: 17, height: 17, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", children: _jsx(motion.path, { d: "M4 12l5 5L20 6", initial: reduced ? false : { pathLength: 0, opacity: 0 }, animate: { pathLength: 1, opacity: 1 }, transition: { pathLength: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter], delay: .05 }, opacity: { duration: .05, delay: .05 } } }) });
+}
+export function ActionButton({ label, successLabel = "Saved", pendingLabel = "Saving", onAction, resetAfterMs = 2400, onActionError, className, disabled, ...props }) {
+    const [state, setState] = useState("idle");
+    const resetTimer = useRef(null);
+    const buttonRef = useRef(null);
+    const reduceMotion = useReducedMotion() ?? false;
+    const text = state === "pending" ? pendingLabel : state === "success" ? successLabel : label;
+    useEffect(() => () => { if (resetTimer.current)
+        clearTimeout(resetTimer.current); }, []);
+    async function run() {
+        if (state === "pending")
+            return;
+        if (resetTimer.current)
+            clearTimeout(resetTimer.current);
+        setState("pending");
+        try {
+            await onAction();
+            setState("success");
+            if (resetAfterMs > 0)
+                resetTimer.current = setTimeout(() => setState("idle"), resetAfterMs);
+        }
+        catch (error) {
+            setState("idle");
+            onActionError?.(error);
+        }
+    }
+    const pending = state === "pending";
+    const arrow = state === "idle";
+    // Pending stays focusable (aria-disabled instead of disabled), so a keyboard user keeps focus through the whole save.
+    return _jsxs(motion.button, { ...props, ref: buttonRef, tabIndex: props.tabIndex ?? 0, type: props.type ?? "button", className: [styles.button, className].filter(Boolean).join(" "), "data-variant": "primary", disabled: disabled, "aria-disabled": pending ? true : props["aria-disabled"], "aria-busy": pending, "data-state": state, onClick: run, custom: buttonRef, variants: pressVariants, whileTap: reduceMotion || disabled || pending ? undefined : "pressed", transition: motionTokens.spring.snappy, children: [_jsxs("span", { className: styles.content, "aria-hidden": "true", children: [_jsx(TextMorph, { children: text }), _jsx("span", { className: styles.iconSlot, children: _jsx(AnimatePresence, { initial: false, children: _jsx(motion.span, { className: styles.phase, initial: reduceMotion ? fadeIn : arrow ? arrowIn : iconIn, animate: iconRest, exit: reduceMotion ? fadeOut : arrow ? arrowOut : iconOut, transition: reduceMotion ? { duration: motionTokens.duration.instant } : iconEnter, children: pending ? _jsx("span", { className: styles.spinner }) : state === "success" ? _jsx(DrawnCheck, { reduced: reduceMotion }) : _jsx(ArrowRight, { className: styles.arrow, width: 17, height: 17 }) }, state) }) })] }), _jsx("span", { className: styles.visuallyHidden, children: label }), _jsx("span", { className: styles.visuallyHidden, role: "status", children: state === "pending" ? pendingLabel : state === "success" ? successLabel : "" })] });
+}
+export default ActionButton;

package/components/action-button/action-button.module.css

@@ -0,0 +1,15 @@
+/* The button hugs its label: TextMorph morphs the text in place and springs its width, so no state ever snaps the layout. */
+.button { position: relative; display: inline-flex; min-height: var(--control-height-md); align-items: center; justify-content: center; overflow: hidden; padding: 0 var(--space-comfort); border: 1px solid var(--primary); border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: var(--primary); color: var(--primary-foreground); font: inherit; font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); cursor: pointer; -webkit-tap-highlight-color: transparent; transition: background var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard), opacity var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .button:hover:not(:disabled) { box-shadow: var(--shadow-resting); } }
+.button:disabled { cursor: not-allowed; }
+.button:disabled:not([data-state="pending"]) { opacity: .7; }
+.button[data-state="pending"] { cursor: progress; }
+.content { display: inline-flex; min-height: 1.25rem; align-items: center; justify-content: center; gap: var(--space-related); white-space: nowrap; }
+.iconSlot { display: grid; width: 17px; height: 17px; flex: 0 0 17px; place-items: center; }
+.phase { grid-area: 1 / 1; display: grid; width: 17px; height: 17px; place-items: center; }
+.arrow { flex: none; }
+.statusIcon { color: currentColor; }
+.spinner { display: inline-block; width: var(--space-inset); height: var(--space-inset); border: 1.5px solid currentColor; border-right-color: transparent; border-radius: var(--radius-full); corner-shape: round; animation: spin .7s linear infinite; }
+.visuallyHidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+@keyframes spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) { .button { transition: none; } .spinner { animation: none; } }

package/components/activity-heatmap/activity-heatmap.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+export interface ActivityDay {
+    /** Calendar day as YYYY-MM-DD. */
+    date: string;
+    count: number;
+}
+/**
+ * A contribution style calendar: one square per day, weeks as columns, with four accent tints for how busy a day was.
+ * Use it when rhythm, streaks, and quiet weeks matter more than exact comparisons; use a bar chart when the exact
+ * comparison is the point. Cells wave in once on view, a tooltip glides between cells on hover or keyboard focus, and a
+ * new range recolors the grid in a sweep instead of redrawing it. Arrow keys move by day and week, Enter selects.
+ */
+export interface ActivityHeatmapProps {
+    /** One entry per day, oldest first. Days missing inside the range count as zero. */
+    days: ActivityDay[];
+    /** Accessible name for the grid, such as "Contributions in 2025". */
+    label: string;
+    /** Finishes the summary line: "1,284 contributions in {period}". */
+    period: string;
+    /** Nouns for the count. */
+    unit?: {
+        one: string;
+        other: string;
+    };
+    /** Upper bounds for levels one to three; anything above the last is level four. Defaults to quarters of the busiest day. */
+    thresholds?: [number, number, number];
+    weekStartsOn?: 0 | 1;
+    selectedDate?: string | null;
+    onSelectDate?: (date: string) => void;
+    /** Controls beside the summary, such as a range switch. */
+    actions?: ReactNode;
+    /** Formatting locale. Fixed by default so server and client render the same labels. */
+    locale?: string;
+    className?: string;
+}
+export declare function ActivityHeatmap({ days, label, period, unit: unitProp, thresholds, weekStartsOn, selectedDate, onSelectDate, actions, locale, className }: ActivityHeatmapProps): import("react").JSX.Element;
+export default ActivityHeatmap;