@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.
- package/dist/Button/Button.variants.js +1 -1
- package/dist/ContextMenu/ContextMenu.d.ts +29 -45
- package/dist/ContextMenu/ContextMenu.js +6 -33
- package/dist/Kbd/Kbd.js +11 -4
- package/dist/Menu/Menu.d.ts +7 -2
- package/dist/Menu/Menu.js +3 -2
- package/dist/MessageScroller/MessageScroller.js +77 -34
- package/dist/Popover/Popover.js +1 -1
- package/dist/Tooltip/Tooltip.js +1 -1
- package/package.json +1 -1
- package/skills/design-system/SKILL.md +46 -131
- package/skills/design-system/references/controls.md +29 -0
- package/skills/design-system/references/destructive-actions.md +10 -0
- package/skills/design-system/references/theming.md +13 -31
- package/skills/design-system/references/typeset.md +13 -0
- package/skills/design-system-package/SKILL.md +48 -57
- package/skills/design-system-package/references/release.md +9 -0
- package/skills/design-system-package/references/tokens.md +7 -0
- package/skills/design-system-package/references/verification.md +16 -0
|
@@ -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,
|
|
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 {
|
|
3
|
-
|
|
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 }:
|
|
43
|
-
|
|
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 }:
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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 }:
|
|
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 }:
|
|
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
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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[
|
|
23
|
+
return MOD_SYMBOLS[modKey] ?? 'Ctrl';
|
|
23
24
|
if (lower === 'ctrl')
|
|
24
|
-
return
|
|
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
|
-
|
|
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 };
|
package/dist/Menu/Menu.d.ts
CHANGED
|
@@ -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<
|
|
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:
|
|
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-[
|
|
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
|
|
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
|
|
191
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
662
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
870
|
-
}, [ref, setContentElement]);
|
|
913
|
+
}, [setContentElement]));
|
|
871
914
|
const handleSpacerRef = useCallback((element) => {
|
|
872
915
|
spacerElementRef.current = element;
|
|
873
916
|
setSpacerElement(element);
|
package/dist/Popover/Popover.js
CHANGED
|
@@ -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-[
|
|
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,
|
package/dist/Tooltip/Tooltip.js
CHANGED
|
@@ -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-[
|
|
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,137 +1,52 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: design-system
|
|
3
|
-
description:
|
|
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
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
##
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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 `
|
|
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
|
|
43
|
-
| `--muted` |
|
|
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
|
-
##
|
|
70
|
+
## Adding a semantic token
|
|
71
71
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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:
|
|
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
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
-
|
|
51
|
-
|
|
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.
|