@cosxai/ui 1.0.0-alpha.2 → 1.0.0-alpha.4

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.0.0-alpha.4 (2026-09-29)
+
+- ToastCard: one toast drawn in place (documentation specimens, previews).
+- theme.css is now theme-reset.css + theme-base.css. An app moving to the
+  kit screen by screen imports `@cosxai/ui/theme-base.css`: the kit's
+  utilities are added and Tailwind's own palette and sizes keep working.
+  New apps keep importing theme.css (unchanged result).
+
+## 1.0.0-alpha.3 (2026-09-29)
+
+- Button: busy and done draw over the idle content, kept in place and
+  hidden, so the width never changes — also when the button first
+  renders busy (it used to shrink to the spinner). No width measuring.
+
 ## 1.0.0-alpha.2 (2026-09-29)
 
 MetaRoom product patterns (spec P0), checked light / ink × en / zh.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosxai/ui",
-  "version": "1.0.0-alpha.2",
-  "description": "COSX Design System 3.0 — tokens, Tailwind v4 theme and React components",
+  "version": "1.0.0-alpha.4",
+  "description": "COSX Design System 3.0 \u2014 tokens, Tailwind v4 theme and React components",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,7 +10,8 @@
     ".": "./src/index.ts",
     "./styles.css": "./src/styles.css",
     "./theme.css": "./src/theme.css",
