@carbonid1/design-system 7.3.0 → 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.
@@ -0,0 +1,125 @@
1
+ // GENERATED by `cn build` — do not edit.
2
+ // Pair with createCn from "cn/engine":
3
+ // import tables from "./cn.tables.js"
4
+ // import { createCn } from "cn/engine"
5
+ // export const cn = createCn(tables)
6
+ const P = 48;
7
+ const U = (s, o = 0) => {
8
+ const out = new Int32Array(s.length);
9
+ for (let i = 0; i < s.length; i++)
10
+ out[i] = s.charCodeAt(i) - P - o;
11
+ return out;
12
+ };
13
+ const PS = (counts) => {
14
+ const out = new Int32Array(counts.length + 1);
15
+ for (let i = 0; i < counts.length; i++)
16
+ out[i + 1] = out[i] + counts[i];
17
+ return out;
18
+ };
19
+ // zigzag-delta stream → running values
20
+ const DZ = (s) => {
21
+ const out = new Int32Array(s.length);
22
+ let a = 0;
23
+ for (let i = 0; i < s.length; i++) {
24
+ const z = s.charCodeAt(i) - P;
25
+ a += (z >>> 1) ^ -(z & 1);
26
+ out[i] = a;
27
+ }
28
+ return out;
29
+ };
30
+ const GROUP_COUNT = 384;
31
+ const customValidatorNames = [];
32
+ const edgeStart = PS(U("E0500002005282000000002000150000020021820000011200000003022202000300004200120000200420001200021200301200010400162000010000220021010:2192001200220012000220012000200200200400010200040000000000400200108200110100000022010313000162002000020020012020080213000228200000000082000000000120002000120020020040101020300130001001010"));
33
+ const labelStart = PS(U(":11111111211111119311546544411119731869:671397415686432441111111111161114151214313433415:78311132233313187211117221449443411141111151152226611131111112212518142224214215421421542142424242516171151615616347111111111197911327451111111111111111111113134714133513411111311111111111111111111112444411111342312715245411117:3"));
34
+ const labelText = "@containerabcdefghinlmoprstunderlineviawzccentlignnimatespectuto-colsrowsaglorightnessckdrop-sisbcontrastfiltergrayscalehue-rotateinvertopacityslurrightnessaturateepia-coniclinearpositionradialsizeockurrderttom-belrstxyespacing-xyaretoursorlnt-umnsendspantartainentrasteividerop-shadowurationcorationlay-xyasendillexontromlter-featuresstretchapr-xyayscaleidow-colsrowsue-rotatedentlinesetvert-beringsxyeshadoweiadingftnest-clamp-imageabein-lrstxyskx--b-coniclpositionrsizet-x-y-fromto-fromto-inearfromto-fromto-adialfromto-fromtofromtofromtofromtoblockhinlinew-screenesblockhinlinewbjectpacityrutlinederigin-offsetbelrstxyesrspective-originaceholderioghtng-offsettateundedw-xyz-belrstlreseslr-endspantartaturatecepiahizekewpace-taleroll-xyz-barmpbelrstxyesbelrstxyes-thumbrackadowrink-xyxyartrokeabextora-shadowpckingnsformitionlate-xyz-offsetill-changeoom";
35
+ // pre-order tree: targets derived from edge counts via subtree sizes
36
+ const edgeTarget = (() => {
37
+ const N = edgeStart.length - 1;
38
+ const sizes = new Int32Array(N);
39
+ for (let i = N - 1; i >= 0; i--) {
40
+ let s = 1;
41
+ let c = i + 1;
42
+ for (let k = edgeStart[i]; k < edgeStart[i + 1]; k++) {
43
+ s += sizes[c];
44
+ c += sizes[c];
45
+ }
46
+ sizes[i] = s;
47
+ }
48
+ const out = new Int32Array(edgeStart[N]);
49
+ let e = 0;
50
+ for (let i = 0; i < N; i++) {
51
+ let c = i + 1;
52
+ for (let k = edgeStart[i]; k < edgeStart[i + 1]; k++) {
53
+ out[e++] = c;
54
+ c += sizes[c];
55
+ }
56
+ }
57
+ return out;
58
+ })();
59
+ const nodeGroup = U("02000000000000900<=0?000B000F00F00ŏI0J0LNPRTVX0000]_a00000000000000000000000rst0000000zŏ00000000000…ŏ000ˆ0000ŏ0000000000—0000000000000000000000000000000000000000000000000000Ë000000000000000000000Þ000000000000000000ð0000000ø0ùúûüýþÿĀāĂ㥹Ć000000000000000000000000000000000000000000ħ0ĨĪ00000000000000000000ļĽ00000Ŭ000000", 1);
60
+ // vlists = op-pattern pool + per-list refs; the engine indexes these directly
61
+ const vlistPat = PS(U("1233333593464636351265367151576"));
62
+ const vlistOps = U("93203242332583253248325D>E?F@03263243255B:032523853:0325B:8GA032542H<C=12727B:0324325853;D>E?3257D>03258432585:0325B:;0328B:032");
63
+ const vlistRef = U("012123445661666666789111:5;;;;;;;;444;;;:62999<1161=62>>?61:21@ABCD4446996:64E:::;:?::64:F114GHHIHHHHIHH1HH1HH1HHHHHH::EJK4444::EJ4444441691;644444114244444:;L6666555555555555555999666664444444444444444444444226?6:66644M9N?D:111::::6DJ199");
64
+ const vlistGroup = DZ("0202002020020020020020020020020200200200200200200200002020202001003040106000200200200200200200200200200200200200200200200200200200200200200200200200200200200020020020020020020002020200202002002002002002002002002002020002002020020200220200200200200200200200200200200020020020000200020002000200200200020020020002000200200200020020202002020202000200200020022000200200020020002002000200220002002000200W0Z00020020002002020002002000200g0j0002002000200200020020002002000200200020020002000200002000002002002002002000200020000200002002002002002002002020020020200200200200200200200200202020020020020020020020020002002002020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020020002002002002002002000200200200200200200200200200020202020002000200020002002002002000020200200");
65
+ // nodeVlist rebuilt sparse: (anchor deltas, vlist ids)
66
+ const nodeVlist = (() => {
67
+ const out = new Int32Array(319).fill(-1);
68
+ const A = DZ("02422242:222222242224222242442222222422222244442242226224222426222422442462222422622222222626222462242622422622422424242422222222422222222242422222222222222222622442224222222222222224424442262222222222222222222226224222424242422224422422422222");
69
+ const V = DZ("02222222222222222222202222222222222222222222221422222222222222222222222222222222222Y\\222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222221422222222222222222222222222222222222222Ŀł222222222222222222");
70
+ for (let i = 0; i < A.length; i++)
71
+ out[A[i]] = V[i];
72
+ return out;
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) => {
75
+ const tails = s.split(' ');
76
+ const prefix = tails.shift();
77
+ for (let i = 0; i < tails.length; i++) {
78
+ tails[i] = prefix + tails[i];
79
+ }
80
+ return tails;
81
+ });
82
+ const AA = DZ("0000000000000000000000000000000000000000000000000000000000000262242:6@200000006:240B428:4422400002046044222426220026642642462026224222824220022400000000\\00N222422242222222224062242222222422226264222422222222222222442804222422222222222222222222220<4<0204260002444020204224422");
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
+ const AS = DZ("02222222222222222222222222222222222222222222222222222222222222222203062222222222IL2200IL021042222]`222IL0gj2e50n2222U00X202[^2y0000|{0~}€…ˆ22‹Ž>22~22222222222G000sˆQXI00000œ2>40000ŽŸB00000Iª¯000²00000000000000021Q´³00¶•000000000000000000000˜222HGHa5À222Å6Â2222ÏÒ000¯²2³");
85
+ const litAnchor = new Int32Array(992);
86
+ const litGroup = new Int32Array(992);
87
+ const litPool = new Int32Array(992);
88
+ let poolText = '';
89
+ const poolOffsets = new Int32Array(1032);
90
+ {
91
+ const tailRef = new Map();
92
+ let nextRef = 0;
93
+ let e = 0;
94
+ for (let i = 0; i < AA.length; i++) {
95
+ for (const tail of SETS[AS[i]]) {
96
+ let r = tailRef.get(tail);
97
+ if (r === undefined) {
98
+ r = nextRef++;
99
+ tailRef.set(tail, r);
100
+ poolOffsets[r * 2] = poolText.length;
101
+ poolOffsets[r * 2 + 1] = tail.length;
102
+ poolText += tail;
103
+ }
104
+ litAnchor[e] = AA[i];
105
+ litGroup[e] = AG[i];
106
+ litPool[e] = r;
107
+ e++;
108
+ }
109
+ }
110
+ }
111
+ // conflict adjacency (engine builds claim bitmask CSR at init)
112
+ const adjGid = DZ("0b2N:222@R>F@286¦2@H2D266226FB22B2>BD\\6N22222Z222D222p");
113
+ const adjStart = PS(U("1::22222432:222:22:22>222222:22:2221322511111311111114"));
114
+ const adjTgt = DZ("2Š4A;33N=C@H4A;33N=C@<2;363@QTQʰ222ˉºŴŽ2R2=18cƴÅҜÜÛŲǝȈ:ħ25=11D3A@216Er25;11B3?<438Cn9@7=<8192>2E121@9@EHE@9>2T25511<398216=V25511<398216=„ƧNž2Đå242L222290000f22500ɛ000ǘ222");
115
+ const patGid = U("ij");
116
+ const patTgt = U("—");
117
+ const postfixLookupGroups = U("1");
118
+ const orderSensitiveModifiers = "* ** after backdrop before details-content file first-letter first-line marker placeholder selection";
119
+ export default {
120
+ GROUP_COUNT, customValidatorNames, edgeStart, labelStart, labelText,
121
+ edgeTarget, nodeGroup, nodeVlist, vlistPat, vlistOps, vlistRef, vlistGroup,
122
+ litAnchor, litGroup, litPool, poolOffsets, poolText,
123
+ adjGid, adjStart, adjTgt, patGid, patTgt, postfixLookupGroups,
124
+ orderSensitiveModifiers,
125
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carbonid1/design-system",
3
- "version": "7.3.0",
3
+ "version": "7.4.0",
4
4
  "description": "Shared React UI primitives + design tokens (themes, postcss config)",
5
5
  "repository": {
6
6
  "type": "git",
@@ -35,11 +35,10 @@
35
35
  "dependencies": {
36
36
  "@tailwindcss/postcss": "^4.2.0",
37
37
  "class-variance-authority": "^0.7.1",
38
- "clsx": "^2.1.1",
38
+ "cn": "0.3.0",
39
39
  "lucide-react": "^1.8.0",
40
40
  "next-themes": "^0.4.6",
41
41
  "react-hotkeys-hook": "^5.2.4",
42
- "tailwind-merge": "^3.5.0",
43
42
  "tailwindcss": "^4.2.0"
44
43
  },
45
44
  "peerDependencies": {
@@ -1,137 +1,52 @@
1
1
  ---
2
2
  name: design-system
3
- description: 'Shared UI components and design patterns for carbonid1 apps built on @carbonid1/design-system. ALWAYS use when building UI, creating components, styling Typeset or Markdown prose, adding dropdowns, selects, tooltips, icons, toasts, context menus, badges, or any interactive element. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, typeset, prose, Markdown rendering, using the design system, layout shift, skeleton, context menu, right-click menu, button, theme, palette. To MODIFY @carbonid1/design-system itself — add or change a primitive, token, variant, or the barrel/exports — use the design-system-package skill instead.'
3
+ description: Build or edit app UI using @carbonid1/design-system. For changes to the shared package itself, use design-system-package.
4
4
  ---
5
5
 
6
6
  # Design System
7
7
 
8
- Primitives live in `@carbonid1/design-system`. **Check the package's exports and types before building anything new.** This file is direction and taste, not API reference — the types are the docs.
9
-
10
- ```ts
11
- import {
12
- Badge,
13
- Button,
14
- buttonVariants,
15
- Kbd,
16
- ProgressRing,
17
- Slider,
18
- ContextMenu,
19
- Select,
20
- Tooltip,
21
- Toaster,
22
- toast,
23
- ThemeProvider,
24
- ThemeCycler,
25
- useTheme,
26
- cn,
27
- getModKey,
28
- useHotkeys,
29
- } from '@carbonid1/design-system'
30
- ```
31
-
32
- Palettes are chosen by importing one theme CSS per app: `@carbonid1/design-system/themes/reader` (InkVoice) or `/themes/dashboard` (CoI Calculator).
33
-
34
- If you're editing `@carbonid1/design-system` itself (adding a primitive, changing a token), use the `design-system-package` skill — this file is for _using_ the design system, not building it.
35
-
36
- ## Core rules
37
-
38
- - Never build a tooltip, context menu, or toast from scratch — use `Tooltip`, `ContextMenu`, `toast()`
39
- - All icons from `lucide-react` — search `lucide.dev/icons` before creating anything custom. If nothing fits, build via Lucide's `Icon` + `iconNode`, don't reach for another library.
40
- - All color through semantic tokens — no hardcoded Tailwind color classes. See [references/theming.md](references/theming.md).
41
- - **Missing a token or primitive? Surface it, don't invent one.** When the palette has no token — or the package no component — for what you're building, stop and ask the user, offering 2–3 concrete paths (extend the design system, compose what's already there, or a deliberately-scoped one-off). A silent one-off forks the system: these tokens exist so a single decision propagates everywhere, and a bespoke color or component quietly breaks that. Asking is cheap; an unnoticed fork is expensive to unwind later.
42
- - Tooltip: rely on defaults (`position="top"`, `delay={400}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`, a snappy reveal → a lower `delay`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
43
- - Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
44
-
45
- ## Typeset prose
46
-
47
- Typeset owns semantic document presentation; the application still owns parsing, streaming, and
48
- custom component rendering.
49
-
50
- ```css
51
- @import '@carbonid1/design-system/typesets/base';
52
- @import '@carbonid1/design-system/typesets/compact';
53
- ```
54
-
55
- Apply `typeset typeset-compact` to the rendered document root. Import the base stylesheet once, then
56
- only the presets that application uses. Add `.not-typeset` or `[data-not-typeset]` around injected
57
- application components that must retain their own design-system styling.
58
-
59
- ## Buttons & links
60
-
61
- - **Active/selected state** — pass `selected` (toolbar toggles, segmented controls, filter chips, tabs, nav links). It applies the selection tokens (`bg-primary/10` + `ring-1 ring-primary/20`, tint held on hover); never hand-layer those classes. `selected` is visual only — set the matching ARIA yourself: `aria-pressed` on toggle buttons, `aria-current` on nav links. It rides both `Button` and `buttonVariants(...)`.
62
- - **Dialog actions** — `Dialog.Trigger` and `Dialog.Close` supply behavior, not button appearance. Compose a `Button` through `render` so one component owns the complete visual contract; don't attach `buttonVariants(...)` to the behavior primitive.
63
- ```tsx
64
- <Dialog.Close
65
- render={
66
- <Button variant="ghost" size="small">
67
- Cancel
68
- </Button>
69
- }
70
- />
71
- ```
72
- - **A link that looks like a button** — apply `buttonVariants({ variant, size, selected })` to the `Link`, not `<Button render={<Link/>}>`. Base UI's `Button` is button-semantic: rendering an `<a>` through it either warns or forces `role="button"`, which breaks navigation for screen readers. Keep the element a real link and style it:
73
- ```tsx
74
- <Link
75
- href={href}
76
- aria-current={active ? 'page' : undefined}
77
- className={cn(buttonVariants({ variant: 'ghost', size: 'small', selected: active }))}
78
- >
79
- {label}
80
- </Link>
81
- ```
82
- The `cn(...)` wrap is load-bearing, not cosmetic: `buttonVariants` is cva, which concatenates without merging, so only `cn` (tailwind-merge) drops the variant's own `hover:bg-accent` in favor of the `selected` tint.
83
-
84
- ## Visual Language
85
-
86
- - **Discrete elements** — rows/cards use `rounded-lg` with `space-y-1` gaps, never flat lists with hairline dividers
87
- - **Selection** — `bg-primary/10` tint + `ring-1 ring-primary/20`, never border-left accents
88
- - **Hover reveal** — action buttons use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100` with outer row `hover:bg-accent`. The `group-focus-within` is required — without it, keyboard users tab to an invisible button.
89
- - **Metadata** — use the quietest representation that preserves scanning. Reserve
90
- badges/chips for concise categorical states, filters, or individually
91
- interactive values; prefer secondary text, alignment, grouping, icons, or
92
- restrained surface tone for routine facts. Do not expose an internal category
93
- or repeat information merely because a `Badge` primitive exists.
94
- - **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
95
- - **Avatars** — only with real images, no letter/initial placeholders
96
-
97
- ## Elevation
98
-
99
- Four-tier contract — every themed surface picks one of these tokens. Layering is recessed: cards are sheets on the desk, controls are carved INTO sheets, popovers lift OFF the desk.
100
-
101
- | Token | Role | Pair with |
102
- | ------------------ | --------------------------------------- | ---------------------- |
103
- | `bg-background` | Page (the desk) | — |
104
- | `bg-card` | Raised paper on the desk — peak surface | `shadow-card` |
105
- | `bg-surface-inset` | Inset block carved into a card | `inset-shadow-surface` |
106
- | `bg-popover` | Floating layer above everything | `shadow-popover` |
107
-
108
- `bg-surface-inset` covers form inputs, preview boxes, quote blocks, and language tabs. `bg-popover` covers drawers, menus, and command palettes.
109
-
110
- **`bg-muted`, `bg-accent`, `bg-secondary` are RESERVED for interaction states** — hover backgrounds, skeleton placeholders, badge fills, soft tints. They are never the background of a card or an inset block. Mixing them in breaks the layering contract; see [references/theming.md](references/theming.md) for the deeper rationale.
111
-
112
- **Empty placeholders** — when a slot is meant to be filled (`AddBookCard`, file drop zone, audio preview slot before recording), render a transparent or background-matched surface with `border-dashed`. The empty state reads as a missing piece on its parent surface — never as a recessed input or a card. Once filled, swap to a solid border and the surface adopts its real elevation.
113
-
114
- ## Destructive Actions
115
-
116
- Two tiers. Pick by how hard the action is to redo, not how scary it feels.
117
-
118
- | Severity | Pattern | Example |
119
- | ---------------- | ---------------------------- | ------------------------------------ |
120
- | **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
121
- | **Easy to redo** | No confirmation | Toggle flag, remove a tag |
122
-
123
- **Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `useHotkeys` (re-exported from the design system) → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.
124
-
125
- ## Layout Stability
126
-
127
- Skeleton → real UI transitions must not shift layout. The skeleton is a dimensional contract.
128
-
129
- - Skeletons match real UI structure, counts, heights, spacing. Update the skeleton when the real UI changes.
130
- - Async elements that always render (selectors, user controls) show a same-sized placeholder while loading — never `null`.
131
- - Doesn't apply to user-triggered UI (modals, drawers, toasts) or conditional banners — these are unpredictable by nature.
132
-
133
- ## Theming
134
-
135
- `ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.
136
-
137
- Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.
8
+ Use `@carbonid1/design-system` primitives and semantic tokens. Check the relevant
9
+ exports and types before adding a component; they are the API reference.
10
+
11
+ ## Shared constraints
12
+
13
+ - Use `Tooltip`, `ContextMenu`, and `toast()` for those interactions.
14
+ - Use `lucide-react` icons. Search the Lucide icon catalog before creating a
15
+ custom icon with Lucide's `Icon` and `iconNode`.
16
+ - Use semantic color tokens. Surfaces use `bg-background`, `bg-card` with
17
+ `shadow-card`, `bg-surface-inset` with `inset-shadow-surface`, or `bg-popover`
18
+ with `shadow-popover`. Reserve `bg-muted`, `bg-accent`, and `bg-secondary` for
19
+ interaction states and fills, never card or inset surfaces.
20
+ - For a missing capability, compose existing primitives when they satisfy the
21
+ requirement. If the task requires extending the shared package and that work
22
+ is within the authorized scope, use `design-system-package` and continue.
23
+ Ask when an unresolved product decision or work beyond that scope needs user input. Keep
24
+ reusable tokens and primitives in the package; avoid silent app-local forks.
25
+
26
+ ## Visual language
27
+
28
+ - Rows and cards use `rounded-lg` with `space-y-1` gaps, not hairline dividers.
29
+ - Selected buttons and button-styled links use `selected` with the appropriate
30
+ ARIA state. The system owns the selection tint and ring; avoid border-left
31
+ accents. See the controls reference for composition details.
32
+ - Hover actions use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100`
33
+ with outer-row `hover:bg-accent` so keyboard focus reveals the action.
34
+ - Reserve badges for categorical states, filters, or interactive values. Use
35
+ secondary text, alignment, or grouping for routine facts; omit internal or
36
+ redundant categories.
37
+ - Icon buttons use at least `p-1.5`, with icons at least `w-4 h-4`.
38
+ - Avatars use real images, without letter or initial placeholders.
39
+ - Skeletons match the real structure, counts, dimensions, and spacing. Async
40
+ elements that always render reserve their space; user-triggered UI and
41
+ conditional banners do not need advance placeholders.
42
+ - Empty fillable slots use transparent or background-matched surfaces with a
43
+ dashed border. Filled slots adopt their real elevation and a solid border.
44
+
45
+ ## Read for the affected UI
46
+
47
+ - Buttons, links, dialog actions, tooltips, and toggles:
48
+ [controls](references/controls.md).
49
+ - Typeset or Markdown prose: [Typeset](references/typeset.md).
50
+ - Delete and removal interactions: [destructive actions](references/destructive-actions.md).
51
+ - Palette setup, color roles, and elevation details:
52
+ [theming](references/theming.md).
@@ -0,0 +1,29 @@
1
+ # Controls and links
2
+
3
+ - **Active/selected state** — pass `selected` (toolbar toggles, segmented controls, filter chips, tabs, nav links). It applies the selection tokens (`bg-primary/10` + `ring-1 ring-primary/20`, tint held on hover); never hand-layer those classes. `selected` is visual only — set the matching ARIA yourself: `aria-pressed` on toggle buttons, `aria-current` on nav links. It rides both `Button` and `buttonVariants(...)`.
4
+ - **Dialog actions** — `Dialog.Trigger` and `Dialog.Close` supply behavior, not button appearance. Compose a `Button` through `render` so one component owns the complete visual contract; don't attach `buttonVariants(...)` to the behavior primitive.
5
+ ```tsx
6
+ <Dialog.Close
7
+ render={
8
+ <Button variant="ghost" size="small">
9
+ Cancel
10
+ </Button>
11
+ }
12
+ />
13
+ ```
14
+ - **A link that looks like a button** — apply `buttonVariants({ variant, size, selected })` to the `Link`, not `<Button render={<Link/>}>`. Base UI's `Button` is button-semantic: rendering an `<a>` through it either warns or forces `role="button"`, which breaks navigation for screen readers. Keep the element a real link and style it:
15
+ ```tsx
16
+ <Link
17
+ href={href}
18
+ aria-current={active ? 'page' : undefined}
19
+ className={cn(buttonVariants({ variant: 'ghost', size: 'small', selected: active }))}
20
+ >
21
+ {label}
22
+ </Link>
23
+ ```
24
+ The `cn(...)` wrap is load-bearing, not cosmetic: `buttonVariants` is cva, which concatenates without merging, so only `cn`, which merges conflicting classes, drops the variant's own `hover:bg-accent` in favor of the `selected` tint.
25
+
26
+ ## Tooltips and icon toggles
27
+
28
+ - Tooltip: rely on defaults (`position="top"`, `delay={400}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`, a snappy reveal → a lower `delay`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
29
+ - Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
@@ -0,0 +1,10 @@
1
+ # Destructive actions
2
+
3
+ Two tiers. Pick by how hard the action is to redo, not how scary it feels.
4
+
5
+ | Severity | Pattern | Example |
6
+ | ---------------- | ---------------------------- | ------------------------------------ |
7
+ | **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
8
+ | **Easy to redo** | No confirmation | Toggle flag, remove a tag |
9
+
10
+ **Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `useHotkeys` (re-exported from the design system) → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.
@@ -27,7 +27,7 @@ Primitives must render correctly under every palette × light/dark combination
27
27
 
28
28
  ## Token Inventory
29
29
 
30
- Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inline` block, consumed as Tailwind utilities.
30
+ Tokens are defined in the package’s `themes/reader.css` and `themes/dashboard.css` (`:root` + `.dark`), bridged in each `@theme inline` block, and consumed as Tailwind utilities.
31
31
 
32
32
  ### Base tokens (from shadcn naming)
33
33
 
@@ -39,8 +39,8 @@ Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inli
39
39
  | `--popover` | Floating popover/drawer/menu surfaces | foreground |
40
40
  | `--surface-inset` | Inset blocks carved into a card (inputs, preview boxes) | — |
41
41
  | `--primary` | Interactive color (buttons, links, selections, focus, progress) | foreground |
42
- | `--secondary` | Supporting surfaces | foreground |
43
- | `--muted` | De-emphasized surfaces and text | foreground |
42
+ | `--secondary` | Supporting interaction fills | foreground |
43
+ | `--muted` | Muted interaction fills and text | foreground |
44
44
  | `--accent` | Hover/expanded tints | foreground |
45
45
  | `--destructive` | Errors, danger | — |
46
46
  | `--border` | Default borders | — |
@@ -67,35 +67,11 @@ Why dark mode skips the inset shadow: top-edge highlights fake a "light source f
67
67
  | `--attention` | Warnings, notices, saved-for-later — "look at this" | foreground, muted, border |
68
68
  | `--success` | Completion, positive outcomes | foreground |
69
69
 
70
- ## How to Add a New Semantic Token
70
+ ## Adding a semantic token
71
71
 
72
- 1. **Define values** in `globals.css` — both `:root` (light) and `.dark`. Use oklch for perceptual uniformity. Light and dark values may use different hues if the role reads better that way.
73
-
74
- ```css
75
- :root {
76
- --my-token: oklch(0.65 0.15 45);
77
- --my-token-foreground: oklch(0.25 0.05 40);
78
- }
79
- .dark {
80
- --my-token: oklch(0.7 0.12 200);
81
- --my-token-foreground: oklch(0.95 0.02 195);
82
- }
83
- ```
84
-
85
- 2. **Bridge in `@theme inline`** in `globals.css` so Tailwind generates utilities:
86
-
87
- ```css
88
- @theme inline {
89
- --color-my-token: var(--my-token);
90
- --color-my-token-foreground: var(--my-token-foreground);
91
- }
92
- ```
93
-
94
- 3. **Use in components** via Tailwind classes:
95
- ```tsx
96
- <div className="bg-my-token text-my-token-foreground">
97
- <span className="bg-my-token/10"> // opacity modifier for tints
98
- ```
72
+ Use the `design-system-package` skill and its
73
+ [token changes reference](../../design-system-package/references/tokens.md)
74
+ when extending the shared palette.
99
75
 
100
76
  ## Surfaces & Elevation
101
77
 
@@ -128,3 +104,9 @@ Don't use `bg-surface-inset` for empty placeholders — that signals "a control
128
104
  - **`::selection`** uses solid oklch values, not opacity modifiers — semi-transparent backgrounds create visible seams at line boundaries.
129
105
  - **Tooltip** uses inverted tokens (`bg-foreground text-background`) since it's a dark-on-light / light-on-dark surface. Kbd badge: `bg-background/15`.
130
106
  - **DebugPanel** is excluded from token migration — physically fixed terminal aesthetic.
107
+
108
+ ## Theme controls
109
+
110
+ `ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.
111
+
112
+ Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.
@@ -0,0 +1,13 @@
1
+ # Typeset prose
2
+
3
+ Typeset owns semantic document presentation; the application still owns parsing, streaming, and
4
+ custom component rendering.
5
+
6
+ ```css
7
+ @import '@carbonid1/design-system/typesets/base';
8
+ @import '@carbonid1/design-system/typesets/compact';
9
+ ```
10
+
11
+ Apply `typeset typeset-compact` to the rendered document root. Import the base stylesheet once, then
12
+ only the presets that application uses. Add `.not-typeset` or `[data-not-typeset]` around injected
13
+ application components that must retain their own design-system styling.
@@ -1,61 +1,52 @@
1
1
  ---
2
2
  name: design-system-package
3
- description: 'Building or modifying the @carbonid1/design-system package itself — its primitives, tokens, and variants — NOT using it in an app. Use when adding or changing a DS primitive/component, editing or adding a design token or CSS variable, adding or renaming a variant (a new buttonVariants option), updating the package exports/barrel, or extracting an app-local component into the design system. Triggers on: add a primitive, new design-system component, change a token, add a semantic color, edit themes/reader.css or themes/dashboard.css, add a variant, button variant, new buttonVariants, rename a variant, update the barrel/exports, extract or lift a component into the design system, promote to a DS primitive, modify @carbonid1/design-system, wrap a Base UI primitive, add a Storybook story to a DS primitive, write a changeset for a DS change. To merely USE existing primitives while building app UI, load the design-system skill instead.'
3
+ description: Modify @carbonid1/design-system primitives, tokens, variants, exports, or package releases. For app UI using existing primitives, use design-system.
4
4
  ---
5
5
 
6
- # Design System — Package Development
7
-
8
- How to **build and change `@carbonid1/design-system` itself** — the shared primitives, tokens, and variants every carbonid1 app consumes. This is the opposite end from the `design-system` skill, which is for _using_ the system in app code. Reach for this the moment a task means editing the package: adding a primitive, changing a token or variant, updating exports, or lifting an app-local component into the system.
9
-
10
- The package lives at `packages/design-system` in the `packages` monorepo. This skill is the single source for how we build it — the rules, the Storybook workflow, the token recipe, testing, and release; the package's `AGENTS.md` just points here.
11
-
12
- ## Before you add anything — study what exists
13
-
14
- - **Read the real exports and types.** The barrel is `src/index.ts`; each primitive is `src/<Name>/<Name>.tsx`, with a `.types.ts` when it exports its own prop types and a `.stories.tsx` when it has visual states to show; helpers are `src/helpers/<name>/<name>.ts`, with a co-located test when there's logic worth testing. Read types for the API and existing stories for usage examples.
15
- - **Study comparable shadcn source for structure and accessibility**, then own it. shadcn is a good reference for how a primitive is composed, and we already follow its token _naming_ (~99% token-driven, as validation). But **never import a shadcn component and never add a shadcn runtime dependency** — we hand-own every value and behavior. Reference, not dependency.
16
-
17
- ## Build rules
18
-
19
- - **Base UI is the foundation.** Wrap `@base-ui/react` — not Radix, not hand-rolled. Check Base UI first when adding anything new; for interactive primitives it carries the accessibility and keyboard behavior you'd otherwise reimplement wrong.
20
- - **Compound API for multi-part primitives.** Export a namespace (`ContextMenu.Root`, `.Trigger`, `.Popup`…), not a monolith with config props — mirrors Base UI's own shape and lets consumers compose.
21
- - **Theme-agnostic, tokens only.** Every primitive must render correctly under **every palette × light/dark** with zero consumer styling. Semantic tokens only — no `blue-500`, no hex. The four-tier elevation contract (`bg-background` / `bg-card` / `bg-surface-inset` / `bg-popover`) is the only source of surface elevation; `bg-muted` / `bg-accent` / `bg-secondary` are reserved for interaction states and are never a surface. Full token inventory + rationale: the co-installed `design-system` skill's `references/theming.md` (`.claude/skills/design-system/references/theming.md`).
22
- - **`'use client'` at the top of every interactive file.** Consumers are Next.js server-component apps; hooks, handlers, and Base UI primitives all need a client boundary.
23
- - **Tree-shakable.** The `src/index.ts` barrel is fine because `package.json` sets `"sideEffects": ["**/*.css"]` — unused exports drop. Don't add module-level side effects to component files.
24
- - **Primitive vs product.** This package owns _primitives_ (button, menu, badge) and _patterns every app needs identically_ (toast, undo, destructive tiers). It does **not** own app-specific chrome (page headers, drawers, nav) — those stay in the consumer until a second app wants the same shape.
25
-
26
- ## Prefer evolving the system over an app-local workaround
27
-
28
- When a consumer needs something the system doesn't have — a token, a variant, a primitive — the default is to **add or extend it here**, not to fork a one-off in the app. A bespoke color or component in one app quietly breaks the single-decision-propagates-everywhere contract the tokens exist to keep; that's why the consume-side rule is to surface a missing token, not invent one. **Extracting an app-local component into the package** is the same move in reverse: generalize it (theme-agnostic, no app-specific copy or data logic), give it a compound API if it's multi-part, add stories for every state, and export it from the barrel.
29
-
30
- ## Adding a semantic color token
31
-
32
- 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
33
- 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
34
- 3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.
35
-
36
- Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.
37
-
38
- ## Storybook
39
-
40
- Run these commands from `packages/design-system`:
41
-
42
- - `pnpm storybook` starts the standalone component browser at `http://localhost:7006`.
43
- - `pnpm build-storybook` builds the static component documentation.
44
- - `pnpm test:run:storybook` runs story interaction and accessibility tests through Vitest.
45
-
46
- ## Verify before you ship
47
-
48
- - **Stories for everything visual** — `Component.stories.tsx`, one story per visual state, each rendering under both palettes × both modes (the `.storybook/preview.ts` toolbar switchers prove it in isolation before shipping). Story-level `.test()` methods for interaction behavior. **Vitest** for non-visual helpers in `src/helpers/`.
49
- - **Run the story tests** with `pnpm test:run:storybook` and resolve interaction and accessibility failures before shipping.
50
- - **UI/UX Pro Max accessibility review** — For any visual, interactive, or token change, invoke the UI/UX Pro Max plugin review lens when available (prefer `ui-ux-pro-max:design-system` for primitives and tokens, `ui-ux-pro-max:ui-styling` for component styling, and `ui-ux-pro-max:ui-ux-pro-max` when unsure) and let it choose the relevant checks for the diff. The review must still cover keyboard navigation, visible focus states, contrast, accessible names/ARIA, screen-reader semantics, responsive behavior, interaction states, and reduced-motion behavior where they apply. In the handoff, name the lens used and summarize findings; for non-visual package housekeeping, say it does not apply. Package rules stay authoritative over broad style suggestions.
51
- - **Prove it downstream.** The real proof a change works is at least one app or fixture outside the package rendering it; a primitive that type-checks can still look wrong under a palette you never opened.
52
-
53
- ## Releasing — how a change reaches consumers
54
-
55
- A package change is invisible outside this repo until it's published. For release-intended package work, the agent owns the complete local release flow: implement, verify, review, write a changeset, run `pnpm release`, and leave the published version available for downstream dependency bumps. Do not stop for a separate publish approval unless the user explicitly asks to pause before release.
56
-
57
- `pnpm release` is a local agent-run release step, not CI/GitHub automation. It versions packages, publishes to npm, pushes tags, and expects a clean `main`. Run it only for release-ready package work; don't run it for exploratory or unfinished changes.
58
-
59
- **Publishing auth is exclusively `NPM_TOKEN`**, loaded by the packages repo's release script from its gitignored `.env.local` or an explicitly exported environment variable. Never print or commit it. Do not use `npm login`, `pnpm login`, browser/QR CLI login, OTP prompts, `~/.npmrc` session credentials, a direct publish command, or publishing CI as a fallback. If authentication fails, inspect the token's expiry and package write permissions and replace that token in `.env.local`; token rotation in npm's account settings must not become an alternate publishing session.
60
-
61
- Stop only for real blockers: failing checks, an unexpected major or breaking release, a missing or rejected publishing token, unrelated dirty work, merge conflicts, an unexpected release prompt, or a release script failure. Otherwise publish and continue.
6
+ # Design System Package
7
+
8
+ The source lives at `packages/design-system` in the `packages` monorepo. Make
9
+ shared changes there; installed skill copies belong to the published package.
10
+
11
+ ## Package constraints
12
+
13
+ - Read the relevant exports in `src/index.ts`, types, and comparable stories.
14
+ Primitives live in `src/<Name>/`; helpers live in `src/helpers/<name>/`.
15
+ - Wrap `@base-ui/react` for interactive primitives. Use compound APIs for
16
+ multi-part components. Comparable shadcn source can inform structure and
17
+ accessibility; do not add shadcn components or a shadcn runtime dependency.
18
+ - Components must render under every palette in light and dark modes. Use
19
+ semantic tokens, with `bg-background`, `bg-card`, `bg-surface-inset`, and
20
+ `bg-popover` for surfaces. Reserve `bg-muted`, `bg-accent`, and `bg-secondary`
21
+ for interaction states and fills.
22
+ - Interactive files need `'use client'` for Next.js consumers. Preserve tree
23
+ shaking: no module-level side effects in component files; `package.json`
24
+ declares only CSS in `sideEffects`.
25
+ - This package owns primitives and patterns every app needs identically.
26
+ App-specific headers, navigation, and drawers stay in the app until another
27
+ consumer needs the same shape.
28
+
29
+ ## Extending the system
30
+
31
+ Compose existing primitives when they meet the requirement. When an authorized
32
+ task needs a reusable capability the system lacks, extend it here and continue
33
+ through the relevant verification. Ask when an unresolved product decision or
34
+ work beyond the authorized scope needs user input. A request for a draft stops
35
+ before publication.
36
+
37
+ When extracting an app-local component, remove app-specific copy and data logic,
38
+ make it theme-agnostic, use a compound API where appropriate, add stories for its
39
+ visual states, and export it from the barrel.
40
+
41
+ ## Read for the affected work
42
+
43
+ - Adding or changing semantic tokens: [token changes](references/tokens.md).
44
+ For existing color roles and elevation, use the shared
45
+ [theming reference](../design-system/references/theming.md).
46
+ - Visual, interactive, token, or helper behavior changes:
47
+ [verification](references/verification.md), including Storybook and downstream
48
+ checks appropriate to the change. Skill text and other non-visual documentation
49
+ changes do not require a visual review or Storybook run.
50
+ - Preparing an authorized release: [release workflow](references/release.md).
51
+ Publishing uses `pnpm release` and `NPM_TOKEN`; a draft or implementation
52
+ request alone does not authorize publication.
@@ -0,0 +1,9 @@
1
+ # Releasing the package
2
+
3
+ A package change is invisible outside this repo until it's published. For release-intended package work, the agent owns the complete local release flow: implement, verify, review, write a changeset, run `pnpm release`, and leave the published version available for downstream dependency bumps. Do not stop for a separate publish approval unless the user explicitly asks to pause before release.
4
+
5
+ `pnpm release` is a local agent-run release step, not CI/GitHub automation. It versions packages, publishes to npm, pushes tags, and expects a clean `main`. Run it only for release-ready package work; don't run it for exploratory or unfinished changes.
6
+
7
+ **Publishing auth is exclusively `NPM_TOKEN`**, loaded by the packages repo's release script from its gitignored `.env.local` or an explicitly exported environment variable. Never print or commit it. Do not use `npm login`, `pnpm login`, browser/QR CLI login, OTP prompts, `~/.npmrc` session credentials, a direct publish command, or publishing CI as a fallback. If authentication fails, inspect the token's expiry and package write permissions and replace that token in `.env.local`; token rotation in npm's account settings must not become an alternate publishing session.
8
+
9
+ Stop only for real blockers: failing checks, an unexpected major or breaking release, a missing or rejected publishing token, unrelated dirty work, merge conflicts, an unexpected release prompt, or a release script failure. Otherwise publish and continue.
@@ -0,0 +1,7 @@
1
+ # Adding a semantic color token
2
+
3
+ 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
4
+ 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
5
+ 3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.
6
+
7
+ Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.