NDS IQ

Overview

NDS IQ (Integration Quality) is the instruction system for building with NDS consistently. It covers runtime setup, page implementation, browser verification, porting, and upgrades.

It installs as two pieces: NDS-IQ.md at the project root and a short anchor in CLAUDE.md or AGENTS.md. The anchor contains the project paths and tells the agent to read the rules before NDS work. The rules are loaded on demand, once per session.

The rules are universal; project-specific values stay in the anchor. Updates replace NDS-IQ.md as a whole. Installation and usage are covered in the Get Started guide.

How It Is Built

From the Source Outward

Component lifecycles, events, state, dependencies, markup, APIs, and attribute contracts are defined where agents should not have to guess. Safe-to-derive details are left to the agent.

Hardened by Real Migrations

Rules are based on evidence, not speculation. Failures from real AI-assisted migrations become rule candidates only after verification against the NDS source.

Tested per Revision

Each revision is tested against real failure scenarios on the baseline model tier it supports. New rules follow a fail, fix, pass loop, and passing scenarios remain as regression tests.

Validated baseline

Claude Sonnet is the validated baseline for NDS IQ. The rules are designed to produce consistent results across capable AI models.

What It Governs

Seven hard rules define the core constraints:

Read-only template: never edit the NDS reference folder.
No minified reads: use the readable source beside minified bundles.
Canonical markup: copy component HTML from the documentation.
Sections and primitives: compose pages through the NDS layout system.
Knobs and tokens first: use custom properties before selector overrides.
No legacy libraries: NDS and vanilla JS replace the legacy jQuery-era stack.
Approved porting strategy: plan existing-UI replacement before implementation.

The rules are supported by the inventory → plan → build → verify workflow and NDS-PLAN.md, which carries project state between sessions.

Revision History

NDS IQ is versioned independently from the template. The revision is shown in the rulebook heading and indicates the maturity of the rule set.

Updates compare the content of the installed and published rulebooks. A difference means a newer revision exists. The anchor has no version because it remains unchanged.

Revision	Highlights
v3.0	A 34% shorter read, organised around the work. The session picks a work mode first, each phase has entry and exit gates, and a new authority table settles who decides content, data rules, and structure. Verification sets the viewport rather than the window, and an unmet check now holds the page status open.
v2.2	Client-rendered apps get proper coverage: the mount element and any layout-affecting class have to be right in the initial HTML, before the framework runs. Direction and language are now a required pair. A compacted context counts as a new session, and a matched source ships all its members.
v2.1	Fewer questions, more defaults. The release install, the full chrome, and the bilingual locale ship as-is, and the plan review asks everything in one stop. The plan tracks open items with tick boxes, and the inventory now checks legacy stylesheets for global rules.
v2.0	Verification now runs headless-first, so desktop and mobile are one run. The master layout is copied from a built page, guided by the new Page Shell reference, and older templates fall back to their built pages alone. Framework views that mount, re-render, or unmount route to the refresh and destroy docs.
v1.0	Full rewrite, out of beta. The same rules reordered around the work: standing principles, tables for edit kinds, bans, and stop states, and a 40% shorter read. Validated against the complete scenario suite on three model tiers before release.
v0.10	Field-tested on one production project. Set `.nds/` as the fixed template home, and added runtime bundle cross-checks, an install-time CSP sweep, a no-browser smoke check for page verification, named bans for copy edits, and source-first fix proposals.
v0.9	Field-tested across three projects. Added safer update handling, stable template paths, source-first guidance, page chrome planning, single-page plan waivers, findings for rule gaps, and Content-Security-Policy guidance.
v0.8	Removed version gates and made the rules version-agnostic. Added content-based updates, source population from matching releases, download checks, catalog checks, CSP checks, and release-note review.
v0.7	Moved the rules into `NDS-IQ.md` with a version-free anchor. Added source-based guidance for JavaScript wiring and canonical markup.
v0.6	Added cleanup guidance for stale NDS instructions, superseded blocks, conventions, and notes.
v0.5	Added release-folder handling, runtime-banner-first installs, raw-file fetch discipline, legacy UI guidance, clean resets, and image geometry checks.
v0.4	Introduced the NDS IQ name, greenfield handling, spike guidance, JS wiring facts, and menu portal guidance.
v0.3	Added conformance triage, plan lifecycle, update checks, and block-refresh paths.
v0.2	Added porting strategy, chrome coverage, plan discipline, and the findings report.
v0.1	Initial release with template 1.6.0, before revision stamps were introduced.

