Two files, one repository

hashintel/hash ships 3 formats across 17 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ Copilot instructions AGENTS.md ↔ Cursor rules Copilot instructions ↔ Cursor rules

A · AGENTS.md · 764 words B · libs/@hashintel/ds-components/AGENTS.md · 856 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	14	21	0%
Commands	4	21	7	13%
Section tags	5	3	4	42%

What each file covers

Sections

0 shared · 14 only in A · 21 only in B

− HASH Development Guide
− Repository Structure and Navigation
− Common Commands
− Development
− Starting Services
− Testing
− Linting and Fixing
− For Specific Packages
− For TypeScript/JavaScript packages
− For Rust packages
− Monorepo wiring for Rust crates
− Documentation Maintenance
− Petrinaut user-facing docs
− Contextual Rules
+ @hashintel/ds-components - Agent Context
+ Purpose
+ Architecture
+ Panda CSS Configuration
+ panda.config.ts
+ Token Naming Patterns (Strict Mode)
+ Import Patterns
+ Color Token Naming
+ Core Colors
+ Semantic Colors
+ Token Mapping from Legacy Names
+ Component Patterns
+ Recipe Definition
+ Ark UI Integration
+ Scripts
+ File Structure
+ Regenerating Tokens
+ 1. Regenerate token source files inside ds-components
+ 2. Regenerate the styled-system artifact in ds-helpers
+ 3. Verify the package surface still compiles
+ Related Packages

Commands

4 shared · 21 only in A · 7 only in B

− turbo run <command> --filter '<package-name>'
− cargo nextest run --package <package-name>
− cargo test --package <package-name> --doc
− cargo clippy --all-features --package <package-name>
− mise run sync:turborepo
− yarn dev:backend
− yarn dev:backend:api
− yarn dev:frontend
− yarn start
− yarn start:graph
− yarn start:backend
− yarn start:frontend
− yarn start:worker
− yarn test:integration
− yarn lint
− yarn lint:format
− yarn fix:eslint
− yarn fix:format
− cargo-hack
− cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo
− mise run fix:package-json
+ yarn codegen:colors
+ yarn codegen:tokens
+ yarn codegen
+ yarn dev:lib
+ yarn build
+ yarn build:ladle
+ yarn test:snapshots
yarn dev
yarn test:unit
yarn lint:tsc
yarn lint:eslint

Section tags

5 shared · 3 only in A · 4 only in B

− monorepo
− do-not
− docs
+ build
+ code-style
+ ui
+ agent-behaviour
test
lint-format
architecture
types
dependencies

Line diff

+243 added−78 removed43 unchanged15.0% identical

hashintel/hash · AGENTS.md

@@ −1 @@

1# HASH Development Guide

3## Repository Structure and Navigation

5The HASH repository is organized into several key directories:

7- `/apps` - Core applications powering HASH

8 - `/hash-api` - Backend API service

9 - `/hash-frontend` - Web frontend application

10 - `/hash-graph` - Graph database service

11 - `/hash-ai-worker-ts` - AI worker services

12 - `/hash-integration-worker` - Integration worker services

14- `/infra/compose` - Docker Compose stack for external services (Postgres, Kratos, Hydra, Temporal, observability)

16- `/blocks` - Block Protocol components (each subfolder contains a self-contained block)

18- `/libs` - Shared libraries and packages

19 - `/@blockprotocol` - Block Protocol related libraries

20 - `/@hashintel` - HASH-specific libraries

21 - `/@local` - Internal libraries for the monorepo

22 - Other core libraries (e.g., `error-stack`)

24- `/infra` - Deployment and infrastructure code

25 - `/docker` - Docker configurations

26 - `/terraform` - Terraform infrastructure as code

28- `/tests` - Test suites spanning multiple components

30**Navigation Tips:**

32- When exploring a new feature, first identify which app or lib it belongs to

33- Related code is typically co-located within the same directory

34- Check existing implementations before creating new ones

35- For understanding cross-component interactions, look for integration tests in `/tests`

37## Common Commands

39### Development

41- Main development: `yarn dev` (starts API and frontend)

42- Backend only: `yarn dev:backend` or `yarn dev:backend:api`

43- Frontend only: `yarn dev:frontend`

45### Starting Services

47- Start all services: `yarn start`

48- Start graph only: `yarn start:graph`

49- Start backend only: `yarn start:backend`

50- Start frontend only: `yarn start:frontend`

