# DASH setup and compatibility

Use this reference for adoption, dependency changes, missing styles, or theme and font setup. Start with the target repository's working examples and scripts.

## Package ownership

This reference was checked against `@hashintel/ds-components` 0.5.1, `@hashintel/ds-helpers` 0.2.2, and `@hashintel/ds-icons` 0.0.3. These are a reference snapshot, not versions every application must install.

| Package or entry point            | Responsibility                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| `@hashintel/ds-components`        | React components built on Ark UI and Panda CSS. Inspect its root and per-component exports. |
| `@hashintel/ds-components/preset` | The current Panda preset and configuration helpers.                                         |
| `@hashintel/ds-components/tokens` | The package-owned token definitions.                                                        |
| `@hashintel/ds-helpers/css`       | Generated `css`, `cva`, and `cx` helpers.                                                   |
| `@hashintel/ds-helpers/tokens`    | Token lookup helpers, including `token.var`.                                                |
| `@hashintel/ds-icons`             | Optional HASH icon components and integration helpers.                                      |

In this snapshot, the former `ds-theme` preset ownership has moved into `ds-components`. Check an older application's setup before migrating it. Keep the repository's package manager and lockfile, and inspect peer requirements rather than assuming that any React or Ark UI version is compatible.

## Panda integration

Confirm all of the following in the consuming application:

- Its Panda configuration includes the DASH preset from `@hashintel/ds-components/preset` and uses `@hashintel/ds-helpers` as its `importMap`.
- Its extraction inputs cover application files that declare styles and the component package's published `panda.buildinfo.json`. Use the package's `resolvePandaBuildInfoPath` helper when its setup example requires it.
- If rendering the published documentation blocks, include the separate `docs/panda.buildinfo.json`. Ordinary product screens do not need those documentation blocks.
- If using `ds-icons`, include its build information and `dsIconsPandaPreset` for its animation styles.
- The repository's code-generation and CSS-generation commands run, and the resulting stylesheet is loaded by the application. Importing `css` does not do that loading.

Follow the application's existing choices for output directories, preflight, theme scoping, and bundling. Avoid replacing a working configuration with a generic full-file example. Prefer existing strict-token checks, and justify literal CSS values that are needed for a layout or custom effect.

## Tokens and runtime styles

Style properties use short token names; token lookup uses a category path:

```tsx
import { css } from "@hashintel/ds-helpers/css";
import { token } from "@hashintel/ds-helpers/tokens";

const panel = css({
  padding: "4",
  borderRadius: "lg",
  backgroundColor: "bg.surface",
  color: "fg.body",
});

const externalStyle = {
  padding: token.var("spacing.4"),
  borderRadius: token.var("radii.lg"),
};
```

`token.var` keeps the CSS variable reference. This matters when the value responds to theme or density. Avoid constructing token names or class names from arbitrary strings at runtime; declare a map of supported states that Panda can extract.

## Theme and fonts

Inspect the actual preset and the host's theme provider. The published preset supports root `light` and `dark` classes; preserve how the application chooses and persists the theme. Semantic colors need the correct theme context, including in portals.

HASH's typography guidance uses KH Teka, KH Teka Mono, and limited editorial use of KH Giga. The package snapshot's default stacks can still name Inter, Inter Tight, and Geist Mono. Loading a font alone does not change those stacks. Use the host's approved theme overrides or font variables and verify the computed font. Preserve suitable system fallbacks. Use only fonts the project is authorized to serve.

## Missing styles: inspect before replacing components

If a component looks unstyled, check its import against exports, CSS extraction inputs, the generated stylesheet request, and computed styles. If only an overlay is wrong, inspect its portal and theme context. If only an icon fails, check its build information and animation preset. Read version-matched examples before changing props or inventing CSS fixes.

## Relevant documentation

- [DASH setup](https://hash.design/foundations/design-system.mdx).
- [Typography and font stacks](https://hash.design/foundations/type.mdx).
- [Icons](https://hash.design/foundations/icons.mdx).
- [Libraries](https://hash.design/libs.mdx) and [Changelog](https://hash.design/changelog.mdx).