-    "./tokens/*": "./src/tokens/*"
+    "./tokens/*": "./src/tokens/*",
+    "./theme-base.css": "./src/theme-base.css"
   },
   "files": [
     "src",

package/src/components/Button.tsx

@@ -1,7 +1,7 @@
 import { Slot } from '@radix-ui/react-slot';
 import { cva } from 'class-variance-authority';
 import { Check } from 'lucide-react';
-import { useLayoutEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 
 import { cn } from '../lib/cn';
 import { Spinner } from './Spinner';
@@ -76,7 +76,7 @@ export type ButtonProps = Omit<ComponentProps<'button'>, 'disabled'> & {
   shortcut?: string | undefined;
   /** A count at the end (Comments 12). Hidden at zero, 99+ above 99. */
   count?: number | undefined;
-  /** Async state: busy locks the width and shows a spinner; done confirms in place. See useButtonAction. */
+  /** Async state: busy shows a spinner, done confirms in place; the width never changes. See useButtonAction. */
   state?: ButtonState | undefined;
   /** Label shown while state="done". @default the children */
   doneLabel?: ReactNode;
@@ -119,15 +119,6 @@ export function Button({
   ref,
   ...rest
 }: ButtonProps) {
-  const inner = useRef<HTMLButtonElement | null>(null);
-  const [lockedWidth, setLockedWidth] = useState<number | null>(null);
-
-  // Lock the idle width so busy / done never resize the button.
-  useLayoutEffect(() => {
-    if (state === 'idle') setLockedWidth(null);
-    else if (lockedWidth === null && inner.current) setLockedWidth(inner.current.getBoundingClientRect().width);
-  }, [state, lockedWidth]);
-
   const classes = cn(button({ variant, size, ground: ground ?? 'auto' }), className);
   if (asChild) {
     return (
@@ -138,21 +129,18 @@ export function Button({
   }
 
   const busy = state === 'busy';
+  // Busy and done keep the idle content in place (hidden) and draw on top of
+  // it, so the button never resizes — also when it first renders busy.
+  const overlaid = state !== 'idle';
   const blocked = Boolean(disabledReason) && disabled;
   const shownCount = count === undefined ? null : formatCount(count);
-  const setRefs = (el: HTMLButtonElement | null) => {
-    inner.current = el;
-    if (typeof ref === 'function') ref(el);
-    else if (ref) ref.current = el;
-  };
-
   return (
     <button
       type="button"
       {...rest}
-      ref={setRefs}
+      ref={ref}
       className={classes}
-      style={lockedWidth ? { ...style, width: lockedWidth } : style}
+      style={style}
       disabled={disabled && !disabledReason ? true : undefined}
       // Busy is not disabled (spec: "busy and disabled are different states"):
       // it keeps its look; aria-busy says so and repeat clicks are ignored below.
@@ -167,27 +155,32 @@ export function Button({
         onClick?.(e);
       }}
     >
-      {busy ? (
-        <Spinner />
-      ) : state === 'done' ? (
-        <>
-          <Check size={14} strokeWidth={2} aria-hidden />
-          {doneLabel ?? children}
-        </>
-      ) : (
-        <>
-          {iconLeft}
-          {children}
-          {iconRight}
-          {shownCount && <span className="font-medium tabular-nums opacity-70">{shownCount}</span>}
-          {shortcut && (
-            <kbd className="ml-0.5 font-sans text-[12px] font-medium opacity-60" aria-hidden>
-              {shortcut}
-            </kbd>
+      <span className={cn('contents', overlaid && 'invisible')} aria-hidden={overlaid || undefined} data-button-content="">
+        {iconLeft}
+        {children}
+        {iconRight}
+        {shownCount && <span className="font-medium tabular-nums opacity-70">{shownCount}</span>}
+        {shortcut && (
+          <kbd className="ml-0.5 font-sans text-[12px] font-medium opacity-60" aria-hidden>
+            {shortcut}
+          </kbd>
+        )}
+      </span>
+      {overlaid && (
+        <span className="absolute inset-0 flex items-center justify-center gap-2" data-button-overlay="">
+          {busy ? (
+            <>
+              <Spinner />
+              <span className="sr-only">{children}</span>
+            </>
+          ) : (
+            <>
+              <Check size={14} strokeWidth={2} aria-hidden />
+              {doneLabel ?? children}
+            </>
           )}
-        </>
+        </span>
       )}
-      {busy && <span className="sr-only">{children}</span>}
     </button>
   );
 }

package/src/components/Toast.tsx

@@ -91,6 +91,47 @@ const DEFAULT_LABELS: ToastLabels = {
   region: 'Notifications',
 };
 
+const CARD = 'flex w-80 max-w-full items-start gap-3 rounded-[12px] bg-ink px-4 py-3.5 font-sans text-linen ink:border ink:border-inv-rule ink:bg-ink-raised';
+const ACTION =
+  'mt-2.5 inline-flex h-8 cursor-pointer items-center rounded-md border border-inv-rule bg-transparent px-3 text-[13px] font-semibold text-linen outline-none hover:border-linen focus-visible:shadow-[0_0_0_3px_var(--ink),0_0_0_5px_var(--yellow)]';
+const CLOSE = 'flex cursor-pointer rounded-xs border-0 bg-transparent p-0.5 text-grey-inverse outline-none hover:text-linen focus-visible:shadow-[0_0_0_2px_var(--yellow)]';
+const statusLabelClass = (status: ToastStatus) => cn('mb-0.5 text-meta font-medium', status === 'attention' ? 'text-yellow-accent' : 'text-grey-inverse');
+
+export type ToastCardProps = Omit<ToastOptions, 'duration' | 'action'> & {
+  /** A label, or the full action (label + onClick). */
+  action?: string | ToastOptions['action'];
+  onClose?: (() => void) | undefined;
+  labels?: Partial<ToastLabels> | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * ToastCard — one toast drawn in place, not queued: documentation
+ * specimens and previews. In the product, call toast() instead.
+ */
+export function ToastCard({ title, description, status = 'neutral', action, onClose, labels, className }: ToastCardProps) {
+  const l = { ...DEFAULT_LABELS, ...labels };
+  const act = typeof action === 'string' ? { label: action, onClick: () => {} } : action;
+  return (
+    <div className={cn(CARD, className)}>
+      <span aria-hidden className={cn('mt-[5px] size-2 shrink-0 rounded-pill', DOT[status])} />
+      <div className="min-w-0 flex-1">
+        <div className={statusLabelClass(status)}>{l[status]}</div>
+        <div className="text-ui leading-[1.4] font-medium">{title}</div>
+        {description && <div className="mt-0.5 text-[13px] leading-normal text-grey-inverse">{description}</div>}
+        {act && (
+          <button type="button" onClick={act.onClick} className={ACTION}>
+            {act.label}
+          </button>
+        )}
+      </div>
+      <button type="button" aria-label={l.dismiss} onClick={onClose} className={CLOSE}>
+        <X size={14} strokeWidth={2} aria-hidden />
+      </button>
+    </div>
+  );
+}
+
 export type ToasterProps = {
   /** Wording of the status labels and controls (e.g. Chinese). */
   labels?: Partial<ToastLabels> | undefined;
@@ -120,22 +161,18 @@ export function Toaster({ labels, offset = 24 }: ToasterProps) {
             }}
             duration={t.duration ?? (t.action ? 8000 : 4000)}
             type={status === 'error' ? 'foreground' : 'background'}
-            className={cn(
-              'flex w-80 max-w-full items-start gap-3 rounded-[12px] bg-ink px-4 py-3.5 font-sans text-linen',
-              'ink:border ink:border-inv-rule ink:bg-ink-raised',
-              'data-[swipe=move]:translate-x-(--radix-toast-swipe-move-x) data-[swipe=end]:hidden',
-            )}
+            className={cn(CARD, 'data-[swipe=move]:translate-x-(--radix-toast-swipe-move-x) data-[swipe=end]:hidden')}
           >
             <span aria-hidden className={cn('mt-[5px] size-2 shrink-0 rounded-pill', DOT[status])} />
             <div className="min-w-0 flex-1">
-              <div className={cn('mb-0.5 text-meta font-medium', status === 'attention' ? 'text-yellow-accent' : 'text-grey-inverse')}>{l[status]}</div>
+              <div className={statusLabelClass(status)}>{l[status]}</div>
               <ToastPrimitive.Title className="text-ui leading-[1.4] font-medium">{t.title}</ToastPrimitive.Title>
               {t.description && <ToastPrimitive.Description className="mt-0.5 text-[13px] leading-normal text-grey-inverse">{t.description}</ToastPrimitive.Description>}
               {t.action && (
                 <ToastPrimitive.Action
                   altText={t.action.altText ?? t.action.label}
                   onClick={t.action.onClick}
-                  className="mt-2.5 inline-flex h-8 cursor-pointer items-center rounded-md border border-inv-rule bg-transparent px-3 text-[13px] font-semibold text-linen outline-none hover:border-linen focus-visible:shadow-[0_0_0_3px_var(--ink),0_0_0_5px_var(--yellow)]"
+                  className={ACTION}
                 >
                   {t.action.label}
                 </ToastPrimitive.Action>
@@ -143,7 +180,7 @@ export function Toaster({ labels, offset = 24 }: ToasterProps) {
             </div>
             <ToastPrimitive.Close
               aria-label={l.dismiss}
-              className="flex cursor-pointer rounded-xs border-0 bg-transparent p-0.5 text-grey-inverse outline-none hover:text-linen focus-visible:shadow-[0_0_0_2px_var(--yellow)]"
+              className={CLOSE}
             >
               <X size={14} strokeWidth={2} aria-hidden />
             </ToastPrimitive.Close>

package/src/index.ts

@@ -31,7 +31,7 @@ export { Switch, type SwitchProps } from './components/Switch';
 export { Table, type TableColumn, type TableProps, type TableRowBase, type TableSort, type TableSortDirection } from './components/Table';
 export { Tab, TabList, TabPanel, Tabs, type TabItem, type TabListProps, type TabPanelProps, type TabProps, type TabsProps, type TabsVariant } from './components/Tabs';
 export { Textarea, type TextareaProps } from './components/Textarea';
-export { Toaster, toast, type ToasterProps, type ToastLabels, type ToastOptions, type ToastStatus } from './components/Toast';
+export { ToastCard, Toaster, toast, type ToastCardProps, type ToasterProps, type ToastLabels, type ToastOptions, type ToastStatus } from './components/Toast';
 export { Tooltip, TooltipProvider, type TooltipProps } from './components/Tooltip';
 
 // Stage 2 — product patterns

package/src/theme-base.css

@@ -0,0 +1,123 @@
+/* @cosxai/ui — the design system's Tailwind utilities, without clearing
+ * Tailwind's own palette, sizes, radii, shadows, fonts and easings.
+ *
+ * For an app moving to the kit screen by screen (product-meta during the
+ * move): its existing classes keep working, and the kit's are added. Where
+ * both define a name (radius, font-sans, ease-in/out), the kit's value wins.
+ * New apps import theme.css, which is this plus the reset.
+ */
+/* ink: — styles for ink mode (data-mode="ink" on <html>, or inside
+   .ink-mode). The semantic colours switch by themselves; this is for the
+   rules that flip on ink (the primary becomes the yellow). */
+@custom-variant ink (&:where([data-mode="ink"], [data-mode="ink"] *, .ink-mode, .ink-mode *));
+
+@theme inline {
+
+  /* Materials — fixed, do not switch with ink mode */
+  --color-paper: var(--paper);
+  --color-linen: var(--linen);
+  --color-sunk-2: var(--sunk-2);
+  --color-sunk-3: var(--sunk-3);
+  --color-ink: var(--ink);
+  --color-ink-raised: var(--ink-raised);
+  --color-grey: var(--grey);
+  --color-grey-inverse: var(--grey-inverse);
+
+  /* The yellow — one hue, by area */
+  --color-yellow: var(--yellow);
+  --color-yellow-accent: var(--yellow-accent);
+  --color-yellow-accent-hover: var(--yellow-accent-hover);
+  --color-yellow-light: var(--yellow-light);
+  --color-yellow-hover: var(--yellow-hover);
+  --color-yellow-1: var(--yellow-1);
+  --color-yellow-2: var(--yellow-2);
+  --color-yellow-3: var(--yellow-3);
+  --color-yellow-4: var(--yellow-4);
+  --color-yellow-5: var(--yellow-5);
+  --color-yellow-wash-12: var(--yellow-12);
+  --color-yellow-wash-20: var(--yellow-20);
+  --color-yellow-wash-32: var(--yellow-32);
+  --color-yellow-wash-50: var(--yellow-50);
+  --color-marker: var(--marker);
+
+  /* Semantic — switch with ink mode. Product code uses these. */
+  --color-page: var(--bg-page);
+  --color-sunk: var(--bg-sunk);
+  --color-well: var(--bg-well);
+  --color-chrome: var(--bg-chrome);
+  --color-field: var(--bg-field);
+  --color-fg: var(--text-primary);
+  --color-fg-secondary: var(--text-secondary);
+  --color-fg-label: var(--text-label);
+  --color-fg-on-yellow-secondary: var(--text-on-yellow-secondary);
+  --color-rule: var(--rule);
+  --color-rule-soft: var(--rule-soft);
+  --color-hover: var(--hover);
+  --color-scrim: var(--scrim);
+
+  /* Workspace brand (brand.css): the COSX yellow unless a customer's
+     colour is injected. Selection and grounds use field; dots and
+     progress use mark. Never for text. */
+  --color-brand-field: var(--brand-field);
+  --color-brand-mark: var(--brand-mark);
+
+  /* On an ink surface inside a paper page */
+  --color-inv: var(--inv-bg);
+  --color-inv-raised: var(--inv-bg-raised);
+  --color-inv-fg: var(--inv-text);
+  --color-inv-fg-secondary: var(--inv-text-secondary);
+  --color-inv-rule: var(--inv-rule);
+
+  /* Product status: yellow, ink and one red. Progress is an ink outline and
+     complete a grey dot — they take no colour of their own. */
+  --color-attention: var(--status-attention);
+  --color-attention-wash: var(--status-attention-wash);
+  --color-error: var(--status-error);
+  --color-error-text: var(--status-error-text);
+  --color-error-wash: var(--status-error-wash);
+
+  --color-transparent: transparent;
+  --color-current: currentColor;
+  --color-white: #fff;
+
+  /* Radius ladder — same names and values as 3.0 spacing.css */
+  --radius-xs: 4px;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 16px;
+  --radius-xl: 24px;
+  --radius-pill: 999px;
+
+  /* One family. Same stacks as fonts.css (the ones in effect): font-sans
+     for Latin, font-sans-cjk for Chinese pages (Geist for Latin and
+     figures, Noto Sans SC for hanzi). */
+  --font-sans: "Geist Variable", "Geist", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  --font-sans-cjk: "Geist Variable", "Geist", "Noto Sans SC Variable", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif;
+
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* Type scale (typography.css). Product UI body is 14px, content 15px. */
+  --text-meta: 12px;
+  --text-small: 13.5px;
+  --text-ui: 14px;
+  --text-body: 15px;
+  --text-h3: 18px;
+  --text-lede: 20px;
+  --text-title: 22px;
+  --text-figure: 32px;
+  --text-h2: var(--size-h2);
+  --text-h1: var(--size-h1);
+  --text-display: var(--size-display);
+
+  --tracking-display: -0.025em;
+  --tracking-heading: -0.015em;
+  --tracking-figure: -0.03em;
+
+  /* Motion — flat for state, ease-out for entry; nothing bounces */
+  --ease-standard: cubic-bezier(.2,0,.2,1);
+  --ease-out: cubic-bezier(.16,1,.3,1);
+  --ease-in: cubic-bezier(.4,0,1,1);
+}

package/src/theme-reset.css

@@ -0,0 +1,14 @@
+/* @cosxai/ui — clears Tailwind's defaults so only the design system's
+ * values exist (part of theme.css; see theme-base.css for incremental use). */
+@theme {
+  --color-*: initial;
+  --radius-*: initial;
+  --shadow-*: initial;
+  --inset-shadow-*: initial;
+  --drop-shadow-*: initial;
+  --font-*: initial;
+  --ease-*: initial;
+  --text-*: initial;
+  --font-weight-*: initial;
+  --tracking-*: initial;
+}

package/src/theme.css

@@ -16,128 +16,5 @@
  * (theme.test.ts). In particular font sizes avoid --text-primary /
  * --text-secondary / --text-label, which are colours in 3.0.
  */
-/* ink: — styles for ink mode (data-mode="ink" on <html>, or inside
-   .ink-mode). The semantic colours switch by themselves; this is for the
-   rules that flip on ink (the primary becomes the yellow). */
-@custom-variant ink (&:where([data-mode="ink"], [data-mode="ink"] *, .ink-mode, .ink-mode *));
-
-@theme inline {
-  --color-*: initial;
-  --radius-*: initial;
-  --shadow-*: initial;
-  --inset-shadow-*: initial;
-  --drop-shadow-*: initial;
-  --font-*: initial;
-  --ease-*: initial;
-  --text-*: initial;
-  --font-weight-*: initial;
-  --tracking-*: initial;
-
-  /* Materials — fixed, do not switch with ink mode */
-  --color-paper: var(--paper);
-  --color-linen: var(--linen);
-  --color-sunk-2: var(--sunk-2);
-  --color-sunk-3: var(--sunk-3);
-  --color-ink: var(--ink);
-  --color-ink-raised: var(--ink-raised);
-  --color-grey: var(--grey);
-  --color-grey-inverse: var(--grey-inverse);
-
-  /* The yellow — one hue, by area */
-  --color-yellow: var(--yellow);
-  --color-yellow-accent: var(--yellow-accent);
-  --color-yellow-accent-hover: var(--yellow-accent-hover);
-  --color-yellow-light: var(--yellow-light);
-  --color-yellow-hover: var(--yellow-hover);
-  --color-yellow-1: var(--yellow-1);
-  --color-yellow-2: var(--yellow-2);
-  --color-yellow-3: var(--yellow-3);
-  --color-yellow-4: var(--yellow-4);
-  --color-yellow-5: var(--yellow-5);
-  --color-yellow-wash-12: var(--yellow-12);
-  --color-yellow-wash-20: var(--yellow-20);
-  --color-yellow-wash-32: var(--yellow-32);
-  --color-yellow-wash-50: var(--yellow-50);
-  --color-marker: var(--marker);
-
-  /* Semantic — switch with ink mode. Product code uses these. */
-  --color-page: var(--bg-page);
-  --color-sunk: var(--bg-sunk);
-  --color-well: var(--bg-well);
-  --color-chrome: var(--bg-chrome);
-  --color-field: var(--bg-field);
-  --color-fg: var(--text-primary);
-  --color-fg-secondary: var(--text-secondary);
-  --color-fg-label: var(--text-label);
-  --color-fg-on-yellow-secondary: var(--text-on-yellow-secondary);
-  --color-rule: var(--rule);
-  --color-rule-soft: var(--rule-soft);
-  --color-hover: var(--hover);
-  --color-scrim: var(--scrim);
-
-  /* Workspace brand (brand.css): the COSX yellow unless a customer's
-     colour is injected. Selection and grounds use field; dots and
-     progress use mark. Never for text. */
-  --color-brand-field: var(--brand-field);
-  --color-brand-mark: var(--brand-mark);
-
-  /* On an ink surface inside a paper page */
-  --color-inv: var(--inv-bg);
-  --color-inv-raised: var(--inv-bg-raised);
-  --color-inv-fg: var(--inv-text);
-  --color-inv-fg-secondary: var(--inv-text-secondary);
-  --color-inv-rule: var(--inv-rule);
-
-  /* Product status: yellow, ink and one red. Progress is an ink outline and
-     complete a grey dot — they take no colour of their own. */
-  --color-attention: var(--status-attention);
-  --color-attention-wash: var(--status-attention-wash);
-  --color-error: var(--status-error);
-  --color-error-text: var(--status-error-text);
-  --color-error-wash: var(--status-error-wash);
-
-  --color-transparent: transparent;
-  --color-current: currentColor;
-  --color-white: #fff;
-
-  /* Radius ladder — same names and values as 3.0 spacing.css */
-  --radius-xs: 4px;
-  --radius-sm: 6px;
-  --radius-md: 8px;
-  --radius-lg: 16px;
-  --radius-xl: 24px;
-  --radius-pill: 999px;
-
-  /* One family. Same stacks as fonts.css (the ones in effect): font-sans
-     for Latin, font-sans-cjk for Chinese pages (Geist for Latin and
-     figures, Noto Sans SC for hanzi). */
-  --font-sans: "Geist Variable", "Geist", "Helvetica Neue", Helvetica, Arial, sans-serif;
-  --font-sans-cjk: "Geist Variable", "Geist", "Noto Sans SC Variable", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif;
-
-  --font-weight-normal: 400;
-  --font-weight-medium: 500;
-  --font-weight-semibold: 600;
-  --font-weight-bold: 700;
-
-  /* Type scale (typography.css). Product UI body is 14px, content 15px. */
-  --text-meta: 12px;
-  --text-small: 13.5px;
-  --text-ui: 14px;
-  --text-body: 15px;
-  --text-h3: 18px;
-  --text-lede: 20px;
-  --text-title: 22px;
-  --text-figure: 32px;
-  --text-h2: var(--size-h2);
-  --text-h1: var(--size-h1);
-  --text-display: var(--size-display);
-
-  --tracking-display: -0.025em;
-  --tracking-heading: -0.015em;
-  --tracking-figure: -0.03em;
-
-  /* Motion — flat for state, ease-out for entry; nothing bounces */
-  --ease-standard: cubic-bezier(.2,0,.2,1);
-  --ease-out: cubic-bezier(.16,1,.3,1);
-  --ease-in: cubic-bezier(.4,0,1,1);
-}
+@import "./theme-reset.css";
+@import "./theme-base.css";