@pumba-ui/ui 0.1.0 → 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.
package/README.md CHANGED
@@ -45,6 +45,12 @@ element they render, append your `className` to their own, and take a `render` p
45
45
  the element they render. The rules every component follows are in
46
46
  [`docs/api-conventions.md`](https://github.com/vnloyola/pumba-ui/blob/main/docs/api-conventions.md).
47
47
 
48
+ [`USAGE.md`](./USAGE.md), shipped in the package, is the short guide for building an app with
49
+ Pumba: setup, theming, the props every component shares, compound components, the accessibility
50
+ the app provides and how dialogs stack. It is written so an agent can read it from
51
+ `node_modules/@pumba-ui/ui/USAGE.md`. The design rules that go with it ship as a skill in
52
+ `skills/pumba-design/SKILL.md`; `USAGE.md` shows how to register it in a project.
53
+
48
54
  ## Styles
49
55
 
50
56
  Import the stylesheet once, in your app's entry CSS or JS:
@@ -114,8 +120,8 @@ pnpm --filter @pumba-ui/ui check:package # publint and arethetypeswrong
114
120
  Three tools, one job each:
115
121
 
116
122
  - **Vite** builds `src/` into readable ESM with one output file per source module
117
- (`preserveModules`, `minify: false`; the consumer's bundler minifies). `react`, `react-dom`,
118
- `lucide-react` and `@base-ui/react` stay external, so the consumer installs each once.
123
+ (`preserveModules`, `minify: false`; the consumer's bundler minifies). `react`, `react-dom`
124
+ and `@base-ui/react` stay external, so the consumer installs each once.
119
125
  `emptyOutDir` is off because `dist/` also holds the types and CSS. Each component file
120
126
  (`button.tsx`, `card.tsx`…) starts with `"use client"`, because the components call hooks
121
127
  (`useRender`, `useRef`). The `index.ts` files do not: they build the compound objects
@@ -123,7 +129,8 @@ Three tools, one job each:
123
129
  `Card.Root` gets a client reference instead of `undefined`. A single bundle with one
124
130
  `"use client"` banner cannot do that: the server only sees the `Card` object as an opaque
125
131
  reference and cannot read its parts.
126
- - **`tsc`** emits the declarations (`tsconfig.build.json`, which excludes tests and stories).
132
+ - **`tsc`** emits the declarations (`tsconfig.build.json`, which excludes tests, stories and
133
+ `icons.ts`).
127
134
  Relative imports in `src` carry the `.js` extension so the emitted types resolve under Node's
128
135
  ESM rules.
129
136
  - **`scripts/build-css.mjs`** inlines the CSS `@import`s with `postcss-import`, resolving
@@ -137,7 +144,10 @@ Three tools, one job each:
137
144
  ### Conventions
138
145
 
139
146
  - `src/icons.ts` is the only file that imports `lucide-react`. Components import icons from it,
140
- so the icon library can change without touching them.
147
+ so the icon library can change without touching them. While only stories and tests use icons,
148
+ `icons.ts` is left out of `dist/` and `lucide-react` is a `devDependency`; the first component
149
+ that renders an icon moves `lucide-react` back to `dependencies`, adds it to Vite's `external`
150
+ list and removes `icons.ts` from the `tsconfig.build.json` excludes.
141
151
  - Each component's CSS is added to `src/styles/styles.css` with
142
152
  `@import url("../<name>/<name>.css") layer(pumba.components);`.
143
153
  - `reset.css` is optional and separate from `styles.css`. Tailwind users skip it.
package/USAGE.md ADDED
@@ -0,0 +1,180 @@
1
+ # Using @pumba-ui/ui
2
+
3
+ A guide for whoever builds an app with Pumba, person or agent. It covers what the types do not
4
+ say. For the props of each component, read the type declarations shipped in this package:
5
+ `dist/index.d.ts` and `dist/<component>/<component>.d.ts`. For the token names, read
6
+ `@pumba-ui/tokens/dist/index.d.ts` (`TokenName`). The full contract is
7
+ [`docs/api-conventions.md`](https://github.com/vnloyola/pumba-ui/blob/main/docs/api-conventions.md).
8
+
9
+ The design rules (which variant, token, spacing or elevation to pick) are in
10
+ `skills/pumba-design/SKILL.md`, next to this file, and match the installed version. To register
11
+ them as a skill, add `.claude/skills/pumba-design/SKILL.md` to the project with only a pointer, so
12
+ it never goes stale:
13
+
14
+ ```markdown
15
+ ---
16
+ name: pumba-design
17
+ description: Design rules for building UI with @pumba-ui/ui. Use when creating or reviewing pages, layouts or components that use Pumba.
18
+ ---
19
+
20
+ Read `node_modules/@pumba-ui/ui/skills/pumba-design/SKILL.md` and follow it.
21
+ ```
22
+
23
+ ## Setup
24
+
25
+ Import the styles once, in the app's entry CSS. They hold the tokens, a minimal base and every
26
+ component, and load the Figtree and JetBrains Mono fonts.
27
+
28
+ ```css
29
+ @import "@pumba-ui/ui/reset.css"; /* optional; skip it with Tailwind */
30
+ @import "@pumba-ui/ui/styles.css";
31
+ ```
32
+
33
+ With Tailwind v4, declare the layer order first, before any import:
34
+
35
+ ```css
36
+ @layer theme, base, components, pumba, utilities;
37
+ @import "tailwindcss";
38
+ @import "@pumba-ui/ui/styles.css";
39
+ ```
40
+
41
+ Pumba's CSS lives in the layers `pumba.reset, pumba.tokens, pumba.base, pumba.components`. Your
42
+ CSS outside any layer always wins over it, without raising specificity.
43
+
44
+ Pumba does not style the page itself. Give the root its background, text color and font:
45
+
46
+ ```css
47
+ body {
48
+ background: var(--pumba-color-background);
49
+ color: var(--pumba-color-text);
50
+ font-family: var(--pumba-text-body-font-family);
51
+ font-size: var(--pumba-text-body-font-size);
52
+ line-height: var(--pumba-text-body-line-height);
53
+ }
54
+ ```
55
+
56
+ Components render from React Server Components without a wrapper: each component file already
57
+ ships `"use client"`.
58
+
59
+ ## Tokens and theme
60
+
61
+ - Style your own layout with the semantic tokens (`--pumba-color-*`, `--pumba-space-*`,
62
+ `--pumba-radius-*`, `--pumba-shadow-*`, `--pumba-text-*`), never with literal colors, sizes or
63
+ `--pumba-primitive-*` tokens. Primitives are the raw palette and do not change meaning with the
64
+ theme.
65
+ - Colors follow the OS. `data-theme="dark"` or `data-theme="light"` on `<html>` forces a theme
66
+ for the page; on any other element it themes only that subtree, which then needs its own
67
+ `background` and `color`.
68
+ - To apply a stored theme without a flash, set `data-theme` from a blocking inline script in
69
+ `<head>`, not after React mounts.
70
+ - A surface inside a surface follows its corner with `--pumba-radius-control`: the surface radius
71
+ is the control radius plus `--pumba-space-inset`.
72
+
73
+ ## Props every component shares
74
+
75
+ - Native props: a component accepts everything its element accepts (`Button` takes `type`,
76
+ `form`, `onClick`…). Unknown props reach the element.
77
+ - `className` is added to the component's own class, never replaces it. Do not restyle
78
+ `.pumba-*` classes to change a variant: pick the variant.
79
+ - `variant` and `size` are string unions written to `data-variant` and `data-size`, default value
80
+ included, so `[data-variant="secondary"]` is a valid selector. The default size is `md`.
81
+ - `render` changes the element a component renders and keeps its class, attributes and behavior:
82
+ `<Button render={<a href="/docs" />}>Docs</Button>` is an `<a>` styled as a button. The element
83
+ passed must forward `ref` and spread the props it receives. A Base UI part (`Tabs.Tab`,
84
+ `Dialog.Trigger`, `Dialog.Close`) that renders something other than a `<button>` also needs
85
+ `nativeButton={false}`.
86
+ - `ref` is a regular prop.
87
+ - A `Button` is as wide as its content only in a row. As a direct child of a grid or a
88
+ column flexbox it stretches, so give it `justify-self: start` (grid) or `align-self: start`
89
+ (flex), or put it in a row.
90
+
91
+ ## Compound components
92
+
93
+ `Card`, `Tabs` and `Dialog` are objects of parts. Use the parts, in this shape:
94
+
95
+ ```tsx
96
+ <Card.Root render={<form onSubmit={save} />}>
97
+ <Card.Header>
98
+ <h2 className="card-title">Project details</h2>
99
+ </Card.Header>
100
+ <Card.Content>…</Card.Content>
101
+ <Card.Footer>
102
+ <Button variant="ghost" type="button" onClick={cancel}>Cancel</Button>
103
+ <Button type="submit">Save</Button>
104
+ </Card.Footer>
105
+ </Card.Root>
106
+
107
+ <Tabs.Root defaultValue="overview">
108
+ <Tabs.List aria-label="Project">
109
+ <Tabs.Tab value="overview">Overview</Tabs.Tab>
110
+ <Tabs.Tab value="settings">Settings</Tabs.Tab>
111
+ </Tabs.List>
112
+ <Tabs.Panel value="overview">…</Tabs.Panel>
113
+ <Tabs.Panel value="settings">…</Tabs.Panel>
114
+ </Tabs.Root>
115
+
116
+ <Dialog.Root>
117
+ <Dialog.Trigger>
118
+ <Button variant="destructive">Delete project</Button>
119
+ </Dialog.Trigger>
120
+ <Dialog.Content>
121
+ <Dialog.Title>Delete project</Dialog.Title>
122
+ <Dialog.Description>This cannot be undone.</Dialog.Description>
123
+ <div className="dialog-actions">
124
+ <Dialog.Close>
125
+ <Button variant="secondary">Cancel</Button>
126
+ </Dialog.Close>
127
+ <Dialog.Close>
128
+ <Button variant="destructive" onClick={deleteProject}>Delete project</Button>
129
+ </Dialog.Close>
130
+ </div>
131
+ </Dialog.Content>
132
+ </Dialog.Root>
133
+ ```
134
+
135
+ - `Card.Root` stacks its parts with `--pumba-space-stack`, and `Card.Footer` lays out its
136
+ children in a row with `--pumba-space-gap`, so buttons go straight in the footer. `Card.Header`
137
+ has no type style: put your own heading in it. To make the card a form, render the root as one
138
+ (`render={<form />}`) instead of wrapping the parts, so the spacing between parts stays.
139
+ - `Tabs.Tab` and `Tabs.Panel` pair by the same string `value`. `Tabs.Root` takes `defaultValue`,
140
+ or `value` with `onValueChange(value)`.
141
+ - `Dialog.Root` takes `defaultOpen`, or `open` with `onOpenChange(open)`.
142
+ - `Dialog.Trigger` and `Dialog.Close` with a single element child give it their behavior, so a
143
+ `Button` inside them is one `<button>`. Do not nest them in a `Button` or the other way around
144
+ with `render`.
145
+ - `Dialog.Content` already renders the portal, the backdrop and the scrolling body, and stacks its
146
+ children in a column. Do not add your own overlay. Put the actions in your own row
147
+ (`display: flex; justify-content: flex-end; gap: var(--pumba-space-gap)`), or each button
148
+ stretches to the dialog's width. The confirming action is a `Button` with its `onClick` inside a
149
+ `Dialog.Close`, so it runs and closes the dialog.
150
+ - A `Card.Root` rendered as a link (`render={<a href="…" />}`) is a single link: put no button or
151
+ other link inside it.
152
+
153
+ ## Accessibility you provide
154
+
155
+ - `Button` with `iconOnly` needs an `aria-label`. Icons next to a text label get
156
+ `aria-hidden="true"`. Pumba exports no icons: use any icon set.
157
+ - `Input` always has a visible label (`<label htmlFor>`); a placeholder is not a label. With
158
+ `invalid`, show the error as visible text linked with `aria-describedby`.
159
+ - State is never carried by color alone: a `Badge` with `variant="error"` or `"success"` has text
160
+ that names the state, ideally with an icon.
161
+ - A `Dialog.Content` has a `Dialog.Title`. Give `Tabs.List` an `aria-label` when nothing else
162
+ names it.
163
+ - Use `Button` for actions and a link (`<a>`, or `render={<a />}`) for navigation.
164
+
165
+ ## Layers and stacking
166
+
167
+ `Dialog.Content` is rendered into `document.body`, outside your app's tree. Two consequences:
168
+
169
+ - Give the app's root its own stacking context, so the z-index of a sticky header or a sidebar
170
+ stays inside it and the dialog is drawn above:
171
+
172
+ ```css
173
+ #root {
174
+ isolation: isolate;
175
+ }
176
+ ```
177
+
178
+ A dialog drawn under something is fixed in the app's CSS, never inside the component.
179
+ - A dialog opened from a subtree with its own `data-theme` comes out with the page's theme. Pass
180
+ that subtree as `container`: `<Dialog.Content container={element}>`.
@@ -1,6 +1,6 @@
1
1
  import type { ComponentProps, ReactElement } from "react";
2
2
  export type ButtonProps = ComponentProps<"button"> & {
3
- variant?: "primary" | "secondary" | "ghost";
3
+ variant?: "primary" | "secondary" | "ghost" | "destructive";
4
4
  size?: "sm" | "md" | "lg";
5
5
  loading?: boolean;
6
6
  iconOnly?: boolean;
package/dist/styles.css CHANGED
@@ -7,61 +7,61 @@
7
7
 
8
8
  --pumba-primitive-color-white: oklch(1 0 0);
9
9
  --pumba-primitive-color-black: oklch(0 0 0);
10
- --pumba-primitive-color-neutral-50: oklch(0.985 0.002 60);
11
- --pumba-primitive-color-neutral-100: oklch(0.967 0.002 60);
12
- --pumba-primitive-color-neutral-200: oklch(0.922 0.003 60);
13
- --pumba-primitive-color-neutral-300: oklch(0.87 0.003 60);
14
- --pumba-primitive-color-neutral-400: oklch(0.708 0.004 60);
15
- --pumba-primitive-color-neutral-500: oklch(0.556 0.004 60);
16
- --pumba-primitive-color-neutral-600: oklch(0.439 0.004 60);
17
- --pumba-primitive-color-neutral-700: oklch(0.3 0.004 60);
18
- --pumba-primitive-color-neutral-800: oklch(0.225 0.003 60);
19
- --pumba-primitive-color-neutral-900: oklch(0.165 0.003 60);
20
- --pumba-primitive-color-neutral-950: oklch(0.115 0.002 60);
21
- --pumba-primitive-color-brand-50: oklch(0.97 0.015 55);
22
- --pumba-primitive-color-brand-100: oklch(0.94 0.03 55);
23
- --pumba-primitive-color-brand-200: oklch(0.88 0.06 55);
24
- --pumba-primitive-color-brand-300: oklch(0.8 0.09 55);
25
- --pumba-primitive-color-brand-400: oklch(0.7 0.12 55);
26
- --pumba-primitive-color-brand-500: oklch(0.6 0.14 55);
27
- --pumba-primitive-color-brand-600: oklch(0.52 0.14 55);
28
- --pumba-primitive-color-brand-700: oklch(0.45 0.12 55);
29
- --pumba-primitive-color-brand-800: oklch(0.38 0.1 55);
30
- --pumba-primitive-color-brand-900: oklch(0.31 0.08 55);
31
- --pumba-primitive-color-brand-950: oklch(0.23 0.055 55);
32
- --pumba-primitive-color-success-50: oklch(.97 0.014 150);
33
- --pumba-primitive-color-success-100: oklch(.94 0.035 150);
34
- --pumba-primitive-color-success-200: oklch(.88 0.07 150);
35
- --pumba-primitive-color-success-300: oklch(.80 0.12 150);
36
- --pumba-primitive-color-success-400: oklch(.70 0.17 150);
37
- --pumba-primitive-color-success-500: oklch(.60 0.17 150);
38
- --pumba-primitive-color-success-600: oklch(.52 0.15 150);
39
- --pumba-primitive-color-success-700: oklch(.45 0.12 150);
40
- --pumba-primitive-color-success-800: oklch(.38 0.095 150);
41
- --pumba-primitive-color-success-900: oklch(.31 0.075 150);
42
- --pumba-primitive-color-success-950: oklch(.23 0.05 150);
43
- --pumba-primitive-color-error-50: oklch(.97 0.014 25);
44
- --pumba-primitive-color-error-100: oklch(.94 0.03 25);
45
- --pumba-primitive-color-error-200: oklch(.88 0.065 25);
46
- --pumba-primitive-color-error-300: oklch(.80 0.11 25);
47
- --pumba-primitive-color-error-400: oklch(.70 0.17 25);
48
- --pumba-primitive-color-error-500: oklch(.60 0.22 25);
49
- --pumba-primitive-color-error-600: oklch(.52 0.22 25);
50
- --pumba-primitive-color-error-700: oklch(.45 0.19 25);
51
- --pumba-primitive-color-error-800: oklch(.38 0.16 25);
52
- --pumba-primitive-color-error-900: oklch(.31 0.12 25);
53
- --pumba-primitive-color-error-950: oklch(.23 0.08 25);
54
- --pumba-primitive-color-warning-50: oklch(0.97 0.02 90);
55
- --pumba-primitive-color-warning-100: oklch(0.94 0.045 90);
56
- --pumba-primitive-color-warning-200: oklch(0.88 0.09 90);
57
- --pumba-primitive-color-warning-300: oklch(0.8 0.13 90);
58
- --pumba-primitive-color-warning-400: oklch(0.7 0.14 90);
59
- --pumba-primitive-color-warning-500: oklch(0.64 0.14 90);
60
- --pumba-primitive-color-warning-600: oklch(0.52 0.1 90);
61
- --pumba-primitive-color-warning-700: oklch(0.45 0.085 90);
62
- --pumba-primitive-color-warning-800: oklch(0.38 0.07 90);
63
- --pumba-primitive-color-warning-900: oklch(0.31 0.055 90);
64
- --pumba-primitive-color-warning-950: oklch(0.23 0.04 90);
10
+ --pumba-primitive-color-neutral-50: oklch(0.985 0.003 55);
11
+ --pumba-primitive-color-neutral-100: oklch(0.965 0.003 55);
12
+ --pumba-primitive-color-neutral-200: oklch(0.925 0.0042 55);
13
+ --pumba-primitive-color-neutral-300: oklch(0.87 0.0048 55);
14
+ --pumba-primitive-color-neutral-400: oklch(0.71 0.006 55);
15
+ --pumba-primitive-color-neutral-500: oklch(0.56 0.006 55);
16
+ --pumba-primitive-color-neutral-600: oklch(0.445 0.006 55);
17
+ --pumba-primitive-color-neutral-700: oklch(0.32 0.0072 55);
18
+ --pumba-primitive-color-neutral-800: oklch(0.25 0.0084 55);
19
+ --pumba-primitive-color-neutral-900: oklch(0.19 0.0084 55);
20
+ --pumba-primitive-color-neutral-950: oklch(0.15 0.0078 55);
21
+ --pumba-primitive-color-brand-50: oklch(0.975 0.014 55);
22
+ --pumba-primitive-color-brand-100: oklch(0.95 0.028 55);
23
+ --pumba-primitive-color-brand-200: oklch(0.905 0.048 55);
24
+ --pumba-primitive-color-brand-300: oklch(0.845 0.066 55);
25
+ --pumba-primitive-color-brand-400: oklch(0.77 0.078 55);
26
+ --pumba-primitive-color-brand-500: oklch(0.69 0.082 55);
27
+ --pumba-primitive-color-brand-600: oklch(0.61 0.078 55);
28
+ --pumba-primitive-color-brand-700: oklch(0.52 0.068 55);
29
+ --pumba-primitive-color-brand-800: oklch(0.43 0.056 55);
30
+ --pumba-primitive-color-brand-900: oklch(0.34 0.044 55);
31
+ --pumba-primitive-color-brand-950: oklch(0.25 0.03 55);
32
+ --pumba-primitive-color-success-50: oklch(0.975 0.014 150);
33
+ --pumba-primitive-color-success-100: oklch(0.95 0.03 150);
34
+ --pumba-primitive-color-success-200: oklch(0.905 0.05 150);
35
+ --pumba-primitive-color-success-300: oklch(0.845 0.07 150);
36
+ --pumba-primitive-color-success-400: oklch(0.77 0.09 150);
37
+ --pumba-primitive-color-success-500: oklch(0.69 0.11 150);
38
+ --pumba-primitive-color-success-600: oklch(0.61 0.11 150);
39
+ --pumba-primitive-color-success-700: oklch(0.52 0.1 150);
40
+ --pumba-primitive-color-success-800: oklch(0.43 0.085 150);
41
+ --pumba-primitive-color-success-900: oklch(0.34 0.065 150);
42
+ --pumba-primitive-color-success-950: oklch(0.25 0.045 150);
43
+ --pumba-primitive-color-error-50: oklch(0.975 0.019 25);
44
+ --pumba-primitive-color-error-100: oklch(0.95 0.041 25);
45
+ --pumba-primitive-color-error-200: oklch(0.905 0.068 25);
46
+ --pumba-primitive-color-error-300: oklch(0.845 0.095 25);
47
+ --pumba-primitive-color-error-400: oklch(0.77 0.121 25);
48
+ --pumba-primitive-color-error-500: oklch(0.69 0.149 25);
49
+ --pumba-primitive-color-error-600: oklch(0.61 0.149 25);
50
+ --pumba-primitive-color-error-700: oklch(0.52 0.135 25);
51
+ --pumba-primitive-color-error-800: oklch(0.43 0.115 25);
52
+ --pumba-primitive-color-error-900: oklch(0.34 0.088 25);
53
+ --pumba-primitive-color-error-950: oklch(0.25 0.061 25);
54
+ --pumba-primitive-color-warning-50: oklch(0.975 0.014 85);
55
+ --pumba-primitive-color-warning-100: oklch(0.95 0.03 85);
56
+ --pumba-primitive-color-warning-200: oklch(0.905 0.05 85);
57
+ --pumba-primitive-color-warning-300: oklch(0.845 0.07 85);
58
+ --pumba-primitive-color-warning-400: oklch(0.77 0.09 85);
59
+ --pumba-primitive-color-warning-500: oklch(0.69 0.11 85);
60
+ --pumba-primitive-color-warning-600: oklch(0.61 0.11 85);
61
+ --pumba-primitive-color-warning-700: oklch(0.52 0.1 85);
62
+ --pumba-primitive-color-warning-800: oklch(0.43 0.085 85);
63
+ --pumba-primitive-color-warning-900: oklch(0.34 0.065 85);
64
+ --pumba-primitive-color-warning-950: oklch(0.25 0.045 85);
65
65
  --pumba-primitive-motion-duration-fast: 100ms;
66
66
  --pumba-primitive-motion-duration-normal: 200ms;
67
67
  --pumba-primitive-motion-duration-slow: 300ms;
@@ -73,7 +73,7 @@
73
73
  --pumba-primitive-radius-md: 0.5rem;
74
74
  --pumba-primitive-radius-lg: 0.75rem;
75
75
  --pumba-primitive-radius-xl: 1rem;
76
- --pumba-primitive-radius-2xl: 1.75rem;
76
+ --pumba-primitive-radius-2xl: 1.5rem;
77
77
  --pumba-primitive-radius-full: 9999px;
78
78
  --pumba-primitive-shadow-sm: 0px 1px 2px 0px oklch(0 0 0 / 0.08);
79
79
  --pumba-primitive-shadow-md: 0px 4px 8px -1px oklch(0 0 0 / 0.12);
@@ -127,27 +127,31 @@
127
127
  --pumba-color-scrim: light-dark(var(--pumba-primitive-color-black), var(--pumba-primitive-color-black));
128
128
  --pumba-color-field: light-dark(var(--pumba-primitive-color-neutral-200), var(--pumba-primitive-color-neutral-800));
129
129
  --pumba-color-field-hover: light-dark(var(--pumba-primitive-color-neutral-300), var(--pumba-primitive-color-neutral-700));
130
- --pumba-color-accent: light-dark(var(--pumba-primitive-color-brand-600), var(--pumba-primitive-color-brand-400));
131
- --pumba-color-accent-hover: light-dark(var(--pumba-primitive-color-brand-700), var(--pumba-primitive-color-brand-300));
132
- --pumba-color-accent-pressed: light-dark(var(--pumba-primitive-color-brand-800), var(--pumba-primitive-color-brand-200));
133
- --pumba-color-accent-subtle: light-dark(var(--pumba-primitive-color-brand-50), var(--pumba-primitive-color-brand-950));
130
+ --pumba-color-accent: light-dark(var(--pumba-primitive-color-brand-700), var(--pumba-primitive-color-brand-300));
131
+ --pumba-color-accent-hover: light-dark(var(--pumba-primitive-color-brand-800), var(--pumba-primitive-color-brand-200));
132
+ --pumba-color-accent-pressed: light-dark(var(--pumba-primitive-color-brand-900), var(--pumba-primitive-color-brand-100));
133
+ --pumba-color-accent-subtle: light-dark(var(--pumba-primitive-color-brand-100), var(--pumba-primitive-color-brand-900));
134
+ --pumba-color-accent-subtle-pressed: light-dark(var(--pumba-primitive-color-brand-200), var(--pumba-primitive-color-brand-800));
134
135
  --pumba-color-accent-text: light-dark(var(--pumba-primitive-color-white), var(--pumba-primitive-color-neutral-950));
135
- --pumba-color-focus: light-dark(var(--pumba-primitive-color-brand-600), var(--pumba-primitive-color-brand-400));
136
+ --pumba-color-focus: light-dark(var(--pumba-primitive-color-brand-700), var(--pumba-primitive-color-brand-300));
136
137
  --pumba-color-success: light-dark(var(--pumba-primitive-color-success-600), var(--pumba-primitive-color-success-400));
137
- --pumba-color-success-subtle: light-dark(var(--pumba-primitive-color-success-50), var(--pumba-primitive-color-success-950));
138
+ --pumba-color-success-subtle: light-dark(var(--pumba-primitive-color-success-100), var(--pumba-primitive-color-success-900));
138
139
  --pumba-color-success-text: light-dark(var(--pumba-primitive-color-success-700), var(--pumba-primitive-color-success-300));
139
- --pumba-color-error: light-dark(var(--pumba-primitive-color-error-600), var(--pumba-primitive-color-error-400));
140
- --pumba-color-error-subtle: light-dark(var(--pumba-primitive-color-error-50), var(--pumba-primitive-color-error-950));
140
+ --pumba-color-error: light-dark(var(--pumba-primitive-color-error-700), var(--pumba-primitive-color-error-400));
141
+ --pumba-color-error-hover: light-dark(var(--pumba-primitive-color-error-800), var(--pumba-primitive-color-error-300));
142
+ --pumba-color-error-pressed: light-dark(var(--pumba-primitive-color-error-900), var(--pumba-primitive-color-error-200));
143
+ --pumba-color-error-contrast: light-dark(var(--pumba-primitive-color-white), var(--pumba-primitive-color-neutral-950));
144
+ --pumba-color-error-subtle: light-dark(var(--pumba-primitive-color-error-100), var(--pumba-primitive-color-error-900));
141
145
  --pumba-color-error-text: light-dark(var(--pumba-primitive-color-error-700), var(--pumba-primitive-color-error-300));
142
- --pumba-color-warning: light-dark(var(--pumba-primitive-color-warning-500), var(--pumba-primitive-color-warning-400));
143
- --pumba-color-warning-subtle: light-dark(var(--pumba-primitive-color-warning-50), var(--pumba-primitive-color-warning-950));
146
+ --pumba-color-warning: light-dark(var(--pumba-primitive-color-warning-600), var(--pumba-primitive-color-warning-400));
147
+ --pumba-color-warning-subtle: light-dark(var(--pumba-primitive-color-warning-100), var(--pumba-primitive-color-warning-900));
144
148
  --pumba-color-warning-text: light-dark(var(--pumba-primitive-color-warning-700), var(--pumba-primitive-color-warning-300));
145
149
  --pumba-motion-duration-feedback: var(--pumba-primitive-motion-duration-fast);
146
150
  --pumba-motion-duration-transition: var(--pumba-primitive-motion-duration-normal);
147
151
  --pumba-motion-easing-standard: var(--pumba-primitive-motion-easing-standard);
148
152
  --pumba-motion-easing-enter: var(--pumba-primitive-motion-easing-out);
149
153
  --pumba-motion-easing-exit: var(--pumba-primitive-motion-easing-in);
150
- --pumba-radius-control: var(--pumba-primitive-radius-lg);
154
+ --pumba-radius-control: var(--pumba-primitive-radius-md);
151
155
  --pumba-radius-surface: var(--pumba-primitive-radius-2xl);
152
156
  --pumba-radius-pill: var(--pumba-primitive-radius-full);
153
157
  --pumba-shadow-raised: var(--pumba-primitive-shadow-sm);
@@ -274,7 +278,7 @@
274
278
 
275
279
  .pumba-button[data-variant="secondary"]:active,
276
280
  .pumba-button[data-variant="secondary"][data-pressed] {
277
- background: var(--pumba-color-surface-raised);
281
+ background: var(--pumba-color-accent-subtle-pressed);
278
282
  }
279
283
 
280
284
  .pumba-button[data-variant="ghost"] {
@@ -289,7 +293,22 @@
289
293
 
290
294
  .pumba-button[data-variant="ghost"]:active,
291
295
  .pumba-button[data-variant="ghost"][data-pressed] {
292
- background: var(--pumba-color-surface-raised);
296
+ background: var(--pumba-color-accent-subtle-pressed);
297
+ }
298
+
299
+ .pumba-button[data-variant="destructive"] {
300
+ background: var(--pumba-color-error);
301
+ color: var(--pumba-color-error-contrast);
302
+ }
303
+
304
+ .pumba-button[data-variant="destructive"]:hover,
305
+ .pumba-button[data-variant="destructive"][data-hovered] {
306
+ background: var(--pumba-color-error-hover);
307
+ }
308
+
309
+ .pumba-button[data-variant="destructive"]:active,
310
+ .pumba-button[data-variant="destructive"][data-pressed] {
311
+ background: var(--pumba-color-error-pressed);
293
312
  }
294
313
 
295
314
  .pumba-button[data-size="sm"] {
@@ -382,6 +401,22 @@
382
401
  letter-spacing: var(--pumba-text-body-letter-spacing);
383
402
  }
384
403
 
404
+ .pumba-card:any-link {
405
+ text-decoration: none;
406
+ transition: border-color var(--pumba-motion-duration-feedback) var(--pumba-motion-easing-standard);
407
+ }
408
+
409
+ .pumba-card:any-link:hover,
410
+ .pumba-card:any-link[data-hovered] {
411
+ border-color: var(--pumba-color-border-strong);
412
+ }
413
+
414
+ .pumba-card:any-link:focus-visible,
415
+ .pumba-card:any-link[data-focus-visible] {
416
+ outline: 2px solid var(--pumba-color-focus);
417
+ outline-offset: 2px;
418
+ }
419
+
385
420
  .pumba-card-footer {
386
421
  display: flex;
387
422
  align-items: center;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pumba-ui/ui",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Accessible React components for the Pumba design system.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/vnloyola/pumba-ui#readme",
@@ -31,7 +31,9 @@
31
31
  "./reset.css": "./dist/reset.css"
32
32
  },
33
33
  "files": [
34
- "dist"
34
+ "dist",
35
+ "USAGE.md",
36
+ "skills"
35
37
  ],
36
38
  "sideEffects": [
37
39
  "**/*.css"
@@ -43,12 +45,11 @@
43
45
  "dependencies": {
44
46
  "@base-ui/react": "^1.8.0",
45
47
  "@fontsource-variable/figtree": "^5.3.0",
46
- "@fontsource-variable/jetbrains-mono": "^5.3.0",
47
- "lucide-react": "^1.52.0"
48
+ "@fontsource-variable/jetbrains-mono": "^5.3.0"
48
49
  },
49
50
  "devDependencies": {
50
51
  "@arethetypeswrong/cli": "^0.18.5",
51
- "@pumba-ui/tokens": "0.1.0",
52
+ "@pumba-ui/tokens": "0.2.0",
52
53
  "@storybook/react-vite": "^10.6.1",
53
54
  "@testing-library/dom": "^10.4.2",
54
55
  "@testing-library/react": "^16.3.3",
@@ -56,6 +57,7 @@
56
57
  "@types/react-dom": "^19.3.0",
57
58
  "axe-core": "^4.14.0",
58
59
  "jsdom": "^30.1.3",
60
+ "lucide-react": "^1.52.0",
59
61
  "postcss": "^8.5.0",
60
62
  "postcss-import": "^17.0.0",
61
63
  "publint": "^0.3.25",
@@ -72,7 +74,7 @@
72
74
  "scripts": {
73
75
  "build": "vite build && tsc -p tsconfig.build.json && node scripts/build-css.mjs",
74
76
  "typecheck": "tsc --noEmit",
75
- "check:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints ./styles.css ./reset.css",
77
+ "check:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints ./styles.css ./reset.css && node scripts/check-public-types.mjs",
76
78
  "test": "vitest run",
77
79
  "add:component": "node scripts/add-component.mjs"
78
80
  }
@@ -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
+ ```
package/dist/icons.d.ts DELETED
@@ -1 +0,0 @@
1
- export { ArrowUpRight as ArrowUpRightIcon, Check as CheckIcon, ChevronDown as ChevronDownIcon, Clock as ClockIcon, DollarSign as DollarIcon, Heart as HeartIcon, MapPin as MapPinIcon, Share2 as ShareIcon, ShoppingCart as CartIcon, Sparkles as SparklesIcon, Star as StarIcon, TrendingDown as TrendingDownIcon, TrendingUp as TrendingUpIcon, TriangleAlert as WarningIcon, Users as UsersIcon, X as CloseIcon, } from "lucide-react";