NadicodeAI Design System

The @nadicodeai/design-system package. DESIGN.md is the normative contract for reusable design tokens, mode behavior, CSS architecture, and generated output. The canonical human brand book lives in the monorepo at brand/brand-book/index.html.

This README is a package map and the setup guide for static or non-React consumers. React consumers use the UI package's single stylesheet interface and follow packages/ui/docs/consuming-cross-repo.md. They do not compose design-system stylesheets themselves.

Static and non-React consumption

Import the complete CSS module once:

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

That interface includes the generated tokens, mode aliases, semantic role maps, page geometry, 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. The generation and cascade mechanics live only in DESIGN.md, "CSS Architecture & Token Pipeline".

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:

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

NadicodeAI logo assets

The horizontal lockup identifies the company with both the mark and the readable name. Use the separate mark where space is tight and the separate wordmark where the name must read by itself. Transparent PNG fallbacks are provided for software that cannot place SVG files.

| Treatment | Lockup | Mark | Wordmark | | --- | --- | --- | --- | | Full colour on white or a soft neutral | assets/logo-lockup | assets/logo-mark | assets/logo-wordmark | | Mono ink | assets/logo-lockup-mono | assets/logo-mark-mono | assets/logo-wordmark-mono | | Inverse on ink | assets/logo-lockup-inverse | assets/logo-mark-inverse | assets/logo-wordmark-inverse | | On verde | assets/logo-lockup-on-verde | assets/logo-mark-on-verde | assets/logo-wordmark-on-verde |

Prefix each route with @nadicodeai/design-system/. Append .png for the transparent PNG fallback, for example @nadicodeai/design-system/assets/logo-lockup-on-verde.png.

import logoLockupUrl from "@nadicodeai/design-system/assets/logo-lockup";

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

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

Nadia asset

The approved background-neutral transparent Nadia master is available through:

| Asset | Import | | --- | --- | | Canonical Nadia | @nadicodeai/design-system/assets/nadia-solid-surface |

The import resolves to the approved transparent PNG. Identity and composition are owned by brand/AGENTS.md; this package README documents only the import surface.

Data-only consumption

A consumer that generates its own theme takes the token files and the assets and imports no stylesheet from this package. The Nadia desktop app consumes the package this way.

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.

{
  "devDependencies": {
    "@nadicodeai/design-system": "2.0.0"
  }
}

Two token files ship, both rooted at nadicode, with nadicode.core.* the foundation every product may reach for 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 is the contract a session reads before it styles anything, AGENTS.md is this workspace's rulebook, and CONTEXT.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 and the Nadia master at @nadicodeai/design-system/assets/nadia-solid-surface 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.

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. DESIGN.md owns what those exports mean and how the CSS cascade, modes, tokens, layout, components, motion, and assets behave. The runnable examples/ consume only those public exports and are the inspection surface. This README does not maintain a parallel inventory.

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:

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

The exact layer order and ownership rules are defined in DESIGN.md.

Worked example (static 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/css" />
    <!-- In a bundler, prefer a CSS entry: @import "@nadicodeai/design-system/css"; -->
  </head>
  <body>
    <main class="nc-page-system">
      <div class="nc-page-frame">
        <section class="nc-page-row">
          <div class="nc-row-lane nc-row-lane-active">
            <div class="nc-artifact-surface">Inspectable agent output</div>
          </div>
        </section>
      </div>
    </main>
  </body>
</html>

Use the monorepo's brand/brand-book/ for NadicodeAI story, positioning, buyer, promise, method, use cases, technology story, trust doctrine, identity, voice, visual direction, sales behavior, language, and boundaries.