@carbonid1/design-system 7.3.1 → 7.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { cva } from 'class-variance-authority';
2
- const buttonVariants = cva("group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-[color,background-color,opacity,transform] outline-hidden select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
2
+ const buttonVariants = cva("group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-[color,background-color,opacity,translate] outline-hidden select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
3
3
  variants: {
4
4
  variant: {
5
5
  ghost: 'hover:bg-accent aria-expanded:bg-accent dark:hover:bg-accent/50',
@@ -1,56 +1,40 @@
1
1
  import { ContextMenu as BaseContextMenu } from '@base-ui/react/context-menu';
2
- import type { ComponentPropsWithoutRef, Ref } from 'react';
3
- type BasePopupProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Popup>;
4
- type BasePositionerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Positioner>;
5
- type BaseItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Item>;
6
- type BaseSeparatorProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Separator>;
7
- type BaseGroupLabelProps = ComponentPropsWithoutRef<typeof BaseContextMenu.GroupLabel>;
8
- type BaseSubmenuTriggerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.SubmenuTrigger>;
9
- type BaseCheckboxItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.CheckboxItem>;
10
- type BaseRadioItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.RadioItem>;
11
- type ItemVariant = 'default' | 'destructive';
12
- type PositionerProps = BasePositionerProps & {
13
- ref?: Ref<HTMLDivElement>;
14
- };
15
- type PopupProps = BasePopupProps & {
16
- ref?: Ref<HTMLDivElement>;
17
- };
18
- type SeparatorProps = BaseSeparatorProps & {
19
- ref?: Ref<HTMLDivElement>;
20
- };
21
- type GroupLabelProps = BaseGroupLabelProps & {
22
- ref?: Ref<HTMLDivElement>;
23
- };
24
- type ItemProps = BaseItemProps & {
25
- ref?: Ref<HTMLDivElement>;
26
- variant?: ItemVariant;
27
- };
28
- type CheckboxItemProps = BaseCheckboxItemProps & {
29
- ref?: Ref<HTMLDivElement>;
30
- };
31
- type RadioItemProps = BaseRadioItemProps & {
32
- ref?: Ref<HTMLDivElement>;
33
- };
34
- type SubmenuTriggerProps = BaseSubmenuTriggerProps & {
35
- ref?: Ref<HTMLDivElement>;
36
- };
2
+ import type { ComponentProps } from 'react';
3
+ import { Menu } from '../Menu/Menu';
37
4
  export declare const ContextMenu: {
38
5
  Root: typeof BaseContextMenu.Root;
39
6
  Trigger: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuTriggerProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
7
+ Popup: ({ className, ...props }: ComponentProps<typeof Menu.Popup>) => import("react/jsx-runtime").JSX.Element;
40
8
  Portal: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuPortalProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
41
9
  Backdrop: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuBackdropProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
42
- Positioner: ({ className, sideOffset, ...props }: PositionerProps) => import("react/jsx-runtime").JSX.Element;
43
- Popup: ({ className, ...props }: PopupProps) => import("react/jsx-runtime").JSX.Element;
10
+ Positioner: ({ className, sideOffset, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuPositionerProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref"> & {
11
+ ref?: import("react").Ref<HTMLDivElement>;
12
+ }) => import("react/jsx-runtime").JSX.Element;
44
13
  Arrow: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuArrowProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
45
14
  Group: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuGroupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
46
- GroupLabel: ({ className, ...props }: GroupLabelProps) => import("react/jsx-runtime").JSX.Element;
47
- Separator: ({ className, ...props }: SeparatorProps) => import("react/jsx-runtime").JSX.Element;
48
- Item: ({ className, variant, ...props }: ItemProps) => import("react/jsx-runtime").JSX.Element;
49
- LinkItem: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuLinkItemProps, "ref"> & import("react").RefAttributes<Element>>;
50
- CheckboxItem: ({ className, children, ...props }: CheckboxItemProps) => import("react/jsx-runtime").JSX.Element;
15
+ GroupLabel: ({ className, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuGroupLabelProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref"> & {
16
+ ref?: import("react").Ref<HTMLDivElement>;
17
+ }) => import("react/jsx-runtime").JSX.Element;
18
+ Separator: ({ className, ...props }: Omit<Omit<import("@base-ui/react").SeparatorProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref"> & {
19
+ ref?: import("react").Ref<HTMLDivElement>;
20
+ }) => import("react/jsx-runtime").JSX.Element;
21
+ Item: ({ className, variant, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuItemProps, "ref"> & import("react").RefAttributes<HTMLElement>, "ref"> & {
22
+ ref?: import("react").Ref<HTMLDivElement>;
23
+ variant?: "default" | "destructive";
24
+ }) => import("react/jsx-runtime").JSX.Element;
25
+ LinkItem: ({ className, variant, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuLinkItemProps, "ref"> & import("react").RefAttributes<Element>, "ref"> & {
26
+ ref?: import("react").Ref<HTMLAnchorElement>;
27
+ variant?: "default" | "destructive";
28
+ }) => import("react/jsx-runtime").JSX.Element;
29
+ CheckboxItem: ({ className, children, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuCheckboxItemProps, "ref"> & import("react").RefAttributes<HTMLElement>, "ref"> & {
30
+ ref?: import("react").Ref<HTMLDivElement>;
31
+ }) => import("react/jsx-runtime").JSX.Element;
51
32
  RadioGroup: import("react").NamedExoticComponent<Omit<import("@base-ui/react").ContextMenuRadioGroupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
52
- RadioItem: ({ className, children, ...props }: RadioItemProps) => import("react/jsx-runtime").JSX.Element;
33
+ RadioItem: ({ className, children, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuRadioItemProps, "ref"> & import("react").RefAttributes<HTMLElement>, "ref"> & {
34
+ ref?: import("react").Ref<HTMLDivElement>;
35
+ }) => import("react/jsx-runtime").JSX.Element;
53
36
  SubmenuRoot: typeof BaseContextMenu.SubmenuRoot;
54
- SubmenuTrigger: ({ className, children, ...props }: SubmenuTriggerProps) => import("react/jsx-runtime").JSX.Element;
37
+ SubmenuTrigger: ({ className, children, ...props }: Omit<Omit<import("@base-ui/react").ContextMenuSubmenuTriggerProps, "ref"> & import("react").RefAttributes<HTMLElement>, "ref"> & {
38
+ ref?: import("react").Ref<HTMLDivElement>;
39
+ }) => import("react/jsx-runtime").JSX.Element;
55
40
  };
56
- export {};
@@ -1,41 +1,14 @@
1
1
  'use client';
2
- import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
3
  import { ContextMenu as BaseContextMenu } from '@base-ui/react/context-menu';
4
- import { ChevronRight } from 'lucide-react';
5
- import { cn } from '../helpers/cn/cn';
6
4
  import { mergeStatefulClassName } from '../helpers/mergeStatefulClassName/mergeStatefulClassName';
7
- const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover z-50 min-w-45 origin-[var(--transform-origin)] rounded-lg border py-1 outline-hidden transition-[transform,opacity] data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0';
8
- const itemBaseClasses = 'relative flex h-7 cursor-default items-center gap-1.5 rounded-[calc(var(--radius)-0.25rem)] px-2.5 text-[0.8rem] outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[disabled]:pointer-events-none data-[disabled]:opacity-50';
9
- const itemVariantClasses = {
10
- default: 'data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
11
- destructive: 'text-destructive data-[highlighted]:bg-destructive/10 data-[highlighted]:text-destructive',
12
- };
13
- const Positioner = ({ className, sideOffset = 4, ...props }) => (_jsx(BaseContextMenu.Positioner, { sideOffset: sideOffset, className: mergeStatefulClassName('z-50 outline-hidden', className), ...props }));
14
- const Popup = ({ className, ...props }) => (_jsx(BaseContextMenu.Popup, { className: mergeStatefulClassName(popupClasses, className), ...props }));
15
- const Item = ({ className, variant = 'default', ...props }) => (_jsx(BaseContextMenu.Item, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses[variant]), className), ...props }));
16
- const Separator = ({ className, ...props }) => (_jsx(BaseContextMenu.Separator, { className: mergeStatefulClassName('bg-border my-1 h-px', className), ...props }));
17
- const GroupLabel = ({ className, ...props }) => (_jsx(BaseContextMenu.GroupLabel, { className: mergeStatefulClassName('text-muted-foreground px-2.5 py-1 text-xs', className), ...props }));
18
- const CheckboxItem = ({ className, children, ...props }) => (_jsxs(BaseContextMenu.CheckboxItem, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses.default, 'pl-7'), className), ...props, children: [_jsx("span", { "aria-hidden": true, className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(BaseContextMenu.CheckboxItemIndicator, { className: "size-3.5", children: _jsx(CheckIcon, {}) }) }), children] }));
19
- const RadioItem = ({ className, children, ...props }) => (_jsxs(BaseContextMenu.RadioItem, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses.default, 'pl-7'), className), ...props, children: [_jsx("span", { "aria-hidden": true, className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(BaseContextMenu.RadioItemIndicator, { className: "size-3.5", children: _jsx(DotIcon, {}) }) }), children] }));
20
- const SubmenuTrigger = ({ className, children, ...props }) => (_jsxs(BaseContextMenu.SubmenuTrigger, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses.default, 'data-popup-open:bg-accent data-popup-open:text-accent-foreground pr-2'), className), ...props, children: [children, _jsx(ChevronRight, { className: "ml-auto size-4 opacity-60", "aria-hidden": true })] }));
21
- const CheckIcon = () => (_jsx("svg", { viewBox: "0 0 14 14", fill: "none", className: "size-3.5", children: _jsx("path", { d: "M3 7.5 6 10.5 11 4.5", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) }));
22
- const DotIcon = () => (_jsx("svg", { viewBox: "0 0 14 14", className: "size-3.5", children: _jsx("circle", { cx: "7", cy: "7", r: "3", fill: "currentColor" }) }));
5
+ import { Menu } from '../Menu/Menu';
6
+ // Base UI's ContextMenu is Menu with its own Root and Trigger; every other part is the same
7
+ // component, so the styled Menu parts apply as-is. A context menu just opens a little wider.
8
+ const Popup = ({ className, ...props }) => (_jsx(Menu.Popup, { className: mergeStatefulClassName('min-w-45', className), ...props }));
23
9
  export const ContextMenu = {
10
+ ...Menu,
24
11
  Root: BaseContextMenu.Root,
25
12
  Trigger: BaseContextMenu.Trigger,
26
- Portal: BaseContextMenu.Portal,
27
- Backdrop: BaseContextMenu.Backdrop,
28
- Positioner,
29
13
  Popup,
30
- Arrow: BaseContextMenu.Arrow,
31
- Group: BaseContextMenu.Group,
32
- GroupLabel,
33
- Separator,
34
- Item,
35
- LinkItem: BaseContextMenu.LinkItem,
36
- CheckboxItem,
37
- RadioGroup: BaseContextMenu.RadioGroup,
38
- RadioItem,
39
- SubmenuRoot: BaseContextMenu.SubmenuRoot,
40
- SubmenuTrigger,
41
14
  };
package/dist/Kbd/Kbd.js CHANGED
@@ -1,5 +1,6 @@
1
1
  'use client';
2
2
  import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { useSyncExternalStore } from 'react';
3
4
  import { getModKey } from '../helpers/getModKey/getModKey';
4
5
  import { cn } from '../helpers/cn/cn';
5
6
  import { kbdVariants } from './Kbd.variants';
@@ -16,16 +17,22 @@ const KEY_SYMBOLS = {
16
17
  up: '↑',
17
18
  down: '↓',
18
19
  };
19
- const resolveKey = (key) => {
20
+ const resolveKey = (key, modKey) => {
20
21
  const lower = key.toLowerCase();
21
22
  if (lower === 'mod')
22
- return MOD_SYMBOLS[getModKey()] ?? 'Ctrl';
23
+ return MOD_SYMBOLS[modKey] ?? 'Ctrl';
23
24
  if (lower === 'ctrl')
24
- return getModKey() === 'Cmd' ? '⌃' : 'Ctrl';
25
+ return modKey === 'Cmd' ? '⌃' : 'Ctrl';
25
26
  return KEY_SYMBOLS[lower] ?? key;
26
27
  };
28
+ // The platform never changes after load, so there is nothing to subscribe to. The server
29
+ // snapshot pins SSR and hydration to the non-Mac glyphs; React then re-renders with the
30
+ // client's real platform, so Mac users get ⌘ without a hydration mismatch.
31
+ const subscribeToNothing = () => () => { };
32
+ const getServerModKey = () => 'Ctrl';
27
33
  const Kbd = ({ keys, size, className }) => {
28
34
  const keyList = Array.isArray(keys) ? keys : [keys];
29
- return (_jsx("span", { className: "inline-flex items-center gap-0.5", role: "presentation", children: keyList.map((key, i) => (_jsx("kbd", { className: cn(kbdVariants({ size }), className), children: resolveKey(key) }, i))) }));
35
+ const modKey = useSyncExternalStore(subscribeToNothing, getModKey, getServerModKey);
36
+ return (_jsx("span", { className: "inline-flex items-center gap-0.5", role: "presentation", children: keyList.map((key, i) => (_jsx("kbd", { className: cn(kbdVariants({ size }), className), children: resolveKey(key, modKey) }, i))) }));
30
37
  };
31
38
  export { Kbd };
@@ -8,6 +8,7 @@ type BaseGroupLabelProps = ComponentPropsWithoutRef<typeof BaseMenu.GroupLabel>;
8
8
  type BaseSubmenuTriggerProps = ComponentPropsWithoutRef<typeof BaseMenu.SubmenuTrigger>;
9
9
  type BaseCheckboxItemProps = ComponentPropsWithoutRef<typeof BaseMenu.CheckboxItem>;
10
10
  type BaseRadioItemProps = ComponentPropsWithoutRef<typeof BaseMenu.RadioItem>;
11
+ type BaseLinkItemProps = ComponentPropsWithoutRef<typeof BaseMenu.LinkItem>;
11
12
  type ItemVariant = 'default' | 'destructive';
12
13
  type PositionerProps = BasePositionerProps & {
13
14
  ref?: Ref<HTMLDivElement>;
@@ -16,7 +17,7 @@ type PopupProps = BasePopupProps & {
16
17
  ref?: Ref<HTMLDivElement>;
17
18
  };
18
19
  type SeparatorProps = BaseSeparatorProps & {
19
- ref?: Ref<HTMLHRElement>;
20
+ ref?: Ref<HTMLDivElement>;
20
21
  };
21
22
  type GroupLabelProps = BaseGroupLabelProps & {
22
23
  ref?: Ref<HTMLDivElement>;
@@ -25,6 +26,10 @@ type ItemProps = BaseItemProps & {
25
26
  ref?: Ref<HTMLDivElement>;
26
27
  variant?: ItemVariant;
27
28
  };
29
+ type LinkItemProps = BaseLinkItemProps & {
30
+ ref?: Ref<HTMLAnchorElement>;
31
+ variant?: ItemVariant;
32
+ };
28
33
  type CheckboxItemProps = BaseCheckboxItemProps & {
29
34
  ref?: Ref<HTMLDivElement>;
30
35
  };
@@ -46,7 +51,7 @@ export declare const Menu: {
46
51
  GroupLabel: ({ className, ...props }: GroupLabelProps) => import("react/jsx-runtime").JSX.Element;
47
52
  Separator: ({ className, ...props }: SeparatorProps) => import("react/jsx-runtime").JSX.Element;
48
53
  Item: ({ className, variant, ...props }: ItemProps) => import("react/jsx-runtime").JSX.Element;
49
- LinkItem: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").ContextMenuLinkItemProps, "ref"> & import("react").RefAttributes<Element>>;
54
+ LinkItem: ({ className, variant, ...props }: LinkItemProps) => import("react/jsx-runtime").JSX.Element;
50
55
  CheckboxItem: ({ className, children, ...props }: CheckboxItemProps) => import("react/jsx-runtime").JSX.Element;
51
56
  RadioGroup: import("react").NamedExoticComponent<Omit<import("@base-ui/react").ContextMenuRadioGroupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
52
57
  RadioItem: ({ className, children, ...props }: RadioItemProps) => import("react/jsx-runtime").JSX.Element;
package/dist/Menu/Menu.js CHANGED
@@ -4,7 +4,7 @@ import { Menu as BaseMenu } from '@base-ui/react/menu';
4
4
  import { ChevronRight } from 'lucide-react';
5
5
  import { cn } from '../helpers/cn/cn';
6
6
  import { mergeStatefulClassName } from '../helpers/mergeStatefulClassName/mergeStatefulClassName';
7
- const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover z-50 min-w-36 origin-[var(--transform-origin)] rounded-lg border py-1 outline-hidden transition-[transform,opacity] data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0';
7
+ const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover z-50 min-w-36 origin-[var(--transform-origin)] rounded-lg border py-1 outline-hidden transition-[scale,opacity] data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0 motion-reduce:transition-none';
8
8
  const itemBaseClasses = 'relative flex h-7 cursor-default items-center gap-1.5 rounded-[calc(var(--radius)-0.25rem)] px-2.5 text-[0.8rem] outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[disabled]:pointer-events-none data-[disabled]:opacity-50';
9
9
  const itemVariantClasses = {
10
10
  default: 'data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
@@ -13,6 +13,7 @@ const itemVariantClasses = {
13
13
  const Positioner = ({ className, sideOffset = 4, ...props }) => (_jsx(BaseMenu.Positioner, { sideOffset: sideOffset, className: mergeStatefulClassName('z-50 outline-hidden', className), ...props }));
14
14
  const Popup = ({ className, ...props }) => (_jsx(BaseMenu.Popup, { className: mergeStatefulClassName(popupClasses, className), ...props }));
15
15
  const Item = ({ className, variant = 'default', ...props }) => (_jsx(BaseMenu.Item, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses[variant]), className), ...props }));
16
+ const LinkItem = ({ className, variant = 'default', ...props }) => (_jsx(BaseMenu.LinkItem, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses[variant]), className), ...props }));
16
17
  const Separator = ({ className, ...props }) => (_jsx(BaseMenu.Separator, { className: mergeStatefulClassName('bg-border my-1 h-px', className), ...props }));
17
18
  const GroupLabel = ({ className, ...props }) => (_jsx(BaseMenu.GroupLabel, { className: mergeStatefulClassName('text-muted-foreground px-2.5 py-1 text-xs', className), ...props }));
18
19
  const CheckboxItem = ({ className, children, ...props }) => (_jsxs(BaseMenu.CheckboxItem, { className: mergeStatefulClassName(cn(itemBaseClasses, itemVariantClasses.default, 'pl-7'), className), ...props, children: [_jsx("span", { "aria-hidden": true, className: "absolute left-2 flex size-3.5 items-center justify-center", children: _jsx(BaseMenu.CheckboxItemIndicator, { className: "size-3.5", children: _jsx(CheckIcon, {}) }) }), children] }));
@@ -32,7 +33,7 @@ export const Menu = {
32
33
  GroupLabel,
33
34
  Separator,
34
35
  Item,
35
- LinkItem: BaseMenu.LinkItem,
36
+ LinkItem,
36
37
  CheckboxItem,
37
38
  RadioGroup: BaseMenu.RadioGroup,
38
39
  RadioItem,
@@ -70,6 +70,27 @@ function assignRef(ref, element) {
70
70
  ;
71
71
  ref.current = element;
72
72
  }
73
+ // Returns a ref callback that stays the same across renders and also forwards the element to
74
+ // the consumer's `ref`. An inline `ref={node => ...}` is a new function every render; if our
75
+ // callback changed with it, React would detach and reattach the element each render, and
76
+ // detaching resets the scroller.
77
+ function useForwardedRef(ref, onElement) {
78
+ const elementRef = useRef(null);
79
+ const forwardedRef = useRef(ref);
80
+ useLayoutEffect(() => {
81
+ if (forwardedRef.current === ref) {
82
+ return;
83
+ }
84
+ assignRef(forwardedRef.current, null);
85
+ forwardedRef.current = ref;
86
+ assignRef(ref, elementRef.current);
87
+ });
88
+ return useCallback((element) => {
89
+ elementRef.current = element;
90
+ onElement(element);
91
+ assignRef(forwardedRef.current, element);
92
+ }, [onElement]);
93
+ }
73
94
  function getMessageElements(contentElement, spacerElement) {
74
95
  if (!contentElement) {
75
96
  return [];
@@ -102,6 +123,18 @@ function canKeyboardScroll(viewportElement, event) {
102
123
  }
103
124
  return false;
104
125
  }
126
+ // Keys pressed in a text field move its caret or change its value, and Space presses a button.
127
+ // Neither scrolls the viewport, so they don't mean the reader took over.
128
+ function isKeyHandledByTarget(event) {
129
+ const target = event.target;
130
+ if (!(target instanceof HTMLElement)) {
131
+ return false;
132
+ }
133
+ if (target.isContentEditable || target.matches('input, select, textarea')) {
134
+ return true;
135
+ }
136
+ return event.key === ' ' && target.matches('button, summary');
137
+ }
105
138
  function getElementTop(element, viewportElement) {
106
139
  const elementRectangle = element.getBoundingClientRect();
107
140
  const viewportRectangle = viewportElement.getBoundingClientRect();
@@ -187,8 +220,10 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
187
220
  const userScrollIntentRef = useRef(false);
188
221
  // Smooth bottom scrolls can briefly measure as away from bottom while still settling.
189
222
  const bottomFollowIntentRef = useRef(autoFollow);
190
- const ignoreAnchoredBottomResumeFrameRef = useRef(null);
191
- const ignoreAnchoredBottomResumeRef = useRef(false);
223
+ const lastScrollTopRef = useRef(0);
224
+ // Where the current jump is headed. A smooth jump sends scroll events for many frames, and one
225
+ // that lands on the bottom must not read as the reader scrolling there to resume following.
226
+ const jumpInFlightRef = useRef(null);
192
227
  const pendingDefaultScrollFrameRef = useRef(null);
193
228
  const pendingSyncFrameRef = useRef(null);
194
229
  const pendingScrollToMessageRef = useRef(null);
@@ -266,6 +301,17 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
266
301
  const commitStatus = useCallback(() => {
267
302
  const status = measureStatus();
268
303
  const isAnchoredMode = modeRef.current === 'anchored-to-message' || modeRef.current === 'settling-jump';
304
+ const scrollTop = viewportElementRef.current?.scrollTop ?? 0;
305
+ const scrolledUp = scrollTop < lastScrollTopRef.current - SCROLL_TOLERANCE;
306
+ lastScrollTopRef.current = scrollTop;
307
+ // Following never scrolls up on its own, so moving up means someone else scrolled: a
308
+ // scrollbar drag, find-in-page, or scrollIntoView. None of those fire wheel, touch, or key
309
+ // input, so treat them as the reader taking over.
310
+ if (scrolledUp && modeRef.current === 'following-bottom' && !status.isAtBottom) {
311
+ autoscrollingRef.current = false;
312
+ bottomFollowIntentRef.current = false;
313
+ modeRef.current = 'free-scrolling';
314
+ }
269
315
  if (status.isAtBottom) {
270
316
  userScrollIntentRef.current = false;
271
317
  }
@@ -351,16 +397,6 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
351
397
  syncVisibility();
352
398
  capturePrependAnchor();
353
399
  }, [capturePrependAnchor, commitStatus, syncVisibility]);
354
- const ignoreAnchoredBottomResumeForCurrentFrame = useCallback(() => {
355
- ignoreAnchoredBottomResumeRef.current = true;
356
- if (ignoreAnchoredBottomResumeFrameRef.current !== null) {
357
- window.cancelAnimationFrame(ignoreAnchoredBottomResumeFrameRef.current);
358
- }
359
- ignoreAnchoredBottomResumeFrameRef.current = window.requestAnimationFrame(() => {
360
- ignoreAnchoredBottomResumeFrameRef.current = null;
361
- ignoreAnchoredBottomResumeRef.current = false;
362
- });
363
- }, []);
364
400
  const scheduleSyncAfterScroll = useCallback(() => {
365
401
  if (pendingSyncFrameRef.current !== null) {
366
402
  return;
@@ -447,15 +483,12 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
447
483
  setSpacerHeight(spacerHeight);
448
484
  anchoredElementRef.current = keepPreviousItemPeek ? element : null;
449
485
  modeRef.current = keepPreviousItemPeek ? 'anchored-to-message' : 'settling-jump';
450
- ignoreAnchoredBottomResumeForCurrentFrame();
486
+ jumpInFlightRef.current = {
487
+ distance: Math.abs(viewportElement.scrollTop - Math.max(0, targetScrollTop)),
488
+ targetScrollTop: Math.max(0, targetScrollTop),
489
+ };
451
490
  return scrollToTopValue(targetScrollTop, { behavior });
452
- }, [
453
- clearSpacer,
454
- ignoreAnchoredBottomResumeForCurrentFrame,
455
- scrollToTopValue,
456
- setAutoscrolling,
457
- setSpacerHeight,
458
- ]);
491
+ }, [clearSpacer, scrollToTopValue, setAutoscrolling, setSpacerHeight]);
459
492
  const scrollToAnchorElement = useCallback((element, options = {}) => scrollToElement(element, {
460
493
  align: 'start',
461
494
  behavior: options.behavior,
@@ -491,6 +524,11 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
491
524
  }
492
525
  const element = messageElementsRef.current.get(pendingScrollToMessage.messageId);
493
526
  if (!element) {
527
+ // The jump waited for messages, and these don't have its target. Drop it like a direct
528
+ // miss, or it would fire whenever that id shows up later and yank the reader there.
529
+ if (messageElementsRef.current.size > 0) {
530
+ pendingScrollToMessageRef.current = null;
531
+ }
494
532
  return false;
495
533
  }
496
534
  pendingScrollToMessageRef.current = null;
@@ -601,7 +639,9 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
601
639
  }, [scrollToAnchorElement]);
602
640
  const handleContentChange = useCallback(() => {
603
641
  const contentElement = contentElementRef.current;
604
- if (!contentElement) {
642
+ // Content's layout effects run before the Viewport's ref attaches when both mount together.
643
+ // Wait for the Viewport's own pass instead of spending queued jumps and anchors on nothing.
644
+ if (!contentElement || !viewportElementRef.current) {
605
645
  return;
606
646
  }
607
647
  if (flushPendingScrollToMessage()) {
@@ -658,8 +698,16 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
658
698
  }, [reanchorToAnchoredMessage, scrollToBottom, syncAfterScroll]);
659
699
  const handleViewportScroll = useCallback(() => {
660
700
  syncAfterScroll();
661
- if (ignoreAnchoredBottomResumeRef.current) {
662
- return;
701
+ const jump = jumpInFlightRef.current;
702
+ if (jump && viewportElementRef.current) {
703
+ const distance = Math.abs(viewportElementRef.current.scrollTop - jump.targetScrollTop);
704
+ // Closing in on the target, or resting on it, is the jump itself. Moving away is someone
705
+ // else scrolling, so from then on the bottom check below applies.
706
+ if (distance <= jump.distance + SCROLL_TOLERANCE) {
707
+ jump.distance = Math.min(jump.distance, distance);
708
+ return;
709
+ }
710
+ jumpInFlightRef.current = null;
663
711
  }
664
712
  const status = measureStatus();
665
713
  const isAnchoredMode = modeRef.current === 'anchored-to-message' || modeRef.current === 'settling-jump';
@@ -676,6 +724,7 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
676
724
  }, [clearSpacer, measureStatus, syncAfterScroll]);
677
725
  const markUserScrollIntent = useCallback(() => {
678
726
  userScrollIntentRef.current = true;
727
+ jumpInFlightRef.current = null;
679
728
  if (modeRef.current === 'following-bottom' ||
680
729
  modeRef.current === 'anchored-to-message' ||
681
730
  modeRef.current === 'settling-jump') {
@@ -719,7 +768,7 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
719
768
  userScrollIntentRef.current = false;
720
769
  defaultScrollPositionAppliedRef.current = false;
721
770
  prependRestoreRef.current = null;
722
- ignoreAnchoredBottomResumeRef.current = false;
771
+ jumpInFlightRef.current = null;
723
772
  visibilityStore.setSnapshot(DEFAULT_VISIBILITY);
724
773
  scheduleSyncAfterScroll();
725
774
  }, [clearSpacer, scheduleSyncAfterScroll, visibilityStore]);
@@ -735,9 +784,6 @@ function useMessageScrollerEngine({ autoFollow, defaultScrollPosition, scrollEdg
735
784
  if (pendingDefaultScrollFrameRef.current !== null) {
736
785
  window.cancelAnimationFrame(pendingDefaultScrollFrameRef.current);
737
786
  }
738
- if (ignoreAnchoredBottomResumeFrameRef.current !== null) {
739
- window.cancelAnimationFrame(ignoreAnchoredBottomResumeFrameRef.current);
740
- }
741
787
  }, []);
742
788
  return useMemo(() => ({
743
789
  handleContentChange,
@@ -797,10 +843,7 @@ function MessageScrollerViewport({ 'aria-label': ariaLabel, children, className,
797
843
  const { handleContentChange, handleResize, handleViewportScroll, markUserScrollIntent, preserveScrollOnPrependRef, setViewportElement, viewportElementRef, } = useMessageScrollerContext('MessageScroller.Viewport');
798
844
  const touchClientYRef = useRef(null);
799
845
  preserveScrollOnPrependRef.current = preserveScrollOnPrepend;
800
- const handleRef = useCallback((element) => {
801
- setViewportElement(element);
802
- assignRef(ref, element);
803
- }, [ref, setViewportElement]);
846
+ const handleRef = useForwardedRef(ref, setViewportElement);
804
847
  useLayoutEffect(() => {
805
848
  handleContentChange();
806
849
  }, [handleContentChange]);
@@ -842,6 +885,7 @@ function MessageScrollerViewport({ 'aria-label': ariaLabel, children, className,
842
885
  onKeyDown?.(event);
843
886
  if (!event.defaultPrevented &&
844
887
  USER_SCROLL_INTENT_KEYS.has(event.key) &&
888
+ !isKeyHandledByTarget(event) &&
845
889
  canKeyboardScroll(event.currentTarget, event)) {
846
890
  markUserScrollIntent();
847
891
  }
@@ -862,12 +906,11 @@ function MessageScrollerContent({ 'aria-relevant': ariaRelevant, children, class
862
906
  const contentElementRef = useRef(null);
863
907
  const contentSignatureRef = useRef('');
864
908
  const spacerElementRef = useRef(null);
865
- const handleContentRef = useCallback((element) => {
909
+ const handleContentRef = useForwardedRef(ref, useCallback((element) => {
866
910
  contentElementRef.current = element;
867
911
  contentSignatureRef.current = '';
868
912
  setContentElement(element);
869
- assignRef(ref, element);
870
- }, [ref, setContentElement]);
913
+ }, [setContentElement]));
871
914
  const handleSpacerRef = useCallback((element) => {
872
915
  spacerElementRef.current = element;
873
916
  setSpacerElement(element);
@@ -7,7 +7,7 @@ const POPOVER_COLLISION_AVOIDANCE = {
7
7
  align: 'shift',
8
8
  fallbackAxisSide: 'none',
9
9
  };
10
- const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover box-border max-h-[var(--available-height)] max-w-[var(--available-width)] origin-[var(--transform-origin)] overflow-x-hidden overflow-y-auto rounded-lg border outline-hidden transition-[transform,opacity] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] data-[ending-style]:scale-[0.98] data-[ending-style]:opacity-0 data-[instant]:transition-none data-[starting-style]:scale-[0.98] data-[starting-style]:opacity-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3 focus-visible:transition-none motion-reduce:transform-none motion-reduce:transition-none';
10
+ const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover box-border max-h-[var(--available-height)] max-w-[var(--available-width)] origin-[var(--transform-origin)] overflow-x-hidden overflow-y-auto rounded-lg border outline-hidden transition-[scale,opacity] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] data-[ending-style]:scale-[0.98] data-[ending-style]:opacity-0 data-[instant]:transition-none data-[starting-style]:scale-[0.98] data-[starting-style]:opacity-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3 focus-visible:transition-none motion-reduce:transition-none';
11
11
  const Positioner = ({ className, sideOffset = 6, collisionPadding = 8, collisionAvoidance = POPOVER_COLLISION_AVOIDANCE, positionMethod = 'fixed', ...props }) => (_jsx(BasePopover.Positioner, { sideOffset: sideOffset, collisionPadding: collisionPadding, collisionAvoidance: collisionAvoidance, positionMethod: positionMethod, className: mergeStatefulClassName('z-50 outline-hidden', className), ...props }));
12
12
  const Popup = ({ className, ...props }) => (_jsx(BasePopover.Popup, { className: mergeStatefulClassName(popupClasses, className), ...props }));
13
13
  /** Accessible floating disclosure over Base UI Popover. The popup supplies the semantic surface,
@@ -13,7 +13,7 @@ const TOOLTIP_COLLISION_AVOIDANCE = {
13
13
  align: 'shift',
14
14
  fallbackAxisSide: 'none',
15
15
  };
16
- const popupClasses = 'bg-foreground text-background shadow-popover pointer-events-none flex origin-[var(--transform-origin)] items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs transition-[transform,opacity] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] data-[ending-style]:scale-[0.97] data-[ending-style]:opacity-0 data-[instant]:transition-none data-[starting-style]:scale-[0.97] data-[starting-style]:opacity-0 motion-reduce:transform-none motion-reduce:transition-none';
16
+ const popupClasses = 'bg-foreground text-background shadow-popover pointer-events-none flex origin-[var(--transform-origin)] items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs transition-[scale,opacity] duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] data-[ending-style]:scale-[0.97] data-[ending-style]:opacity-0 data-[instant]:transition-none data-[starting-style]:scale-[0.97] data-[starting-style]:opacity-0 motion-reduce:transition-none';
17
17
  const Positioner = ({ className, sideOffset = TRIGGER_GAP, collisionPadding = VIEWPORT_MARGIN, collisionAvoidance = TOOLTIP_COLLISION_AVOIDANCE, positionMethod = 'fixed', ...props }) => (_jsx(BaseTooltip.Positioner, { sideOffset: sideOffset, collisionPadding: collisionPadding, collisionAvoidance: collisionAvoidance, positionMethod: positionMethod, className: mergeStatefulClassName('z-50 outline-hidden', className), ...props }));
18
18
  const Popup = ({ className, role = 'tooltip', ...props }) => (_jsx(BaseTooltip.Popup, { role: role, className: mergeStatefulClassName(popupClasses, className), ...props }));
19
19
  const TooltipComponent = ({ label, shortcut, position = 'top', delay = DEFAULT_DELAY, maxWidth, disabled, className, children, }) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carbonid1/design-system",
3
- "version": "7.3.1",
3
+ "version": "7.4.0",
4
4
  "description": "Shared React UI primitives + design tokens (themes, postcss config)",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,137 +1,52 @@
1
1
  ---
2
2
  name: design-system
3
- description: 'Shared UI components and design patterns for carbonid1 apps built on @carbonid1/design-system. ALWAYS use when building UI, creating components, styling Typeset or Markdown prose, adding dropdowns, selects, tooltips, icons, toasts, context menus, badges, or any interactive element. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, typeset, prose, Markdown rendering, using the design system, layout shift, skeleton, context menu, right-click menu, button, theme, palette. To MODIFY @carbonid1/design-system itself — add or change a primitive, token, variant, or the barrel/exports — use the design-system-package skill instead.'
3
+ description: Build or edit app UI using @carbonid1/design-system. For changes to the shared package itself, use design-system-package.
4
4
  ---
5
5
 
6
6
  # Design System
7
7
 
8
- Primitives live in `@carbonid1/design-system`. **Check the package's exports and types before building anything new.** This file is direction and taste, not API reference — the types are the docs.
9
-
10
- ```ts
11
- import {
12
- Badge,
13
- Button,
14
- buttonVariants,
15
- Kbd,
16
- ProgressRing,
17
- Slider,
18
- ContextMenu,
19
- Select,
20
- Tooltip,
21
- Toaster,
22
- toast,
23
- ThemeProvider,
24
- ThemeCycler,
25
- useTheme,
26
- cn,
27
- getModKey,
28
- useHotkeys,
29
- } from '@carbonid1/design-system'
30
- ```
31
-
32
- Palettes are chosen by importing one theme CSS per app: `@carbonid1/design-system/themes/reader` (InkVoice) or `/themes/dashboard` (CoI Calculator).
33
-
34
- If you're editing `@carbonid1/design-system` itself (adding a primitive, changing a token), use the `design-system-package` skill — this file is for _using_ the design system, not building it.
35
-
36
- ## Core rules
37
-
38
- - Never build a tooltip, context menu, or toast from scratch — use `Tooltip`, `ContextMenu`, `toast()`
39
- - All icons from `lucide-react` — search `lucide.dev/icons` before creating anything custom. If nothing fits, build via Lucide's `Icon` + `iconNode`, don't reach for another library.
40
- - All color through semantic tokens — no hardcoded Tailwind color classes. See [references/theming.md](references/theming.md).
41
- - **Missing a token or primitive? Surface it, don't invent one.** When the palette has no token — or the package no component — for what you're building, stop and ask the user, offering 2–3 concrete paths (extend the design system, compose what's already there, or a deliberately-scoped one-off). A silent one-off forks the system: these tokens exist so a single decision propagates everywhere, and a bespoke color or component quietly breaks that. Asking is cheap; an unnoticed fork is expensive to unwind later.
42
- - Tooltip: rely on defaults (`position="top"`, `delay={400}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`, a snappy reveal → a lower `delay`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
43
- - Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
44
-
45
- ## Typeset prose
46
-
47
- Typeset owns semantic document presentation; the application still owns parsing, streaming, and
48
- custom component rendering.
49
-
50
- ```css
51
- @import '@carbonid1/design-system/typesets/base';
52
- @import '@carbonid1/design-system/typesets/compact';
53
- ```
54
-
55
- Apply `typeset typeset-compact` to the rendered document root. Import the base stylesheet once, then
56
- only the presets that application uses. Add `.not-typeset` or `[data-not-typeset]` around injected
57
- application components that must retain their own design-system styling.
58
-
59
- ## Buttons & links
60
-
61
- - **Active/selected state** — pass `selected` (toolbar toggles, segmented controls, filter chips, tabs, nav links). It applies the selection tokens (`bg-primary/10` + `ring-1 ring-primary/20`, tint held on hover); never hand-layer those classes. `selected` is visual only — set the matching ARIA yourself: `aria-pressed` on toggle buttons, `aria-current` on nav links. It rides both `Button` and `buttonVariants(...)`.
62
- - **Dialog actions** — `Dialog.Trigger` and `Dialog.Close` supply behavior, not button appearance. Compose a `Button` through `render` so one component owns the complete visual contract; don't attach `buttonVariants(...)` to the behavior primitive.
63
- ```tsx
64
- <Dialog.Close
65
- render={
66
- <Button variant="ghost" size="small">
67
- Cancel
68
- </Button>
69
- }
70
- />
71
- ```
72
- - **A link that looks like a button** — apply `buttonVariants({ variant, size, selected })` to the `Link`, not `<Button render={<Link/>}>`. Base UI's `Button` is button-semantic: rendering an `<a>` through it either warns or forces `role="button"`, which breaks navigation for screen readers. Keep the element a real link and style it:
73
- ```tsx
74
- <Link
75
- href={href}
76
- aria-current={active ? 'page' : undefined}
77
- className={cn(buttonVariants({ variant: 'ghost', size: 'small', selected: active }))}
78
- >
79
- {label}
80
- </Link>
81
- ```
82
- The `cn(...)` wrap is load-bearing, not cosmetic: `buttonVariants` is cva, which concatenates without merging, so only `cn`, which merges conflicting classes, drops the variant's own `hover:bg-accent` in favor of the `selected` tint.
83
-
84
- ## Visual Language
85
-
86
- - **Discrete elements** — rows/cards use `rounded-lg` with `space-y-1` gaps, never flat lists with hairline dividers
87
- - **Selection** — `bg-primary/10` tint + `ring-1 ring-primary/20`, never border-left accents
88
- - **Hover reveal** — action buttons use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100` with outer row `hover:bg-accent`. The `group-focus-within` is required — without it, keyboard users tab to an invisible button.
89
- - **Metadata** — use the quietest representation that preserves scanning. Reserve
90
- badges/chips for concise categorical states, filters, or individually
91
- interactive values; prefer secondary text, alignment, grouping, icons, or
92
- restrained surface tone for routine facts. Do not expose an internal category
93
- or repeat information merely because a `Badge` primitive exists.
94
- - **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
95
- - **Avatars** — only with real images, no letter/initial placeholders
96
-
97
- ## Elevation
98
-
99
- Four-tier contract — every themed surface picks one of these tokens. Layering is recessed: cards are sheets on the desk, controls are carved INTO sheets, popovers lift OFF the desk.
100
-
101
- | Token | Role | Pair with |
102
- | ------------------ | --------------------------------------- | ---------------------- |
103
- | `bg-background` | Page (the desk) | — |
104
- | `bg-card` | Raised paper on the desk — peak surface | `shadow-card` |
105
- | `bg-surface-inset` | Inset block carved into a card | `inset-shadow-surface` |
106
- | `bg-popover` | Floating layer above everything | `shadow-popover` |
107
-
108
- `bg-surface-inset` covers form inputs, preview boxes, quote blocks, and language tabs. `bg-popover` covers drawers, menus, and command palettes.
109
-
110
- **`bg-muted`, `bg-accent`, `bg-secondary` are RESERVED for interaction states** — hover backgrounds, skeleton placeholders, badge fills, soft tints. They are never the background of a card or an inset block. Mixing them in breaks the layering contract; see [references/theming.md](references/theming.md) for the deeper rationale.
111
-
112
- **Empty placeholders** — when a slot is meant to be filled (`AddBookCard`, file drop zone, audio preview slot before recording), render a transparent or background-matched surface with `border-dashed`. The empty state reads as a missing piece on its parent surface — never as a recessed input or a card. Once filled, swap to a solid border and the surface adopts its real elevation.
113
-
114
- ## Destructive Actions
115
-
116
- Two tiers. Pick by how hard the action is to redo, not how scary it feels.
117
-
118
- | Severity | Pattern | Example |
119
- | ---------------- | ---------------------------- | ------------------------------------ |
120
- | **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
121
- | **Easy to redo** | No confirmation | Toggle flag, remove a tag |
122
-
123
- **Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `useHotkeys` (re-exported from the design system) → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.
124
-
125
- ## Layout Stability
126
-
127
- Skeleton → real UI transitions must not shift layout. The skeleton is a dimensional contract.
128
-
129
- - Skeletons match real UI structure, counts, heights, spacing. Update the skeleton when the real UI changes.
130
- - Async elements that always render (selectors, user controls) show a same-sized placeholder while loading — never `null`.
131
- - Doesn't apply to user-triggered UI (modals, drawers, toasts) or conditional banners — these are unpredictable by nature.
132
-
133
- ## Theming
134
-
135
- `ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.
136
-
137
- Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.
8
+ Use `@carbonid1/design-system` primitives and semantic tokens. Check the relevant
9
+ exports and types before adding a component; they are the API reference.
10
+
11
+ ## Shared constraints
12
+
13
+ - Use `Tooltip`, `ContextMenu`, and `toast()` for those interactions.
14
+ - Use `lucide-react` icons. Search the Lucide icon catalog before creating a
15
+ custom icon with Lucide's `Icon` and `iconNode`.
16
+ - Use semantic color tokens. Surfaces use `bg-background`, `bg-card` with
17
+ `shadow-card`, `bg-surface-inset` with `inset-shadow-surface`, or `bg-popover`
18
+ with `shadow-popover`. Reserve `bg-muted`, `bg-accent`, and `bg-secondary` for
19
+ interaction states and fills, never card or inset surfaces.
20
+ - For a missing capability, compose existing primitives when they satisfy the
21
+ requirement. If the task requires extending the shared package and that work
22
+ is within the authorized scope, use `design-system-package` and continue.
23
+ Ask when an unresolved product decision or work beyond that scope needs user input. Keep
24
+ reusable tokens and primitives in the package; avoid silent app-local forks.
25
+
26
+ ## Visual language
27
+
28
+ - Rows and cards use `rounded-lg` with `space-y-1` gaps, not hairline dividers.
29
+ - Selected buttons and button-styled links use `selected` with the appropriate
30
+ ARIA state. The system owns the selection tint and ring; avoid border-left
31
+ accents. See the controls reference for composition details.
32
+ - Hover actions use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100`
33
+ with outer-row `hover:bg-accent` so keyboard focus reveals the action.
34
+ - Reserve badges for categorical states, filters, or interactive values. Use
35
+ secondary text, alignment, or grouping for routine facts; omit internal or
36
+ redundant categories.
37
+ - Icon buttons use at least `p-1.5`, with icons at least `w-4 h-4`.
38
+ - Avatars use real images, without letter or initial placeholders.
39
+ - Skeletons match the real structure, counts, dimensions, and spacing. Async
40
+ elements that always render reserve their space; user-triggered UI and
41
+ conditional banners do not need advance placeholders.
42
+ - Empty fillable slots use transparent or background-matched surfaces with a
43
+ dashed border. Filled slots adopt their real elevation and a solid border.
44
+
45
+ ## Read for the affected UI
46
+
47
+ - Buttons, links, dialog actions, tooltips, and toggles:
48
+ [controls](references/controls.md).
49
+ - Typeset or Markdown prose: [Typeset](references/typeset.md).
50
+ - Delete and removal interactions: [destructive actions](references/destructive-actions.md).
51
+ - Palette setup, color roles, and elevation details:
52
+ [theming](references/theming.md).
@@ -0,0 +1,29 @@
1
+ # Controls and links
2
+
3
+ - **Active/selected state** — pass `selected` (toolbar toggles, segmented controls, filter chips, tabs, nav links). It applies the selection tokens (`bg-primary/10` + `ring-1 ring-primary/20`, tint held on hover); never hand-layer those classes. `selected` is visual only — set the matching ARIA yourself: `aria-pressed` on toggle buttons, `aria-current` on nav links. It rides both `Button` and `buttonVariants(...)`.
4
+ - **Dialog actions** — `Dialog.Trigger` and `Dialog.Close` supply behavior, not button appearance. Compose a `Button` through `render` so one component owns the complete visual contract; don't attach `buttonVariants(...)` to the behavior primitive.
5
+ ```tsx
6
+ <Dialog.Close
7
+ render={
8
+ <Button variant="ghost" size="small">
9
+ Cancel
10
+ </Button>
11
+ }
12
+ />
13
+ ```
14
+ - **A link that looks like a button** — apply `buttonVariants({ variant, size, selected })` to the `Link`, not `<Button render={<Link/>}>`. Base UI's `Button` is button-semantic: rendering an `<a>` through it either warns or forces `role="button"`, which breaks navigation for screen readers. Keep the element a real link and style it:
15
+ ```tsx
16
+ <Link
17
+ href={href}
18
+ aria-current={active ? 'page' : undefined}
19
+ className={cn(buttonVariants({ variant: 'ghost', size: 'small', selected: active }))}
20
+ >
21
+ {label}
22
+ </Link>
23
+ ```
24
+ The `cn(...)` wrap is load-bearing, not cosmetic: `buttonVariants` is cva, which concatenates without merging, so only `cn`, which merges conflicting classes, drops the variant's own `hover:bg-accent` in favor of the `selected` tint.
25
+
26
+ ## Tooltips and icon toggles
27
+
28
+ - Tooltip: rely on defaults (`position="top"`, `delay={400}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`, a snappy reveal → a lower `delay`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
29
+ - Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
@@ -0,0 +1,10 @@
1
+ # Destructive actions
2
+
3
+ Two tiers. Pick by how hard the action is to redo, not how scary it feels.
4
+
5
+ | Severity | Pattern | Example |
6
+ | ---------------- | ---------------------------- | ------------------------------------ |
7
+ | **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
8
+ | **Easy to redo** | No confirmation | Toggle flag, remove a tag |
9
+
10
+ **Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `useHotkeys` (re-exported from the design system) → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.
@@ -27,7 +27,7 @@ Primitives must render correctly under every palette × light/dark combination
27
27
 
28
28
  ## Token Inventory
29
29
 
30
- Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inline` block, consumed as Tailwind utilities.
30
+ Tokens are defined in the package’s `themes/reader.css` and `themes/dashboard.css` (`:root` + `.dark`), bridged in each `@theme inline` block, and consumed as Tailwind utilities.
31
31
 
32
32
  ### Base tokens (from shadcn naming)
33
33
 
@@ -39,8 +39,8 @@ Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inli
39
39
  | `--popover` | Floating popover/drawer/menu surfaces | foreground |
40
40
  | `--surface-inset` | Inset blocks carved into a card (inputs, preview boxes) | — |
41
41
  | `--primary` | Interactive color (buttons, links, selections, focus, progress) | foreground |
42
- | `--secondary` | Supporting surfaces | foreground |
43
- | `--muted` | De-emphasized surfaces and text | foreground |
42
+ | `--secondary` | Supporting interaction fills | foreground |
43
+ | `--muted` | Muted interaction fills and text | foreground |
44
44
  | `--accent` | Hover/expanded tints | foreground |
45
45
  | `--destructive` | Errors, danger | — |
46
46
  | `--border` | Default borders | — |
@@ -67,35 +67,11 @@ Why dark mode skips the inset shadow: top-edge highlights fake a "light source f
67
67
  | `--attention` | Warnings, notices, saved-for-later — "look at this" | foreground, muted, border |
68
68
  | `--success` | Completion, positive outcomes | foreground |
69
69
 
70
- ## How to Add a New Semantic Token
70
+ ## Adding a semantic token
71
71
 
72
- 1. **Define values** in `globals.css` — both `:root` (light) and `.dark`. Use oklch for perceptual uniformity. Light and dark values may use different hues if the role reads better that way.
73
-
74
- ```css
75
- :root {
76
- --my-token: oklch(0.65 0.15 45);
77
- --my-token-foreground: oklch(0.25 0.05 40);
78
- }
79
- .dark {
80
- --my-token: oklch(0.7 0.12 200);
81
- --my-token-foreground: oklch(0.95 0.02 195);
82
- }
83
- ```
84
-
85
- 2. **Bridge in `@theme inline`** in `globals.css` so Tailwind generates utilities:
86
-
87
- ```css
88
- @theme inline {
89
- --color-my-token: var(--my-token);
90
- --color-my-token-foreground: var(--my-token-foreground);
91
- }
92
- ```
93
-
94
- 3. **Use in components** via Tailwind classes:
95
- ```tsx
96
- <div className="bg-my-token text-my-token-foreground">
97
- <span className="bg-my-token/10"> // opacity modifier for tints
98
- ```
72
+ Use the `design-system-package` skill and its
73
+ [token changes reference](../../design-system-package/references/tokens.md)
74
+ when extending the shared palette.
99
75
 
100
76
  ## Surfaces & Elevation
101
77
 
@@ -128,3 +104,9 @@ Don't use `bg-surface-inset` for empty placeholders — that signals "a control
128
104
  - **`::selection`** uses solid oklch values, not opacity modifiers — semi-transparent backgrounds create visible seams at line boundaries.
129
105
  - **Tooltip** uses inverted tokens (`bg-foreground text-background`) since it's a dark-on-light / light-on-dark surface. Kbd badge: `bg-background/15`.
130
106
  - **DebugPanel** is excluded from token migration — physically fixed terminal aesthetic.
107
+
108
+ ## Theme controls
109
+
110
+ `ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.
111
+
112
+ Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.
@@ -0,0 +1,13 @@
1
+ # Typeset prose
2
+
3
+ Typeset owns semantic document presentation; the application still owns parsing, streaming, and
4
+ custom component rendering.
5
+
6
+ ```css
7
+ @import '@carbonid1/design-system/typesets/base';
8
+ @import '@carbonid1/design-system/typesets/compact';
9
+ ```
10
+
11
+ Apply `typeset typeset-compact` to the rendered document root. Import the base stylesheet once, then
12
+ only the presets that application uses. Add `.not-typeset` or `[data-not-typeset]` around injected
13
+ application components that must retain their own design-system styling.
@@ -1,61 +1,52 @@
1
1
  ---
2
2
  name: design-system-package
3
- description: 'Building or modifying the @carbonid1/design-system package itself — its primitives, tokens, and variants — NOT using it in an app. Use when adding or changing a DS primitive/component, editing or adding a design token or CSS variable, adding or renaming a variant (a new buttonVariants option), updating the package exports/barrel, or extracting an app-local component into the design system. Triggers on: add a primitive, new design-system component, change a token, add a semantic color, edit themes/reader.css or themes/dashboard.css, add a variant, button variant, new buttonVariants, rename a variant, update the barrel/exports, extract or lift a component into the design system, promote to a DS primitive, modify @carbonid1/design-system, wrap a Base UI primitive, add a Storybook story to a DS primitive, write a changeset for a DS change. To merely USE existing primitives while building app UI, load the design-system skill instead.'
3
+ description: Modify @carbonid1/design-system primitives, tokens, variants, exports, or package releases. For app UI using existing primitives, use design-system.
4
4
  ---
5
5
 
6
- # Design System — Package Development
7
-
8
- How to **build and change `@carbonid1/design-system` itself** — the shared primitives, tokens, and variants every carbonid1 app consumes. This is the opposite end from the `design-system` skill, which is for _using_ the system in app code. Reach for this the moment a task means editing the package: adding a primitive, changing a token or variant, updating exports, or lifting an app-local component into the system.
9
-
10
- The package lives at `packages/design-system` in the `packages` monorepo. This skill is the single source for how we build it — the rules, the Storybook workflow, the token recipe, testing, and release; the package's `AGENTS.md` just points here.
11
-
12
- ## Before you add anything — study what exists
13
-
14
- - **Read the real exports and types.** The barrel is `src/index.ts`; each primitive is `src/<Name>/<Name>.tsx`, with a `.types.ts` when it exports its own prop types and a `.stories.tsx` when it has visual states to show; helpers are `src/helpers/<name>/<name>.ts`, with a co-located test when there's logic worth testing. Read types for the API and existing stories for usage examples.
15
- - **Study comparable shadcn source for structure and accessibility**, then own it. shadcn is a good reference for how a primitive is composed, and we already follow its token _naming_ (~99% token-driven, as validation). But **never import a shadcn component and never add a shadcn runtime dependency** — we hand-own every value and behavior. Reference, not dependency.
16
-
17
- ## Build rules
18
-
19
- - **Base UI is the foundation.** Wrap `@base-ui/react` — not Radix, not hand-rolled. Check Base UI first when adding anything new; for interactive primitives it carries the accessibility and keyboard behavior you'd otherwise reimplement wrong.
20
- - **Compound API for multi-part primitives.** Export a namespace (`ContextMenu.Root`, `.Trigger`, `.Popup`…), not a monolith with config props — mirrors Base UI's own shape and lets consumers compose.
21
- - **Theme-agnostic, tokens only.** Every primitive must render correctly under **every palette × light/dark** with zero consumer styling. Semantic tokens only — no `blue-500`, no hex. The four-tier elevation contract (`bg-background` / `bg-card` / `bg-surface-inset` / `bg-popover`) is the only source of surface elevation; `bg-muted` / `bg-accent` / `bg-secondary` are reserved for interaction states and are never a surface. Full token inventory + rationale: the co-installed `design-system` skill's `references/theming.md` (`.claude/skills/design-system/references/theming.md`).
22
- - **`'use client'` at the top of every interactive file.** Consumers are Next.js server-component apps; hooks, handlers, and Base UI primitives all need a client boundary.
23
- - **Tree-shakable.** The `src/index.ts` barrel is fine because `package.json` sets `"sideEffects": ["**/*.css"]` — unused exports drop. Don't add module-level side effects to component files.
24
- - **Primitive vs product.** This package owns _primitives_ (button, menu, badge) and _patterns every app needs identically_ (toast, undo, destructive tiers). It does **not** own app-specific chrome (page headers, drawers, nav) — those stay in the consumer until a second app wants the same shape.
25
-
26
- ## Prefer evolving the system over an app-local workaround
27
-
28
- When a consumer needs something the system doesn't have — a token, a variant, a primitive — the default is to **add or extend it here**, not to fork a one-off in the app. A bespoke color or component in one app quietly breaks the single-decision-propagates-everywhere contract the tokens exist to keep; that's why the consume-side rule is to surface a missing token, not invent one. **Extracting an app-local component into the package** is the same move in reverse: generalize it (theme-agnostic, no app-specific copy or data logic), give it a compound API if it's multi-part, add stories for every state, and export it from the barrel.
29
-
30
- ## Adding a semantic color token
31
-
32
- 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
33
- 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
34
- 3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.
35
-
36
- Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.
37
-
38
- ## Storybook
39
-
40
- Run these commands from `packages/design-system`:
41
-
42
- - `pnpm storybook` starts the standalone component browser at `http://localhost:7006`.
43
- - `pnpm build-storybook` builds the static component documentation.
44
- - `pnpm test:run:storybook` runs story interaction and accessibility tests through Vitest.
45
-
46
- ## Verify before you ship
47
-
48
- - **Stories for everything visual** — `Component.stories.tsx`, one story per visual state, each rendering under both palettes × both modes (the `.storybook/preview.ts` toolbar switchers prove it in isolation before shipping). Story-level `.test()` methods for interaction behavior. **Vitest** for non-visual helpers in `src/helpers/`.
49
- - **Run the story tests** with `pnpm test:run:storybook` and resolve interaction and accessibility failures before shipping.
50
- - **UI/UX Pro Max accessibility review** — For any visual, interactive, or token change, invoke the UI/UX Pro Max plugin review lens when available (prefer `ui-ux-pro-max:design-system` for primitives and tokens, `ui-ux-pro-max:ui-styling` for component styling, and `ui-ux-pro-max:ui-ux-pro-max` when unsure) and let it choose the relevant checks for the diff. The review must still cover keyboard navigation, visible focus states, contrast, accessible names/ARIA, screen-reader semantics, responsive behavior, interaction states, and reduced-motion behavior where they apply. In the handoff, name the lens used and summarize findings; for non-visual package housekeeping, say it does not apply. Package rules stay authoritative over broad style suggestions.
51
- - **Prove it downstream.** The real proof a change works is at least one app or fixture outside the package rendering it; a primitive that type-checks can still look wrong under a palette you never opened.
52
-
53
- ## Releasing — how a change reaches consumers
54
-
55
- A package change is invisible outside this repo until it's published. For release-intended package work, the agent owns the complete local release flow: implement, verify, review, write a changeset, run `pnpm release`, and leave the published version available for downstream dependency bumps. Do not stop for a separate publish approval unless the user explicitly asks to pause before release.
56
-
57
- `pnpm release` is a local agent-run release step, not CI/GitHub automation. It versions packages, publishes to npm, pushes tags, and expects a clean `main`. Run it only for release-ready package work; don't run it for exploratory or unfinished changes.
58
-
59
- **Publishing auth is exclusively `NPM_TOKEN`**, loaded by the packages repo's release script from its gitignored `.env.local` or an explicitly exported environment variable. Never print or commit it. Do not use `npm login`, `pnpm login`, browser/QR CLI login, OTP prompts, `~/.npmrc` session credentials, a direct publish command, or publishing CI as a fallback. If authentication fails, inspect the token's expiry and package write permissions and replace that token in `.env.local`; token rotation in npm's account settings must not become an alternate publishing session.
60
-
61
- Stop only for real blockers: failing checks, an unexpected major or breaking release, a missing or rejected publishing token, unrelated dirty work, merge conflicts, an unexpected release prompt, or a release script failure. Otherwise publish and continue.
6
+ # Design System Package
7
+
8
+ The source lives at `packages/design-system` in the `packages` monorepo. Make
9
+ shared changes there; installed skill copies belong to the published package.
10
+
11
+ ## Package constraints
12
+
13
+ - Read the relevant exports in `src/index.ts`, types, and comparable stories.
14
+ Primitives live in `src/<Name>/`; helpers live in `src/helpers/<name>/`.
15
+ - Wrap `@base-ui/react` for interactive primitives. Use compound APIs for
16
+ multi-part components. Comparable shadcn source can inform structure and
17
+ accessibility; do not add shadcn components or a shadcn runtime dependency.
18
+ - Components must render under every palette in light and dark modes. Use
19
+ semantic tokens, with `bg-background`, `bg-card`, `bg-surface-inset`, and
20
+ `bg-popover` for surfaces. Reserve `bg-muted`, `bg-accent`, and `bg-secondary`
21
+ for interaction states and fills.
22
+ - Interactive files need `'use client'` for Next.js consumers. Preserve tree
23
+ shaking: no module-level side effects in component files; `package.json`
24
+ declares only CSS in `sideEffects`.
25
+ - This package owns primitives and patterns every app needs identically.
26
+ App-specific headers, navigation, and drawers stay in the app until another
27
+ consumer needs the same shape.
28
+
29
+ ## Extending the system
30
+
31
+ Compose existing primitives when they meet the requirement. When an authorized
32
+ task needs a reusable capability the system lacks, extend it here and continue
33
+ through the relevant verification. Ask when an unresolved product decision or
34
+ work beyond the authorized scope needs user input. A request for a draft stops
35
+ before publication.
36
+
37
+ When extracting an app-local component, remove app-specific copy and data logic,
38
+ make it theme-agnostic, use a compound API where appropriate, add stories for its
39
+ visual states, and export it from the barrel.
40
+
41
+ ## Read for the affected work
42
+
43
+ - Adding or changing semantic tokens: [token changes](references/tokens.md).
44
+ For existing color roles and elevation, use the shared
45
+ [theming reference](../design-system/references/theming.md).
46
+ - Visual, interactive, token, or helper behavior changes:
47
+ [verification](references/verification.md), including Storybook and downstream
48
+ checks appropriate to the change. Skill text and other non-visual documentation
49
+ changes do not require a visual review or Storybook run.
50
+ - Preparing an authorized release: [release workflow](references/release.md).
51
+ Publishing uses `pnpm release` and `NPM_TOKEN`; a draft or implementation
52
+ request alone does not authorize publication.
@@ -0,0 +1,9 @@
1
+ # Releasing the package
2
+
3
+ A package change is invisible outside this repo until it's published. For release-intended package work, the agent owns the complete local release flow: implement, verify, review, write a changeset, run `pnpm release`, and leave the published version available for downstream dependency bumps. Do not stop for a separate publish approval unless the user explicitly asks to pause before release.
4
+
5
+ `pnpm release` is a local agent-run release step, not CI/GitHub automation. It versions packages, publishes to npm, pushes tags, and expects a clean `main`. Run it only for release-ready package work; don't run it for exploratory or unfinished changes.
6
+
7
+ **Publishing auth is exclusively `NPM_TOKEN`**, loaded by the packages repo's release script from its gitignored `.env.local` or an explicitly exported environment variable. Never print or commit it. Do not use `npm login`, `pnpm login`, browser/QR CLI login, OTP prompts, `~/.npmrc` session credentials, a direct publish command, or publishing CI as a fallback. If authentication fails, inspect the token's expiry and package write permissions and replace that token in `.env.local`; token rotation in npm's account settings must not become an alternate publishing session.
8
+
9
+ Stop only for real blockers: failing checks, an unexpected major or breaking release, a missing or rejected publishing token, unrelated dirty work, merge conflicts, an unexpected release prompt, or a release script failure. Otherwise publish and continue.
@@ -0,0 +1,7 @@
1
+ # Adding a semantic color token
2
+
3
+ 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
4
+ 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
5
+ 3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.
6
+
7
+ Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.
@@ -0,0 +1,16 @@
1
+ # Package verification
2
+
3
+ ## Storybook
4
+
5
+ Run these commands from `packages/design-system`:
6
+
7
+ - `pnpm storybook` starts the standalone component browser at `http://localhost:7006`.
8
+ - `pnpm build-storybook` builds the static component documentation.
9
+ - `pnpm test:run:storybook` runs story interaction and accessibility tests through Vitest.
10
+
11
+ ## Verify before you ship
12
+
13
+ - **Stories for everything visual** — `Component.stories.tsx`, one story per visual state, each rendering under both palettes × both modes (the `.storybook/preview.ts` toolbar switchers prove it in isolation before shipping). Story-level `.test()` methods for interaction behavior. **Vitest** for non-visual helpers in `src/helpers/`.
14
+ - **Run the story tests** with `pnpm test:run:storybook` and resolve interaction and accessibility failures before shipping.
15
+ - **UI/UX Pro Max accessibility review** — For any visual, interactive, or token change, invoke the UI/UX Pro Max plugin review lens when available (prefer `ui-ux-pro-max:design-system` for primitives and tokens, `ui-ux-pro-max:ui-styling` for component styling, and `ui-ux-pro-max:ui-ux-pro-max` when unsure) and let it choose the relevant checks for the diff. The review must still cover keyboard navigation, visible focus states, contrast, accessible names/ARIA, screen-reader semantics, responsive behavior, interaction states, and reduced-motion behavior where they apply. In the handoff, name the lens used and summarize findings; for non-visual package housekeeping, say it does not apply. Package rules stay authoritative over broad style suggestions.
16
+ - **Prove it downstream.** The real proof a change works is at least one app or fixture outside the package rendering it; a primitive that type-checks can still look wrong under a palette you never opened.