51- Start workers: `yarn start:worker`

53### Testing

55- Unit tests: `yarn test:unit`

56- Integration tests: `yarn test:integration`

58### Linting and Fixing

60- Lint everything: `yarn lint`

61- TypeScript type check: `yarn lint:tsc`

62- ESLint: `yarn lint:eslint`

63- Formatting check: `yarn lint:format`

65- Fix ESLint issues: `yarn fix:eslint`

66- Fix formatting: `yarn fix:format`

68### For Specific Packages

70When working on a specific package, use:

72```bash

73# For TypeScript/JavaScript packages

74turbo run <command> --filter '<package-name>'

76# For Rust packages

77cargo nextest run --package <package-name>

78cargo test --package <package-name> --doc # For doc tests

79cargo clippy --all-features --package <package-name>

80```

82For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.

84### Monorepo wiring for Rust crates

86Each Rust crate has a `package.json` whose **identity and workspace-dependency wiring** — its `@rust/<name>` name, version, and the `dependencies` mirroring its `Cargo.toml` — is generated from `Cargo.toml`. After **adding, removing, or renaming a Rust crate**, or changing its `Cargo.toml` dependencies, re-sync that wiring:

88```bash

89mise run sync:turborepo # sync package.json identity + deps from Cargo.toml metadata

90```