Staying Current

Template upgrade: updates the matching rules revision as part of the upgrade.
Standalone update: fetches the latest published revision on demand.

Both paths compare the installed and published files, then replace the rulebook when they differ. There is no merging or partial patching. The anchor and project paths remain unchanged. Use the upgrade prompts in the Get Started guide.

Compatibility

NDS IQ is agent-agnostic and assumes a capable local coding agent with file and shell access. It is validated end to end with Claude Code.

The rules work with any template release. If an older release lacks a feature referenced by the current rules, the agent falls back to the relevant documentation and source, reports the gap, and can propose an upgrade.

The Instructions

The complete rulebook is rendered below from its source in the repository.

Markdown IQ v3.0


# NDS IQ — building UI with the National Design System (instructions v3.0)

## How to use this file

The project's agent file (`CLAUDE.md` / `AGENTS.md`) declares `NDS_ROOT` and `NDS_ASSETS` and points here.

- Read this file top to bottom once per session before any NDS/UI work or when unsure.
- This file is universal and read-only: no project values and no edits.
- Path values live only in the anchor.
- Updates replace this file whole. After any replacement or context compaction, reread it before continuing.
- At each phase boundary, reread that phase's entry and exit gates before acting.

## The two paths

**`NDS_ROOT`** — the flat contents of one NDS template release from https://github.com/mazin-musleh/NDS-vanilla/releases. Default: `.nds/` at project root, gitignored. The path is correct when `NDS_ROOT/_site/` resolves directly; never keep the zip's versioned wrapper. Read-only.

**`NDS_ASSETS`** — the project's static folder receiving NDS runtime assets; never under `NDS_ROOT`.

- Derive its served URL from the stack and confirm it before the first asset tag.
- Placeholder path? Stop NDS-side work and ask the dev. Inventory/plan work may continue; NDS targets stay `blocked on NDS_ROOT` until sources resolve.
- Never adopt candidate paths yourself. Enumerate candidates, read their banners, and let the dev choose.
- Persist any dev-supplied path in the anchor that session. Never store paths in `NDS-PLAN.md`.

## Standing principles

**P1 — Check before claim.**

| Claim | Required check |
|---|---|
| "NDS has no X" — yours or the dev's "use native X" | search catalog `use_when` (§Build) |
| release known / unknown | banner check (P2) |
| cannot see page | headless attempt (§Verify) |
| no CSP concern | response-header sweep (§Plan) |
| page done | both browser passes (§Verify) |

**P2 — Banner checks are bounded.** Read only a bundle's opening comment for `Version:`. If absent, the release is unknown. Never scan deeper into minified files or infer the version elsewhere → P5.

**P3 — Source first.** Before asking/answering an NDS question or wiring page JS, read the relevant source:

| Need | Read |
|---|---|
| component markup/usage | `_source/<folder>/<name>.md` (`folder` from catalog `url`) |
| chrome, head, CSP, locale | `_source/ui-shell/*.md` |
| runtime/framework lifecycle APIs | `_source/core/*.md` |
| component JS API | `_source/_js/nds-<name>.js` banner |
| available UI | `_source/_data/content/*.yml` |
| styling knobs/tokens | `_source/_sass/components/*.scss`, `_source/_sass/tokens/` |
| built visual twin | `_site/**/*.html` |

Ask the dev only what NDS does not answer: project paths/conventions, pacing, or unresolved trade-offs.

**P4 — Copy is a contract.** Canonical markup, the head, and copied page scripts stay canonical. Only hard rule #3's four edit types are allowed.

**P5 — Report and stop** when a dev decision is required:

| State | Report | Dev decides |
|---|---|---|
| JS/CSS banners disagree | hand-assembled runtime or interrupted upgrade | release |
| both lack `Version:` | release unknown | release |
| `-dev` banner | no matching release | release |
| runtime outside `NDS_ASSETS` | location + affected pages | point anchor there / move it |
| reference newer than runtime | pending upgrade | upgrade or not |
| no runtime anywhere | first setup | install latest and report |
| prior NDS work / inherited plan | conformance split (§Plan) | adopt / retire / rebuild |
| project rules conflict | conflict | which rules win |
| NDS itself needs changes | gap | separate conversation |

