@pumba-ui/ui 0.0.0-stage → 0.2.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,8 @@
1
+ import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./tabs.js";
2
+ export type { TabsProps } from "./tabs.js";
3
+ export declare const Tabs: {
4
+ Root: typeof TabsRoot;
5
+ List: typeof TabsList;
6
+ Tab: typeof TabsTab;
7
+ Panel: typeof TabsPanel;
8
+ };
@@ -0,0 +1,10 @@
1
+ import { TabsList, TabsPanel, TabsRoot, TabsTab } from "./tabs.js";
2
+ //#region src/tabs/index.ts
3
+ var Tabs = {
4
+ Root: TabsRoot,
5
+ List: TabsList,
6
+ Tab: TabsTab,
7
+ Panel: TabsPanel
8
+ };
9
+ //#endregion
10
+ export { Tabs };
@@ -0,0 +1,25 @@
1
+ import type { ComponentProps, ReactElement } from "react";
2
+ type Render<Tag extends "div" | "button"> = ReactElement | ((props: ComponentProps<Tag>) => ReactElement);
3
+ export type TabsProps = Omit<ComponentProps<"div">, "defaultValue"> & {
4
+ value?: string;
5
+ defaultValue?: string;
6
+ onValueChange?: (value: string) => void;
7
+ render?: Render<"div">;
8
+ };
9
+ type TabsListProps = ComponentProps<"div"> & {
10
+ render?: Render<"div">;
11
+ };
12
+ type TabsTabProps = ComponentProps<"button"> & {
13
+ value: string;
14
+ nativeButton?: boolean;
15
+ render?: Render<"button">;
16
+ };
17
+ type TabsPanelProps = ComponentProps<"div"> & {
18
+ value: string;
19
+ render?: Render<"div">;
20
+ };
21
+ declare function TabsRoot({ className, onValueChange, ...rest }: TabsProps): import("react").JSX.Element;
22
+ declare function TabsList({ className, children, ...rest }: TabsListProps): import("react").JSX.Element;
23
+ declare function TabsTab({ className, ...rest }: TabsTabProps): import("react").JSX.Element;
24
+ declare function TabsPanel({ className, ...rest }: TabsPanelProps): import("react").JSX.Element;
25
+ export { TabsList, TabsPanel, TabsRoot, TabsTab };
@@ -0,0 +1,35 @@
1
+ "use client";
2
+ import { jsx, jsxs } from "react/jsx-runtime";
3
+ import { Tabs } from "@base-ui/react/tabs";
4
+ //#region src/tabs/tabs.tsx
5
+ var join = (own, className) => className ? `${own} ${className}` : own;
6
+ function TabsRoot({ className, onValueChange, ...rest }) {
7
+ return /* @__PURE__ */ jsx(Tabs.Root, {
8
+ className: join("pumba-tabs", className),
9
+ onValueChange: (value) => {
10
+ if (typeof value === "string") onValueChange?.(value);
11
+ },
12
+ ...rest
13
+ });
14
+ }
15
+ function TabsList({ className, children, ...rest }) {
16
+ return /* @__PURE__ */ jsxs(Tabs.List, {
17
+ className: join("pumba-tabs-list", className),
18
+ ...rest,
19
+ children: [children, /* @__PURE__ */ jsx(Tabs.Indicator, { className: "pumba-tabs-indicator" })]
20
+ });
21
+ }
22
+ function TabsTab({ className, ...rest }) {
23
+ return /* @__PURE__ */ jsx(Tabs.Tab, {
24
+ className: join("pumba-tabs-tab", className),
25
+ ...rest
26
+ });
27
+ }
28
+ function TabsPanel({ className, ...rest }) {
29
+ return /* @__PURE__ */ jsx(Tabs.Panel, {
30
+ className: join("pumba-tabs-panel", className),
31
+ ...rest
32
+ });
33
+ }
34
+ //#endregion
35
+ export { TabsList, TabsPanel, TabsRoot, TabsTab };
package/package.json CHANGED
@@ -1,6 +1,81 @@
1
1
  {
2
2
  "name": "@pumba-ui/ui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "Accessible React components for the Pumba design system.",
5
+ "license": "MIT",
6
+ "homepage": "https://github.com/vnloyola/pumba-ui#readme",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/vnloyola/pumba-ui.git",
10
+ "directory": "packages/ui"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/vnloyola/pumba-ui/issues"
14
+ },
15
+ "keywords": [
16
+ "react",
17
+ "design-system",
18
+ "components",
19
+ "accessible",
20
+ "base-ui",
21
+ "css-layers",
22
+ "dark-mode"
23
+ ],
24
+ "type": "module",
25
+ "exports": {
26
+ ".": {
27
+ "types": "./dist/index.d.ts",
28
+ "default": "./dist/index.js"
29
+ },
30
+ "./styles.css": "./dist/styles.css",
31
+ "./reset.css": "./dist/reset.css"
32
+ },
33
+ "files": [
34
+ "dist",
35
+ "USAGE.md",
36
+ "skills"
37
+ ],
38
+ "sideEffects": [
39
+ "**/*.css"
40
+ ],
41
+ "peerDependencies": {
42
+ "react": "^19.0.0",
43
+ "react-dom": "^19.0.0"
44
+ },
45
+ "dependencies": {
46
+ "@base-ui/react": "^1.8.0",
47
+ "@fontsource-variable/figtree": "^5.3.0",
48
+ "@fontsource-variable/jetbrains-mono": "^5.3.0"
49
+ },
50
+ "devDependencies": {
51
+ "@arethetypeswrong/cli": "^0.18.5",
52
+ "@pumba-ui/tokens": "0.2.0",
53
+ "@storybook/react-vite": "^10.6.1",
54
+ "@testing-library/dom": "^10.4.2",
55
+ "@testing-library/react": "^16.3.3",
56
+ "@types/react": "^19.3.0",
57
+ "@types/react-dom": "^19.3.0",
58
+ "axe-core": "^4.14.0",
59
+ "jsdom": "^30.1.3",
60
+ "lucide-react": "^1.52.0",
61
+ "postcss": "^8.5.0",
62
+ "postcss-import": "^17.0.0",
63
+ "publint": "^0.3.25",
64
+ "react": "^19.3.0",
65
+ "react-dom": "^19.3.0",
66
+ "storybook": "^10.6.1",
67
+ "vite": "^8.3.2",
68
+ "vitest": "^5.0.5"
69
+ },
70
+ "publishConfig": {
71
+ "access": "public",
72
+ "provenance": true
73
+ },
74
+ "scripts": {
75
+ "build": "vite build && tsc -p tsconfig.build.json && node scripts/build-css.mjs",
76
+ "typecheck": "tsc --noEmit",
77
+ "check:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints ./styles.css ./reset.css && node scripts/check-public-types.mjs",
78
+ "test": "vitest run",
79
+ "add:component": "node scripts/add-component.mjs"
80
+ }
6
81
  }
