@carbonid1/design-system 7.3.1 → 7.5.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/Autocomplete/Autocomplete.d.ts +1 -1
- package/dist/Autocomplete/Autocomplete.js +6 -4
- package/dist/Badge/Badge.js +1 -1
- package/dist/Button/Button.variants.js +2 -2
- package/dist/ContextMenu/ContextMenu.d.ts +29 -45
- package/dist/ContextMenu/ContextMenu.js +6 -33
- package/dist/Input/Input.js +1 -1
- package/dist/InputGroup/InputGroup.d.ts +1 -0
- package/dist/InputGroup/InputGroup.js +3 -1
- package/dist/Item/Item.js +1 -1
- 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/Select/Select.d.ts +1 -1
- package/dist/Select/Select.js +13 -3
- package/dist/Select/Select.types.d.ts +1 -0
- package/dist/Slider/Slider.js +2 -2
- package/dist/Switch/Switch.js +2 -2
- package/dist/Tooltip/Tooltip.js +1 -1
- package/dist/helpers/cn/cn.tables.js +5 -5
- 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 +11 -0
- package/skills/design-system-package/references/verification.md +16 -0
package/dist/Select/Select.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
3
3
|
import { Select as BaseSelect } from '@base-ui/react/select';
|
|
4
4
|
import { ChevronDown } from 'lucide-react';
|
|
5
|
+
import { useCallback, useState } from 'react';
|
|
5
6
|
import { mergeStatefulClassName } from '../helpers/mergeStatefulClassName/mergeStatefulClassName';
|
|
6
7
|
const triggerClasses = 'border-border bg-background text-foreground focus-visible:ring-ring/50 group flex items-center justify-between gap-2 rounded-lg border px-3 py-2 text-sm outline-hidden focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-invalid:ring-3 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40';
|
|
7
8
|
const popupClasses = 'bg-popover text-popover-foreground border-border shadow-popover z-50 min-w-[var(--anchor-width)] max-w-[var(--available-width)] overflow-hidden rounded-lg border outline-hidden';
|
|
@@ -20,17 +21,26 @@ const OptionItem = ({ option, renderOption }) => (_jsx(Item, { value: option.val
|
|
|
20
21
|
selected: state.selected,
|
|
21
22
|
})
|
|
22
23
|
: option.label }) })) }));
|
|
23
|
-
const SelectComponent = ({ value, onChange, options, groups, placeholder, id, className, menuClassName, menuAlign = 'start', renderOption, onOpenChange, name, form, autoComplete, required, disabled, readOnly, 'aria-label': ariaLabel, }) => {
|
|
24
|
+
const SelectComponent = ({ value, onChange, options, groups, placeholder, id, className, menuClassName, menuAlign = 'start', renderOption, onOpenChange, name, form, autoComplete, required, disabled, readOnly, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, }) => {
|
|
24
25
|
const items = [...(options ?? []), ...(groups ?? []).flatMap(group => group.options)];
|
|
25
26
|
const selectedOption = items.find(option => option.value === value);
|
|
26
27
|
const selectedValue = selectedOption ? value : null;
|
|
27
28
|
const displayPlaceholder = selectedOption ? undefined : (placeholder ?? value);
|
|
28
|
-
|
|
29
|
+
// A combobox isn't named by its text, so an unlabelled select borrows its current text as a
|
|
30
|
+
// name. A <label> around the trigger or pointing at its id names it natively, and aria-label
|
|
31
|
+
// would override that. Until the trigger mounts, an id stands in for a label pointing at it.
|
|
32
|
+
const [hasNativeLabel, setHasNativeLabel] = useState(id !== undefined);
|
|
33
|
+
const detectNativeLabel = useCallback((trigger) => {
|
|
34
|
+
if (trigger)
|
|
35
|
+
setHasNativeLabel(trigger.labels.length > 0);
|
|
36
|
+
}, []);
|
|
37
|
+
const accessibleLabel = ariaLabel ??
|
|
38
|
+
(hasNativeLabel || ariaLabelledBy ? undefined : (selectedOption?.label ?? displayPlaceholder));
|
|
29
39
|
return (_jsxs(BaseSelect.Root, { value: selectedValue, onValueChange: nextValue => {
|
|
30
40
|
if (nextValue !== null) {
|
|
31
41
|
onChange(nextValue);
|
|
32
42
|
}
|
|
33
|
-
}, items: items, onOpenChange: open => onOpenChange?.(open), name: name, form: form, autoComplete: autoComplete, required: required, disabled: disabled, readOnly: readOnly, modal: false, children: [_jsxs(Trigger, { id: id, "aria-label": accessibleLabel, className: className, children: [_jsx(BaseSelect.Value, { className: "truncate", placeholder: displayPlaceholder }), _jsx(BaseSelect.Icon, { children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-4 shrink-0 transition-transform duration-150 group-data-[popup-open]:rotate-180 motion-reduce:transition-none" }) })] }), _jsx(BaseSelect.Portal, { children: _jsx(Positioner, { align: menuAlign, children: _jsx(Popup, { children: _jsxs(List, { className: menuClassName, children: [(options ?? []).map(option => (_jsx(OptionItem, { option: option, renderOption: renderOption }, option.value))), (groups ?? []).map(group => (_jsxs(BaseSelect.Group, { children: [_jsx(GroupLabel, { children: group.label }), group.options.map(option => (_jsx(OptionItem, { option: option, renderOption: renderOption }, option.value)))] }, group.label)))] }) }) }) })] }));
|
|
43
|
+
}, items: items, onOpenChange: open => onOpenChange?.(open), name: name, form: form, autoComplete: autoComplete, required: required, disabled: disabled, readOnly: readOnly, modal: false, children: [_jsxs(Trigger, { ref: detectNativeLabel, id: id, "aria-label": accessibleLabel, ...(ariaLabelledBy && { 'aria-labelledby': ariaLabelledBy }), className: className, children: [_jsx(BaseSelect.Value, { className: "truncate", placeholder: displayPlaceholder }), _jsx(BaseSelect.Icon, { children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-4 shrink-0 transition-transform duration-150 group-data-[popup-open]:rotate-180 motion-reduce:transition-none" }) })] }), _jsx(BaseSelect.Portal, { children: _jsx(Positioner, { align: menuAlign, children: _jsx(Popup, { children: _jsxs(List, { className: menuClassName, children: [(options ?? []).map(option => (_jsx(OptionItem, { option: option, renderOption: renderOption }, option.value))), (groups ?? []).map(group => (_jsxs(BaseSelect.Group, { children: [_jsx(GroupLabel, { children: group.label }), group.options.map(option => (_jsx(OptionItem, { option: option, renderOption: renderOption }, option.value)))] }, group.label)))] }) }) }) })] }));
|
|
34
44
|
};
|
|
35
45
|
SelectComponent.displayName = 'Select';
|
|
36
46
|
export const Select = Object.assign(SelectComponent, {
|
package/dist/Slider/Slider.js
CHANGED
|
@@ -4,8 +4,8 @@ import { Slider as BaseSlider } from '@base-ui/react/slider';
|
|
|
4
4
|
import { mergeStatefulClassName } from '../helpers/mergeStatefulClassName/mergeStatefulClassName';
|
|
5
5
|
const rootClasses = 'relative flex touch-none flex-col gap-2 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-48 data-[orientation=vertical]:w-fit';
|
|
6
6
|
const controlClasses = 'relative flex data-[orientation=horizontal]:w-full data-[orientation=horizontal]:items-center data-[orientation=horizontal]:py-2 data-[orientation=vertical]:h-full data-[orientation=vertical]:justify-center data-[orientation=vertical]:px-2';
|
|
7
|
-
const trackClasses = 'bg-input relative rounded-full data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5';
|
|
8
|
-
const indicatorClasses = 'bg-primary rounded-full data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full';
|
|
7
|
+
const trackClasses = 'bg-input relative rounded-full forced-colors:border data-[orientation=horizontal]:h-1.5 data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-1.5';
|
|
8
|
+
const indicatorClasses = 'bg-primary rounded-full data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full forced-colors:bg-[Highlight]';
|
|
9
9
|
const thumbClasses = 'bg-primary border-background block size-4 rounded-full border-2 shadow-sm has-[input:focus-visible]:ring-ring/50 has-[input:focus-visible]:ring-3 data-[disabled]:pointer-events-none data-[disabled]:opacity-50 forced-colors:has-[input:focus-visible]:ring-0 forced-colors:has-[input:focus-visible]:outline-2 forced-colors:has-[input:focus-visible]:outline-offset-2 forced-colors:has-[input:focus-visible]:outline-[Highlight]';
|
|
10
10
|
const Root = ({ className, ...props }) => (_jsx(BaseSlider.Root, { className: mergeStatefulClassName(rootClasses, className), ...props }));
|
|
11
11
|
const Label = ({ className, ...props }) => (_jsx(BaseSlider.Label, { className: mergeStatefulClassName('text-foreground text-sm font-medium', className), ...props }));
|
package/dist/Switch/Switch.js
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
3
3
|
import { Switch as BaseSwitch } from '@base-ui/react/switch';
|
|
4
4
|
import { cn } from '../helpers/cn/cn';
|
|
5
|
-
const Root = ({ className, ...props }) => (_jsx(BaseSwitch.Root, { "data-slot": "switch", className: cn('border-input-border bg-input data-checked:border-primary data-checked:bg-primary inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border p-0.5 outline-hidden', 'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3', 'data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50', className), ...props }));
|
|
6
|
-
const Thumb = ({ className, ...props }) => (_jsx(BaseSwitch.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 translate-x-0 rounded-full shadow-sm', 'transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none', 'data-checked:translate-x-4', className), ...props }));
|
|
5
|
+
const Root = ({ className, ...props }) => (_jsx(BaseSwitch.Root, { "data-slot": "switch", className: cn('border-input-border bg-input data-checked:border-primary data-checked:bg-primary inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border p-0.5 outline-hidden', 'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3', 'forced-colors:focus-visible:outline-[Highlight] forced-colors:data-checked:border-[Highlight] forced-colors:data-checked:bg-[Highlight]', 'data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50', className), ...props }));
|
|
6
|
+
const Thumb = ({ className, ...props }) => (_jsx(BaseSwitch.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 translate-x-0 rounded-full shadow-sm', 'transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none', 'data-checked:translate-x-4', 'forced-colors:bg-[CanvasText] forced-colors:data-checked:bg-[HighlightText]', className), ...props }));
|
|
7
7
|
export const Switch = {
|
|
8
8
|
Root,
|
|
9
9
|
Thumb,
|
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, }) => {
|
|
@@ -71,7 +71,7 @@ const nodeVlist = (() => {
|
|
|
71
71
|
out[A[i]] = V[i];
|
|
72
72
|
return out;
|
|
73
73
|
})();
|
|
74
|
-
const SETS = "container |break-after- all auto avoid avoid-page column left page right|break-before- all auto avoid avoid-page column left page right|break-inside-a uto void void-column void-page|box-decoration- clone slice|box- border content| contents flow-root hidden table table-caption table-cell table-column table-column-group table-footer-group table-header-group table-row table-row-group| not-sr-only sr-only|float- end left none right start|clear- both end left none right start|isolat e ion-auto|overflow- auto clip hidden scroll visible|overflow-x- auto clip hidden scroll visible|overflow-y- auto clip hidden scroll visible|overscroll- auto contain none|overscroll-x- auto contain none|overscroll-y- auto contain none| absolute fixed relative static sticky| collapse invisible visible|justify- around baseline between center center-safe end end-safe evenly normal start stretch|justify-items- center center-safe end end-safe normal start stretch|justify-self- auto center center-safe end end-safe start stretch|items- baseline baseline-last center center-safe end end-safe start stretch|self- auto baseline baseline-last center center-safe end end-safe start stretch|place-content- around baseline between center center-safe end end-safe evenly start stretch|place-items- baseline center center-safe end end-safe start stretch|place-self- auto center center-safe end end-safe start stretch| antialiased subpixel-antialiased| italic not-italic|normal-nums |ordinal |slashed-zero | lining-nums oldstyle-nums| proportional-nums tabular-nums| diagonal-fractions stacked-fractions| no-underline overline| capitalize lowercase normal-case uppercase|truncate |whitespace- break-spaces normal nowrap pre pre-line pre-wrap|break- all keep normal words|wrap- anywhere break-word normal|hyphens- auto manual none|mix-blend- color color-burn color-dodge darken difference exclusion hard-light hue lighten luminosity multiply normal overlay plus-darker plus-lighter saturation screen soft-light|table- auto fixed|caption- bottom top|backface- hidden visible|appearance- auto none|scheme- dark light light-dark normal only-dark only-light|field-sizing- content fixed|pointer-events- auto none|resize -none -x -y|snap- align-none center end start|snap- always normal|snap- both none x y|snap- mandatory proximity|touch- auto manipulation none|touch-pan- left right x|touch-pan- down up y|touch-pinch-zoom |select- all auto none text|forced-color-adjust- auto none| normal size| baseline bottom middle sub super text-bottom text-top top|none | auto square video| auto fr max min px| auto full px| fixed local scroll|clip- border content padding text|origin- border content padding| bottom bottom-left bottom-right center left left-bottom left-top right right-bottom right-top top top-left top-right| no-repeat repeat repeat-round repeat-space repeat-x repeat-y| auto contain cover| gradient-to-b gradient-to-bl gradient-to-br gradient-to-l gradient-to-r gradient-to-t gradient-to-tl gradient-to-tr none|blend- color color-burn color-dodge darken difference exclusion hard-light hue lighten luminosity multiply normal overlay saturation screen soft-light|to- b bl br l r t tl tr| auto dvh fit full lh lvh max min px screen svh| dashed dotted double hidden none solid| collapse separate|px |auto |full | content none strict| inline-size size|layout |paint |style | around baseline between center center-safe end end-safe evenly normal start stretch| alias all-scroll auto cell col-resize context-menu copy crosshair default e-resize ew-resize grab grabbing help move n-resize ne-resize nesw-resize no-drop none not-allowed ns-resize nw-resize nwse-resize pointer progress row-resize s-resize se-resize sw-resize text vertical-text w-resize wait zoom-in zoom-out| dashed dotted double solid wavy| auto from-font|reverse |initial | in in-out initial linear out| col col-reverse row row-reverse| nowrap wrap wrap-reverse| auto initial none| black bold extrabold extralight light medium normal semibold thin| condensed expanded extra-condensed extra-expanded normal semi-condensed semi-expanded ultra-condensed ultra-expanded|flow- col col-dense dense row row-dense| none subgrid| auto dvh dvw fit full lh lvh lvw max min px screen svh svw| block flex grid table| auto dvw fit full lvw max min px screen svw| none surface| loose none normal px relaxed snug tight|through |item | inside outside| decimal disc none| auto px| clip-border clip-content clip-fill clip-padding clip-stroke clip-view no-clip| add exclude intersect subtract| alpha luminance match|origin- border content fill padding stroke view|type- alpha luminance| circle ellipse| closest-corner closest-side farthest-corner farthest-side|at- bottom bottom-left bottom-right center left left-bottom left-top right right-bottom right-top top top-left top-right| dvh fit full lh lvh max min none px screen svh| auto dvh dvw fit full lh lvh lvw max min none px screen svh svw| dvw fit full lvw max min none px screen svw| auto dvh dvw fit full lvh lvw max min none prose px svh svw| auto dvh dvw fit full lvh lvw max min none px screen svh svw| contain cover fill none scale-down| first last none| distant dramatic midrange near none normal|inset | full none|3d | auto smooth|gutter- auto both stable| auto none thin| inner none| auto dvh dvw fit full lvh lvw max min px svh svw|base | center end justify left right start| clip ellipsis| balance nowrap pretty wrap| normal tight tighter wide wider widest| cpu gpu none| 3d flat| all colors none opacity shadow transform| discrete normal| full px| auto dvh dvw fit full lvh lvw max min px screen svh svw| auto contents scroll transform".split('|').map((s) => {
|
|
74
|
+
const SETS = "container |break-after- all auto avoid avoid-page column left page right|break-before- all auto avoid avoid-page column left page right|break-inside-a uto void void-column void-page|box-decoration- clone slice|box- border content| contents flow-root hidden table table-caption table-cell table-column table-column-group table-footer-group table-header-group table-row table-row-group| not-sr-only sr-only|float- end left none right start|clear- both end left none right start|isolat e ion-auto|overflow- auto clip hidden scroll visible|overflow-x- auto clip hidden scroll visible|overflow-y- auto clip hidden scroll visible|overscroll- auto contain none|overscroll-x- auto contain none|overscroll-y- auto contain none| absolute fixed relative static sticky| collapse invisible visible|justify- around baseline between center center-safe end end-safe evenly normal start stretch|justify-items- center center-safe end end-safe normal start stretch|justify-self- auto center center-safe end end-safe start stretch|items- baseline baseline-last center center-safe end end-safe start stretch|self- auto baseline baseline-last center center-safe end end-safe start stretch|place-content- around baseline between center center-safe end end-safe evenly start stretch|place-items- baseline center center-safe end end-safe start stretch|place-self- auto center center-safe end end-safe start stretch| antialiased subpixel-antialiased| italic not-italic|normal-nums |ordinal |slashed-zero | lining-nums oldstyle-nums| proportional-nums tabular-nums| diagonal-fractions stacked-fractions| no-underline overline| capitalize lowercase normal-case uppercase|truncate |whitespace- break-spaces normal nowrap pre pre-line pre-wrap|break- all keep normal words|wrap- anywhere break-word normal|hyphens- auto manual none|mix-blend- color color-burn color-dodge darken difference exclusion hard-light hue lighten luminosity multiply normal overlay plus-darker plus-lighter saturation screen soft-light|table- auto fixed|caption- bottom top|backface- hidden visible|appearance- auto none|scheme- dark light light-dark normal only-dark only-light|field-sizing- content fixed|pointer-events- auto none|resize -none -x -y|snap- align-none center end start|snap- always normal|snap- both none x y|snap- mandatory proximity|touch- auto manipulation none|touch-pan- left right x|touch-pan- down up y|touch-pinch-zoom |select- all auto none text|forced-color-adjust- auto none| normal size| baseline bottom middle sub super text-bottom text-top top|none | auto square video| auto fr max min px| auto full px| fixed local scroll|clip- border content padding text|origin- border content padding| bottom bottom-left bottom-right center left left-bottom left-top right right-bottom right-top top top-left top-right| no-repeat repeat repeat-round repeat-space repeat-x repeat-y| auto contain cover| gradient-to-b gradient-to-bl gradient-to-br gradient-to-l gradient-to-r gradient-to-t gradient-to-tl gradient-to-tr none|blend- color color-burn color-dodge darken difference exclusion hard-light hue lighten luminosity multiply normal overlay saturation screen soft-light|to- b bl br l r t tl tr| auto dvh fit full lh lvh max min px screen svh| dashed dotted double hidden none solid| collapse separate|px |auto |full | content none strict| inline-size size|layout |paint |style | around baseline between center center-safe end end-safe evenly normal start stretch| alias all-scroll auto cell col-resize context-menu copy crosshair default e-resize ew-resize grab grabbing help move n-resize ne-resize nesw-resize no-drop none not-allowed ns-resize nw-resize nwse-resize pointer progress row-resize s-resize se-resize sw-resize text vertical-text w-resize wait zoom-in zoom-out| dashed dotted double solid wavy| auto from-font|reverse |initial | in in-out initial linear out| col col-reverse row row-reverse| nowrap wrap wrap-reverse| auto initial none| black bold extrabold extralight light medium normal semibold thin| condensed expanded extra-condensed extra-expanded normal semi-condensed semi-expanded ultra-condensed ultra-expanded|flow- col col-dense dense row row-dense| none subgrid| auto dvh dvw fit full lh lvh lvw max min px screen svh svw| block flex grid table| auto dvw fit full lvw max min px screen svw| none surface| loose none normal px relaxed snug tight|through |item | inside outside| decimal disc none| auto px| clip-border clip-content clip-fill clip-padding clip-stroke clip-view no-clip| add exclude intersect subtract| alpha luminance match|origin- border content fill padding stroke view|type- alpha luminance| circle ellipse| closest-corner closest-side farthest-corner farthest-side|at- bottom bottom-left bottom-right center left left-bottom left-top right right-bottom right-top top top-left top-right| dvh fit full lh lvh max min none px screen svh| auto dvh dvw fit full lh lvh lvw max min none px screen svh svw| dvw fit full lvw max min none px screen svw| auto dvh dvw fit full lvh lvw max min none prose px svh svw| auto dvh dvw fit full lvh lvw max min none px screen svh svw| contain cover fill none scale-down| first last none| distant dramatic midrange near none normal|inset | full none|3d | auto smooth|gutter- auto both stable| auto none thin| card inner none popover| auto dvh dvw fit full lvh lvw max min px svh svw|base | center end justify left right start| clip ellipsis| balance nowrap pretty wrap| normal tight tighter wide wider widest| cpu gpu none| 3d flat| all colors none opacity shadow transform| discrete normal| full px| auto dvh dvw fit full lvh lvw max min px screen svh svw| auto contents scroll transform".split('|').map((s) => {
|
|
75
75
|
const tails = s.split(' ');
|
|
76
76
|
const prefix = tails.shift();
|
|
77
77
|
for (let i = 0; i < tails.length; i++) {
|
|
@@ -82,11 +82,11 @@ const SETS = "container |break-after- all auto avoid avoid-page column left page
|
|
|
82
82
|
const AA = DZ("0000000000000000000000000000000000000000000000000000000000000262242:6@200000006:240B428:4422400002046044222426220026642642462026224222824220022400000000\\00N222422242222222224062242222222422226264222422222222222222442804222422222222222222222222220<4<0204260002444020204224422");
|
|
83
83
|
const AG = DZ("ɠ222222222222222222222222222222222222222222222222222222222222˕4222226>ʶ22ʷʺʷ2ʸʷ42ʴ2ʓ22>621422ɶ222ɹɼɷɺɷɺ22ɱ42222ɨ2ɧ26622ɘɓ244ƸƵ222]d24242ǖǓƚÄȫ2263ȨȥȨ2222222ǣ222222222222222222ǂƽ2ƾƵ2222222422222ƜƑ22222222222222222222144Ŧţ22Ţş222222222222222222222ĸ2ı68ĦģĦɡŰ4Ġ«®ĝ822ĔđĔ2ē2222622");
|
|
84
84
|
const AS = DZ("02222222222222222222222222222222222222222222222222222222222222222203062222222222IL2200IL021042222]`222IL0gj2e50n2222U00X202[^2y0000|{0~}
22>22~22222222222G000sQXI000002>40000B00000Iª¯000²00000000000000021Q´³00¶000000000000000000000222HGHa5À222Å6Â2222ÏÒ000¯²2³");
|
|
85
|
-
const litAnchor = new Int32Array(
|
|
86
|
-
const litGroup = new Int32Array(
|
|
87
|
-
const litPool = new Int32Array(
|
|
85
|
+
const litAnchor = new Int32Array(994);
|
|
86
|
+
const litGroup = new Int32Array(994);
|
|
87
|
+
const litPool = new Int32Array(994);
|
|
88
88
|
let poolText = '';
|
|
89
|
-
const poolOffsets = new Int32Array(
|
|
89
|
+
const poolOffsets = new Int32Array(1036);
|
|
90
90
|
{
|
|
91
91
|
const tailRef = new Map();
|
|
92
92
|
let nextRef = 0;
|
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.
|