If the dev says a found runtime is legacy, ignore it: treat setup as new — the latest release becomes the default — and assess its pages as prior NDS work.

## Seven hard rules

1. **Never edit `NDS_ROOT`.** It is read-only. If NDS itself needs a change, report it and stop.

2. **Never read minified JS/CSS.** Use the `NDS_ROOT/_source/` twin. Exception: read only a bundle's opening comment for the `Version:` banner (P2).

3. **Copy canonical markup verbatim. Never invent it.** Copy the `lang-html` block from `_source/<folder>/<name>.md`; use `_site/<folder>/<name>.html` as the built reference. Preserve structure, classes, `data-*`, and ARIA.

   Only these edits are allowed:

   | Edit | Allowed change |
   |---|---|
   | Asset URL | Rewrite template `href`/`src` to `NDS_ASSETS` URLs |
   | Content | Replace placeholder text/content attributes; reset replaced-image `width`/`height` to real dimensions |
   | Modifier | Add classes listed in the component's Modifier Classes table |
   | CSP knob | Under strict `style-src`, move inline `style="--…"` values to a project-scoped class in an allowed `<style>`; nonce/hash covers `<style>`, never the attribute |

   Apply these rules at the point of copy:

   - Keep every canonical part in order. A small dataset or minimal existing page is not a reason to remove canonical parts. A matched source ships every part. Name any domain-required removal to the dev before the page is complete.
   - Put host-framework bindings on canonical elements as attributes. Never insert framework-generated UI elements into the structure.
   - Edit a copied script point by point against its source. Never rewrite it from scratch.
   - Keep canonical wrappers with their children. Never lift a child out of its wrapper.

   Inherited markup follows the same rule. Copy layout-coupled components (side menu/info, steppers, heroes) from a FULL page that uses them.

4. **All page content uses NDS sections and layout primitives.** Read `_source/layout/section.md` first.
   - Every content block uses `<section class="nds-content-section">` with the documented tier.
   - Every section lives inside `.nds-content-layout > .nds-main-content`.
   - Compose only with `nds-grid`, `nds-flex`, and `nds-block`; no Bootstrap layout or custom flex wrappers.
   - Use primitive `--gap` for spacing, not margins. `.nds-section-body` adds no gap. Give standalone buttons their own row/full width; wrap `.nds-form` fields in a gapped container.

5. **Style in this order: knobs → tokens → scoped overrides.**
   - **Knobs:** use documented CSS variables. Find them via `var(--` in `_source/_sass/components/_<name>.scss`. Under strict `style-src`, use rule #3's CSP conversion.
   - **Tokens:** rebind semantic tokens from `_source/_sass/tokens/_semantic.scss` after `nds-main.min.css`. If dark mode remains, mirror rebinds under `:root[data-theme~="dark"]`.
   - **Overrides:** only when neither works; scope under a project class/`data-*` and comment why. Do not override `.nds-*` internals directly.

6. **No legacy UI libraries: NDS + vanilla JS only.**

   | Legacy | Use |
   |---|---|
   | Select2 | autocomplete / multiselect |
   | Summernote / TinyMCE | editor |
   | jTables / DataTables | table + sort + filter + pagination + export |
   | Font Awesome | HGI icons |
   | Bootstrap | NDS layout primitives |
   | jQuery | vanilla JS / NDS APIs |
   | global `site.css` / `site.js` | rule #5 + §JS wiring |

   Do not mix NDS and legacy UI on the same page. NDS pages use the runtime from `NDS_ROOT`, exclude inherited legacy CSS, and migrate inherited JS through §JS wiring. Removing legacy libraries project-wide is the dev's decision.

   An NDS spike is ONE parallel page with the full head, runtime, and canonical markup. No plan required; all other rules apply.

7. **Replacing existing UI requires an approved porting strategy before file #1.**
   - **Default: parallel files.** Create each NDS page beside the legacy page on a separate route/flag; keep legacy as reference and rollback. Prior non-conformant NDS rebuilds in place (§Plan).
   - **Score the strategy:** (1) NDS markup stays in templates/HTML, never code strings; (2) minimize existing-file edits; (3) preserve side-by-side serving/rollback; (4) co-locate page JS. Show the dev the comparison; in-place edits/deletions require approval.
   - **Page JS:** co-locate where possible and load after the chrome scripts. Inline page JS uses `<script type="module">`; never rely on inline `<script defer>`.

