@carbonid1/design-system 7.1.1 → 7.2.1

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/README.md CHANGED
@@ -72,6 +72,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
72
72
  | `Kbd` | Keyboard key display (`⌘K`, `⇧B`) |
73
73
  | `ProgressRing` | Base UI-backed circular task progress indicator, including indeterminate work |
74
74
  | `MeterRing` | Base UI-backed circular meter for bounded resource or capacity usage |
75
+ | `ScrollArea` | Overlay scrolling with activity-only scrollbars by default and an explicit `visibility="persistent"` escape hatch |
75
76
  | `Slider` | Base UI-backed range slider with a convenience wrapper and compound `Root` / `Control` / `Track` / `Thumb` parts |
76
77
  | `Switch` | Boolean setting control with a compound `Root` / `Thumb` API |
77
78
  | `ContextMenu` | Right-click / long-press menu (compound API) |
@@ -3,7 +3,7 @@ export declare const ScrollArea: {
3
3
  Root: ({ className, ...props }: ScrollAreaRootProps) => import("react/jsx-runtime").JSX.Element;
4
4
  Viewport: ({ className, ...props }: ScrollAreaViewportProps) => import("react/jsx-runtime").JSX.Element;
5
5
  Content: ({ className, ...props }: ScrollAreaContentProps) => import("react/jsx-runtime").JSX.Element;
6
- Scrollbar: ({ className, orientation, ...props }: ScrollAreaScrollbarProps) => import("react/jsx-runtime").JSX.Element;
6
+ Scrollbar: ({ className, orientation, visibility, ...props }: ScrollAreaScrollbarProps) => import("react/jsx-runtime").JSX.Element;
7
7
  Thumb: ({ className, ...props }: ScrollAreaThumbProps) => import("react/jsx-runtime").JSX.Element;
8
8
  Corner: ({ className, ...props }: ScrollAreaCornerProps) => import("react/jsx-runtime").JSX.Element;
9
9
  };
@@ -3,11 +3,13 @@ import { jsx as _jsx } from "react/jsx-runtime";
3
3
  import { ScrollArea as BaseScrollArea } from '@base-ui/react/scroll-area';
4
4
  import { cn } from '../helpers/cn/cn';
5
5
  import { mergeStatefulClassName } from '../helpers/mergeStatefulClassName/mergeStatefulClassName';
6
- const scrollbarClasses = 'm-1 flex touch-none select-none justify-center rounded-full opacity-0 transition-opacity delay-100 duration-150 data-[hovering]:delay-0 data-[hovering]:opacity-100 data-[scrolling]:opacity-100 motion-reduce:transition-none';
6
+ const scrollbarClasses = 'm-1 flex touch-none select-none justify-center rounded-full transition-opacity motion-reduce:transition-none';
7
+ const activityScrollbarClasses = 'pointer-events-none opacity-0 delay-0 duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] data-[scrolling]:pointer-events-auto data-[scrolling]:opacity-100 data-[scrolling]:duration-0';
8
+ const persistentScrollbarClasses = 'pointer-events-auto opacity-100 delay-0 duration-0';
7
9
  const Root = ({ className, ...props }) => (_jsx(BaseScrollArea.Root, { className: mergeStatefulClassName('relative overflow-hidden', className), ...props }));
8
10
  const Viewport = ({ className, ...props }) => (_jsx(BaseScrollArea.Viewport, { className: mergeStatefulClassName('focus-visible:ring-ring/50 h-full w-full overscroll-contain rounded-[inherit] outline-hidden focus-visible:ring-2', className), ...props }));
9
11
  const Content = ({ className, ...props }) => (_jsx(BaseScrollArea.Content, { className: mergeStatefulClassName('', className), ...props }));
10
- const Scrollbar = ({ className, orientation = 'vertical', ...props }) => (_jsx(BaseScrollArea.Scrollbar, { orientation: orientation, className: mergeStatefulClassName(cn(scrollbarClasses, orientation === 'vertical' && 'w-1.5', orientation === 'horizontal' && 'h-1.5 flex-col'), className), ...props }));
12
+ const Scrollbar = ({ className, orientation = 'vertical', visibility = 'activity', ...props }) => (_jsx(BaseScrollArea.Scrollbar, { orientation: orientation, className: mergeStatefulClassName(cn(scrollbarClasses, visibility === 'activity' && activityScrollbarClasses, visibility === 'persistent' && persistentScrollbarClasses, orientation === 'vertical' && 'w-1.5', orientation === 'horizontal' && 'h-1.5 flex-col'), className), ...props }));
11
13
  const Thumb = ({ className, ...props }) => (_jsx(BaseScrollArea.Thumb, { className: mergeStatefulClassName('bg-muted-foreground/30 rounded-full data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full', className), ...props }));
12
14
  const Corner = ({ className, ...props }) => (_jsx(BaseScrollArea.Corner, { className: mergeStatefulClassName('bg-transparent', className), ...props }));
