AGENTS.md

1# @hashintel/ds-helpers - Agent Context
2 
3## Purpose
4 
5`@hashintel/ds-helpers` is now a thin generated artifact package.
6 
7It should only contain:
8 
9- `styled-system/**` generated by Panda
10- minimal publish/package metadata (for example `package.json`, README, and licenses)
11 
12It should not own:
13 
14- Panda config
15- preset source
16- stories or Ladle config
17- Playwright tests
18- token generation scripts
19 
20The source package is `@hashintel/ds-components`, which writes into `ds-helpers/styled-system` via Panda `outdir`.
21 
22## Architecture
23 
24```
25ds-components preset/scripts/demo source
26        │
27        │ panda codegen (outdir)
28        ▼
29   ds-helpers/styled-system
30        │
31        ▼
32css(), cva(), token(), jsx runtime for consumers
33```
34 
35Boundary rules:
36 
37- never add a runtime or package-manager dependency edge from `ds-helpers` back to `ds-components`
38- build orchestration may invoke `ds-components` codegen to materialize `styled-system/**`, but `ds-components` remains the source owner
39- never move source-of-truth token or preset code into this package
40- if you need to regenerate this package, run `yarn workspace @hashintel/ds-components codegen`
41 
42### Generated Output
43 
44The `styled-system/` directory is generated by Panda CSS codegen and exported as the package's public API:
45 
46| Export                           | Description                                    |
47| -------------------------------- | ---------------------------------------------- |
48| `@hashintel/ds-helpers/css`      | `css()`, `cva()`, `sva()` utility functions    |
49| `@hashintel/ds-helpers/tokens`   | `token()` function and token type definitions  |
50| `@hashintel/ds-helpers/types`    | TypeScript types for style properties          |
51| `@hashintel/ds-helpers/patterns` | Layout patterns (stack, flex, grid, etc.)      |
52| `@hashintel/ds-helpers/jsx`      | Styled JSX components (Box, Flex, Stack, etc.) |
53 
54### Usage in ds-components
55 
56Components in `@hashintel/ds-components` import utilities from this package:
57 
58```tsx
59import { css, cva } from "@hashintel/ds-helpers/css";
60import { token } from "@hashintel/ds-helpers/tokens";
61import { Box, Flex } from "@hashintel/ds-helpers/jsx";
62```
63 
64## Regeneration
65 
66Run regeneration from the source package, not here:
67 
68```bash
69cd libs/@hashintel/ds-components
70yarn codegen
71```
72 
73`ds-helpers` itself intentionally has no local codegen or demo workflow now.
74 
75## File Structure
76 
77```
78libs/@hashintel/ds-helpers/
79├── styled-system/        # Panda CSS generated output (committed)
80│   ├── css/              # css(), cva(), sva() functions
81│   ├── jsx/              # Styled JSX components
82│   ├── patterns/         # Layout patterns
83│   ├── tokens/           # Token utilities
84│   └── types/            # TypeScript types
85└── package.json
86```
87 
88## Related Packages
89 
90- **ds-components**: source-owning design-system package that generates this artifact (`libs/@hashintel/ds-components`)
91