Skip to content

docs: shared design contract guidance (AGENTS.md + CONTRIBUTING) #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KKranthi6881 merged 1 commit into from
Jun 26, 2026
Merged

docs: shared design contract guidance (AGENTS.md + CONTRIBUTING) #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Agent guide — DataLex

Guidance for AI agents (and humans) making changes here. Most of DataLex is yours
to evolve freely. The one thing to be careful about is the **shared design
contract** below.

## ⚠️ Shared design contract with Governed Analytics Cloud — do not break

DataLex is embedded inside the **Governed Analytics Cloud**, which reskins the
embedded surface to the global theme. That works only because DataLex exposes a
small, stable contract that the cloud drives from outside. The canonical source
is the cloud's `@duckcodeai/design-tokens` package (and `docs/adr/ADR-0002` in the
cloud repo). **Renaming or removing any of the following silently breaks the
cloud embed** — and the cloud's sync runs a contract check
(`scripts/embed-contract.test.mjs`) that will **fail the build** if you do:

1. **Theme selector** — `data-theme` on `<html>` (mirrored on `<body>` by the
Shell), values **`paper` | `white` | `obsidian`**. Keep these theme blocks in
`packages/web-app/src/styles/datalex-design.css`. `white` is the cloud's crisp
light theme — do not drop it.
2. **Token vocabulary** — the shared semantic vars every surface reads:
`--bg-0..4`, `--bg-canvas`, `--text-primary/secondary/tertiary/muted`,
`--accent`/`--accent-hover`/`--accent-dim`/`--accent-fg`,
`--border-subtle/default/strong`. **No app-prefixed colour vars** (no
`--lux-color-*`). Rename a token → rename it in the cloud's design-tokens too.
3. **Theme persistence key** — `dm_theme` (the `uiStore` key). The cloud writes it
(and sets `data-theme`) to drive the embedded theme. Don't rename it.
4. **Layout classes the cloud's fit override targets** — `.app` (the shell grid),
`.activity-rail`, `.topbar`, `.topchrome`, `.left-resizer`. The cloud hides its
own chrome and collapses the activity-rail column by selecting these. Renaming
them re-opens the gap / brings back hidden chrome.

If you must change any of the above, **coordinate with the cloud repo**
(`governed-analytics-cloud`): update `packages/design-tokens` + the
`embed-overrides/datalex.css`, and run `node scripts/embed-contract.test.mjs`
there. Standalone DataLex is unaffected by the cloud — these are just stability
guarantees on the names the cloud depends on.

## General
- Web app: `packages/web-app` (React/Vite, Zustand, React Flow). Build: `npm run
build` inside that package.
- See `CONTRIBUTING.md` for setup, tests, and the release process.
11 changes: 11 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,3 +159,14 @@ See [RELEASING.md](RELEASING.md) for the full process. Short version:
bump `project.version` in `pyproject.toml`, move items from
`[Unreleased]` into a new dated section in `CHANGELOG.md`, merge, then
push a signed `vX.Y.Z` tag. CI publishes to PyPI automatically.

## Shared design contract (Governed Analytics Cloud embed)

DataLex is embedded by the Governed Analytics Cloud, which reskins it to the
global theme. A small set of names is a **shared contract** the cloud depends on
— don't rename them without coordinating: the `data-theme` values
(`paper`/`white`/`obsidian`), the `--bg-*`/`--text-*`/`--accent*`/`--border-*`
vars, the `dm_theme` storage key, and the `.app`/`.activity-rail`/`.topbar`/
`.topchrome`/`.left-resizer` layout classes. The cloud's build runs a contract
check that fails on a break. See [`AGENTS.md`](AGENTS.md) for the full list and
the canonical source (`@duckcodeai/design-tokens`).
Loading