## Install

**Existing runtime version wins; never follow `latest` when `NDS_ASSETS` already has one.**

1. Read the opening `Version:` banners in `NDS_ASSETS/js/nds-main.min.js` and `NDS_ASSETS/css/nds-main.min.css`. They must agree; otherwise → P5.
2. Download that exact release: `releases/download/v<version>/nds-vanilla-template-v<version>.zip`. Extract its contents flat into `NDS_ROOT`.
3. If `NDS_ROOT/_source/` is absent (newer zips do not ship it), download the SAME tag's source zip to a temp folder outside the project and copy available `_js`, `_sass`, `components`, `utilities`, `layout`, `ui-shell`, `core`, `templates`, `examples`, `_data/content` into `NDS_ROOT/_source/`.
4. Copy all of `NDS_ROOT/_site/assets/` into `NDS_ASSETS` unchanged. Preserve lazy-bundle and `i18n/<component>/<lang>.json` paths.

- Never copy `_site/docs-assets/`, except one explicitly wanted event skin and its script.
- Empty `NDS_ASSETS` is not proof of first setup: search the project for `nds-main.min.js` and its loading layouts. Found → P5. None → install latest and report it.
- At session start compare the `NDS_ROOT` runtime banner with `NDS_ASSETS`. Older reference → re-download the runtime's release and repopulate `_source/`; newer reference → P5.
- Older releases remain valid canon. Populate `_source/` from the matching tag only; never substitute newer source, never raw main. A JS file without a banner remains readable: use its doc source and the file itself. Report the gap; propose the upgrade as the dev's call.

## Plan

NDS is a UI layer. The host project is the application that serves the UI. It may contain both frontend and backend. NDS IQ does not choose or scaffold the stack.

### Choose the work mode

| Project state | Workflow | Plan |
|---|---|---|
| No host project exists | Stop NDS work. Handle project setup outside NDS IQ, then resume after the host project serves. | No NDS plan yet |
| Host project serves; no UI exists | Greenfield: use the dev brief for pages and content, and NDS canon for structure and behavior. | Required for multiple pages. The dev may waive it for one page. |
| Existing non-NDS UI | Port: preserve requirements and project contracts; replace UI structure with NDS canon. | Required by default. An explicit waiver permits one parallel page. |
| Conformant NDS project; one new page | Extend: use its verified family archetype, then the composition cascade. | No full plan. Build and Verify gates still apply. |
| Conformant NDS project; several new pages | Inventory the named pages and their shared shapes. | Required |
| Prior NDS conformance is unknown | Assess current pages before extension. | Required |

**Plan entry gate.** Choose the work mode first. When a plan applies, list routes, layouts, shared partials, pages/views, and legacy UI libraries. Each client-side view gets its own row. Map every page through the §Build composition cascade and record its chrome shape (`full`, `console`, `minimal`). For greenfield work, include only pages the dev named and leave legacy columns empty. For no-plan work, inspect only the named page, its shared layout, loaded global files, and project contracts.

Check response headers/middleware for CSP once, project-wide, and record the result in the plan or no-plan work update. No CSP found → record `no CSP`; this closes the question — skip this file's CSP rules and ask the dev nothing about CSP. CSP found → read `ui-shell/head.md` §CSP and record the required nonce (server-rendered) or hash (static host).

Inspect every globally loaded stylesheet for element selectors (`body`, `h1`, `a`, `input`, etc.). Treat each hit as affecting every NDS page served through that entry. Record the isolation in the plan or no-plan work update.

- **Repeated families:** map one archetype; keep sibling rows as `same as <archetype>`.
- **Prior NDS:** assess each page against current canon. Conformant → `Awaiting Verification`; non-conformant → prior NDS that needs a rebuild. Never silently resume an inherited plan.
- **Non-conformant prior NDS:** rebuild clean in place. Use old work only as a content, flow, and data reference. Never use it as a copy source. Remove its NDS footprint through the approved plan; rollback is git. The approval names the cost: unported pages use the new runtime before their rebuild and may render worse.
- **Second runtime:** only by explicit dev decision; use parallel files plus a second assets folder, accepting the two-runtime cost.
- Project-rule conflict → P5.

