@neo4j-ndl/react 4.20.0 → 4.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-ndl/react",
-  "version": "4.20.0",
+  "version": "4.20.1",
   "sideEffects": false,
   "description": "React implementation of Neo4j Design System",
   "keywords": [

package/skills/ndl-react/SKILL.md

@@ -38,8 +38,26 @@ Use Neo4j Needle components instead of hand-rolling equivalent UI.
   package's `.d.ts` type contract is authoritative: if the types disagree with
   these docs, the **types win**. Do not reverse-engineer behavior from the
   compiled implementation source in `node_modules`.
-- Pass native HTML attributes, `aria-*`, and `data-*` via the `htmlAttributes`
-  prop, only where the component's doc says so.
+- **Customize via component props first.** Needle components expose typed
+  props for spacing, layout, variant, and accessibility — use those before
+  reaching for `className` or `htmlAttributes`. The escape-hatch order is:
+  1. **Component props** (e.g. `gap="8"`, `variant="danger"`, `size="small"`) —
+     always preferred; type-checked and token-constrained.
+  2. **`className`** — for utility classes the component doesn't cover (e.g.
+     `n-flex`, `n-items-center` on a plain element or when composing). Verify
+     every class against the stylesheet; see the class-names rule below.
+  3. **`htmlAttributes`** — for native HTML attributes, `aria-*`, and `data-*`
+     the component doesn't expose as props. Valid reasons include:
+     - `id` — for `aria-controls` references, portal targets, or form label wiring
+     - `aria-*` — when no dedicated prop exists (e.g. `aria-haspopup`, `aria-expanded`
+       on a trigger, `aria-label` on a TextInput without a label)
+     - `data-*` — custom data attributes for testing or integration
+     - Native HTML attributes not surfaced as props (e.g. `type="email"`,
+       `type="password"`, `max`/`min`/`step` on a TextInput, `href` on
+       Typography as `as="a"`)
+     Do **not** use `htmlAttributes` to override behavior the component already
+     provides (e.g. setting `role="alertdialog"` on a Dialog — use `variant`
+     instead), or for styling — use component props or `className`.
 - Compound components are exposed as subcomponents (e.g. `Tooltip.Trigger`,
   `Tooltip.Content`). Follow each component's own doc — don't assume one
   component's compound shape matches another's.
@@ -61,15 +79,48 @@ Use Neo4j Needle components instead of hand-rolling equivalent UI.
   Tailwind-shaped guesses (`n-justify-between`, `n-items-baseline`) and
   near-misses on real scales (`n-gap-token-1` when the scale is 2/4/6/8/12/16)
   become invisible layout bugs, not errors. `Flex`, `Box` and `Typography` with
-  token props sidestep the question entirely — prefer them.
+  token props sidestep the question entirely — prefer them. For the full token
+  list and class verification, see [references/styling.md](references/styling.md).
+- **Tokens only.** Never hardcode `hex`, `rgb()`, `oklch()`, or arbitrary
+  Tailwind color values in generated code. All colors come from semantic theme
+  custom properties (`--theme-color-*`) that resolve to the correct light/dark
+  value automatically. See [references/styling.md](references/styling.md) for
+  the complete token catalog.
 - Follow the accessibility guidance in each component's doc; don't strip built-in
   roles or keyboard behavior.
 