@@ -0,0 +1,317 @@
1
+ ---
2
+ name: pumba-design
3
+ description: Design rules for building interfaces with the Pumba design system (@pumba-ui/ui and @pumba-ui/tokens). Use when creating or reviewing pages, layouts or components in a project that depends on @pumba-ui/ui, to choose variants, tokens, spacing, elevation and states the way Pumba intends.
4
+ ---
5
+
6
+ # Pumba design rules
7
+
8
+ Pumba is warm, simple and firm: near-pure grays, one mahogany accent, one font family, strong
9
+ contrast and no decorative effects. These rules keep a page inside that direction.
10
+
11
+ Read `node_modules/@pumba-ui/ui/USAGE.md` first: it covers setup, theming, shared props, compound
12
+ components and the accessibility the app provides. The props of each component are in the
13
+ package's `.d.ts` files. This skill does not repeat them; it covers the choices the types allow but
14
+ the design does not.
15
+
16
+ ## 1. Use a Pumba component before building one
17
+
18
+ If Pumba has it, use it and adjust layout with `className`. Do not rebuild a button, field, badge,
19
+ card, tabs or dialog with plain elements, and do not restyle a `.pumba-*` class to get a look a
20
+ variant already gives.
21
+
22
+ Good:
23
+
24
+ ```tsx
25
+ <Button variant="secondary" size="sm">Export</Button>
26
+ ```
27
+
28
+ Avoid:
29
+
30
+ ```tsx
31
+ <button className="rounded-lg border px-3 py-1 text-sm">Export</button>
32
+ ```
33
+
34
+ ## 2. One primary action per region
35
+
36
+ The accent is the only color with emphasis, so it marks the one action the region is for. Other
37
+ actions are `secondary`, and low-priority or repeated ones (toolbars, rows) are `ghost`.
38
+
39
+ Good:
40
+
41
+ ```tsx
42
+ <Card.Footer>
43
+ <Button variant="ghost">Cancel</Button>
44
+ <Button>Save changes</Button>
45
+ </Card.Footer>
46
+ ```
47
+
48
+ Avoid:
49
+
50
+ ```tsx
51
+ <Card.Footer>
52
+ <Button>Cancel</Button>
53
+ <Button>Save changes</Button>
54
+ </Card.Footer>
55
+ ```
56
+
57
+ ## 3. Destructive means it cannot be undone
58
+
59
+ `destructive` is for deleting or other irreversible actions, and it is confirmed in a `Dialog`
60
+ whose title names the object. The button that opens that dialog keeps its natural width and sits
61
+ apart from the everyday actions (at the end of the page or in its own card), never as a
62
+ full-width bar. The confirm button repeats the verb; the way out is `secondary`.
63
+ "Sign out" or "Remove filter" are not destructive.
64
+
65
+ Good:
66
+
67
+ ```tsx
68
+ <Dialog.Content>
69
+ <Dialog.Title>Delete "Q3 report"?</Dialog.Title>
70
+ <Dialog.Description>The report and its 12 comments are deleted for everyone.</Dialog.Description>
71
+ <div className="dialog-actions">
72
+ <Dialog.Close>
73
+ <Button variant="secondary">Keep report</Button>
74
+ </Dialog.Close>
75
+ <Dialog.Close>
76
+ <Button variant="destructive" onClick={deleteReport}>Delete report</Button>
77
+ </Dialog.Close>
78
+ </div>
79
+ </Dialog.Content>
80
+ ```
81
+
82
+ Avoid:
83
+
84
+ ```tsx
85
+ <Button variant="destructive" onClick={deleteReport}>Delete</Button>
86
+ ```
87
+
88
+ ## 4. Every value comes from a semantic token
89
+
90
+ Colors, spacing, radii, shadows and type sizes come from `--pumba-*` tokens. No hex, `rgb()`,
91
+ `oklch()`, Tailwind palette colors (`slate-500`, `blue-600`) or `--pumba-primitive-*`. Primitives
92
+ and literals do not switch with the theme, so they break dark mode.
93
+
94
+ Good:
95
+
96
+ ```css
97
+ .page-header {
98
+ border-bottom: 1px solid var(--pumba-color-border);
99
+ color: var(--pumba-color-text-secondary);
100
+ padding-block: var(--pumba-space-4);
101
+ }
102
+ ```
103
+
104
+ Avoid:
105
+
106
+ ```css
107
+ .page-header {
108
+ border-bottom: 1px solid #e5e7eb;
109
+ color: var(--pumba-primitive-color-neutral-500);
110
+ padding-block: 18px;
111
+ }
112
+ ```
113
+
114
+ ## 5. Spacing has roles
115
+
116
+ Inside a surface the padding is `--pumba-space-inset`, the vertical gap between blocks is
117
+ `--pumba-space-stack`, and the gap between controls in a row is `--pumba-space-gap`. Anything
118
+ else takes a step of the numbered scale (`--pumba-space-1` to `--pumba-space-24`); no value off
119
+ the scale.
120
+
121
+ Good:
122
+
123
+ ```css
124
+ .settings-panel {
125
+ display: grid;
126
+ gap: var(--pumba-space-stack);
127
+ padding: var(--pumba-space-inset);
128
+ }
129
+ ```
130
+
131
+ Avoid:
132
+
133
+ ```css
134
+ .settings-panel {
135
+ display: grid;
136
+ gap: 14px;
137
+ padding: 22px;
138
+ }
139
+ ```
140
+
141
+ ## 6. Elevation is surfaces and borders, not shadows
142
+
143
+ Layers read through `background`, `surface` and `surface-raised` plus a `border`. A card already
144
+ has its shadow. `--pumba-shadow-overlay` is only for things that float above the page (popovers,
145
+ dialogs). No gradients, glows, blurs or colored shadows.
146
+
147
+ Good:
148
+
149
+ ```css
150
+ .sidebar {
151
+ background: var(--pumba-color-surface);
152
+ border-inline-end: 1px solid var(--pumba-color-border);
153
+ }
154
+ ```
155
+
156
+ Avoid:
157
+
158
+ ```css
159
+ .sidebar {
160
+ background: linear-gradient(180deg, #fff, #f5f5f5);
161
+ box-shadow: 0 10px 30px rgb(0 0 0 / 0.2);
162
+ }
163
+ ```
164
+
165
+ ## 7. Radii nest, they are not invented
166
+
167
+ Surfaces use `--pumba-radius-surface`, controls and anything inside a surface that follows its
168
+ corner (an image in a card) use `--pumba-radius-control`, and pills use `--pumba-radius-pill`.
169
+ The surface radius equals the control radius plus the inset, so a child that fills a card's padding
170
+ lines up with its corner.
171
+
172
+ Good:
173
+
174
+ ```css
175
+ .card-cover {
176
+ border-radius: var(--pumba-radius-control);
177
+ }
178
+ ```
179
+
180
+ Avoid:
181
+
182
+ ```css
183
+ .card-cover {
184
+ border-radius: 6px;
185
+ }
186
+ ```
187
+
188
+ ## 8. Hierarchy from the text styles
189
+
190
+ One family. Titles, subtitles, body, labels, captions and code use the `--pumba-text-<style>-*`
191
+ tokens (`heading`, `subheading`, `body`, `label`, `caption`, `code`), each with its
192
+ `font-family`, `font-size`, `font-weight`, `line-height` and `letter-spacing`. Do not add a font,
193
+ a size or a weight outside them. Secondary text is `--pumba-color-text-secondary`, not lighter
194
+ opacity.
195
+
196
+ Good:
197
+
198
+ ```css
199
+ .page-title {
200
+ font-family: var(--pumba-text-heading-font-family);
201
+ font-size: var(--pumba-text-heading-font-size);
202
+ font-weight: var(--pumba-text-heading-font-weight);
203
+ line-height: var(--pumba-text-heading-line-height);
204
+ letter-spacing: var(--pumba-text-heading-letter-spacing);
205
+ }
206
+ ```
207
+
208
+ Avoid:
209
+
210
+ ```css
211
+ .page-title {
212
+ font-family: "Inter", sans-serif;
213
+ font-size: 28px;
214
+ font-weight: 800;
215
+ opacity: 0.9;
216
+ }
217
+ ```
218
+
219
+ ## 9. State is never color alone
220
+
221
+ Success, error and warning always come with text that names them, and ideally an icon (Pumba
222
+ exports none; any icon set works). A red
223
+ border alone, or a green dot alone, is not enough: the error hue sits close to the mahogany accent.
224
+
225
+ Good:
226
+
227
+ ```tsx
228
+ <Badge variant="error">
229
+ <TriangleAlert aria-hidden="true" />
230
+ Payment failed
231
+ </Badge>
232
+ ```
233
+
234
+ Avoid:
235
+
236
+ ```tsx
237
+ <Badge variant="error" aria-label="Payment failed" />
238
+ ```
239
+
240
+ ## 10. Status colors are for status
241
+
242
+ `Badge` is `neutral` by default and `accent` to highlight something. `success`, `error` and
243
+ `warning` describe a real state (paid, failed, expiring), never a category or decoration.
244
+
245
+ Good:
246
+
247
+ ```tsx
248
+ <Badge>Draft</Badge>
249
+ <Badge variant="accent">New</Badge>
250
+ <Badge variant="success">Paid</Badge>
251
+ ```
252
+
253
+ Avoid:
254
+
255
+ ```tsx
256
+ <Badge variant="success">Marketing</Badge>
257
+ <Badge variant="warning">Engineering</Badge>
258
+ ```
259
+
260
+ ## 11. Fields are filled, with the label above
261
+
262
+ An `Input` is filled and borderless by design. Do not add a border or a shadow to make it stand
263
+ out; give it a visible label above, and put hints and errors as text below it. A hint is
264
+ `--pumba-color-text-secondary`; an error message is `--pumba-color-error-text`, in the caption
265
+ style.
266
+
267
+ Good:
268
+
269
+ ```tsx
270
+ <label htmlFor="email">Email</label>
271
+ <Input id="email" type="email" invalid aria-describedby="email-error" />
272
+ <p id="email-error" className="field-error">Enter an email like name@example.com.</p>
273
+ ```
274
+
275
+ ```css
276
+ .field-error {
277
+ color: var(--pumba-color-error-text);
278
+ font-size: var(--pumba-text-caption-font-size);
279
+ line-height: var(--pumba-text-caption-line-height);
280
+ }
281
+ ```
282
+
283
+ Avoid:
284
+
285
+ ```tsx
286
+ <Input placeholder="Email" style={{ border: "1px solid red" }} />
287
+ ```
288
+
289
+ ## 12. Check both themes
290
+
291
+ Every page is reviewed in light and dark (`data-theme` on `<html>`). A subtree with its own
292
+ `data-theme` sets its own `background` and `color`, and a dialog opened from it receives that
293
+ subtree as `container`.
294
+
295
+ Good:
296
+
297
+ ```tsx
298
+ <section data-theme="dark" className="promo" ref={setPromo}>
299
+ <Dialog.Root>
300
+ <Dialog.Trigger><Button>Details</Button></Dialog.Trigger>
301
+ <Dialog.Content container={promo}>…</Dialog.Content>
302
+ </Dialog.Root>
303
+ </section>
304
+ ```
305
+
306
+ ```css
307
+ .promo {
308
+ background: var(--pumba-color-background);
309
+ color: var(--pumba-color-text);
310
+ }
311
+ ```
312
+
313
+ Avoid:
314
+
315
+ ```tsx
316
+ <section data-theme="dark">…</section>
317
+ ```