AGENTS.md

1# @hashintel/ds-components - Agent Context
2 
3## Purpose
4 
5`@hashintel/ds-components` is now the source-owning design-system package.
6 
7It owns:
8 
9- the Panda preset source in `src/preset/**`
10- token/codegen scripts in `scripts/**`
11- the component library in `src/components/**`
12- the token/demo surface in `src/tokens/**`, `src/stories/Intro.mdx`, `.ladle/`, and `tests/**`
13 
14It still consumes the generated runtime styling utilities from `@hashintel/ds-helpers`.
15 
16## Architecture
17 
18```
19┌─────────────────────────────────────┐
20│           ds-components             │
21│  preset source + scripts + demos    │
22└──────────────────────┬──────────────┘
23                       │
24                       │ panda codegen
25                       ▼
26              ┌─────────────────┐
27              │   ds-helpers    │
28              │ generated only  │
29              │ styled-system   │
30              └────────┬────────┘
31                       ▼
32              css(), cva(), jsx runtime
33```
34 
35Boundary rules:
36 
37- `ds-components` generates `../ds-helpers/styled-system` via Panda `outdir`.
38- `ds-helpers` must not depend on `ds-components`.
39- `@hashintel/ds-components/preset` is the canonical public styling entrypoint.
40- `@hashintel/ds-components/tokens` is the public package-owned token export for `tokens` and `semanticTokens`.
41 
42## Panda CSS Configuration
43 
44### panda.config.ts
45 
46```ts
47import { defineConfig } from "@pandacss/dev";
48 
49import { preset } from "./src/preset";
50 
51export default defineConfig({
52  importMap: "@hashintel/ds-helpers",
53  outdir: "../ds-helpers/styled-system",
54  include: ["./src/components/**/*.{ts,tsx}"],
55  jsxFramework: "react",
56  outExtension: "mjs",
57  preflight: false,
58  presets: [preset],
59  strictPropertyValues: true,
60  strictTokens: true,
61  validation: "error",
62});
63```
64 
65Key points:
66 
67- `src/preset.ts` is the local source of truth for the preset.
68- publish codegen writes to `../ds-helpers/styled-system`
69- `panda.local.config.ts` also writes to `../ds-helpers/styled-system`; it only broadens the scanned demo/story globs.
70- `panda.local.config.ts` exists separately for local demo surfaces such as Ladle
71 
72### Token Naming Patterns (Strict Mode)
73 
74With `strictTokens: true`, you must use the exact token names:
75 
76| Token Type       | ❌ Invalid            | ✅ Valid                                         |
77| ---------------- | --------------------- | ------------------------------------------------ |
78| Spacing          | `spacing.4`, `"4"`    | `default.4`, `compact.4`, `comfortable.4`        |
79| Radii            | `radius.2`, `md`      | `md.2`, `sm.3`, `lg.full`, `component.button.sm` |
80| FontSize         | `size.textsm`         | `sm`, `xs`, `base`, `lg`, `xl`, `2xl`            |
81| LineHeight       | `leading.none.textsm` | `none.text-sm`, `normal.text-base`               |
82| Arbitrary values | `64px`                | `[64px]`                                         |
83 
84Token types for stories and public token access should come from `@hashintel/ds-helpers/tokens`.
85 
86### Import Patterns
87 
88Component implementation continues to use the generated styling runtime from `@hashintel/ds-helpers`:
89 
90```tsx
91import { css, cva, cx } from "@hashintel/ds-helpers/css";
92import { Box, Flex, Stack } from "@hashintel/ds-helpers/jsx";
93```
94 
95When you need token lookup helpers or token types, use:
96 
97```ts
98import { token, type Token } from "@hashintel/ds-helpers/tokens";
99```
100 
101## Color Token Naming
102 
103### Core Colors
104 
105Direct color scales with numeric shades:
106 
107```
108gray.{00,10,20,30,35,40,50,60,70,80,90,95}
109red.{00,10,20,...,90}
110blue.{00,10,20,...,90}
111accent.{00,10,20,...,90}
112neutral.{white,black}
113```
114 
115### Semantic Colors
116 
117Semantic tokens reference core colors:
118 
119**Backgrounds (`bg.*`):**
120 
121```
122bg.accent.subtle.{default,hover,active}
123bg.accent.bold.{default,hover,pressed,active}
124bg.neutral.subtle.{default,hover,active,pressed}
125bg.neutral.bold.{default,hover,active,pressed}
126bg.status.{info,success,caution,warning}.subtle.{default,hover,active}
127bg.status.critical.subtle.{default,hover,active}
128bg.status.critical.strong.{default,hover,active}
129```
130 
131**Text (`text.*`):**
132 
133```
134text.{primary,secondary,tertiary,disabled,inverted}
135text.{link,linkHover}
136text.status.{info,success,warning,critical}
137```
138 
139**Borders (`border.*`):**
140 
141```
142border.neutral.{muted,subtle,default,emphasis,hover,active}
143border.status.{info,success,caution,warning,critical}
144```
145 
146**Surfaces (`surface.*`):**
147 
148```
149surface.{default,subtle,muted,emphasis,alt,inverted}
150```
151 
152### Token Mapping from Legacy Names
153 
154When updating components, use this mapping:
155 
156| Old (incorrect)          | New (correct)          |
157| ------------------------ | ---------------------- |
158| `bg.brand.*`             | `bg.accent.*`          |
159| `core.gray.20`           | `gray.20`              |
160| `core.red.50`            | `red.50`               |
161| `core.custom.30`         | `accent.30`            |
162| `text.linkhover`         | `text.linkHover`       |
163| `text.semantic.critical` | `text.status.critical` |
164 
165## Component Patterns
166 
167### Recipe Definition
168 
169Components use `cva()` for variant-based styling:
170 
171```tsx
172import { cva } from "@hashintel/ds-helpers/css";
173 
174const buttonRecipe = cva({
175  base: {
176    display: "inline-flex",
177    alignItems: "center",
178    // ...base styles
179  },
180  variants: {
181    variant: {
182      primary: {},
183      secondary: {},
184      ghost: {},
185    },
186    size: {
187      sm: { height: "[28px]", px: "spacing.5" },
188      md: { height: "[32px]", px: "spacing.6" },
189      lg: { height: "[40px]", px: "spacing.8" },
190    },
191  },
192  compoundVariants: [
193    {
194      variant: "primary",
195      colorScheme: "brand",
196      css: {
197        backgroundColor: "bg.accent.bold.default",
198        color: "text.inverted",
199        _hover: { backgroundColor: "bg.accent.bold.hover" },
200      },
201    },
202  ],
203});
204```
205 
206### Ark UI Integration
207 
208Components wrap Ark UI primitives with Panda styling:
209 
210```tsx
211import { Checkbox as ArkCheckbox } from "@ark-ui/react/checkbox";
212import { css } from "@hashintel/ds-helpers/css";
213 
214export const Checkbox = (props) => (
215  <ArkCheckbox.Root
216    className={css({
217      /* styles */
218    })}
219    {...props}
220  >
221    <ArkCheckbox.Control
222      className={css({
223        /* styles */
224      })}
225    >
226      <ArkCheckbox.Indicator>{/* check icon */}</ArkCheckbox.Indicator>
227    </ArkCheckbox.Control>
228    <ArkCheckbox.Label>{props.children}</ArkCheckbox.Label>
229  </ArkCheckbox.Root>
230);
231```
232 
233## Scripts
234 
235| Script                | Description                                                        |
236| --------------------- | ------------------------------------------------------------------ |
237| `yarn dev`            | Start the primary Ladle-based demo loop                            |
238| `yarn dev:lib`        | Watch the publishable component library build                      |
239| `yarn codegen`        | Generate token source files and `../ds-helpers/styled-system`      |
240| `yarn build`          | Build the component library entrypoints                            |
241| `yarn build:ladle`    | Build the Ladle demo surface                                       |
242| `yarn lint:eslint`    | Lint the publishable package surface                               |
243| `yarn lint:tsc`       | TypeScript type checking                                           |
244| `yarn test:unit`      | Run the Vitest unit suites without the Playwright snapshot harness |
245| `yarn test:snapshots` | Build Ladle and run the Playwright snapshot suite                  |
246 
247## File Structure
248 
249```
250libs/@hashintel/ds-components/
251├── .ladle/                 # Ladle/demo harness
252├── src/
253│   ├── components/
254│   ├── preset/             # Panda preset source of truth
255│   ├── stories/            # Shared docs such as Intro.mdx
256│   ├── tokens/             # Token stories and fixtures
257│   ├── tokens.ts           # Public `./tokens` facade
258├── scripts/                # Token/codegen scripts
259├── tests/                  # Snapshot/demo tests
260├── panda.config.ts
261├── panda.local.config.ts
262├── package.json
263└── tsconfig.json
264```
265 
266## Regenerating Tokens
267 
268When tokens or preset inputs change:
269 
270```bash
271# 1. Regenerate token source files inside ds-components
272cd libs/@hashintel/ds-components
273yarn codegen:colors
274yarn codegen:tokens
275 
276# 2. Regenerate the styled-system artifact in ds-helpers
277yarn codegen
278 
279# 3. Verify the package surface still compiles
280yarn lint:tsc
281```
282 
283## Related Packages
284 
285- **ds-helpers**: generated Panda styled-system artifact (`libs/@hashintel/ds-helpers`)
286