When the table requires a plan, create root `NDS-PLAN.md`. Start it with `Managed by NDS IQ`. Add columns for page, route, legacy libraries, NDS target, and status. Stop before building. Ask all project-wide decisions in ONE numbered review message. Include asset URL prefix, porting strategy, prior-NDS split, CSP grant (only when the sweep found a CSP), and pacing. Give options and a recommended default for each. Record answers in the plan. Defer page-specific questions to that page's build session. The plan records the answers, the conversation asks the questions — this holds for every question in every phase, not just this review.

**The plan is cross-session memory.**

- Statuses only: `Planned`, `In Progress`, `Awaiting Verification`, `Built and Verified`. Only dev confirmation sets `Built and Verified`; status lives only in the Status column.
- `Awaiting Verification` means every agent-owned check passed and its evidence is recorded. Any unmet required check keeps the row `In Progress` with an open checkbox.
- Every open question/check/fix/deferred decision is a `- [ ]` item; resolve as `- [x]`, never delete. Checkboxes are not page status.
- **Pacing:** `gate-by-gate` (default) or `whole plan`. Whole-plan mode uses file defaults, verifies each page, updates rows as pages complete, and leaves them `Awaiting Verification` until dev confirmation.
- When all rows are verified, retire the plan. A new multi-page effort or a dev-requested re-audit recreates it from current state: passing pages enter `Awaiting Verification`, drifted pages `Planned` with their deltas named.
- **No-plan work:** scope is one named page. State its source paths and open questions before work. The final report records verification evidence and unmet checks. If the dev waived a required plan, note the loss of cross-session memory once. In an existing non-NDS UI, the waiver permits one parallel NDS page. All Build and Verify gates still apply.
- Optional `NDS-REPORT.md` records NDS findings only: missing APIs/events, canon/rule/doc contradictions, reproducible bugs, or rule gaps. Include NDS version, instruction version, component, generic repro; never project markup/routes/data.

## Build

**Build entry gate.** Reopen the page's plan row when one exists. Before markup, record the work mode, selected archetype/template/example or custom case, built twin, and component sources. For no-plan work, state them before editing. Resolve every open source or path question before building.

**Chrome first, components second.** Build each required chrome shape once, then its pages. Shape references: `_source/examples/sign-in.md` / `registration.md` = minimal; `console-demo.md` = console.

1. **Head** — copy the head from `NDS_ROOT/_site/index.html` as a unit; use `ui-shell/head.html` as reference. Rewrite asset URLs only; do not remove/reorder entries. Keep `<title>` and hero preloads page-specific. Never add `nds-delegated.min.js` or `nds-extras.min.js` manually. Replace the favicon. Under CSP, authorize the head's inline script.
2. **Master layout** — copy the complete `<body>` from a built `_site/` page matching the required shape and swap the content; never recreate it from prose. Use `_source/layout/page-shell.md` for shapes/modifiers. Older templates: choose the matching built page by inspection and report the missing reference.
   - Layout-affecting modifiers (`nds-full-width`, `nds-wSideMenu`, and all `page-shell.md` modifiers) must exist in initial HTML. Route-dependent modifiers are set synchronously before framework mount, never in a mount effect.
   - Client-rendered apps mount the copied shell inside `#root`/equivalent with `display: contents` in project CSS.
   - Put copied runtime `<script defer>` tags at the end of `<body>`: `nds-main.min.js`, plus `nds-accessibility.min.js` when its panel remains.
   - Set both `<html lang>` and `dir`: Arabic → `ar`/`rtl`; others → `ltr`. With no locale mechanism, ship Arabic-first bilingual with the existing switcher.
3. **Brand** — put the project logo on `.nds-brand-logo`; remove its text span unless the logo is a bare mark. Then build inner components.

**Admin/console:** add `nds-full-width` to `<body>` and place the hero inside `.nds-main-content` beside the side menu (`console-demo.md`).

**Copied chrome ships as-is.** Chrome means the topbar, main navigation, footer, accessibility panel and its FAB, cookie popup, DGA stamp, and dark-mode toggle. Keep every self-contained piece; record removable items as plan checkboxes. Only the dev ticks them. Never infer affiliation.

