@nadicodeai/design-system 12.1.172 → 12.1.174

package/AGENTS.md

@@ -1,12 +1,43 @@
 # @nadicodeai/design-system
 
-`DESIGN.md` is nadicode's design authority for the tokens, the visual direction
-and the rules every component, website section and product screen shares. React
-components belong to `@nadicodeai/ui`, and a component's own contract is the
-usage page in its source; `examples/` contains rendered specimens.
+React components belong to `@nadicodeai/ui`, and a component's own contract is
+the usage page in its source; `examples/` contains rendered specimens.
 
-- Design and CSS changes: `product-design` first, then the relevant section of
-  `DESIGN.md`.
+## What goes in DESIGN.md
+
+`DESIGN.md` is nadicode's visual identity in
+[Google's DESIGN.md format](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md):
+the four token groups in its front matter, and prose saying how those values
+look applied, in the format's sections (Overview, Colors, Typography, Layout,
+Elevation & Depth, Shapes, Components, Do's and Don'ts) and the ones it adds for
+the same purpose (Data Visualization, Motion, Iconography, Brand media
+authority, Registers). Its Components section says how components look: the
+tokens, materials and states their appearance takes.
+
+It never says how a component, a composition or a page is built, filled or
+placed, such as what a card's header holds, which composition a page renders or
+where a command goes, even when several components share the rule
+([ADR](../../docs/adr/2026-10-27-design-md-holds-the-visual-identity.md)). Such a
+rule goes to its owner:
+
+- What a component or composition does, takes or holds: its types and the usage
+  page in its source in `@nadicodeai/ui`.
+- How a Portal page is assembled: its composition, and the block in
+  `apps/portal/registry/blocks/` that shows it.
+- What code can detect: a type or a lint rule in `packages/oxlint-plugin/`.
+- What a pull request decided and worth repeating: an exemplar in the
+  `product-design` skill, whose rule index links every rule to its owner.
+- A product's pages and scope: that app's docs.
+
+Edit `DESIGN.md` only when the look changes: a token, a material, the type
+scale, a colour's meaning, a radius, a motion value. Its sections that still
+hold rules of the second kind move to their owners in
+[#5187](https://github.com/nadicodeai/nadicodeai/issues/5187); edit them only to
+move a rule out.
+
+## Working here
+
+- Design and CSS changes: `product-design` first, then the owner above.
 - Placement: `../ui/AGENTS.md`. Every reusable component lives in
   `@nadicodeai/ui`, even while one product alone uses it.
 - Terms: `GLOSSARY.md`. Static consumption: `README.md`.

package/DESIGN.md

@@ -2,11 +2,10 @@
 version: alpha
 name: nadicode Design System
 description: >-
-  nadicode's design system and its design authority for tokens, visual
-  direction and the rules every component and page shares: every component,
-  website section, and product screen in the website, the Portal, the Nadia
-  desktop app, and the Alveare desktop app builds on it. A component's own
-  contract is the usage page in its source in @nadicodeai/ui.
+  nadicode's visual identity: the tokens and how they look applied in every
+  component, website section and product screen of the website, the Portal,
+  the Nadia desktop app and the Alveare desktop app. What a component does,
+  takes or holds is the usage page in its source in @nadicodeai/ui.
 
 colors:
   action: "#1e3cff"
@@ -525,7 +524,7 @@ spacing:
 
 ## Overview
 
-This file is nadicode's design system and its design authority for tokens, 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`. The tokens above are the values; the sections below are the rules for applying them. Every component in `@nadicodeai/ui`, every website section, and every screen in the Portal, Nadia and Alveare builds on it. Another document may say how one product applies a rule, and links here for the rule; it never restates one. A shared rule that is missing here is added here first; a rule of one component is added to its usage page.
+This file is nadicode's visual identity: the tokens above are the values, and the sections below say how they look applied. Every component in `@nadicodeai/ui`, every website section, and every screen in the Portal, Nadia and Alveare builds on it. What a component, a composition or a page does, takes or holds is never written here: [`AGENTS.md`](AGENTS.md#what-goes-in-designmd) says what this file holds and where every other design rule goes.
 
 nadicode puts AI Agents to work inside small and mid-sized companies. Its sites and products read as a technology company with a real product: the interface is neutral and exact, the product is shown working, and colour and depth give the page its energy. Three ideas carry every screen:
 
@@ -914,7 +913,7 @@ Every component has a usage page, as Geist documents each of its own: what it is
 | Words | Which strings the product words, and how. |
 | Access | Its role, its name, its keyboard path and its focus. |
 
-The page is written in the component's own source, as the TSDoc of its main export (`@family`, `@when`, `@instead`, `@behaviour`, `@words`, `@access`), so an editor shows it on hover in every product; `@nadicodeai/ui`'s showcase renders every page, family by family, with the component drawn in its states. A component without its usage page, or a page without its specimen, fails the package's checks. A usage page holds its component's own rules, applies the shared rules in this file and never restates one.
+The page is written in the component's own source, as the TSDoc of its main export (`@family`, `@when`, `@instead`, `@behaviour`, `@words`, `@access`), so an editor shows it on hover in every product; `@nadicodeai/ui`'s showcase renders every page, family by family, with the component drawn in its states. A component without its usage page, or a page without its specimen, fails the package's checks. A usage page holds what its component does, takes and holds, applies the look in this file and never restates it.
 
 The table below maps all 73 entries in the [Geist component reference](https://vercel.com/geist/introduction) to our shared owners; how each owner is used is on its usage page. **Component** means a public owner exists for the job; it does not promise every Geist prop. **Composition** means existing parts provide the presentation together. An **enhanced capability gap** names specific behavior, not the absence of a matching component name. Use our exported APIs and names, not Geist's prop names: for example, our Button appearance is `variant`, while HTML submission behavior is `type`. A dedicated name in Geist does not require another primitive in our library; prefer existing compositions before adding another registry or dependency.
 
@@ -1255,7 +1254,7 @@ The clear space is one stroke width of the rendered logo on every side. The mini
 - Do use the dotted field only on a canvas where things are arranged. Don't put it behind lists, dashboards, settings or website sections.
 - Do build a page from its composition. Don't assemble a page's header, toolbar, rows or menus by hand.
 - Do put navigation in the top bar and the page's actions on its title row. Don't put an action in the top bar or a second sidebar beside the first.
-- Do add a shared rule here, and a component's own rule to its usage page, before a product needs it. Don't restate a rule in another document; link to it.
+- Do change this file when the look changes, and put how a component or a page is built with its owner. Don't restate this file in another document; link to it.
 
 ## Token extension
 

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+The `@nadicodeai/design-system` package. [`DESIGN.md`](./DESIGN.md) is nadicode's visual identity: every token and how it looks applied. [What goes in it](AGENTS.md#what-goes-in-designmd) says where every other design rule goes. 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.
 

package/dist/tokens/nadicode.dtcg-resolved.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
-  "$description": "nadicode's design system and its design authority for tokens, visual direction and the rules every component and page shares: every component, website section, and product screen in the website, the Portal, the Nadia desktop app, and the Alveare desktop app builds on it. A component's own contract is the usage page in its source in @nadicodeai/ui.",
+  "$description": "nadicode's visual identity: the tokens and how they look applied in every component, website section and product screen of the website, the Portal, the Nadia desktop app and the Alveare desktop app. What a component does, takes or holds is the usage page in its source in @nadicodeai/ui.",
   "nadicode": {
     "core": {
       "color": {

package/dist/tokens/nadicode.dtcg.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
-  "$description": "nadicode's design system and its design authority for tokens, visual direction and the rules every component and page shares: every component, website section, and product screen in the website, the Portal, the Nadia desktop app, and the Alveare desktop app builds on it. A component's own contract is the usage page in its source in @nadicodeai/ui.",
+  "$description": "nadicode's visual identity: the tokens and how they look applied in every component, website section and product screen of the website, the Portal, the Nadia desktop app and the Alveare desktop app. What a component does, takes or holds is the usage page in its source in @nadicodeai/ui.",
   "nadicode": {
     "core": {
       "color": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/design-system",
-  "version": "12.1.172",
+  "version": "12.1.174",
   "type": "module",
   "publishConfig": {
     "access": "public"