Overview

nadesign is short for Nexus Application Design (na) — the global design contract for every Nexus Agentic app (Admin, Chat, CRM, Account, User Management) and every future app that ships on our stack. Every package in this repo is published under the @na/* namespace (@na/ui, @na/tokens, @na/icons).

This is not a suggestion. If a screen violates these rules, the screen is wrong.

How to use this spec

Read in order the first time. After that, treat it as reference.

Doc	What it tells you	When you need it
01-principles.md	Why we make the decisions we make	Disagreement about approach; reviewing a new pattern
02-foundations.md	Color, type, spacing, motion, density, latency, breakpoints, icons	Any visual decision
03-layout.md	Shell, page anatomy, named page archetypes, templates	Building a new page
04-components.md	Every `@na/ui` component — when to use, when not	Picking the right primitive
05-patterns.md	Global rules: feedback, nav, data entry, data display, buttons, lists, empty states	Recurring UI problem
06-flows.md	Canonical flows: CRUD, auth, onboarding, bulk, wizard	Designing a multi-step task
07-voice.md	Copywriting, microcopy, vocabulary glossary, tone per surface	Writing any user-facing string
08-accessibility.md	Keyboard contract, focus, ARIA, contrast, SR	Every interactive element
09-i18n-testing.md	i18n conventions, test conventions, testid strategy	Any translated string, any component test
10-review-checklist.md	The scan list for authors (self-review), reviewers (peer review), and AI code reviewers	Before requesting review; during review; every PR
11-templates-catalog.md	Use-case-indexed catalog of every screen template + master decision tree + per-route map for nx-agent	Choosing the right template for a new surface
12-cross-cutting-patterns.md	Concurrent-edit conflict resolution, recovery (offline/crash/stale), cross-tab sync, bulk-action confirmation matrix, frontend idempotency	Multi-user / multi-tab / unreliable-network scenarios
13-section-anatomy.md	The inside of a template: per-template area tables (what each area is for, what it must contain) + canonical row patterns (15 settings rows, list rows, RightPanel rows, toolbar rows, activity entries)	Building a screen — after you’ve picked a template, this tells you what each section needs

Reference material

Companion docs under references/. Read these for deep patterns and when-to-use decisions. They inform (and sometimes override) the in-spec chapters during the Attio layout migration.

Doc	What it tells you	When you need it
references/attio-design-language.md	Live-inspected Attio tokens, 5 archetypes, card-vs-flat rule, spacing, interaction timings	Writing UI that must match Attio’s visual language
references/attio-layout-patterns.md	Deep anatomy of Attio’s layout patterns: collection views, view switcher, detail layouts (split/tabbed/drawer), right-panel, inbox, hover card, slash menu, command palette, filter chips, flat sections	Building a net-new pattern; reviewing a PR that introduces one
references/attio-layout-decision-guide.md	One-page decision trees + per-screen mapping for every nx-agent route	Open this before building any new screen

Influences

This spec fuses two design-system lineages. We copy what’s proven; we don’t pretend to invent philosophy.

Linear (linear.app/method, linear.app/readme) — craft as product, opinionated defaults, keyboard-first, density, speed as a spec not a vibe, one canonical name per concept.
Ant Design (ant.design/docs/spec/*) — coverage rigor, named page archetypes, applied principles citing UX laws (Fitts, Cooper, Gestalt, Norman, Newton), copywriting treated as a chapter not an afterthought, 8px ladder, dual color system.

Where the two conflict we bias Linear for opinion and Ant for coverage.

Scope boundaries

In scope	Out of scope
Visual, interaction, copy, motion, keyboard, accessibility	Backend, data modeling, DB migrations
Component do/don’t, patterns, flows	Deploy/CI/build infrastructure
Admin, Chat, CRM, Account, User Mgmt, embed widget	External marketing site
Shared `@na/ui` + `@na/shell`	App-local business logic

Ownership and change

Owners: Design + frontend leads. Changes require a review that justifies the new rule against the existing one (see “restraint rule” in 01-principles.md).
Who reads it: every engineer shipping UI, every AI agent writing UI code (loaded via .claude/rules/design-system.md), every designer making screens.
Versioning: changes are commits on dev-v2 with a clear message (docs(design-system): ...). Breaking rule changes call out which screens need updating.

Where this lives in the repo

docs/design-system/        # this spec (13 files)
.claude/rules/design-system.md   # auto-loads when editing *.tsx, *.css
AGENTS.md                  # short rules inline, links out for depth
packages/ui/src/components/*.tsx # the enforced primitives

If you’re new to this codebase

Skim 01-principles.md so you understand why.
Read 03-layout.md end-to-end so you can build a page.
Bookmark 04-components.md and 05-patterns.md.
Return to 07-voice.md the moment you write a user-facing string.
Open 11-templates-catalog.md when picking a template for a new screen — it routes you back to the relevant chapters.
Open 13-section-anatomy.md once you know your template — it tells you what each area needs and how to present each kind of setting / row.
Open 12-cross-cutting-patterns.md when working on multi-user editing, recovery, or cross-tab behavior.

That’s it. Build something people want. Ship it. Make it actually work.