Before page #2, wire project-backed controls to real session/API/route data. Remove controls the project cannot back; never ship fake identity or dead widgets.

### Composition cascade

Search `use_when` across `templates.yml`, `examples.yml`, and `components.yml`; match by `use_when`, never title.

1. Matching DGA template → copy `_source/templates/<name>.md`.
2. No template → closest `_source/examples/*.md`.
3. No match → custom scaffold inside hard rule #4, reusing canonical wiring patterns.

Whichever source matches, keep its structure and put the project's content into every part; never rebuild it. The source is a floor, not a ceiling: add the sections the project needs, matching their parts through the catalogs like any other part.

A page family's `Built and Verified` archetype outranks the cascade; siblings copy it and put their own entity content into every part.

At each page start, resolve its recorded questions, list every UI part, and match each against `components.yml`. Missing parts come from their canonical component; no match → custom case. A controls bar above a table/list/grid is the Toolbar component. P1 applies before claiming NDS lacks anything.

Before page JS, list every intended behavior and check the component catalogs/banners. If NDS ships the behavior, use its methods/events; do not rebuild it. Apply the same rule to core helpers (§JS wiring).

### Authority by concern

The existing UI means the screens being replaced, not a separate app or repository. The project frontend and backend are layers of the host project. These sources govern different decisions:

| Concern | Authority |
|---|---|
| Required content, fields, order, and business outcomes | Existing UI; the dev brief when no prior UI exists |
| Routes, views, client state, asset paths, and load order | Project frontend |
| APIs, authentication, permissions, validation, and data rules | Project backend |
| Shell, sections, component markup, classes, ARIA, `data-*`, and component interactions | NDS canonical sources |

A conflict between the existing UI and a backend contract is a dev decision. Report it and do not guess.

### UI defaults

**NDS UI outranks the legacy UI.** The table above gives the existing UI the content, fields, order and outcomes a page must carry. It never sets how that content is presented, and it never caps a component's feature set. A legacy page that lacked a control is a page missing a default, not a scope boundary.

Search, sorting, filtering, export, counts, validation chrome, and responsive behavior are NDS UI defaults, not questions to ask. They never authorize changes to business rules or backend contracts.

Hard rule #3 keeps every part a matched source ships. Map each one to the project's own data: a two-state field is a single-choice facet, a numeric field is a range. Legacy filtering by one thing is not a reason to ship one facet.

- Existing pages without heroes get `nds-sub`; heavy-text pages also get `nds-flat`. Hero sliders stay on home/hub pages.
- When required presentation differs, select a documented NDS variant first. The requirement never authorizes changes to canonical component anatomy.
- Forms default to TWO input steps: form + review. Add more input steps only when the flow requires them. A terminal confirmation step is not an input step — keep the success step your matched source ships.
- Greenfield work uses the dev brief. In greenfield only, remove a template section the brief does not cover; never invent content to fill one.

**Copy rendered markup when source markup is generated.** Do not copy Liquid tags. For front-matter-generated regions or page wrappers, copy the built twin's rendered HTML/full `<body>`.

**Replacing a legacy library:** name the capability, search the catalogs, compose NDS components if needed, and port callbacks through NDS methods/events. Truly uncovered → vanilla inside hard rule #4; never reintroduce the legacy library for one widget.

**Build exit gate.** Before §Verify:

- Name the canonical page source, built twin, and component sources used.
- Confirm every page part and intended behavior was matched through the catalogs and banners.
- List the matched source's facets, controls and columns beside the page's. Equal counts, or each difference named.
- Confirm structural changes fit hard rule #3's four sanctioned edits.
- Check every `nds-hgi-*` token in page HTML and JS against `icons.yml`. Other glyphs use `<i class="hgi hgi-stroke hgi-<name>">` from `_source/_sass/_hgiRoundedStroke.scss`.
- Under strict `style-src`, grep the page for `style="` and convert every canonical inline knob through hard rule #3's CSP edit.

Record the evidence under the plan row. For no-plan work, carry it into the final report. Any unmet check stays open. A plan row stays `In Progress`; no-plan work remains unverified.

## JS wiring

