# nadicode Design System

The `@nadicodeai/design-system` package. [`DESIGN.md`](./DESIGN.md) is nadicode's design system and its design authority: every token, the visual direction and the rules every component and page shares. A component's own contract is the usage page in its source in `@nadicodeai/ui`. This README says how to consume the package and how the build turns `DESIGN.md` into what it ships.

This README is a package map and the setup guide for static or non-React consumers. React consumers use the UI package's stylesheet and follow [`packages/ui/README.md`](../ui/README.md); they do not compose design-system stylesheets themselves.

## Static and non-React consumption

Import the complete CSS module once:

```css
@import "@nadicodeai/design-system/css";
```

That interface includes the generated tokens, mode aliases, semantic role maps, the website's content column, type utilities, motion primitives, and framework-agnostic CSS components. Apply `.dark` to the document root or to a scoped static composition to select dark mode. How it is generated is in "How the build works" below.

That interface also registers the brand typeface. Geist and Geist Mono (SIL Open Font License 1.1) ship with the package, and the CSS module declares their `@font-face` rules and loads the woff2 files from package paths, so no consumer supplies its own font loading. The `@font-face` shim stays exported for a consumer that wants the faces without the CSS module:

```css
@import "@nadicodeai/design-system/assets/fonts/geist.css";
```

Individual font files are also exposed under `@nadicodeai/design-system/assets/fonts/*` if the consumer needs to write its own `@font-face` declarations.

## nadicode logo assets