+## Reuse before you create
+
+Needle is a maintained design system. Before writing custom UI, check whether an
+existing component already covers the need — you get the maintained component,
+not a lookalike you now own.
+
+1. **Scan the component catalog below.** The table lists every shipped
+   component with its docs file and import path. If a Needle component covers
+   the need, use it instead of hand-rolling an equivalent.
+2. **Read the component's doc** (`components/<file>`) before using it — props,
+   compound shape, and accessibility behavior differ per component.
+3. **Create only when no component fits.** If the catalog doesn't cover it,
+   compose existing components (e.g. `Flex` + `Typography` + `Banner.Actions`)
+   rather than introducing a new component. Only create a new component when the
+   pattern is genuinely novel and no combination of existing primitives works.
+
+### Don't restyle a component into another
+
+Each button variant is a distinct component with its own visual language.
+Don't take a `FilledButton` and restyle it to look like an `OutlinedButton` —
+use `OutlinedButton` directly. Same for tags (`Tag`, `SelectableTag`,
+`DismissibleTag`, `ReadOnlyTag`), and any other variant family.
+
 ## How to use this skill
 
 1. Find the component in the catalog below to get its docs file and import path.
 2. Read `components/<file>` for that component's props, accessibility
    requirements, and runnable examples; prefer those examples.
+3. For styling — token names, utility class lists, prefix rules — consult
+   [references/styling.md](references/styling.md). It points at the shipped
+   stylesheet so class and token lists can't drift from what the package
+   actually ships.
 
 ## Components
 

package/skills/ndl-react/references/styling.md

