{ "id": "nord-design-system", "name": "Nord Design System", "org": "Nordhealth", "category": "design-system", "docs_url": "https://nordhealth.design", "repo_url": "https://github.com/nordhealth/design-system", "license": "Proprietary (\"SEE LICENSE IN LICENSE.md\"); npm packages published publicly under @nordhealth/*", "summary": "Nord is Nordhealth’s healthcare (veterinary/therapy) design system: 156+ Lit-based `` web components, CSS custom-property tokens, Tailwind CSS v4 integration with an `n:` variant prefix, two brands with dark and high-contrast variants. Its AI story is entirely consumption-side and unusually current for July 2026: a dedicated /ai/ section, /llms.txt plus a ~1M-token /llms-full.txt, a `/raw/.md` markdown twin for every docs page, and, the standout here, two officially published Agent Skills served from a `/.well-known/skills/` discovery endpoint following the Cloudflare Agent Skills Discovery RFC, installable with `npx skills add https://nordhealth.design`. The building side is invisible: the source repo is explicitly private, so no CLAUDE.md/AGENTS.md/cursor rules are observable, and the promised MCP server is still roadmap, not shipped.", "ai_maturity": "invested", "maintenance": { "actively_maintained": true, "last_release": "@nordhealth/components 5.0.3 — published 2026-07-13", "activity_note": "Very active. Major 5.0.0 line shipped July 2026 alongside a docs relaunch (“18 New Components, 56 Component Parts, and a Redesigned Docs Website”, 2026-07-06). All eight @nordhealth/* packages (components 5.0.3, css 5.2.3, themes 10.0.3, tokens 9.0.3, icons 3.17.2, color 3.0.21, fonts 3.0.4, ag-theme-nord 3.0.22) republished in the same 2026-07-13 batch. Three public updates in 2026: Nuxt docs rewrite (Feb), Storybook 10 playground (Mar), component release (Jul). @nordhealth/eslint-plugin at 1.1.2." }, "affordances": [ { "type": "claude-skill", "name": "Nord Agent Skills (`nord` and `nord-full`) served from /.well-known/skills/", "official": true, "audience": "consumers", "docs_url": "https://nordhealth.design/docs/developer/working-with-ai/skills/", "code_url": "https://nordhealth.design/.well-known/skills/", "description": "Two officially published agent skills served over HTTP from the docs domain, discoverable via a JSON manifest at /.well-known/skills/ and installable with `npx skills add https://nordhealth.design`. `nord` is the lean tier (87 files: SKILL.md + one reference markdown per component + migration guides); `nord-full` is the complete tier (152 files: adds tokens, CSS/Tailwind, themes, accessibility checklist, changelogs, design foundations, contributing, updates). Follows the Cloudflare Agent Skills Discovery RFC, which Nord explicitly cites; the third-party `npx skills` CLI (vercel-labs/skills) fans the same skill out to Claude Code, Cursor, Codex CLI, GitHub Copilot, Windsurf, Cline, Aider, Continue and ~40 other agents from one source of truth.", "notes": "The most notable thing Nord has built. It replaces per-editor rule files (.cursorrules, copilot-instructions.md, CLAUDE.md) with one host-served skill. Nord ships zero editor-specific rule templates and does not need to. Verified bug: the `nord` tier’s SKILL.md links to references/tokens.md, references/themes.md, references/accessibility-checklist.md and references/css/eslint.md, all of which return 404, because those files exist only in the `nord-full` manifest.", "snippet": { "content": "---\nname: nord\ndescription: Nord Design System — accessible Lit web components, design tokens, and Tailwind CSS theming. Use when working with `` components, design tokens, forms, or layouts.\nmetadata:\n author: Nordhealth\n---\n\nNord Design System provides 156+ accessible, production-ready Lit web components (`` prefix), design tokens (CSS custom properties), Tailwind CSS v4 integration, two brands (therapy/veterinary) with dark mode and high-contrast variants. Framework-agnostic — works with React, Vue, Angular, Svelte, plain HTML.\n\n## Components\n\n| Component | Description | Reference |\n| ----------------------- | ------------------------------------- | -------------------------------------- |\n| Web Components Overview | All component APIs, slots, and events | [components](references/components.md) |\n| nord-accordion | Accordion is a set of collapsible sections, each with a header that toggles the visibility of its content. | [accordion](references/components/accordion.md) |", "language": "markdown", "source_url": "https://nordhealth.design/.well-known/skills/nord/SKILL.md" } }, { "type": "registry", "name": "/.well-known/skills/ discovery manifest", "official": true, "audience": "consumers", "code_url": "https://nordhealth.design/.well-known/skills/", "description": "Machine-readable JSON manifest at the well-known endpoint enumerating available skills and every file each contains, which is what `npx skills add https://nordhealth.design` reads. Effectively a component registry for agents: 87 file paths for `nord`, 152 for `nord-full`, one markdown reference per component.", "snippet": { "content": "{\n \"skills\": [\n {\n \"name\": \"nord\",\n \"description\": \"Build UIs with Nord Design System — accessible Lit web components, design tokens, and Tailwind CSS theming.\",\n \"files\": [\n \"SKILL.md\",\n \"references/components.md\",\n \"references/components/accordion.md\",\n \"references/components/aside-drawer.md\",\n \"references/components/aside-trigger.md\",\n \"references/components/aside.md\",\n \"references/components/autocomplete.md\",\n \"references/components/avatar.md\",", "language": "json", "source_url": "https://nordhealth.design/.well-known/skills/" } }, { "type": "llms-txt", "name": "/llms.txt and /llms-full.txt (two-tier, context-budget aware)", "official": true, "audience": "consumers", "docs_url": "https://nordhealth.design/docs/developer/working-with-ai/llms-txt/", "code_url": "https://nordhealth.design/llms.txt", "description": "/llms.txt (~19 KB, advertised ~5K tokens) is a curated index: a one-line system description then a link per component/guideline pointing at that page’s raw markdown twin. /llms-full.txt is ~997 KB of fully inlined documentation (Nord advertises ~1M+ tokens). The docs page explicitly routes users between the two by context-window size and warns that pasting the `@` symbol into Cursor/Windsurf breaks docs referencing.", "notes": "Nord’s llms.txt is a routing index rather than a dump: every entry links to https://nordhealth.design/raw/.md, so an agent can pull only the components it needs.", "snippet": { "content": "> [!NOTE]\n> **Most users should start with `/llms.txt`** - it contains all essential information and works with standard LLM context windows. Use `/llms-full.txt` only if you need comprehensive implementation examples and your AI tool supports large contexts (200K+ tokens).\n\n## Important usage notes\n\n> [!WARNING]\n> **@-symbol must be typed manually** - When using tools like Cursor or Windsurf, the `@` symbol must be typed by hand in the chat interface. Copy-pasting breaks the tool's ability to recognize it as a context reference.", "language": "markdown", "source_url": "https://nordhealth.design/raw/docs/developer/working-with-ai/llms-txt.md" } }, { "type": "ai-docs-page", "name": "Working with AI docs section (/ai/ → /docs/developer/working-with-ai)", "official": true, "audience": "consumers", "docs_url": "https://nordhealth.design/docs/developer/working-with-ai", "description": "The vanity URL https://nordhealth.design/ai/ serves a meta-refresh to /docs/developer/working-with-ai, a hub with two children (LLMs.txt, Agent Skills). Names Claude, ChatGPT, Cursor and Windsurf explicitly and frames the value as accurate, up-to-date context: structured component info, usage examples, token references, best practices.", "snippet": { "content": "# Working with AI\n\n*Nord Design System provides AI-friendly integrations that enable AI assistants and tools to understand and work with our components, design tokens, and documentation.*\n\n## Available Integrations\n\nUse these integrations to enhance your AI-assisted development workflow with Nord Design System.\n\n**[LLMs.txt](/docs/developer/working-with-ai/llms-txt/)** - Structured documentation for LLMs\n\n**[Agent Skills](/docs/developer/working-with-ai/skills/)** - Install Nord skills for AI coding agents\n\n## Why AI Integration?\n\nAI assistants like Claude, ChatGPT, Cursor, and Windsurf can help you build faster with Nord Design System when they have access to accurate, up-to-date documentation.", "language": "markdown", "source_url": "https://nordhealth.design/raw/docs/developer/working-with-ai.md" } }, { "type": "other", "name": "/raw/.md — a markdown twin for every docs page", "official": true, "audience": "consumers", "code_url": "https://nordhealth.design/raw/components/button.md", "description": "Every page on the Nuxt docs site is also served as clean markdown at https://nordhealth.design/raw/.md (verified 200 for docs/developer.md, components/button.md, docs/developer/web-components.md, resources/contributing.md, design/foundations/figma.md). This is what llms.txt links to and what the skills’ reference files are generated from, so agents fetch precise per-component context without scraping HTML.", "notes": "Caveat: non-existent /raw paths return the Nuxt SPA shell with a 404 status but HTML body, so agents must check content type, not just status." }, { "type": "storybook-integration", "name": "Storybook 10 playground embedded on every component page", "official": true, "audience": "both", "docs_url": "https://nordhealth.design/storybook/", "description": "Since March 2026 every component page embeds a Storybook 10 Playground story with the controls panel open; a standalone Storybook is served at /storybook/ (verified 200). Stories are the single source for docs examples, testing and Storybook itself; auto-generated property tables come from the custom elements manifest; every story has an ‘Open in CodePen’ export emitting working HTML plus correct CDN links. Roadmap: visual regression testing and design token docs in Storybook.", "notes": "Not AI-specific, but the custom-elements-manifest → generated API tables → skill reference markdown pipeline is what makes the agent-facing docs cheap to keep accurate." }, { "type": "other", "name": "@nordhealth/eslint-plugin — auto-fixable legacy-class codemod", "official": true, "audience": "consumers", "docs_url": "https://nordhealth.design/docs/developer/eslint/", "code_url": "https://www.npmjs.com/package/@nordhealth/eslint-plugin", "description": "v1.1.2 (2026-07-13). Ships `recommended` and `vue` presets bundling eslint-plugin-better-tailwindcss, plus an auto-fixable `@nordhealth/no-legacy-classes` rule that migrates legacy `n-*` classes to Tailwind v4 equivalents, gated by category (spacing, borders, typography, colors, layout, components, utilities). Off by default in the recommended config; opted into for the duration of a migration. The only machine-checkable enforcement loop Nord offers, and it is never framed for agents.", "notes": "Deterministic codemod, not AI-assisted. The obvious missing move is telling the agent skill to run `eslint --fix` as a verification loop; SKILL.md does not." } ], "techniques": [ { "name": "Host-served skill via well-known discovery instead of per-editor rule files", "category": "instruction-files", "description": "Rather than publishing .cursorrules / copilot-instructions.md / CLAUDE.md templates for consumers to copy (and let rot), Nord serves the skill from its own domain at /.well-known/skills/ and lets the `npx skills` CLI translate it into whatever format each agent expects. One install command covers ~40 agents, and Nord can update the skill server-side with no consumer action. The single most transferable technique in Nord’s setup.", "snippet": { "content": "## Installation\n\nInstall the Nord skill using the `npx skills` CLI:\n\n```bash\nnpx skills add https://nordhealth.design\n```\n\nThis fetches the skill from our well-known discovery endpoint and adds it to your project.\n\n## What the skill provides\n\nThe Nord skill gives your AI agent:\n\n- **Component guidance** — how to use all 55+ `` web components correctly\n- **Design tokens** — CSS custom property naming (`--n-color-*`, `--n-space-*`)\n- **Styling approach** — Tailwind CSS v4 with `n:` variant prefix\n- **Theming** — therapy/veterinary brands, dark mode, high contrast\n- **Forms** — native form participation, validation patterns\n- **Accessibility** — built-in ARIA, keyboard nav, screen reader support\n- **Do/Don't rules** — common mistakes to avoid\n- **Documentation index** — links to raw markdown for every component and guideline page", "language": "markdown", "source_url": "https://nordhealth.design/raw/docs/developer/working-with-ai/skills.md" } }, { "name": "SKILL.md as a pure routing table (progressive disclosure, no inlined rules)", "category": "curated-context", "description": "Nord’s SKILL.md contains essentially no prose rules: ~218 lines of markdown tables mapping every component and guideline to a `references/*.md` path, preceded by a two-sentence system description. All behavioural constraint lives one hop away in the per-component reference files, keeping the always-loaded context ~32 KB while the agent pulls only what it touches. Grepping the whole `nord` SKILL.md for ‘never’, “don’t”, ‘always’ or ‘avoid’ returns zero rule hits. That is deliberate, but it means the top-level skill exerts no direct pressure beyond naming the `` prefix.", "snippet": { "content": "## Design Tokens\n\n| Topic | Description | Reference |\n| ------------- | ---------------------------------------------------------------- | ------------------------------ |\n| Design Tokens | CSS custom properties for colour, spacing, typography, elevation | [tokens](references/tokens.md) |\n\n## CSS Framework\n\n| Topic | Description | Reference |\n| ------------- | -------------------------------------------------------------- | ------------------------------------------ |\n| CSS Overview | Nord CSS framework, utility classes, reset styles | [css](references/css.md) |\n| Tailwind CSS | Tailwind CSS v4 integration, `n:` variant prefix, theme config | [css/tailwind](references/css/tailwind.md) |\n| ESLint Plugin | Linting rules for Nord CSS conventions | [css/eslint](references/css/eslint.md) |", "language": "markdown", "source_url": "https://nordhealth.design/.well-known/skills/nord/SKILL.md" } }, { "name": "Per-component Do/Don’t blocks that route the model to the correct sibling component", "category": "prohibition", "description": "Every component reference file opens with a `> **Do:**` / `> **Don't:**` pair. The prohibitions are unusually well targeted at LLM failure modes: they name the component the model should have reached for instead ('Don’t use for a single disclosure of content, use Collapsible instead’; 'Don’t use when the value must be one of a fixed set of options, see Combobox instead’), and they call out the accessibility attribute an agent typically omits ('Don’t omit `label` — the rail button has no visible text, so the accessible name comes from this attribute’). This is the real coercion surface, and it ships verbatim into the skill.", "snippet": { "content": "> **Do:** - Only use one primary button per section, as a main call-to-action.\n- Use clear and accurate labels.\n- Use established button colors appropriately. For example, only use a danger button style for an action that's difficult or impossible to undo.\n- Prioritize the most important actions. Too many buttons will cause confusion.\n- Be consistent with positioning of buttons in the user interface.\n- Use strong, actionable verbs in labels such as \"Add\", \"Close\", \"Cancel\", or \"Save\".\n\n> **Don't:** - Don't use a primary button in every row of a table.\n- Don't use buttons to link to other pages. Use regular link or a plain style instead where necessary.\n- Don't use buttons for navigation where the link appears within or following a sentence.\n- Don't use labels such as \"Read more\", \"Click here\" or \"More\".", "language": "markdown", "source_url": "https://nordhealth.design/.well-known/skills/nord/references/components/button.md" } }, { "name": "Private-API prohibition: component properties over CSS custom properties, never `--_n-*`", "category": "token-enforcement", "description": "The strongest single constraint in the corpus, a WARNING callout in the Web Components guide (inherited by nord-full’s references/docs/developer/web-components.md). It establishes an API hierarchy the model must respect: component properties first, public custom properties second, the `--_n-` private tier explicitly off-limits. Transferable pattern: give the private tier a visually distinct prefix so a model can pattern-match the prohibition instead of memorising a list.", "snippet": { "content": "> [!WARNING]\n> Always use a component's properties over a CSS custom property wherever possible. CSS Custom properties are built with a counterpart \"private\" property, prefixed with \n> `\n> --_n-\n> `\n> . Please refrain from using private properties as they are always subject to change and intended for internal component use only.", "language": "markdown", "source_url": "https://nordhealth.design/raw/docs/developer/web-components.md" } }, { "name": "Two-tier skill packaging keyed to context budget", "category": "curated-context", "description": "Nord ships `nord` (87 files, components and migrations only) and `nord-full` (152 files, adding tokens, CSS/Tailwind, themes, accessibility checklist, changelogs, design foundations, even contributing and updates pages), mirroring the /llms.txt vs /llms-full.txt split. The same discipline applied twice: publish a lean default and an exhaustive opt-in. Outside the manifest itself, only the lean tier is advertised: the Agent Skills page documents `npx skills add https://nordhealth.design` and nothing else, and neither /llms.txt nor the 997KB /llms-full.txt names `nord-full`.", "snippet": { "language": "json", "source_url": "https://nordhealth.design/.well-known/skills/", "content": " \"references/migrations/figma-4.0.0.md\",\n \"references/migrations/tailwind.md\"\n ]\n },\n {\n \"name\": \"nord-full\",\n \"description\": \"Nord Design System — comprehensive documentation including all components, design guidelines, tokens, CSS, and migration guides.\",\n \"files\": [\n \"SKILL.md\",\n \"references/changelogs.md\",\n \"references/changelogs/color.md\",\n \"references/changelogs/css.md\",\n \"references/changelogs/eslint-plugin.md\",\n \"references/changelogs/figma.md\"," } }, { "name": "Auto-fixable codemod rule as a migration lever (deterministic, not AI)", "category": "validation-loop", "description": "`@nordhealth/no-legacy-classes` ships in the recommended config but disabled by default; consumers enable it, optionally scoped to categories, run `eslint --fix`, then turn it off. A genuine machine-checked convergence loop toward Tailwind v4 + Nord tokens, but framed as a human migration tool, never wired into the skill as something the agent must run.", "snippet": { "content": "The migration rules are included in the recommended config but **off by default**. Enable them during migration:\n\n```javascript\n// eslint.config.mjs\nimport nordPlugin from '@nordhealth/eslint-plugin'\n\nexport default [\n nordPlugin.configs.recommended,\n {\n rules: {\n // Enable migration rules - disable after migration is complete\n '@nordhealth/no-legacy-classes': 'warn'\n }\n }\n]\n```\n\n### Running the fix\n\nOnce configured, run ESLint with the `--fix` flag to automatically migrate classes:\n\n```bash\npnpm eslint --fix \"src/**/*.{ts,tsx,vue,html}\"\n```", "language": "markdown", "source_url": "https://nordhealth.design/llms-full.txt" } } ], "platform_integrations": [ { "platform": "storybook", "url": "https://nordhealth.design/storybook/", "description": "Storybook 10, launched March 2026. Playground story embedded as the default example on every component page with controls open; standalone Storybook at /storybook/ (verified 200). Theme switcher (therapy/veterinary, light/dark/high-contrast), viewport tool, a11y audit panel, ‘Open in CodePen’ export on every story. Auto-generated property tables from the custom elements manifest. Stated roadmap: visual regression testing, design token docs in Storybook." }, { "platform": "figma", "url": "https://nordhealth.design/design/foundations/figma/", "description": "Nord Figma Toolkit v4 plus Nordicons and Brand Elements, distributed as Figma Team Libraries gated to Nordhealth email accounts and approved external partners. Variables (tokens) plus text/shadow/grid styles published. Nordhealth also maintains a public Figma plugin, github.com/nordhealth/themer, for swapping between identically-named styles across published libraries. No Figma Code Connect and no Dev Mode MCP integration anywhere in the docs or llms-full.txt (grep for ‘code connect’, ‘dev mode’, ‘figma mcp’ returns nothing)." }, { "platform": "other", "url": "https://nordhealth.design", "description": "Docs are self-built on Nuxt 4 / @nuxt/content v3 / Tailwind v4, ~2000 prerendered routes, deployed to GitHub Pages (Feb 2026 rewrite). No Supernova, Knapsack or zeroheight involvement; Nord runs its own docs platform, which is exactly what let it add /raw/*.md twins, /llms.txt and the /.well-known/skills/ endpoint as first-class server routes." } ], "building_vs_consumption": { "for_consumers": "Strong and current. An agent building product UI with Nord has four escalating options: (1) install the official skill with one command, `npx skills add https://nordhealth.design`, landing the same content in Claude Code, Cursor, Codex, Copilot, Windsurf, Cline, Aider and ~40 others via the Cloudflare Agent Skills Discovery RFC; (2) point at /llms.txt as a ~5K-token routing index; (3) fetch /llms-full.txt for the whole ~1M-token corpus; (4) fetch any single page’s markdown twin at /raw/.md. The per-component Do/Don’t blocks are the real behavioural constraint and they are good: they name the correct alternative component and the accessibility attribute agents usually drop. Weak spots: no MCP server (roadmapped only), no Figma Code Connect, no CLI scaffolding of Nord’s own, no ‘Add to Cursor’ button, no few-shot exemplar app wired to the skill, and the ESLint plugin is never presented to the agent as a verification loop it must run.", "for_builders": "Effectively unobservable, and that is the finding. github.com/nordhealth/design-system is private, and the contributing page says so outright: ‘Nord GitHub Repository — Our private repository, not for public use.’ github.com/NordhealthDesign/nord (the frequently cited claim) does not exist; that org returns 404 from the GitHub API. Probing the public nordhealth org’s related repos (react-example-project, vue-example-project, advanced-table-examples, adele) turns up no AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md or .claude/ at any root. The publicly documented contribution model is entirely human: proposal, kick-off, pairing, review, publish, with Zalando-style light/medium/heavy weighting, and it mentions no AI assistance, AI-assisted codemods, or review bots. The only maintenance-side automation visible is the deterministic @nordhealth/eslint-plugin codemod and a public code-review-rotation script. Whether the Nord team uses Claude Code or Cursor internally cannot be determined from public sources." }, "gaps": "1) MCP server: announced as a roadmap item in the Feb 2026 Nuxt docs rewrite post: ‘**MCP server** for connecting Nord Design System directly to AI-powered development tools’ under 'What’s next’, listed alongside ‘AI skills’ which HAS since shipped. As of 2026-07-27 no MCP endpoint exists: /mcp and /.well-known/mcp.json return the SPA shell / 404, and npm has no @nordhealth/mcp, @nordhealth/mcp-server or nord-mcp. No community Nord MCP server found either. 2) Broken skill references (verified bug): the lean `nord` skill’s SKILL.md tables link to references/tokens.md, references/themes.md, references/accessibility-checklist.md, references/css.md, references/css/tailwind.md and references/css/eslint.md, but the /.well-known/skills/ manifest lists only 87 files for `nord` (SKILL.md + components + migrations) and all four probed paths return 404. An agent following the SKILL.md’s token or Tailwind links gets nothing; only `nord-full` (152 files, under references/core/ and references/design/) resolves. 3) Builder-side AI practice is unverifiable because the source repo is private. That is absence of evidence, not evidence of absence. 4) No Figma Code Connect, no Dev Mode MCP, no distributed editor-rule templates, no ‘Add to Cursor’ install button, no Nord-authored CLI (`npx skills` is a third-party CLI from vercel-labs). 5) Inconsistent component counts an agent may repeat: the skills docs page says '55+ `` web components’, SKILL.md says ‘156+’, and the runtime custom-element list carries ~150 tags.", "sources": [ "https://nordhealth.design/ai/", "https://nordhealth.design/raw/docs/developer/working-with-ai.md", "https://nordhealth.design/raw/docs/developer/working-with-ai/skills.md", "https://nordhealth.design/raw/docs/developer/working-with-ai/llms-txt.md", "https://nordhealth.design/llms.txt", "https://nordhealth.design/llms-full.txt", "https://nordhealth.design/.well-known/skills/", "https://nordhealth.design/.well-known/skills/nord/SKILL.md", "https://nordhealth.design/.well-known/skills/nord-full/SKILL.md", "https://nordhealth.design/.well-known/skills/nord/references/components/button.md", "https://nordhealth.design/raw/docs/developer/web-components.md", "https://nordhealth.design/raw/resources/contributing.md", "https://nordhealth.design/raw/design/foundations/figma.md", "https://nordhealth.design/storybook/", "https://www.npmjs.com/package/@nordhealth/components" ] }