[Brand media authority](DESIGN.md#brand-media-authority) says what each form
is and where it goes, and [`examples/logo.html`](./examples/logo.html) shows
them all. This table is the file behind each, with transparent PNG fallbacks
for software that cannot place SVG.

| Form | On white or a soft neutral | On black or another dark ground |
| --- | --- | --- |
| Mark, the logo | `assets/mark` | `assets/mark-white` |
| Wordmark | `assets/wordmark` | `assets/wordmark-white` |
| Wordmark, one ink | `assets/wordmark-one-ink` | `assets/wordmark-one-ink-white` |
| Icon, brand tile | `assets/app-icon` | `assets/app-icon` |
| Icon, light and dark tiles | `assets/app-icon-light` | `assets/app-icon-dark` |
| Signature form, from 128 px | `assets/app-icon-signature` | `assets/app-icon-dark` |

The one-ink files exist for embossing, stamps and one-colour print, where a
second colour cannot be laid down. The brand tile carries its own field, so
one file serves both grounds.

Prefix each route with `@nadicodeai/design-system/`. Append `.png` for the
transparent PNG fallback, for example
`@nadicodeai/design-system/assets/wordmark-white.png`.

```ts
import wordmarkUrl from "@nadicodeai/design-system/assets/wordmark";

document.querySelector<HTMLImageElement>("[data-nc-logo]")!.src = wordmarkUrl;
```

For direct HTML or CDN delivery, use a version-pinned file URL such as
`https://unpkg.com/@nadicodeai/design-system@<version>/dist/assets/wordmark.svg`.
The clear-space, minimum-size, accessibility, background, and prohibited-use rules live only in
[`DESIGN.md`, "Brand media authority"](./DESIGN.md#brand-media-authority).

## Data-only consumption

A consumer that generates its own theme takes the token files and the assets. The Nadia desktop app's theme script reads `tokens/dtcg-resolved` this way, and its desktop imports `css/host` rather than the complete bundle.

Pin an exact version, never a range: the DTCG group paths are the interface, and a new group arrives in a minor. `npm view @nadicodeai/design-system version` reports the published one.

Two DTCG token files ship, both rooted at `nadicode`: `nadicode.core.*` is the foundation, `nadicode.semantic.*` the shared colour roles per mode, and `nadicode.register.<product>.*` one product's own values:

| Import | What it holds | What it is for |
| --- | --- | --- |
| `@nadicodeai/design-system/tokens/dtcg` | the canonical contract: every alias and every `$extensions` entry preserved | reading which foundation value a register role derives from |
| `@nadicodeai/design-system/tokens/dtcg-resolved` | the same groups, types, descriptions, and extensions, with every alias replaced by its value | generating a theme without an alias engine |

The tarball also carries three root documents. [`DESIGN.md`](./DESIGN.md) is the contract a session reads before it styles anything, [`AGENTS.md`](./AGENTS.md) is this workspace's rulebook, and [`GLOSSARY.md`](./GLOSSARY.md) is the shared design vocabulary.

Load the brand typeface from `@nadicodeai/design-system/assets/fonts/geist.css`, which declares the `@font-face` rules and points them at the packaged woff2 files. One loader per app: a second declaration of Geist, from Google Fonts or a hand-written `@font-face`, downloads the face twice and is a defect.

The logo routes in the table above resolve to files, so a data-only consumer copies or references them without touching the CSS. `LICENSES/` carries the third-party notices the package ships under.

`@nadicodeai/design-system/data/reserved-agent-identifiers.json` lists the profile identifiers Hermes refuses, its `_RESERVED_NAMES` in `apps/nadia/hermes/hermes_cli/profiles.py`. A product that derives an Agent's identifier from the name a person typed avoids them.

The CSS interfaces are not for this consumer. `@nadicodeai/design-system/css` and the `@nadicodeai/ui` stylesheet declare `--color-*` and the generated role map; an app that already owns those names takes the token files and generates its own.

## Package surface

`package.json` owns the current public export paths, and [`DESIGN.md`](./DESIGN.md)
what the tokens, layout, components, motion and assets mean. The runnable
[`examples/`](./examples/) consume only those public exports and are the
inspection surface.

CSS partials and generated adapter files are implementation details. React
components and compositions are discovered through the UI package rather than
inferred from this CSS package.

Consumer overrides belong in an explicit later layer:

```css
@layer page;
@layer page {
  /* Page-specific overrides. */
}
```

## How the build works

`npm run build -w @nadicodeai/design-system` reads two sources: the
`@google/design.md` CLI exports `DESIGN.md`'s YAML front matter, and
`scripts/sd/token-extension.ts` reads the token extension, `src/tokens/extension.tokens.json`.
`scripts/sd/compose-token-graph.ts` joins them into the single `nadicode` token
graph and checks that every alias resolves and points the allowed way (`core`
reaches nothing outside itself; `semantic` names only `core`; a register reaches
`core` and itself). `scripts/build.ts` validates the graph against the vendored
schema and writes the two DTCG files.

Style Dictionary emits the CSS from that graph into `src/css/*.generated.css`;
the header of each `scripts/sd/format-*.ts` says what its output holds, and
`scripts/build.ts` (`OUTPUT 3b`) says what `theme-host.generated.css` holds.

The source graph under `src/css/` is bundled into three public stylesheets:
`css` (everything), `css/tokens` (the token layer alone) and `css/host` (for a
host with base styles of its own). `src/css/index.css` declares the cascade's
layer order.
Generated files and `dist/` are outputs, which git does not track: edit
`DESIGN.md` or `src/tokens/extension.tokens.json` and rebuild, never the output.
Every install builds them through the root `prepare`, and `tests/guards/` holds
the structural checks on every output.
The favicons are the exception: `generate:favicons` writes them and git tracks
them. A consumer reaches any output through the package's `exports`, never a
path into `dist/` or `src/`.

### Worked example (static HTML)

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- One stylesheet: tokens, geometry, components, and the brand typeface -->
    <link rel="stylesheet" href="https://unpkg.com/@nadicodeai/design-system@<version>/dist/css/index.css" />
    <!-- In a bundler, prefer a CSS entry: @import "@nadicodeai/design-system/css"; -->
  </head>
  <body>
    <main>
      <section>
        <div class="nc-page">
          <h1 class="nc-type-display-lg">Agents at work with your team</h1>
          <p class="nc-type-body-lg">One stylesheet carries the tokens, the column and the type.</p>
        </div>
      </section>
    </main>
  </body>
</html>
```

Use the monorepo's `brand/positioning/nadicode/references/story.md` for the nadicode story, positioning, buyer and promise, and `brand/writing/VOICE.md` for the voice and the language.