**Use NDS APIs before direct DOM wiring.** Before adding listeners to `.nds-*` elements or writing NDS-owned `data-*`, read the component banner in `_source/_js/nds-<name>.js`:

- **Rides** — base component/inherited surface.
- **Methods** — public calls.
- **Events** — dispatched events and `detail`.
- **Hooks** — owned `data-*` / action roles.
- **Gotchas** — required traps/constraints.

Before hand-writing fetch, debounce, resize, or state/status DOM logic, read `nds-core.js` for `NDS.request`, `NDS.State`/`NDS.Status`, `NDS.lang`/`NDS.isRTL`/`NDS.breakpoints`, `NDS.debounce`, `NDS.i18n.load`.

Every request needs a visible failure path through the form/component status or an alert; exercise it during verification.

If NDS has no needed surface, direct code is allowed; comment what was checked and create/add the finding to `NDS-REPORT.md`.

- After dynamic DOM changes, prefer `NDS.<Component>.reinit()`; check the banner because component lifecycle APIs differ.
- Lazy namespace existence proves nothing; use the banner/grep to confirm methods.
- Copied template/example page JS is canonical and follows hard rule #3.
- Data scale: follow the existing API shape. An endpoint that returns the full set → fetch once and use client-side table/filter/sort/export. An endpoint that pages/sorts/filters server-side → wire the NDS controls to those parameters. Shape does not fit the data size (a huge set in one payload, a tiny set behind paging) → report it; backend changes are the dev's.

## Verify

**Verify entry gate.** Confirm the §Build exit evidence is recorded. Reopen the matching built twin before the browser passes.

Never verify from code inspection. A page needs both browser passes:

- **Behavioral:** load it, run `NDS.Init.audit()`, inspect NDS warnings, and exercise wired behavior including one request failure path. Also check every `nds-hgi-*` token in the page HTML and its page JS against `_source/_data/content/icons.yml`: `NDS.Init.audit()` does not see icon names inside JS strings. Submit every required field type empty, one by one: the types share one required mark but each validates through different code, so one passing field proves nothing about the next. During active work, `window.NDSInitConfig = { enableLogging: true }` may be set before NDS scripts.
- **Visual:** serve `NDS_ROOT/_site` over HTTP (a quick static server — never `file://`, which floods the console with false errors) and compare your page against the matching built page at desktop and mobile widths. **The built twin is the visual spec:** a difference you chose is a content swap; a difference you didn't is a bug. Also inspect spacing, icons, width/sticky behavior, dark mode, and overall coherence. Measurements alone are not visual verification.

**Drive both passes headlessly** with a browser your own tool loop can control. Use tooling available in the environment or project. Keep temporary tooling outside the project and never change its lockfile. Behavioral proof is the console plus audit. Visual proof is screenshots you inspect at desktop and mobile widths.

**Set the viewport, never the window.** OS window minimums can clamp small widths while screenshots still crop to the requested size. This creates a false responsive failure. Use Puppeteer `page.setViewport()`, a Playwright context `viewport`, or CDP `Emulation.setDeviceMetricsOverride`. Never use `--window-size` or browser-window resize as viewport proof. No CDP-capable tool at hand? Set one up: `puppeteer-core` or Playwright in a scratch folder outside the project, pointed at the installed Chrome, is the default mobile path. Declare the viewport unmet only after that attempt fails. Before trusting a screenshot, read `window.innerWidth`; it must equal the target. A mismatch means the viewport is wrong, not the page; the pass remains unmet.

Claim "cannot see the page" only after the headless attempt fails. Report the failure. An unreachable viewport remains unmet.

If the attempt fails, use the first available fallback and report what remains unverified:

1. Existing browser tool/harness, including authenticated sessions. Any unreachable viewport remains unmet.
2. Smoke check: `curl -sI` for status/CSP; `curl -s` for intact head/scripts, server errors, and forbidden inline styles under strict CSP.
3. Dev checklist:

   [VERIFICATION CHECKLIST FOR DEV]
   - [ ] Check console for `NDS`-prefixed warnings.
   - [ ] Test responsiveness below 768px.
   - [ ] Check expected spacing.
   - [ ] Check every icon renders as a glyph.
   - [ ] Check dark mode on page content.

Under strict `style-src`, confirm §Build's `style=` grep ran on this page; run it if not.

**Verify exit gate.** Record this evidence under the page's plan row, or in the final report for no-plan work:

