# @hashintel/ds-helpers - Agent Context

## Purpose

`@hashintel/ds-helpers` is now a thin generated artifact package.

It should only contain:

- `styled-system/**` generated by Panda
- minimal publish/package metadata (for example `package.json`, README, and licenses)

It should not own:

- Panda config
- preset source
- stories or Ladle config
- Playwright tests
- token generation scripts

The source package is `@hashintel/ds-components`, which writes into `ds-helpers/styled-system` via Panda `outdir`.

## Architecture

```
ds-components preset/scripts/demo source
        │
        │ panda codegen (outdir)
        ▼
   ds-helpers/styled-system
        │
        ▼
css(), cva(), token(), jsx runtime for consumers
```

Boundary rules:

- never add a runtime or package-manager dependency edge from `ds-helpers` back to `ds-components`
- build orchestration may invoke `ds-components` codegen to materialize `styled-system/**`, but `ds-components` remains the source owner
- never move source-of-truth token or preset code into this package
- if you need to regenerate this package, run `yarn workspace @hashintel/ds-components codegen`

### Generated Output

The `styled-system/` directory is generated by Panda CSS codegen and exported as the package's public API:

| Export                           | Description                                    |
| -------------------------------- | ---------------------------------------------- |
| `@hashintel/ds-helpers/css`      | `css()`, `cva()`, `sva()` utility functions    |
| `@hashintel/ds-helpers/tokens`   | `token()` function and token type definitions  |
| `@hashintel/ds-helpers/types`    | TypeScript types for style properties          |
| `@hashintel/ds-helpers/patterns` | Layout patterns (stack, flex, grid, etc.)      |
| `@hashintel/ds-helpers/jsx`      | Styled JSX components (Box, Flex, Stack, etc.) |

### Usage in ds-components

Components in `@hashintel/ds-components` import utilities from this package:

```tsx
import { css, cva } from "@hashintel/ds-helpers/css";
import { token } from "@hashintel/ds-helpers/tokens";
import { Box, Flex } from "@hashintel/ds-helpers/jsx";
```

## Regeneration

Run regeneration from the source package, not here:

```bash
cd libs/@hashintel/ds-components
yarn codegen
```

`ds-helpers` itself intentionally has no local codegen or demo workflow now.

## File Structure

```
libs/@hashintel/ds-helpers/
├── styled-system/        # Panda CSS generated output (committed)
│   ├── css/              # css(), cva(), sva() functions
│   ├── jsx/              # Styled JSX components
│   ├── patterns/         # Layout patterns
│   ├── tokens/           # Token utilities
│   └── types/            # TypeScript types
└── package.json
```

## Related Packages

- **ds-components**: source-owning design-system package that generates this artifact (`libs/@hashintel/ds-components`)