13
15
  export const ScrollArea = {
@@ -9,7 +9,10 @@ export type ScrollAreaViewportProps = BaseViewportProps & {
9
9
  export type ScrollAreaContentProps = BaseContentProps & {
10
10
  ref?: Ref<HTMLDivElement>;
11
11
  };
12
- export type ScrollAreaScrollbarProps = BaseScrollbarProps & {
12
+ export type ScrollAreaScrollbarVisibility = 'activity' | 'persistent';
13
+ export type ScrollAreaScrollbarProps = Omit<BaseScrollbarProps, 'visibility'> & {
14
+ /** Controls whether the scrollbar follows scroll activity or remains visible. @default 'activity' */
15
+ visibility?: ScrollAreaScrollbarVisibility;
13
16
  ref?: Ref<HTMLDivElement>;
14
17
  };
15
18
  export type ScrollAreaThumbProps = BaseThumbProps & {
package/dist/index.d.ts CHANGED
@@ -32,7 +32,7 @@ export type { SwitchRootProps, SwitchThumbProps } from './Switch/Switch.types';
32
32
  export { SegmentedControl } from './SegmentedControl/SegmentedControl';
33
33
  export type { SegmentedControlItemProps, SegmentedControlRootProps, SegmentedControlSize, } from './SegmentedControl/SegmentedControl.types';
34
34
  export { ScrollArea } from './ScrollArea/ScrollArea';
35
- export type { ScrollAreaContentProps, ScrollAreaCornerProps, ScrollAreaRootProps, ScrollAreaScrollbarProps, ScrollAreaThumbProps, ScrollAreaViewportProps, } from './ScrollArea/ScrollArea.types';
35
+ export type { ScrollAreaContentProps, ScrollAreaCornerProps, ScrollAreaRootProps, ScrollAreaScrollbarProps, ScrollAreaScrollbarVisibility, ScrollAreaThumbProps, ScrollAreaViewportProps, } from './ScrollArea/ScrollArea.types';
36
36
  export { ContextMenu } from './ContextMenu/ContextMenu';
37
37
  export { Menu } from './Menu/Menu';
38
38
  export { Dialog } from './Dialog/Dialog';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carbonid1/design-system",
3
- "version": "7.1.1",
3
+ "version": "7.2.1",
4
4
  "description": "Shared React UI primitives + design tokens (themes, postcss config)",
5
5
  "repository": {
6
6
  "type": "git",
@@ -55,7 +55,6 @@
55
55
  "@base-ui/react": "^1.6.0",
56
56
  "@storybook/addon-a11y": "^10.3.5",
57
57
  "@storybook/addon-docs": "^10.3.5",
58
- "@storybook/addon-mcp": "^0.6.0",
59
58
  "@storybook/addon-themes": "^10.3.5",
60
59
  "@storybook/addon-vitest": "^10.3.5",
61
60
  "@storybook/react-vite": "^10.3.5",
@@ -7,11 +7,11 @@ description: 'Building or modifying the @carbonid1/design-system package itself
7
7
 
8
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
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 MCP workflow, the token recipe, testing, and release; the package's `AGENTS.md` just points here.
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
11
 
12
12
  ## Before you add anything — study what exists
13
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. The types are the API — don't guess props; read them (use the Storybook MCP below).
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
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
16
 
17
17
  ## Build rules
@@ -35,19 +35,18 @@ When a consumer needs something the system doesn't have — a token, a variant,
35
35
 
36
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
37
 
38
- ## Storybook MCP
38
+ ## Storybook
39
39
 
40
- `@storybook/addon-mcp` makes Storybook serve an MCP endpoint so an agent can read the primitives' real props, docs, and stories — and run their interaction/a11y tests in a self-healing loop — instead of guessing.
40
+ Run these commands from `packages/design-system`:
41
41
 
42
- - **Start it:** `pnpm storybook` — fixed port **7006** (pet-project convention; consumer apps point their agents at this exact port). The endpoint is `http://localhost:7006/mcp` and only exists while Storybook is running.
43
- - **Registered as** the `design-system-storybook` MCP server in `.mcp.json` (project scope). Reconnect Claude Code after the first launch to pick it up.
44
- - **When Storybook is running, use it** before adding or changing a primitive: `list-all-documentation` for what exists, `get-documentation` for a component's props, `run-story-tests` to validate stories (interaction + a11y). Read props from the MCP — don't hallucinate them.
45
- - React-only and preview-stage upstream; `@storybook/addon-mcp` is pinned to `^0.6.0` and may churn.
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.
46
45
 
47
46
  ## Verify before you ship
48
47
 
49
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/`.
50
- - **Run the story tests** through the Storybook MCP (`run-story-tests`) in a self-healing loop until interaction + a11y pass.
49
+ - **Run the story tests** with `pnpm test:run:storybook` and resolve interaction and accessibility failures before shipping.
51
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.
52
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.
53
52