@@ -0,0 +1,290 @@
+# Styling reference
+
+The stylesheet is the source of truth for which classes and custom properties
+exist. **Never hardcode a class name or token value from memory** — verify it
+against the shipped CSS first.
+
+## Where the stylesheet lives
+
+```
+node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css
+```
+
+In the Needle repo source it is generated from `packages/base/src/` (Tailwind
+preset + token JSON), but the built file above is what a consuming app ships.
+When checking whether a class or custom property exists, grep the built file —
+not the source `.pcss` — because Tailwind tree-shakes classes that no source
+file uses.
+
+### Quick verification
+
+```sh
+# Does a class exist?
+CSS=node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css
+grep -qE '\.n-flex\b' "$CSS" && echo "exists" || echo "MISSING"
+
+# Does a custom property exist?
+grep -qE -- '--space-8:' "$CSS" && echo "exists" || echo "MISSING"
+```
+
+## Tokens only — never raw color values
+
+Generated or hand-written code must **never** contain hardcoded `hex`, `rgb()`,
+`oklch()`, or arbitrary Tailwind color values. All colors come from semantic
+theme tokens that automatically resolve to the correct light/dark value:
+
+```css
+/* ✅ Token — adapts to theme */
+color: var(--theme-color-neutral-text-default);
+background: var(--theme-color-primary-bg-weak);
+
+/* ❌ Hardcoded — breaks dark mode, drifts from the system */
+color: #1a1b1d;
+background: rgb(10 97 144);
+```
+
+### Semantic color families
+
+Each family has the same suffix set (`text`, `icon`, `bg-weak`, `bg-strong`,
+`bg-status`, `border-strong`, `border-weak`, and for primary/danger also
+`hover-*`, `pressed-*`):
+
+| Family | CSS custom property prefix | Utility class prefix |
+|--------|---------------------------|---------------------|
+| Neutral | `--theme-color-neutral-*` | `n-text-neutral-*`, `n-bg-neutral-*`, `n-border-neutral-*` |
+| Primary | `--theme-color-primary-*` | `n-text-primary-*`, `n-bg-primary-*`, `n-border-primary-*` |
+| Danger | `--theme-color-danger-*` | `n-text-danger-*`, `n-bg-danger-*`, `n-border-danger-*` |
+| Warning | `--theme-color-warning-*` | `n-text-warning-*`, `n-bg-warning-*`, `n-border-warning-*` |
+| Success | `--theme-color-success-*` | `n-text-success-*`, `n-bg-success-*`, `n-border-success-*` |
+| Discovery | `--theme-color-discovery-*` | `n-text-discovery-*`, `n-bg-discovery-*`, `n-border-discovery-*` |
+
+**Do not use `n-bg-dark-*` / `n-bg-light-*` prefixed classes.** They pin a
+specific theme and break when the user switches. The non-prefixed classes
+above resolve to the active theme automatically.
+
+### Space tokens
+
+| Token | Value | Utility class (gap/padding) |
+|-------|-------|-----|
+| `--space-2` | 2px | `n-gap-token-2` |
+| `--space-4` | 4px | `n-gap-token-4` |
+| `--space-6` | 6px | `n-gap-token-6` |
+| `--space-8` | 8px | `n-gap-token-8` |
+| `--space-12` | 12px | `n-gap-token-12` |
+| `--space-16` | 16px | `n-gap-token-16` |
+| `--space-20` | 20px | `n-gap-token-20` (not in the prebuilt CSS) |
+| `--space-24` | 24px | `n-gap-token-24` (not in the prebuilt CSS) |
+| `--space-32` | 32px | `n-gap-token-32` |
+| `--space-48` | 48px | `n-gap-token-48` |
+| `--space-64` | 64px | `n-gap-token-64` |
+
+### The same number means different things in the two systems
+
+This is the easiest way to get spacing silently wrong, and it is invisible to
+`tsc`, to the build and to review:
+
+| What you write | Renders |
+|----------------|---------|
+| `<Flex gap="16">` — component prop | **16px** |
+| `className="gap-token-16"` — token-named utility | **16px** |
+| `className="gap-16"` — Tailwind numeric utility | **64px** |
+
+A Needle spacing prop takes a **token name that is its pixel value**. A Tailwind
+numeric utility takes a **step on Tailwind's 4px scale**. So `gap="8"` is 8px
+while `gap-8` is 32px, and the two scales never coincide at any step — mixing
+them multiplies the spacing you meant by four.
+
+Two gap scales are **defined in the preset**: the token-named one
+(`n-gap-token-2` … `n-gap-token-64`) and Tailwind's numeric one (`n-gap-1`,
+`n-gap-1.5`, `n-gap-2`, `n-gap-3` …). Both are valid wherever Tailwind is
+generating classes. Only a handful of each are present in the prebuilt
+stylesheet — see [which classes work in your app](#whether-a-utility-class-works-is-a-property-of-the-app-not-the-class)
+before relying on any specific one. `Flex` and `Box` accept token values
+directly (`gap="8"`, `padding="12"`) and sidestep the question entirely, which
+is why they are preferred.
+
+### Border-radius tokens
+
+| Token | Value |
+|-------|-------|
+| `--border-radius-none` | 0 |
+| `--border-radius-sm` | 4px |
+| `--border-radius-md` | 6px |
+| `--border-radius-lg` | 8px |
+| `--border-radius-xl` | 12px |
+| `--border-radius-2xl` | 16px |
+| `--border-radius-3xl` | 24px |
+| `--border-radius-full` | 9999px |
+
+`Box` and `Flex` accept `borderRadius="xl"` directly. Utility classes
+`n-rounded-sm/md/lg/xl/2xl` also exist.
+
+### Shadow tokens
+
+| Token | Utility class |
+|-------|---------------|
+| `--theme-shadow-raised` | `n-shadow-raised` |
+| `--theme-shadow-overlay` | `n-shadow-overlay` |
+
+### JS token imports
+
+For inline styles or JS logic, import the token object:
+
+```tsx
+import { tokens } from '@neo4j-ndl/base';
+
+tokens.space['8']        // '8px'
+tokens.borderRadius.xl   // '12px'
+tokens.colors.primary['500']  // raw palette value
+```
+
+Prefer CSS custom properties in `style` over JS token values where possible —
+`var(--theme-color-*)` adapts to theme, a JS palette value does not.
+
+## Whether a utility class works is a property of the app, not the class
+
+Two independent questions decide it, and the app's `tailwind.config` answers
+both. Read it before writing a single class.
+
+**1. Does the app run its own Tailwind build?**
+
+| | What works |
+|---|-----------|
+| **Yes** — it consumes the Needle preset | Any standard Tailwind utility, generated on demand: `sr-only`, `p-token-6`, `gap-3` and the rest |
+| **No** — it only imports `@neo4j-ndl/base/lib/neo4j-ds-styles.css` | Only the classes already present in that file. Everything else silently does nothing |
+
+**2. What prefix does it use?**
+
+The Needle preset sets `prefix: 'n-'`, but an app can override it and the app's
+config wins. The Aura console monorepo sets `prefix: ''`, so utilities there are
+written unprefixed — `flex`, `gap-4`, not `n-flex`. An app with no Tailwind build
+at all gets only the prebuilt stylesheet's classes, and those are `n-` prefixed.
+
+Getting this wrong is invisible: a class at the wrong prefix compiles, passes
+type-checking and renders nothing. And it can look fine by accident — in a
+`prefix: ''` app that also imports the prebuilt CSS, `n-flex` still renders
+because it happens to be baked in, while `n-items-baseline` does not.
+
+The prebuilt stylesheet is a **by-product of building Needle, not a utility
+library.** Its production build scans only Needle's own component source
+(`packages/react/src`, excluding stories and Playwright specs), so the utilities
+in it are whatever those components happened to use. Nothing curates that set for
+consumers, and it shifts whenever component source changes.
+
+This is also why a class can work in Needle's Storybook and fail in a consuming
+app: the non-production build widens the scan to include
+`packages/storybook/src`, so writing a class in a story generates it. `n-sr-only`
+behaves exactly this way — it is used in Needle's own `.pcss` via
+`@apply n-sr-only`, which **inlines the declarations** into the component's rule
+rather than emitting a reusable `.n-sr-only` selector. It works in Storybook and
+is absent from the published CSS.
+
+If there is no `tailwind.config` in the app, treat the prebuilt stylesheet as the
+complete set and grep it.
+
+An app that wants the full utility set opts into the first setup by consuming the
+preset, which `@neo4j-ndl/base` exports from its main entry:
+
+```js
+// tailwind.config.js
+import { tailwindConfig } from '@neo4j-ndl/base';
+
+export default {
+  presets: [tailwindConfig],
+  content: ['./src/**/*.{ts,tsx}'],
+};
+```
+
+### The prebuilt set changes between releases
+
+Because it is a by-product of component source, it moves without anyone
+curating it. Read the
+version from `node_modules/@neo4j-ndl/base/package.json` and grep *that* copy of
+the stylesheet; never a copy from elsewhere on disk, and never this document
+alone.
+
+### Two things that are fictional in both setups
+
+Everything above is a real utility somewhere. These are not — they are invented
+namespaces that resolve to nothing no matter how the app is built, and both have
+been written by generated code more than once:
+
+- **`--theme-palette-*` is not a namespace.** The semantic one is
+  `--theme-color-*`. There are zero occurrences of `--theme-palette` in the
+  package.
+- **Radius is not under `--theme-*`.** The tokens are `--border-radius-sm|md|lg|
+  xl|2xl|3xl|full|none`, so `--theme-radius-lg` is nothing.
+
+A `var()` with no fallback renders nothing when the property is undefined, so
+both fail silently rather than loudly.
+
+## Layout utility classes present in the prebuilt stylesheet
+
+**This section matters only in an app with no Tailwind build of its own** — where
+the prebuilt stylesheet is the complete set. With a Tailwind build, any valid
+utility generates and the lists below do not constrain you.
+
+The right-hand column is **not** a list of invalid class names — every one is a
+real Tailwind utility the preset can generate. They are simply absent from the
+prebuilt `neo4j-ds-styles.css`. Names are `n-` prefixed here because that is the
+prefix the shipped stylesheet was built with, whatever prefix your own build
+uses. Use them only when a component prop isn't available: `Flex`,
+`Box` and `Typography` cover most layout needs with type-safe token props.
+
+| Purpose | In the prebuilt CSS | Valid, but NOT in the prebuilt CSS |
+|---------|-------------------|--------------------------|
+| Flexbox | `n-flex`, `n-flex-row`, `n-flex-col`, `n-flex-1`, `n-flex-shrink-0` | — |
+| Align items | `n-items-start`, `n-items-end`, `n-items-center` | `n-items-baseline`, `n-items-stretch` |
+| Justify content | `n-justify-start`, `n-justify-end`, `n-justify-center`, `n-justify-between`, `n-justify-items-center` | `n-justify-around`, `n-justify-evenly` |
+| Gap | `n-gap-1`, `n-gap-2`, `n-gap-4`, `n-gap-6`, `n-gap-9`, `n-gap-12`; `n-gap-token-2/4/6/8/12/16/32/48/64` | `n-gap-1.5`, `n-gap-3`, `n-gap-5`, `n-gap-8`, `n-gap-16`, `n-gap-token-20`, `n-gap-token-24` |
+| Width | `n-w-full`, `n-w-fit`, `n-w-max`, `n-w-token-32` | `n-w-1/2` and other fractional widths |
+| Padding | `n-p-0`, `n-p-2`, `n-p-3`, `n-p-4`, `n-p-8`, `n-p-14` | `n-p-12`, and the whole `n-p-token-*` scale — prefer `Box padding="12"` |
+| Text align | `n-text-left`, `n-text-center` | `n-text-right` |
+
+**A class in the right-hand column compiles and renders nothing in a
+prebuilt-CSS app** — a silent layout bug, invisible to `tsc` and to review.
+Prefer a component prop, or an inline style with a real token.
+
+## How to verify before writing
+
+1. **Check component props first.** `Flex`, `Box`, `Typography` accept typed
+   token values that are always correct — prefer them over utility classes or
+   `htmlAttributes`. See the customization hierarchy below.
+2. **Check the stylesheet**: grep `neo4j-ds-styles.css` for the exact class
+   or property.
+3. **Check the consuming app's Tailwind config** for `prefix` if you're unsure
+   whether `n-` or bare classes are in use.
+4. **Never copy a class from another library** (MUI, Radix, Chakra, plain
+   Tailwind). They won't exist in the Needle stylesheet.
+
+## Customization hierarchy
+
+When adjusting a Needle component, work through these in order. Each level is
+more error-prone than the one before it:
+
+1. **Component props** — typed, token-constrained, and type-checked. Always the
+   first choice. Examples: `gap="8"`, `padding="12"`, `borderRadius="xl"`,
+   `variant="danger"`, `size="small"`, `isFluid`, `ariaLabel`.
+
+2. **`className`** — for utility classes the component doesn't cover (e.g.
+   `n-flex`, `n-items-center` on a plain element, or when composing). These are
+   unchecked strings: verify every class against
+   `node_modules/@neo4j-ndl/base/lib/neo4j-ds-styles.css`. A wrong class compiles
+   and silently renders nothing.
+
+3. **`htmlAttributes`** — escape hatch for native HTML attributes, `aria-*`, and
+   `data-*` the component doesn't expose as props. Valid reasons, drawn from the
+   component docs:
+
+   - `id` — for `aria-controls` references, portal targets, or form label wiring
+   - `aria-*` — when no dedicated prop exists (e.g. `aria-haspopup` or
+     `aria-expanded` on a trigger button, `aria-label` on a `TextInput` without
+     a label)
+   - `data-*` — custom data attributes for testing or integration
+   - Native HTML attributes not surfaced as props (e.g. `type="email"`,
+     `type="password"`, `max`/`min`/`step` on a `TextInput`, `href` on
+     `Typography` with `as="a"`, `title` on an icon button)
+
+   Do **not** use `htmlAttributes` to override behavior the component already
+   provides — e.g. setting `role="alertdialog"` on a `Dialog` (use `variant`
+   instead) — or for styling (use component props or `className`).