@vokality/design-system 3.0.0 → 4.0.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/CHANGELOG.md +36 -0
- package/README.md +24 -9
- package/bin/vokality-skill.mjs +68 -0
- package/dist/components/Alert/Alert.js +1 -1
- package/dist/components/AppShell/AppShell.js +4 -1
- package/dist/components/Button/Button.d.ts +2 -1
- package/dist/components/Button/Button.js +1 -1
- package/dist/components/ChatWidget/ChatWidget.js +1 -1
- package/dist/components/CommandPalette/CommandPalette.js +2 -2
- package/dist/components/ErrorSummary/ErrorSummary.js +3 -1
- package/dist/components/Fieldset/Fieldset.d.ts +2 -0
- package/dist/components/Fieldset/Fieldset.js +2 -2
- package/dist/components/FileUpload/FileUpload.js +1 -1
- package/dist/components/IconButton/IconButton.d.ts +2 -1
- package/dist/components/IconButton/IconButton.js +2 -2
- package/dist/components/Menu/Menu.d.ts +1 -2
- package/dist/components/Menu/Menu.js +7 -1
- package/dist/components/Popover/Popover.d.ts +1 -1
- package/dist/components/Popover/Popover.js +1 -1
- package/dist/components/Prose/Prose.d.ts +3 -1
- package/dist/components/Prose/Prose.js +2 -2
- package/dist/components/RichTextEditor/RichTextEditor.js +20 -7
- package/dist/components/SegmentedControl/SegmentedControl.d.ts +1 -1
- package/dist/components/SegmentedControl/SegmentedControl.js +1 -1
- package/dist/components/ThemeProvider/ThemeProvider.d.ts +13 -0
- package/dist/components/ThemeProvider/ThemeProvider.js +11 -0
- package/dist/components/TimePicker/TimePicker.js +3 -1
- package/dist/components/Toaster/Toaster.js +1 -1
- package/dist/components.css +54 -8
- package/dist/hooks/useTheme.d.ts +3 -2
- package/dist/hooks/useTheme.js +6 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/internal/ThemeOptionsProvider.d.ts +15 -0
- package/dist/internal/ThemeOptionsProvider.js +26 -0
- package/dist/internal/themeOptions.d.ts +3 -0
- package/dist/internal/themeOptions.js +4 -0
- package/dist/lib/theme.d.ts +5 -1
- package/dist/lib/theme.js +3 -2
- package/dist/tokens.css +1 -0
- package/dist/tokens.dtcg.json +5 -0
- package/dist/tokens.json +5 -0
- package/dist/vokality.css +55 -8
- package/dist/vokality.iife.js +483 -434
- package/docs/brand.md +2 -2
- package/docs/components/Button/README.md +4 -1
- package/docs/components/DatePicker/README.md +1 -1
- package/docs/components/Fieldset/README.md +3 -1
- package/docs/components/FileUpload/README.md +3 -2
- package/docs/components/Menu/README.md +3 -3
- package/docs/components/NavList/README.md +1 -1
- package/docs/components/Popover/README.md +1 -1
- package/docs/components/Prose/README.md +4 -0
- package/docs/components/RichTextEditor/README.md +1 -1
- package/docs/components/SegmentedControl/README.md +1 -1
- package/docs/components/{ThemeScript → ThemeProvider}/README.md +16 -11
- package/package.json +27 -12
- package/skills/vokality-design-system/SKILL.md +55 -0
- package/skills/vokality-design-system/references/examples.tsx +103 -0
- package/dist/components/ThemeScript/ThemeScript.d.ts +0 -7
- package/dist/components/ThemeScript/ThemeScript.js +0 -9
package/docs/brand.md
CHANGED
|
@@ -98,7 +98,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
|
|
|
98
98
|
|
|
99
99
|
## Space and layout
|
|
100
100
|
|
|
101
|
-
- Dense operational apps
|
|
101
|
+
- Dense operational apps opt in with `density="compact"` on `ThemeProvider`. The shared compact scale is 20px page titles, 16px section titles, 14px body and fine-pointer controls (16px input text with a coarse pointer, which stops iOS focus zoom), 24px statistics; smaller text (metadata, captions) keeps its size. Table cells, list and navigation rows, menus and cards tighten too. Headers add no trailing section margin; compose vertical rhythm with `Stack`. Actions align with the page title. Controls share a 32px height for fine pointers and retain 44px when a coarse pointer is available. Toolbars, record rows and status lines can use 24px `xs` actions (fine pointers only). The default scale is unchanged.
|
|
102
102
|
|
|
103
103
|
- Apps: wrap the screen in `AppShell` (56px top bar, 15rem sidebar that collapses to icons and becomes an overlay below 48rem), put a `PageHeader` at the top of each page, and lay out content with `Stack`, `Inline` and `Grid`. Start new pages from the templates.
|
|
104
104
|
- Sites and documents: set content in one frame, max-width 80rem (`--content-max`), outlined left, right and bottom by `border-subtle`, over a faint 10px dot grid (`.vk-dot-grid`) on marketing pages.
|
|
@@ -154,7 +154,7 @@ The test suite checks these pairs in every theme and fails the build if one slip
|
|
|
154
154
|
|
|
155
155
|
## Using the system in code
|
|
156
156
|
|
|
157
|
-
- Install `@vokality/design-system` from the public npm registry, and import `@vokality/design-system/vokality.css` once. Installation does not require a token. It holds the fonts, all three themes and the component styles. The React components come from the package root; they are client components (`"use client"`) and render on the server without warnings. The formatting helpers are plain functions, usable in server components. `
|
|
157
|
+
- Install `@vokality/design-system` from the public npm registry, and import `@vokality/design-system/vokality.css` once. Installation does not require a token. It holds the fonts, all three themes and the component styles. The React components come from the package root; they are client components (`"use client"`) and render on the server without warnings. The formatting helpers are plain functions, usable in server components. `ThemeProvider` sets theme and density once and `useTheme` switches the theme; `LinkProvider` makes the system's links use the app's router. New projects start from the `Vokality/app-template` repository.
|
|
158
158
|
- Tailwind CSS v4 projects also import `@vokality/design-system/tailwind.css`, which maps every token onto Tailwind utilities (`bg-background`, `text-muted-foreground`, `border-input-border`, `font-display`, `md:` and the other breakpoints). Corners stay square.
|
|
159
159
|
- Design tools: `tokens.dtcg.json` is the W3C design-tokens format with one set per theme plus a shared set, and theme definitions. Import it into Figma with Tokens Studio, or feed it to Style Dictionary.
|
|
160
160
|
- Icons ship as SVG files under `icons/` as well as the `Icon` component.
|
|
@@ -21,6 +21,9 @@ The button for actions and record names, with square corners and a visible keybo
|
|
|
21
21
|
| --- | --- | --- | --- |
|
|
22
22
|
| default | 40px | 12px | 0.65rem 1.25rem |
|
|
23
23
|
| `sm` | 32px | 11px | 0.4rem 0.85rem |
|
|
24
|
+
| `xs` | 24px (44px with a coarse pointer) | 11px; 12px for `text` | 0 `space-sm` |
|
|
25
|
+
|
|
26
|
+
Use `xs` in toolbars, record rows and status lines where a 32px control crowds the content. `IconButton`, `Menu`, `Popover` and `SegmentedControl` take the same `size="xs"`, so a row of mixed actions stays flush.
|
|
24
27
|
|
|
25
28
|
## States
|
|
26
29
|
| State | Primary | Outline | Ghost |
|
|
@@ -32,7 +35,7 @@ The button for actions and record names, with square corners and a visible keybo
|
|
|
32
35
|
|
|
33
36
|
## Props
|
|
34
37
|
- `children`: the label in sentence case, starting with a verb.
|
|
35
|
-
- `variant`: `primary` (default), `outline`, `ghost`, `danger` or `text`. `size`: `sm` for dense screens.
|
|
38
|
+
- `variant`: `primary` (default), `outline`, `ghost`, `danger` or `text`. `size`: `sm` for dense screens, `xs` for toolbars, record rows and status lines.
|
|
36
39
|
- `href` renders an `<a>`; otherwise a `<button type="button">`. Pass `type="submit"` in forms.
|
|
37
40
|
- `arrow` adds the external-link glyph cell. Other attributes pass through.
|
|
38
41
|
- `loading` disables the button, sets `aria-busy` and shows a spinner before the label; `loadingLabel` replaces the label while it runs ("Saving…"). Use it instead of building the spinner yourself.
|
|
@@ -5,7 +5,7 @@ A field that opens a `Calendar` in a popover to choose a date or a date range. T
|
|
|
5
5
|
## Anatomy
|
|
6
6
|
1. **Trigger**: in single mode, a text input with a calendar button inside its right edge (Alt+↓ opens the calendar); in range mode, the `Input` box as a button, with a `calendar` icon (16px, `muted-foreground`) and the formatted date ("Oct 17, 2026", or "Sep 10 – Oct 10, 2026" for a range), or the placeholder in `muted-subtle`.
|
|
7
7
|
2. **Popover**: a dialog rendered at the end of the page (so scrolling containers, dialogs and drawers never clip it), 4px below the trigger and start-aligned with it (the whole field in typing mode), flipping above when there's no room and kept 8px inside the viewport: `surface-elevated`, 1px `border`, square, 0.75rem padding, at most the room on its side tall (it scrolls). It fades and rises 0.5rem over `motion-normal`; no motion under reduced motion.
|
|
8
|
-
3. **Calendar**: see `Calendar`.
|
|
8
|
+
3. **Calendar**: see `Calendar`. On the elevated panel the weekday row and days outside the month use `muted-foreground`, since `muted-subtle` keeps 4.5:1 only on `background` and `card`.
|
|
9
9
|
4. **Footer**: above a `border-subtle` rule, a ghost `Clear` button and, in single mode, an outline `Today` button, both `sm`.
|
|
10
10
|
|
|
11
11
|
## States
|
|
@@ -4,12 +4,14 @@ A labelled group of related controls, such as permissions or notification prefer
|
|
|
4
4
|
|
|
5
5
|
## Anatomy
|
|
6
6
|
- Native `fieldset` and `legend` preserve grouping for assistive technology.
|
|
7
|
-
- A square 1px `border-subtle` rule and `space-md` padding enclose the group; controls use `space-sm` gaps.
|
|
7
|
+
- A square 1px `border-subtle` rule and `space-md` padding enclose the group; controls use `space-sm` gaps. With `plain` there is no frame, and the group reads as part of the surrounding form.
|
|
8
|
+
- The legend uses the field label style (12px, 600, uppercase tracking, `muted-foreground`), so a group's name matches the labels of the fields beside it.
|
|
8
9
|
- Optional `hint` and `error` text describe the entire group through `aria-describedby`. An error also sets `aria-invalid`.
|
|
9
10
|
|
|
10
11
|
## Props
|
|
11
12
|
- `legend`: the visible accessible name.
|
|
12
13
|
- `hint`, `error`: instructions or validation applying to the whole group.
|
|
14
|
+
- `plain`: no frame or padding; use it for a group inside a form, such as assignee checkboxes between text fields.
|
|
13
15
|
- `children`: controls, usually `Checkbox` or `Radio`.
|
|
14
16
|
- Native fieldset attributes, including `disabled`, plus a forwarded ref.
|
|
15
17
|
|
|
@@ -5,8 +5,9 @@ A drop zone with a browse button for attaching files, and a list of the chosen f
|
|
|
5
5
|
## Anatomy
|
|
6
6
|
1. **Drop zone**: 1px dashed `muted-subtle` border on `card-fill`, with an `upload` icon, "Drop files here or browse", and a hint (types and size limit) in `muted-subtle`.
|
|
7
7
|
2. **Drag-over state**: a solid `primary` border, `primary-tint` fill and a `primary` icon.
|
|
8
|
-
3. **
|
|
9
|
-
4. **
|
|
8
|
+
3. **Disabled**: transparent fill, with the icon, title and browse button in `muted-subtle`, as a disabled `Input`.
|
|
9
|
+
4. **File list**: rows in a 1px `border-subtle` frame: `file` icon, name (truncated), size in Space Grotesk, and a remove `IconButton`.
|
|
10
|
+
5. **Error row**: `circle-alert` icon and the message in `danger` ("Larger than 10.0 MB.").
|
|
10
11
|
|
|
11
12
|
## Props
|
|
12
13
|
- `accept`, `multiple`, `maxSize` (bytes), `name`, `disabled`, `title`, `hint`, `defaultFiles`.
|
|
@@ -5,8 +5,8 @@ A button that opens a list of actions: row actions in a table, "More" in a toolb
|
|
|
5
5
|
## Anatomy
|
|
6
6
|
1. **Trigger**: an outline `Button` with a chevron glyph cell (`label`), or an `IconButton` (`icon` with `triggerLabel`), usually `ellipsis`.
|
|
7
7
|
2. **Panel**: `surface-elevated`, 1px `border`, square, at least 13rem wide, rendered in a portal at `z-popover` (so a scrolling table, dialog or drawer never clips it), 0.25rem below the trigger (above when there's no room), left- or right-aligned (`align="end"`), and scrolling when taller than the room it has. It fades and rises 0.5rem in over `motion-normal`; it closes at once.
|
|
8
|
-
3. **Item**: 36px tall, an optional 16px icon in `muted-foreground`, label in `small`, an optional shortcut in Space Grotesk `muted-
|
|
9
|
-
4. **Separator**: 1px `border-subtle`. **Group label**: 11px uppercase `muted-
|
|
8
|
+
3. **Item**: 36px tall, an optional 16px icon in `muted-foreground`, label in `small`, an optional shortcut in Space Grotesk `muted-foreground`.
|
|
9
|
+
4. **Separator**: 1px `border-subtle`. **Group label**: 11px uppercase `muted-foreground`.
|
|
10
10
|
|
|
11
11
|
## Item states
|
|
12
12
|
| State | Treatment |
|
|
@@ -41,7 +41,7 @@ WAI-ARIA menu button: the trigger has `aria-haspopup="menu"`, `aria-expanded` an
|
|
|
41
41
|
|
|
42
42
|
## Props
|
|
43
43
|
- `items`: `{ label, onSelect, icon, shortcut, danger, disabled }`, checkable and submenu items as above, `{ type: 'separator' }` or `{ type: 'label', label }`.
|
|
44
|
-
- `label` or `icon` + `triggerLabel`, `variant`, `size
|
|
44
|
+
- `label` or `icon` + `triggerLabel`, `variant`, `size` (`sm` or `xs`; an icon-only trigger becomes a 24px icon button at `xs`), `align`, `disabled`.
|
|
45
45
|
|
|
46
46
|
## Rules
|
|
47
47
|
- Menus hold actions. To pick a value, use `Select`; to navigate, use links.
|
|
@@ -5,7 +5,7 @@ The vertical navigation for an app's sidebar: sections of links with icons, coun
|
|
|
5
5
|
## Anatomy
|
|
6
6
|
1. **Section heading** (optional): 11px uppercase `muted-subtle`.
|
|
7
7
|
2. **Item**: 36px tall, a 16px icon, label in `small` 500 in `muted-foreground`, an optional count in Space Grotesk `muted-subtle` on the right.
|
|
8
|
-
3. **Current item**: `primary-tint` fill, `foreground` label, `primary` icon
|
|
8
|
+
3. **Current item**: `primary-tint` fill, `foreground` label, `primary` icon, count in `muted-foreground`.
|
|
9
9
|
|
|
10
10
|
## States
|
|
11
11
|
Hover: `card-fill` and `foreground`. Focus: the 2px `ring`, inset.
|
|
@@ -12,7 +12,7 @@ A small non-modal panel attached to a button, for interactive content that doesn
|
|
|
12
12
|
- The page stays usable behind it; nothing else is blocked.
|
|
13
13
|
|
|
14
14
|
## Props
|
|
15
|
-
- `label`, `title`, `icon`, `variant`, `size
|
|
15
|
+
- `label`, `title`, `icon`, `variant`, `size` (`sm` or `xs`), `align`, `width`.
|
|
16
16
|
- Native Radix state and mode: `open`, `defaultOpen`, `onOpenChange`, `modal`.
|
|
17
17
|
- `children`: panel content. `close`: one focusable element rendered through Radix Close. The former render-function child is replaced by native Close composition; for more application-specific actions, control `open` through `onOpenChange`.
|
|
18
18
|
|
|
@@ -7,6 +7,10 @@ Headings in Manrope 700, paragraphs in `muted-foreground` at 1.7 line height, `s
|
|
|
7
7
|
|
|
8
8
|
## Props
|
|
9
9
|
- `children` (the HTML, or `dangerouslySetInnerHTML` on your own element inside), `as`, `className`.
|
|
10
|
+
- `tone`: `muted` (default) for articles and release notes; `foreground` when the text is the record itself, such as a task description or a message.
|
|
11
|
+
|
|
12
|
+
## Compact density
|
|
13
|
+
With `data-density="compact"`, prose uses 14px text at 1.6 line height, 0.75em block spacing and headings from 20px down to 14px, so rendered Markdown sits beside compact interface text.
|
|
10
14
|
|
|
11
15
|
## Rules
|
|
12
16
|
- Sanitize any HTML you didn't write before rendering it.
|
|
@@ -62,7 +62,7 @@ Links accept HTTP(S), mailto, tel and relative/fragment URLs. Attachment and ima
|
|
|
62
62
|
|
|
63
63
|
- Default: `card` fill, `input-border`, body type from `control-font-size`.
|
|
64
64
|
- Focus: `primary` border with a 2px `ring` outline on the editor or toolbar action.
|
|
65
|
-
- Pressed formatting: `
|
|
65
|
+
- Pressed formatting: `foreground` on `primary-tint` with a `primary-line` edge, plus `aria-pressed`.
|
|
66
66
|
- Invalid: `danger` border; pair with `Field error` for an explanation.
|
|
67
67
|
- Disabled: dashed border and unavailable toolbar; `readOnly` retains selectable content and hides the toolbar.
|
|
68
68
|
- Forced colors: selected tools use system `Highlight`/`HighlightText`. There are no animations. Touch actions meet the shared control height.
|
|
@@ -12,7 +12,7 @@ Arrow keys move the selection (wrapping); one Tab stop for the whole control.
|
|
|
12
12
|
Built on Radix RadioGroup: `role="radiogroup"` (named by `label`) with `radio` buttons and `aria-checked`; the selected segment has `data-state="checked"`.
|
|
13
13
|
|
|
14
14
|
## Props
|
|
15
|
-
- `options`: strings or `{ value, label, icon, disabled }`. `value` + `onChange`, or `defaultValue`. `label`, `size
|
|
15
|
+
- `options`: strings or `{ value, label, icon, disabled }`. `value` + `onChange`, or `defaultValue`. `label`, `size` (`sm`, or `xs` for 22px segments with 12px labels inside toolbars).
|
|
16
16
|
|
|
17
17
|
## Rules
|
|
18
18
|
- The choice applies immediately. For a choice inside a form, use `RadioGroup`.
|
|
@@ -1,22 +1,25 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ThemeProvider and useTheme
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The one way to set an app's theme and density. `ThemeProvider` applies the saved or system theme, and the density, to `<html>` before the page paints, so there is no flash of the wrong theme. `useTheme` reads and changes the theme below it.
|
|
4
4
|
|
|
5
5
|
## Setup (Next.js App Router)
|
|
6
6
|
```tsx
|
|
7
|
-
// app/layout.tsx
|
|
8
|
-
import {
|
|
7
|
+
// app/layout.tsx (a server component)
|
|
8
|
+
import { ThemeProvider } from "@vokality/design-system";
|
|
9
9
|
|
|
10
10
|
export default function RootLayout({ children }) {
|
|
11
11
|
return (
|
|
12
12
|
<html lang="en" suppressHydrationWarning>
|
|
13
|
-
<
|
|
14
|
-
|
|
13
|
+
<body>
|
|
14
|
+
<ThemeProvider storageKey="app.theme" density="compact">{children}</ThemeProvider>
|
|
15
|
+
</body>
|
|
15
16
|
</html>
|
|
16
17
|
);
|
|
17
18
|
}
|
|
18
19
|
```
|
|
19
|
-
|
|
20
|
+
- Render it once, at the top of `<body>` in the root layout, around everything else. It inlines a small blocking script before its children, which must come from server-rendered HTML: React never runs a `<script>` created on the client.
|
|
21
|
+
- `suppressHydrationWarning` is needed because the script sets `data-theme` (and `data-density`) on `<html>` before React hydrates.
|
|
22
|
+
- Don't set `data-theme` or `data-density` yourself; the provider owns both, and portalled dialogs, menus and toasts inherit them from `<html>`.
|
|
20
23
|
|
|
21
24
|
## Switching
|
|
22
25
|
```tsx
|
|
@@ -29,18 +32,20 @@ export function ThemeSwitch() {
|
|
|
29
32
|
options={[{ value: "system", label: "System" }, { value: "dark", label: "Dark" }, { value: "light", label: "Light" }, { value: "contrast", label: "High contrast" }]} />;
|
|
30
33
|
}
|
|
31
34
|
```
|
|
35
|
+
- `useTheme()` takes no options; it uses the provider's.
|
|
32
36
|
- `theme` is the saved preference, or `"system"` when none is saved. `resolvedTheme` is the theme in effect. `setTheme("system")` clears the saved choice.
|
|
33
37
|
- Every `useTheme` on the page updates together, and other tabs follow through the `storage` event. While on `"system"`, the theme follows OS changes live.
|
|
34
38
|
- On the server, `useTheme` returns `"system"` and `defaultTheme`; the real values arrive after hydration. Don't render theme-specific markup on the server.
|
|
35
39
|
|
|
36
|
-
##
|
|
40
|
+
## Props
|
|
41
|
+
- `storageKey`: `vk-theme` by default.
|
|
37
42
|
- `defaultTheme`: `dark` (default), `light` or `contrast`, used when nothing is saved and the system has no preference.
|
|
38
43
|
- `followSystem`: `true` (default) uses `prefers-contrast: more` (→ `contrast`) and `prefers-color-scheme`.
|
|
39
|
-
- `
|
|
40
|
-
- `
|
|
44
|
+
- `density`: `default` or `compact` for dense operational interfaces (see the README's compact section).
|
|
45
|
+
- `nonce`: for a Content-Security-Policy that allows inline scripts by nonce.
|
|
41
46
|
|
|
42
47
|
## Without React
|
|
43
|
-
`themeScript(options)
|
|
48
|
+
Pages not rendered by React inline `themeScript(options)`, which returns the same script as a string.
|
|
44
49
|
|
|
45
50
|
## Rules
|
|
46
51
|
- Offer `contrast` as a choice, never as the default.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vokality/design-system",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "4.0.0",
|
|
4
4
|
"description": "Vokality's design system: tokens, themes and React components for every Vokality project.",
|
|
5
5
|
"license": "UNLICENSED",
|
|
6
6
|
"private": false,
|
|
@@ -49,7 +49,9 @@
|
|
|
49
49
|
"README.md",
|
|
50
50
|
"CHANGELOG.md",
|
|
51
51
|
"docs/brand.md",
|
|
52
|
-
"docs/components/*/README.md"
|
|
52
|
+
"docs/components/*/README.md",
|
|
53
|
+
"skills",
|
|
54
|
+
"bin/vokality-skill.mjs"
|
|
53
55
|
],
|
|
54
56
|
"sideEffects": [
|
|
55
57
|
"*.css"
|
|
@@ -58,16 +60,16 @@
|
|
|
58
60
|
"build": "bun scripts/build.mjs",
|
|
59
61
|
"test": "bun run build && bun test test/",
|
|
60
62
|
"test:browser": "bun run build && bun test --timeout 30000 e2e/",
|
|
61
|
-
"test:visual": "bun
|
|
62
|
-
"test:visual:update": "bun
|
|
63
|
-
"test:next": "bun run build && bun scripts/test-next.mjs build &&
|
|
64
|
-
"typecheck": "tsc -p tsconfig.json",
|
|
65
|
-
"lint": "eslint src --max-warnings 0",
|
|
63
|
+
"test:visual": "bun scripts/visual.mjs",
|
|
64
|
+
"test:visual:update": "bun scripts/visual.mjs --update",
|
|
65
|
+
"test:next": "bun run build && bun scripts/test-next.mjs build && bunx playwright test -c validation/playwright.config.mjs",
|
|
66
|
+
"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.stories.json",
|
|
67
|
+
"lint": "eslint src docs/foundations docs/templates .storybook --max-warnings 0",
|
|
66
68
|
"doctor": "react-doctor --yes --scope full --blocking warning --no-supply-chain --no-score",
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
"
|
|
70
|
-
"
|
|
69
|
+
"storybook": "bun run build && storybook dev -p 6006",
|
|
70
|
+
"build-storybook": "bun run build && storybook build -o artifact/storybook",
|
|
71
|
+
"test:stories": "bun run build && vitest run --project 'storybook (*)'",
|
|
72
|
+
"prepack": "bun run build"
|
|
71
73
|
},
|
|
72
74
|
"peerDependencies": {
|
|
73
75
|
"react": ">=18.2",
|
|
@@ -77,19 +79,29 @@
|
|
|
77
79
|
"@axe-core/playwright": "4.14.0",
|
|
78
80
|
"@eslint/js": "9.39.5",
|
|
79
81
|
"@playwright/test": "1.56.1",
|
|
82
|
+
"@storybook/addon-a11y": "10.6.1",
|
|
83
|
+
"@storybook/addon-docs": "10.6.1",
|
|
84
|
+
"@storybook/addon-vitest": "10.6.1",
|
|
85
|
+
"@storybook/react-vite": "10.6.1",
|
|
80
86
|
"@types/node": "26.6.5",
|
|
81
87
|
"@types/react": "^18",
|
|
82
88
|
"@types/react-dom": "^18",
|
|
89
|
+
"@vitest/browser": "5.0.3",
|
|
90
|
+
"@vitest/browser-playwright": "5.0.3",
|
|
83
91
|
"eslint": "9.39.5",
|
|
84
92
|
"eslint-plugin-react": "7.37.5",
|
|
85
93
|
"eslint-plugin-react-hooks": "7.1.1",
|
|
94
|
+
"eslint-plugin-storybook": "10.6.1",
|
|
86
95
|
"next": "16.4.2",
|
|
87
96
|
"playwright": "1.56.1",
|
|
88
97
|
"react": "18.3.1",
|
|
89
98
|
"react-doctor": "0.9.18",
|
|
90
99
|
"react-dom": "18.3.1",
|
|
100
|
+
"storybook": "10.6.1",
|
|
91
101
|
"typescript": "6.0.3",
|
|
92
|
-
"typescript-eslint": "8.71.2"
|
|
102
|
+
"typescript-eslint": "8.71.2",
|
|
103
|
+
"vite": "8.3.1",
|
|
104
|
+
"vitest": "5.0.3"
|
|
93
105
|
},
|
|
94
106
|
"publishConfig": {
|
|
95
107
|
"registry": "https://registry.npmjs.org",
|
|
@@ -118,5 +130,8 @@
|
|
|
118
130
|
"prosemirror-state": "1.4.4",
|
|
119
131
|
"prosemirror-view": "1.42.6",
|
|
120
132
|
"radix-ui": "1.8.0"
|
|
133
|
+
},
|
|
134
|
+
"bin": {
|
|
135
|
+
"vokality-skill": "./bin/vokality-skill.mjs"
|
|
121
136
|
}
|
|
122
137
|
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vokality-design-system
|
|
3
|
+
description: Build and update Vokality interfaces with the installed @vokality/design-system package. Use for component selection, layouts, forms, themes, localization, rich-text editing, and chat surfaces in projects using this package or explicitly requesting Vokality styling.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vokality design system
|
|
7
|
+
|
|
8
|
+
Use the installed package's components and visual language within the user's requested scope. Keep the application's framework, router, data ownership, and existing conventions unless the task requires changing them.
|
|
9
|
+
|
|
10
|
+
## Start with the installed contract
|
|
11
|
+
|
|
12
|
+
If this skill was registered through a symlink, resolve its physical directory in the installed package before following relative links. The `../../README.md` and `../../docs/` paths below are relative to that real skill directory, not the application's `.agents/skills` directory.
|
|
13
|
+
|
|
14
|
+
1. Read the relevant sections of the [package README](../../README.md) and [brand guide](../../docs/brand.md).
|
|
15
|
+
2. Find the component in the README, then read its `../../docs/components/ComponentName/README.md`. Check the installed public declarations for exact props and ref types before coding; component-specific contracts take precedence over broad descriptions in the brand guide.
|
|
16
|
+
3. Compose existing components before creating a new control. Use `Stack`, `Inline`, and `Grid` for layout; `Heading` and `Text` for interface copy; `Prose` for rendered long-form content. Use semantic `as` elements where appropriate.
|
|
17
|
+
|
|
18
|
+
Do not deep-import `src/` or `dist/`, invent props from another component library, or add a parallel UI kit to implement an existing component. The examples in [references/examples.tsx](references/examples.tsx) compile against the public package API; read them when implementing forms, Markdown editing, or conversations.
|
|
19
|
+
|
|
20
|
+
## Imports and presentation
|
|
21
|
+
|
|
22
|
+
- Import `@vokality/design-system/vokality.css` once at the application's stylesheet entry. Core components and their prop types come from `@vokality/design-system`.
|
|
23
|
+
- Use the direct entrypoints `@vokality/design-system/localization`, `@vokality/design-system/rich-text`, `@vokality/design-system/chat-widget`, `@vokality/design-system/chat-inbox`, and `@vokality/design-system/chat-models` for those features. Keep type imports explicit. These features are not root exports.
|
|
24
|
+
- Use existing tokens such as `var(--background)`, `var(--foreground)`, `var(--primary)`, `var(--border-subtle)`, and `var(--space-lg)` for application CSS. Prefer component variants and layout props over overriding internal selectors. Corners are square, surfaces have thin outlines, and orange identifies the primary action or selection. Avoid decorative shadows and gradients.
|
|
25
|
+
- Write labels in sentence case; styles provide uppercase presentation. Use the supplied icons and accessible labels. User-authored emoji belong in rich text; interface copy follows the brand guide.
|
|
26
|
+
- Set theme and density once with [ThemeProvider](../../docs/components/ThemeProvider/README.md) at the top of `<body>` in the root layout (`density="compact"` for dense apps); never set `data-theme` or `data-density` yourself. Themes are `dark`, `light`, and `contrast`; switch them with `useTheme()`, which takes no options. Use `size="xs"` on `Button`, `IconButton`, `Menu`, `Popover` and `SegmentedControl` for actions in toolbars, record rows and status lines; fields keep the control height.
|
|
27
|
+
- In Tailwind v4 applications, follow the README's stylesheet order and token mapping. Do not introduce Tailwind or replace the application's styling setup merely to use the package.
|
|
28
|
+
|
|
29
|
+
## Behavior, forms, and React
|
|
30
|
+
|
|
31
|
+
The fully supplied Radix controls already own keyboard interaction, focus, selection, dismissal, gestures, timers, and native form integration. Compose and style them through their public props. Do not add a second keyboard/focus engine, synthetic input-event targets, or wrapper-owned default-selection policy. Composite controls such as `Combobox` and `DatePicker` already compose their required behavior too; use their documented APIs.
|
|
32
|
+
|
|
33
|
+
- [Checkbox](../../docs/components/Checkbox/README.md) uses `onCheckedChange(boolean | "indeterminate")`; [Switch](../../docs/components/Switch/README.md) uses `onCheckedChange(boolean)`. Their refs and DOM callbacks target buttons, not native checkbox inputs. Map state explicitly only when the application's domain requires it.
|
|
34
|
+
- [RadioGroup](../../docs/components/RadioGroup/README.md) uses `onValueChange(string)`, `Select` uses `onChange(value, option)`, and `SegmentedControl` uses `onChange(value)`. Supply `value` or `defaultValue` when selection is intended. Native `Input` and standalone `Radio` keep native input events.
|
|
35
|
+
- [Field](../../docs/components/Field/README.md) labels one control and wires its ID, hint, and error attributes. Checkbox and Switch provide their own labels; RadioGroup provides a legend. Give form controls names and use their documented `required` and `disabled` props. Submit through the form's native event and `FormData`; a save action needs `type="submit"` because `Button` defaults to `button`.
|
|
36
|
+
- Choose controlled `value` plus its change callback, or uncontrolled `defaultValue`; do not synchronize both through an effect. Keep handlers and stateful composition in the framework's client boundary. Preserve React 18.2+ compatibility, server-safe rendering, and actual DOM ref types. Do not access browser globals or read/write refs during render.
|
|
37
|
+
- For server-rendered Calendar/DatePicker output, pass the same explicit `today` value on server and client when their day or time zone may differ. Read the component docs for date-string and locale contracts.
|
|
38
|
+
|
|
39
|
+
## Locale and content ownership
|
|
40
|
+
|
|
41
|
+
Use [LocaleProvider](../../docs/components/LocaleProvider/README.md) from the localization entrypoint for built-in labels and formatting. It supports scoped, typed message overrides and reaches portals. Explicit label props remain application copy. Keep placeholders, custom emoji labels, and server-provided content in the application's language. Use the exported formatting helpers rather than constructing localized number or date strings by hand.
|
|
42
|
+
|
|
43
|
+
For [RichTextEditor](../../docs/components/RichTextEditor/README.md), store a CommonMark Markdown string. `value`/`onChange` are Markdown, not HTML or editor JSON; serialization may normalize equivalent syntax. Use `toolbar="minimal"` for a small writing-first composer when appropriate. The application owns persistence and rendering saved Markdown; `Prose` supplies reading styles, not a parser.
|
|
44
|
+
|
|
45
|
+
Attachments are opt-in through `onUploadAttachment(file, { signal })`, returning a durable `{ name, url }`. Reuse the application's upload service, validate unknown responses at that service boundary, honor cancellation, and enforce upload policy on the server. The editor handles upload feedback, cancel/retry, safe URL checks, and Markdown links. Removing a link does not delete its server asset. Use `onUploadPendingChange` when an external send action must wait for uploads.
|
|
46
|
+
|
|
47
|
+
For [ChatWidget](../../docs/components/ChatWidget/README.md) and [ChatInbox](../../docs/components/ChatInbox/README.md), supply typed `ChatMessage`/`ChatThread` data with stable IDs. Message `content` is a render-ready React node; a string displays as text. Use the application's established safe Markdown renderer if formatted incoming content is needed. The composer emits Markdown.
|
|
48
|
+
|
|
49
|
+
`composer.onSend` synchronously accepts a draft; the application owns async transport, streaming, pending/error state, retry callbacks, and persistence. An uncontrolled draft clears after normal callback return. Clear a controlled draft explicitly after application acceptance. Inbox selection is controlled, Back emits `null`, and switching threads resets uncontrolled drafts and cancels pending uploads. Keep controlled drafts by thread ID if navigation must preserve them. Do not invent an AI backend or upload endpoint for a presentation task.
|
|
50
|
+
|
|
51
|
+
## Motion and verification
|
|
52
|
+
|
|
53
|
+
Keep the package's existing motion and reduced-motion handling. Chat already uses Motion for panel entry/exit and newly added messages while Radix retains interaction ownership. Avoid animating existing history, stacking a second transition on an overlay, or adding timers to retain content. Any requested application motion should be brief and stop under reduced motion.
|
|
54
|
+
|
|
55
|
+
Run the host application's relevant type, lint, and behavioral checks. Verify changed UI at its narrow container size and with long real content, keyboard focus, disabled/loading/error states, and the themes or density affected by the task. Check portalled content and short viewport containment when changing overlays. Keep verification proportional to the change; do not expand a component task into an application rewrite.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
|
|
3
|
+
import { useState } from "react";
|
|
4
|
+
import { Button, Checkbox, Field, Input, RadioGroup, Stack, Switch } from "@vokality/design-system";
|
|
5
|
+
import { LocaleProvider } from "@vokality/design-system/localization";
|
|
6
|
+
import { RichTextEditor } from "@vokality/design-system/rich-text";
|
|
7
|
+
import type { RichTextUpload } from "@vokality/design-system/rich-text";
|
|
8
|
+
import { ChatWidget } from "@vokality/design-system/chat-widget";
|
|
9
|
+
import { ChatInbox } from "@vokality/design-system/chat-inbox";
|
|
10
|
+
import type { ChatComposerOptions, ChatMessage, ChatThread } from "@vokality/design-system/chat-models";
|
|
11
|
+
|
|
12
|
+
// Import @vokality/design-system/vokality.css once in the application entry.
|
|
13
|
+
// Upload and persistence callbacks below belong to the application, not the UI.
|
|
14
|
+
interface NotesFormProps {
|
|
15
|
+
initialMarkdown: string;
|
|
16
|
+
uploadAttachment?: RichTextUpload;
|
|
17
|
+
onSave: (data: FormData) => void;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function NotesForm({ initialMarkdown, uploadAttachment, onSave }: NotesFormProps) {
|
|
21
|
+
const [markdown, setMarkdown] = useState(initialMarkdown);
|
|
22
|
+
const [notify, setNotify] = useState(false);
|
|
23
|
+
const [uploadPending, setUploadPending] = useState(false);
|
|
24
|
+
return (
|
|
25
|
+
<LocaleProvider locale="en-US">
|
|
26
|
+
<Stack as="form" gap="lg" onSubmit={(event) => {
|
|
27
|
+
event.preventDefault();
|
|
28
|
+
if (uploadPending) return;
|
|
29
|
+
onSave(new FormData(event.currentTarget));
|
|
30
|
+
}}>
|
|
31
|
+
<Field label="Subject">
|
|
32
|
+
<Input name="subject" required />
|
|
33
|
+
</Field>
|
|
34
|
+
<Field label="Notes" hint="Formatting and attachments are saved as Markdown.">
|
|
35
|
+
<RichTextEditor name="notes" value={markdown} onChange={setMarkdown} onUploadAttachment={uploadAttachment} onUploadPendingChange={setUploadPending} />
|
|
36
|
+
</Field>
|
|
37
|
+
<RadioGroup label="Visibility" name="visibility" defaultValue="team" options={[
|
|
38
|
+
{ value: "team", label: "Team" },
|
|
39
|
+
{ value: "private", label: "Only me" },
|
|
40
|
+
]} />
|
|
41
|
+
<Checkbox label="Notify the team" name="notify" checked={notify} onCheckedChange={(next) => {
|
|
42
|
+
// This domain is binary. Preserve "indeterminate" in domains that need it.
|
|
43
|
+
setNotify(next === true);
|
|
44
|
+
}} />
|
|
45
|
+
<Button type="submit" disabled={uploadPending}>Save notes</Button>
|
|
46
|
+
</Stack>
|
|
47
|
+
</LocaleProvider>
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// Switch applies an immediate setting through its boolean callback.
|
|
52
|
+
export function EmailSetting({ enabled, onChange }: { enabled: boolean; onChange: (enabled: boolean) => void }) {
|
|
53
|
+
return <Switch label="Weekly summary email" checked={enabled} onCheckedChange={onChange} />;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
interface SupportWidgetProps {
|
|
57
|
+
messages: readonly ChatMessage[];
|
|
58
|
+
sending: boolean;
|
|
59
|
+
// Accept synchronously; the application manages the eventual transport result.
|
|
60
|
+
acceptMessage: (markdown: string) => void;
|
|
61
|
+
retryMessage: (messageId: string) => void;
|
|
62
|
+
uploadAttachment?: RichTextUpload;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export function SupportWidget({ messages, sending, acceptMessage, retryMessage, uploadAttachment }: SupportWidgetProps) {
|
|
66
|
+
const [draft, setDraft] = useState("");
|
|
67
|
+
return (
|
|
68
|
+
<ChatWidget title="Support" messages={messages} onRetryMessage={retryMessage} composer={{
|
|
69
|
+
value: draft,
|
|
70
|
+
onChange: setDraft,
|
|
71
|
+
sending,
|
|
72
|
+
onUploadAttachment: uploadAttachment,
|
|
73
|
+
onSend(markdown) {
|
|
74
|
+
acceptMessage(markdown);
|
|
75
|
+
// A controlled draft clears only when the application acknowledges it.
|
|
76
|
+
setDraft("");
|
|
77
|
+
},
|
|
78
|
+
}} />
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
interface SupportInboxProps {
|
|
83
|
+
threads: readonly ChatThread[];
|
|
84
|
+
selectedThreadId: string | null;
|
|
85
|
+
onSelectThread: (threadId: string | null) => void;
|
|
86
|
+
// These messages and this composer must belong to the selected thread.
|
|
87
|
+
messages: readonly ChatMessage[];
|
|
88
|
+
// Supply value/onChange backed by thread IDs to preserve drafts on navigation.
|
|
89
|
+
composer: ChatComposerOptions;
|
|
90
|
+
retryMessage: (messageId: string) => void;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export function SupportInbox({ threads, selectedThreadId, onSelectThread, messages, composer, retryMessage }: SupportInboxProps) {
|
|
94
|
+
return <ChatInbox title="Inbox" threads={threads} selectedThreadId={selectedThreadId} onSelectThread={onSelectThread} messages={messages} composer={composer} onRetryMessage={retryMessage} />;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// content is ready to render. A Markdown string here would display as text.
|
|
98
|
+
export const welcomeMessage: ChatMessage = {
|
|
99
|
+
id: "support-welcome",
|
|
100
|
+
direction: "incoming",
|
|
101
|
+
author: { name: "Support" },
|
|
102
|
+
content: <p>What can we help you with?</p>,
|
|
103
|
+
};
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
import { type ThemeOptions } from "../../lib/theme.js";
|
|
2
|
-
export interface ThemeScriptProps extends ThemeOptions {
|
|
3
|
-
/** For a Content-Security-Policy that allows inline scripts by nonce. */
|
|
4
|
-
nonce?: string;
|
|
5
|
-
}
|
|
6
|
-
/** Put in <head>: applies the saved or system theme before first paint, so there is no flash. */
|
|
7
|
-
export declare function ThemeScript(props: ThemeScriptProps): import("react/jsx-runtime").JSX.Element;
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
-
// No "use client": ThemeScript has no hooks or browser APIs, so it renders as a
|
|
3
|
-
// React Server Component in a layout. React never runs a <script> created by a
|
|
4
|
-
// client component.
|
|
5
|
-
import { themeScript } from "../../lib/theme.js";
|
|
6
|
-
/** Put in <head>: applies the saved or system theme before first paint, so there is no flash. */
|
|
7
|
-
export function ThemeScript(props) {
|
|
8
|
-
return _jsx("script", { nonce: props.nonce, dangerouslySetInnerHTML: { __html: themeScript(props) } });
|
|
9
|
-
}
|