- `NDS.Init.audit()` result, exercised behavior, and the request failure-path result.
- Built twin used and the inspected desktop screenshot.
- Mobile target width, equal `window.innerWidth`, and the inspected mobile screenshot.
- Icon, dark-mode, and strict-CSP results that apply to the page.
- Every unmet item, if any.

Every required item must be complete. An unmet item keeps a plan row `In Progress`; no-plan work reports the page as unverified. After all agent-owned checks pass, a plan row may move to `Awaiting Verification`. No-plan work reports that it awaits dev confirmation. Only dev confirmation makes the page `Built and Verified`.

## Upgrading NDS

An explicit upgrade request is approval. Download latest and replace `NDS_ROOT` exactly as §Install; prior-rules work takes §Plan conformance first.

For an update check, compare the runtime banner with the latest release and report relevant changelog changes; upgrade only on dev approval.

For rules updates, compare raw main `NDS-IQ.md` content with the project-root copy. Any difference means a newer revision; install only on dev approval. An explicit update request runs step 4 directly.

Use absolute paths for writes; never `cd` into `NDS_ROOT`/`NDS_ASSETS`. After each write, inspect the destination.

1. **Compare versions** — opening `Version:` banners in `NDS_ROOT/_site/assets/js/nds-main.min.js` and `NDS_ASSETS/js/nds-main.min.js`.
2. **Replace runtime** — copy new `_site/assets/` over `NDS_ASSETS`; preserve project `img/favicon.svg`. Keep project-added files; deletions require dev approval.
3. **Sweep pages** — read every `### Migrating from` section in `CHANGELOG.md` between the two banners; add affected work to `NDS-PLAN.md`, map it to pages, execute, and report. Also report useful `Added` / `Changed` / `Fixed` items for dev choice.
4. **Update this file** — download raw main `NDS-IQ.md` with curl/the stack HTTP client, not a web-fetch tool. Accept only if line 1 starts `# NDS IQ`; otherwise discard and retry once — a second failure is reported and the installed copy stays. Replace the project-root copy whole — no merging, anchor untouched — then reread the file before continuing.

## Install and upgrade this file

NDS IQ has two pieces:

1. **`NDS-IQ.md`** at project root, committed and replaced whole on update. Source: `https://raw.githubusercontent.com/mazin-musleh/NDS-vanilla/refs/heads/main/_includes/NDS-IQ.md`.
2. **Anchor** in `CLAUDE.md` / `AGENTS.md`: the only project-specific path values plus the read trigger. Install once.

Use this anchor, setting `NDS_ASSETS` to the project's real static root:

```markdown
## NDS — National Design System (UI layer)

- `NDS_ROOT` = `.nds/`
- `NDS_ASSETS` = `/path/to/your-project/public/assets/`

All UI in this project is built with NDS. Before any UI, page, component, styling,
or asset work — or when unsure whether a task touches NDS — read `NDS-IQ.md` at this
project's root, top to bottom, once per session. Do no NDS work before that read.
A compacted or summarized context starts a new session: read the file again before
more NDS work.
If the file is missing, stop and ask the dev.

These hold even before the read:
- Never edit anything under `NDS_ROOT`; never hand-edit NDS files in `NDS_ASSETS`.
- Never write `.nds-*` markup from memory — copy from the sources `NDS-IQ.md` names.
```

**Anchor update:** if the compacted-context sentence is missing, add it exactly; change nothing else.

**First install:** download raw `NDS-IQ.md` to project root; add the anchor with `NDS_ROOT=.nds/` and the real `NDS_ASSETS` path; commit both; then run §Plan inventory and create `NDS-PLAN.md`.

**Migrating from pasted instructions (v6 and earlier):** install this file + anchor, carry over the two path values, delete the old pasted instruction block — everything from its `## Design system: NDS Vanilla` heading through its `<!-- end NDS instructions -->` marker — then run §Plan conformance as prior NDS work.

**Update:** use §Upgrading NDS step 4.

Feeding the Next Revision

Real adoption findings feed future revisions. Record verified NDS gaps, misleading documentation, or reproducible bugs in the optional NDS-REPORT.md. The report is designed to contain no project-private information.

Send verified findings to GitHub Issues. They can become a rule or source fix in a later revision.