# @nadicodeai/design-system

`DESIGN.md` is nadicode's design authority for the tokens, the visual direction
and the rules every component, website section and product screen shares. React
components belong to `@nadicodeai/ui`, and a component's own contract is the
usage page in its source; `examples/` contains rendered specimens.

- Design and CSS changes: `product-design` first, then the relevant section of
  `DESIGN.md`.
- Placement: `../ui/AGENTS.md`. Every reusable component lives in
  `@nadicodeai/ui`, even while one product alone uses it.
- Terms: `GLOSSARY.md`. Static consumption: `README.md`.
- React consumption: `../ui/README.md`.
- Visual checks: `playwright.visual.config.ts` and `tests/visual/`, run by
  post-merge's `test (website, packages)` job. Its `-linux` baselines are what the
  CI runner image (`../../tools/ci/host/Dockerfile`) renders: after an intended
  visual change, rerun `npm run test:visual -w @nadicodeai/design-system --
  --update-snapshots` inside that image and commit the new screenshots.
- Releases: `../../docs/agents/publish.md`.

Edit token sources (the four groups in `DESIGN.md`'s front matter, every other
value in `src/tokens/extension.tokens.json`), then run
`npm run build -w @nadicodeai/design-system`. Generated CSS and `dist/`
are outputs, not hand-edited sources. Favicon source changes use
`generate:favicons`; a lucide-static upgrade uses `generate:icons`.
`package.json` owns the commands; shared validation policy is in
`../../docs/agents/develop.md`.

Visual behavior comes from `DESIGN.md`, a component's usage page, a shipped
surface, or the user's design decision. Screenshots verify that behavior. Name primitives
for nadicode's concepts, keeping source-brand lineage in references.