92`sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.

94## Documentation Maintenance

96### Petrinaut user-facing docs

98The Petrinaut user guide lives at `libs/@hashintel/petrinaut/docs/*.md` and is the source of truth for end-user behaviour. The in-app AI assistant reads these pages at runtime via the `readPetrinautDoc` tool, so stale docs lead directly to wrong advice in the product.

100When you change UI or behaviour in the petrinaut packages (`libs/@hashintel/petrinaut`, `libs/@hashintel/petrinaut-core`), you MUST:

101

1021. Review the user-facing docs that mention the affected feature and update them in the same change.

1032. If you add a brand-new user-facing surface (panel, view, mode, tool, settings dialog, ...), add a corresponding page and link it from `libs/@hashintel/petrinaut/docs/README.md`.

1043. When you add a new doc page, also register it in `petrinautDocNames` and `petrinautDocSummaries` in `libs/@hashintel/petrinaut-core/src/ai.ts`, and add a `?raw` import in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts`. The tests in `libs/@hashintel/petrinaut-core/src/ai.test.ts` and `petrinaut-docs-content.test.ts` enforce that every enum value has a summary and a content entry.

1054. Keep the docs end-user-focused: describe what the user sees, what they click, what happens. Do not document Storybook, internal modules, or test setup in the user guide.

1065. If UI are changes that may make screenshots in the docs outdated, you MUST prompt your user to replace the screenshots.

107

108If a change ships without doc updates, call that out in your summary so the user can decide whether to follow up.

109

110## Contextual Rules

111

112CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand:

113

114- .config/agents/rules/\*.md

115

116Instructions:

117

118- Do NOT preemptively load all references - use lazy loading based on actual need

119- When loaded, treat content as mandatory instructions that override defaults

120- Follow references recursively when needed

121

hashintel/hash · libs/@hashintel/ds-components/AGENTS.md

@@ +1 @@

1# @hashintel/ds-components - Agent Context

3## Purpose

5`@hashintel/ds-components` is now the source-owning design-system package.

7It owns:

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/**`

14It still consumes the generated runtime styling utilities from `@hashintel/ds-helpers`.

16## Architecture

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```

35Boundary rules:

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`.

42## Panda CSS Configuration

44### panda.config.ts

46```ts

47import { defineConfig } from "@pandacss/dev";

49import { preset } from "./src/preset";

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```

65Key points:

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

72### Token Naming Patterns (Strict Mode)

74With `strictTokens: true`, you must use the exact token names:

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]` |

84Token types for stories and public token access should come from `@hashintel/ds-helpers/tokens`.

86### Import Patterns

88Component implementation continues to use the generated styling runtime from `@hashintel/ds-helpers`:

90```tsx

91import { css, cva, cx } from "@hashintel/ds-helpers/css";

92import { Box, Flex, Stack } from "@hashintel/ds-helpers/jsx";

93```

95When you need token lookup helpers or token types, use:

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

@@ −1 +1 @@

1−# HASH Development Guide

1+# @hashintel/ds-components - Agent Context

3−## Repository Structure and Navigation

3+## Purpose

5−The HASH repository is organized into several key directories:

5+`@hashintel/ds-components` is now the source-owning design-system package.

7−- `/apps` - Core applications powering HASH

8− - `/hash-api` - Backend API service

9− - `/hash-frontend` - Web frontend application

10− - `/hash-graph` - Graph database service

11− - `/hash-ai-worker-ts` - AI worker services

12− - `/hash-integration-worker` - Integration worker services

7+It owns:

138

14−- `/infra/compose` - Docker Compose stack for external services (Postgres, Kratos, Hydra, Temporal, observability)

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/**`

1513

16−- `/blocks` - Block Protocol components (each subfolder contains a self-contained block)

14+It still consumes the generated runtime styling utilities from `@hashintel/ds-helpers`.

1715

18−- `/libs` - Shared libraries and packages

19− - `/@blockprotocol` - Block Protocol related libraries

20− - `/@hashintel` - HASH-specific libraries

21− - `/@local` - Internal libraries for the monorepo

22− - Other core libraries (e.g., `error-stack`)

16+## Architecture

2317

24−- `/infra` - Deployment and infrastructure code

25− - `/docker` - Docker configurations

26− - `/terraform` - Terraform infrastructure as code

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+```

2734

28−- `/tests` - Test suites spanning multiple components

35+Boundary rules:

2936

30−**Navigation Tips:**

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`.

3141

32−- When exploring a new feature, first identify which app or lib it belongs to

33−- Related code is typically co-located within the same directory

34−- Check existing implementations before creating new ones

35−- For understanding cross-component interactions, look for integration tests in `/tests`

42+## Panda CSS Configuration

3643

37−## Common Commands

44+### panda.config.ts

3845

39−### Development

46+```ts

47+import { defineConfig } from "@pandacss/dev";

4048

41−- Main development: `yarn dev` (starts API and frontend)

42−- Backend only: `yarn dev:backend` or `yarn dev:backend:api`

43−- Frontend only: `yarn dev:frontend`

49+import { preset } from "./src/preset";

4450

45−### Starting Services

51+export 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+```

4664

47−- Start all services: `yarn start`

48−- Start graph only: `yarn start:graph`

49−- Start backend only: `yarn start:backend`

50−- Start frontend only: `yarn start:frontend`

51−- Start workers: `yarn start:worker`

65+Key points:

5266

53−### Testing

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

5471

55−- Unit tests: `yarn test:unit`

56−- Integration tests: `yarn test:integration`

72+### Token Naming Patterns (Strict Mode)

5773

58−### Linting and Fixing

74+With `strictTokens: true`, you must use the exact token names:

5975

60−- Lint everything: `yarn lint`

61−- TypeScript type check: `yarn lint:tsc`

62−- ESLint: `yarn lint:eslint`

63−- Formatting check: `yarn lint:format`

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]` |

6483

65−- Fix ESLint issues: `yarn fix:eslint`

66−- Fix formatting: `yarn fix:format`

84+Token types for stories and public token access should come from `@hashintel/ds-helpers/tokens`.

6785

68−### For Specific Packages

86+### Import Patterns

6987

70−When working on a specific package, use:

88+Component implementation continues to use the generated styling runtime from `@hashintel/ds-helpers`:

7189

72−```bash

73−# For TypeScript/JavaScript packages

74−turbo run <command> --filter '<package-name>'

90+```tsx

91+import { css, cva, cx } from "@hashintel/ds-helpers/css";

92+import { Box, Flex, Stack } from "@hashintel/ds-helpers/jsx";

93+```

7594

76−# For Rust packages

77−cargo nextest run --package <package-name>

78−cargo test --package <package-name> --doc # For doc tests

79−cargo clippy --all-features --package <package-name>

95+When you need token lookup helpers or token types, use:

96+

97+```ts

98+import { token, type Token } from "@hashintel/ds-helpers/tokens";

8099 ```

81100

82−For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.

101+## Color Token Naming

83102

84−### Monorepo wiring for Rust crates

103+### Core Colors

85104

86−Each Rust crate has a `package.json` whose **identity and workspace-dependency wiring** — its `@rust/<name>` name, version, and the `dependencies` mirroring its `Cargo.toml` — is generated from `Cargo.toml`. After **adding, removing, or renaming a Rust crate**, or changing its `Cargo.toml` dependencies, re-sync that wiring:

105+Direct color scales with numeric shades:

87106

88−```bash

89−mise run sync:turborepo # sync package.json identity + deps from Cargo.toml metadata

90107 ```

108+gray.{00,10,20,30,35,40,50,60,70,80,90,95}

109+red.{00,10,20,...,90}

110+blue.{00,10,20,...,90}

111+accent.{00,10,20,...,90}

112+neutral.{white,black}

113+```

91114

92−`sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.

115+### Semantic Colors

93116

94−## Documentation Maintenance

117+Semantic tokens reference core colors:

95118

96−### Petrinaut user-facing docs

119+**Backgrounds (`bg.*`):**

97120

98−The Petrinaut user guide lives at `libs/@hashintel/petrinaut/docs/*.md` and is the source of truth for end-user behaviour. The in-app AI assistant reads these pages at runtime via the `readPetrinautDoc` tool, so stale docs lead directly to wrong advice in the product.

121+```

122+bg.accent.subtle.{default,hover,active}

123+bg.accent.bold.{default,hover,pressed,active}

124+bg.neutral.subtle.{default,hover,active,pressed}

125+bg.neutral.bold.{default,hover,active,pressed}

126+bg.status.{info,success,caution,warning}.subtle.{default,hover,active}

127+bg.status.critical.subtle.{default,hover,active}

128+bg.status.critical.strong.{default,hover,active}

129+```

99130

100−When you change UI or behaviour in the petrinaut packages (`libs/@hashintel/petrinaut`, `libs/@hashintel/petrinaut-core`), you MUST:

131+**Text (`text.*`):**

101132

102−1. Review the user-facing docs that mention the affected feature and update them in the same change.

103−2. If you add a brand-new user-facing surface (panel, view, mode, tool, settings dialog, ...), add a corresponding page and link it from `libs/@hashintel/petrinaut/docs/README.md`.

104−3. When you add a new doc page, also register it in `petrinautDocNames` and `petrinautDocSummaries` in `libs/@hashintel/petrinaut-core/src/ai.ts`, and add a `?raw` import in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts`. The tests in `libs/@hashintel/petrinaut-core/src/ai.test.ts` and `petrinaut-docs-content.test.ts` enforce that every enum value has a summary and a content entry.

105−4. Keep the docs end-user-focused: describe what the user sees, what they click, what happens. Do not document Storybook, internal modules, or test setup in the user guide.

106−5. If UI are changes that may make screenshots in the docs outdated, you MUST prompt your user to replace the screenshots.

133+```

134+text.{primary,secondary,tertiary,disabled,inverted}

135+text.{link,linkHover}

136+text.status.{info,success,warning,critical}

137+```

107138

108−If a change ships without doc updates, call that out in your summary so the user can decide whether to follow up.

139+**Borders (`border.*`):**

109140

110−## Contextual Rules

141+```

142+border.neutral.{muted,subtle,default,emphasis,hover,active}

143+border.status.{info,success,caution,warning,critical}

144+```

111145

112−CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand:

146+**Surfaces (`surface.*`):**

113147

114−- .config/agents/rules/\*.md

148+```

149+surface.{default,subtle,muted,emphasis,alt,inverted}

150+```

115151

116−Instructions:

152+### Token Mapping from Legacy Names

117153

118−- Do NOT preemptively load all references - use lazy loading based on actual need

119−- When loaded, treat content as mandatory instructions that override defaults

120−- Follow references recursively when needed

154+When 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+

169+Components use `cva()` for variant-based styling:

170+

171+```tsx

172+import { cva } from "@hashintel/ds-helpers/css";

173+

174+const 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+

208+Components wrap Ark UI primitives with Panda styling:

209+

210+```tsx

211+import { Checkbox as ArkCheckbox } from "@ark-ui/react/checkbox";

212+import { css } from "@hashintel/ds-helpers/css";

213+

214+export 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+```

250+libs/@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+

268+When tokens or preset inputs change:

269+

270+```bash

271+# 1. Regenerate token source files inside ds-components

272+cd libs/@hashintel/ds-components

273+yarn codegen:colors

274+yarn codegen:tokens

275+

276+# 2. Regenerate the styled-system artifact in ds-helpers

277+yarn codegen

278+

279+# 3. Verify the package surface still compiles

280+yarn lint:tsc

281+```

282+

283+## Related Packages

284+

285+- **ds-helpers**: generated Panda styled-system artifact (`libs/@hashintel/ds-helpers`)

121286