@dscout/particle 1.0.0-alpha.54 → 1.0.0-alpha.55

package/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md
+
+Guidance for AI agents working in an application that **consumes** `@dscout/particle`.
+
+> This file ships inside the published package. It describes how to *use* Particle, not how to develop it. (Contributors to Particle itself should read `CLAUDE.md` in the repo root instead.)
+
+## What Particle is
+
+Particle is dscout's design system: a React component library plus a set of SCSS/CSS stylesheets, published as `@dscout/particle`. You import components, utility classes, and styles from it; you do not modify it from a consuming app.
+
+The authoritative reference for what components exist, their props, and their variants is the hosted Storybook: https://dscout.github.io/particle/v1/storybook/ — prefer it over guessing a component or prop name.
+
+## Installing and peer dependencies
+
+```bash
+yarn add @dscout/particle react react-dom react-router-dom
+```
+
+- **Peer dependencies (you install these):** `react`, `react-dom` (18.x or 19.x), and `react-router-dom` (6.x or 7.x).
+- **`@floating-ui/dom`** is a regular dependency of Particle — it is installed automatically and powers `TooltipContainer` and `DropdownContainer`. You do not add it yourself.
+
+Particle is built against React 18 but supports React 19 with no code changes; validate behavior when running on 19.
+
+## Importing components
+
+Everything is a **named export** off the package root. There are no deep component import paths.
+
+```tsx
+import { Container, Heading, Button } from '@dscout/particle';
+```
+
+Components accept text as props rather than hardcoding copy — e.g. `Button` takes its label as a prop. Supply all user-facing strings from the consuming app.
+
+## Importing styles
+
+Components are unstyled, and the utility classes below are unavailable, until you import Particle's stylesheet once near your app entry point.
+
+Pre-compiled CSS (no build tooling required):
+
+```css
+@import 'node_modules/@dscout/particle/lib/stylesheets/particle.css';
+/* or the minified build */
+@import 'node_modules/@dscout/particle/lib/stylesheets/particle.min.css';
+```
+
+SCSS source (if your app compiles SCSS):
+
+```scss
+@import '@dscout/particle/styles/particle.scss';
+```
+
+## Utility classes
+
+Importing the stylesheet also brings in Particle's utility classes — single-purpose classes that apply design-system values for layout, spacing, color, typography, etc. **Prefer these over hand-written CSS or inline styles in a consuming app**: they keep you on the system's scale and tokens, and they're the intended way to compose layouts around Particle components.
+
+The class-name convention is `category--value` (a double dash before the value). Categories live in the package's `styles/utilities/` directory. The common ones:
+
+| Category | Examples | What it does |
+|---|---|---|
+| Display | `.display--f` (flex), `.display--ib` (inline-block), `.display--n` (none) | `display` |
+| Flex / alignment | `.flex`, `.flex--1`, `.direction--column`, `.align-items--center`, `.align-content--between` | flexbox layout |
+| Spacing — gap | `.flex-gap--1em`, `.flex-gap-v--0.5em`, `.flex-gap-h--1em` | `gap` between flex children |
+| Spacing — margin | `.margin--1em`, `.margin-t--0.5em`, `.margin-h--2em` | `margin` (t/b/l/r/v/h variants) |
+| Spacing — padding | `.padding--1em`, `.padding-v--0.5em`, `.padding-h--1em` | `padding` |
+| Color | `.color--gray-500`, `.bg-color--blue-500`, `.b-color--gray-50` | text / background / border color |
+| Typography | `.font-size--base`, `.font-weight--bold`, `.font--monospace` | type scale, weight, family |
+
+Spacing values come from a fixed em-based scale — `none`, `0.25em`, `0.5em`, `0.75em`, `1em`, `1.25em`, `1.5em`, `2em`, `3em`, `4em`. Use a value from the scale; don't expect arbitrary values like `.margin--13px` to exist.
+
+Color utility values mirror the base color tokens (e.g. `gray-5`…`gray-900`, `blue-500`, `red-500`, `green-500`). If you're unsure a class exists, check `styles/utilities/` in the installed package rather than guessing.
+
+## Theming and overrides: the token naming pattern
+
+For per-component look-and-feel, Particle exposes **CSS variables (design tokens)**, so a consuming app can re-theme components without targeting their class names. This is the intended override mechanism — overriding raw class names is not.
+
+The token naming convention is precise, and getting a separator wrong silently does nothing. The pattern is:
+
+```
+--[ComponentName][--variant][__NestedElement][____property]
+```
+
+- **Four underscores (`____`)** separate the component (or nested element) from the property.
+- **Double dash (`--`)** separates a variant.
+- **Two underscores (`__`)** separate a nested element.
+
+| Example token | Meaning |
+|---|---|
+| `--Button____bg-color` | Button background color |
+| `--Button--outline____b-color` | Outline-variant button border color |
+| `--Input____border-color` | Input border color |
+| `--Checkbox--checked__Icon____color` | Icon color inside a checked checkbox |
+
+Do not invent token names. If you can't confirm a token exists, check Storybook or the package's `styles/` directory rather than approximating one.
+
+## Links
+
+- Storybook (components, props, variants): https://dscout.github.io/particle/v1/storybook/
+- Documentation site: https://dscout.github.io/particle/
+- npm: https://www.npmjs.com/package/@dscout/particle

package/README.md

@@ -25,7 +25,7 @@ yarn add @dscout/particle react@^19.0.0 react-dom@^19.0.0
 
 ### Peer dependencies
 
-Particle requires the implementing application install React and React Router. Optionally the implementing application can also install `lodash` and `@floating-ui/dom`. These optional peer dependencies are **required** when using the tooltip or dropdown components from Particle, but can be omitted if those are not used.
+Particle requires the implementing application install React (`react`, `react-dom`) and React Router (`react-router-dom`). `@floating-ui/dom` — which powers the tooltip and dropdown components — is a regular dependency of Particle and installs automatically; the implementing application does not need to add it.
 
 ### Importing
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dscout/particle",
-  "version": "1.0.0-alpha.54",
+  "version": "1.0.0-alpha.55",
   "description": "A pattern library for building dscout user interfaces",
   "main": "lib/cjs/index.js",
   "module": "lib/esm/index.js",
   "files": [
     "lib/",
-    "styles/"
+    "styles/",
+    "AGENTS.md"
   ],
   "sideEffects": [
     "styles/particle.scss"