noecosystem-design 0.2.0 → 0.2.2

package/apps/storybook/stories/catalog/card.stories.tsx

@@ -38,3 +38,16 @@ export const Default: Story = {
     </Card>
   ),
 };
+
+export const Outlined: Story = {
+  render: () => (
+    <Card appearance="outlined" style={{ maxWidth: '24rem' }}>
+      <CardHeader>
+        <CardTitle>Selection boundary</CardTitle>
+        <CardDescription>
+          Use this only when a visible boundary conveys interaction or data-entry state.
+        </CardDescription>
+      </CardHeader>
+    </Card>
+  ),
+};

package/docs/design-system/brand-theme.md

@@ -0,0 +1,31 @@
+# Official NOE brand theme
+
+The NOEcosystem landing is the canonical visual identity for NOE products. Product
+interfaces use the same language rather than a related palette.
+
+## Foundation
+
+- Light canvas: paper `#f3f0ea`, raised paper `#f6f4f2` and bright reading surface.
+- Dark canvas: graphite `#252423`, raised graphite `#302f2e`.
+- Primary action: mint `#98e8cf`; hover mint `#abefd9`; the label is graphite.
+- Supporting interaction and focus: deep teal `#0f6d5b` / `#0b6f6b`.
+- Signal: coral `#ff5b57` / `#c43f3c`; cyan, amber and violet remain status/data
+  signals, not the default product CTA.
+- Latin copy uses the SF system stack; Persian copy uses IRANYekanXFaNum.
+
+## Composition
+
+Use large, confident headings; quiet metadata with tracked uppercase only for
+Latin labels; generous spacing; and low-contrast graphite/paper layers. Interactive
+boundaries use the semantic border token and the shared rounded geometry. Floating
+chat and modal surfaces use `shadow.raised` or `shadow.overlay` plus the quiet mint
+ambient gradient from the official reference. Do not create a separate app palette.
+
+## Product mapping
+
+- Chat composer/send action: mint fill, graphite icon/text, deep-teal focus ring.
+- Assistant/AI surfaces: graphite/paper raised surface with a quiet mint radial
+  ambient layer; do not use blue/cyan as the product identity.
+- Admin, expert and profile shells: the same paper/graphite canvas, thin utility
+  dividers, and one mint primary action per region.
+- Destructive paths continue to use coral and must retain explicit labels.

package/docs/design-system/components.md

@@ -42,6 +42,11 @@ matching the direction contract in `rtl.md`. Products consume the highest
 layer that fits; screens should not reassemble primitives into ad-hoc page
 scaffolds when a registered block exists.
 
+For application pages, compose `app-frame`, `page-header`, `sidebar-navigation`,
+`bottom-navigation`, `drawer`, and `Card` before creating a page-local shell.
+Use the [flat surface and navigation policy](surface-policy.md) to decide surface
+tone, CTA hierarchy, adaptive navigation, icon coloring, and review evidence.
+
 Mapping to the Untitled UI reference taxonomy (honest as of 2026-08-27 — foundation stabilization):
 
 | Untitled UI category      | NOE coverage                                                        |

package/docs/design-system/foundations.md

@@ -35,6 +35,17 @@ Typography is a language-aware semantic contract, not a per-component choice.
 
 Radii are compact and semantic. Controls use shared heights. Cards are not nested merely to create hierarchy. Dense professional surfaces may use tighter spacing than consumer surfaces but share the same token scale.
 
+## Surface hierarchy
+
+NOE uses graphite/paper surface hierarchy: page canvas and raised regions are
+separated first by semantic background tone, spacing, and radius. The official
+NOEcosystem visual language adds soft ambient elevation only to floating chat,
+drawers and modal layers; it is never used as chrome around every section.
+`Card` therefore defaults to a raised, borderless appearance. Its outlined
+appearance is only for controls or data boundaries with a meaningful selection
+state. See [Official NOE brand theme](brand-theme.md) and [Flat surface and
+navigation policy](surface-policy.md) for the product-level contract.
+
 ## Responsive behavior
 
 The reference app validates 390, 768, 1024, 1280 and 1440 pixel widths. Sidebars collapse by capability; data remains in logical DOM order; tables scroll rather than reverse data; agent artifacts progressively disclose on smaller layouts.

package/docs/design-system/surface-policy.md

@@ -0,0 +1,60 @@
+# Flat surface and navigation policy
+
+This is the default NOE policy for application pages. It prevents corrective UI
+passes caused by arbitrary shadows, card borders, or ambiguous mobile navigation.
+
+## Surface hierarchy
+
+1. The page canvas uses `color.background` or `color.surface`.
+2. A top-level section or card uses `color.surfaceRaised`.
+3. Grouping comes from the difference between those two tones, radius, and the
+   spacing scale—not a border or a shadow.
+4. A nested region uses spacing first. Do not nest cards merely to create depth.
+5. `Card` defaults to `appearance="raised"`, which has no visible stroke.
+   `appearance="outlined"` is reserved for a selection, data-entry, or comparison
+   boundary where a stroke conveys real meaning.
+
+Use the shared shadow tokens only for floating chat, drawer, popover and modal
+layers. Sections and ordinary cards do not receive ad-hoc elevation. A focus state
+is an outline/ring, not elevation.
+
+## Actions
+
+- One screen has one contained primary CTA.
+- Secondary actions are outline or ghost actions. On a dark or colored surface,
+  a white outline action remains transparent with a white label and stroke; never
+  give it an opaque white fill that removes its hierarchy.
+- Destructive actions retain an explicit label and confirmation/recovery path;
+  color alone is never the signal.
+- Every focusable action keeps a visible `focus-visible` outline.
+
+## Adaptive navigation
+
+- Use a sidebar for application navigation at desktop widths and a labelled drawer
+  trigger at smaller widths.
+- Mobile bottom navigation is only for top-level destinations and has at most five
+  labelled items. The active item has a text and icon state, not color alone.
+- A drawer is secondary navigation, not the only route to a primary action.
+- Every page frame exposes a skip link to its main landmark; a route change places
+  the reading start at that main region.
+- Menu triggers include an icon and a visible label when surrounding layout does
+  not already make their purpose obvious.
+
+## Icons and direction
+
+- Use `@noe/icons` only. Icons inherit `currentColor` from their interactive
+  parent, with explicit `color` only for a semantic status.
+- Keep icon size on the NOE token scale and icon-plus-label gaps logical.
+- Use logical CSS properties. Do not solve RTL with global `row-reverse` or
+  blanket SVG mirroring.
+
+## Product review checklist
+
+- Test every route in Persian/RTL and English/LTR, in light and dark themes.
+- Verify no page-level horizontal overflow at the mobile breakpoint.
+- Verify sections/cards have no visible outer stroke or ad-hoc shadow unless they
+  are an explicitly outlined control or a floating overlay using `shadow.overlay`.
+- Verify interactive targets are at least 44 px on touch devices and have
+  accessible names.
+- Test desktop sidebar and mobile drawer independently, including keyboard focus
+  and Escape dismissal.

package/llms.txt

@@ -32,6 +32,8 @@
 - Agent workflow and retrieval: `docs/design-system/agent-guide.md`
 - Components and catalog terms: `docs/design-system/components.md`
 - Tokens and foundations: `docs/design-system/foundations.md`, `docs/design-system/tokens.md`
+- Flat cards, action hierarchy and adaptive application navigation: `docs/design-system/surface-policy.md`
+- Official NOEcosystem visual-language contract: `docs/design-system/brand-theme.md`
 - Locale, RTL, and bidi: `docs/design-system/i18n.md`, `docs/design-system/rtl.md`
 - Accessibility: `docs/design-system/accessibility.md`
 - Agent and tool-state UI: `docs/design-system/agentic-ui.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noecosystem-design",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "description": "Agent-readable NOE design-system source, registry metadata, and verification contracts.",
   "keywords": [

package/packages/design-tokens/src/tokens.css

@@ -145,9 +145,9 @@
   --noe-color-muted-foreground: var(--noe-primitive-color-ink-500);
   --noe-color-border: rgba(23, 25, 24, 0.16);
   --noe-color-border-strong: var(--noe-primitive-color-ink-300);
-  --noe-color-accent: var(--noe-primitive-color-cyan-500);
-  --noe-color-accent-hover: var(--noe-primitive-color-cyan-500);
-  --noe-color-accent-foreground: var(--noe-primitive-color-paper-0);
+  --noe-color-accent: var(--noe-primitive-color-mint-100);
+  --noe-color-accent-hover: var(--noe-primitive-color-mint-200);
+  --noe-color-accent-foreground: var(--noe-primitive-color-ink-900);
   --noe-color-signal: var(--noe-primitive-color-coral-500);
   --noe-color-success: var(--noe-primitive-color-green-600);
   --noe-color-success-foreground: var(--noe-primitive-color-paper-0);
@@ -159,8 +159,8 @@
   --noe-color-info-foreground: var(--noe-primitive-color-paper-0);
   --noe-color-focus-ring: var(--noe-primitive-color-alpha-focus-light);
   --noe-color-overlay: var(--noe-primitive-color-alpha-overlay-light);
-  --noe-shadow-raised: 0 1px 2px rgba(23, 25, 24, 0.05), 0 14px 34px rgba(23, 25, 24, 0.07);
-  --noe-shadow-overlay: 0 24px 64px rgba(23, 25, 24, 0.16);
+  --noe-shadow-raised: 0 8px 20px rgba(23, 25, 24, 0.055);
+  --noe-shadow-overlay: 0 36px 100px rgba(23, 25, 24, 0.28);
 }
 
 /* Semantic tokens: explicit dark theme. */
@@ -175,8 +175,8 @@
   --noe-color-muted-foreground: var(--noe-primitive-color-ink-400);
   --noe-color-border: rgba(246, 244, 242, 0.14);
   --noe-color-border-strong: var(--noe-primitive-color-ink-600);
-  --noe-color-accent: var(--noe-primitive-color-cyan-400);
-  --noe-color-accent-hover: var(--noe-primitive-color-cyan-400);
+  --noe-color-accent: var(--noe-primitive-color-mint-100);
+  --noe-color-accent-hover: var(--noe-primitive-color-mint-200);
   --noe-color-accent-foreground: var(--noe-primitive-color-ink-950);
   --noe-color-signal: var(--noe-primitive-color-coral-400);
   --noe-color-success: var(--noe-primitive-color-green-500);
@@ -189,8 +189,8 @@
   --noe-color-info-foreground: var(--noe-primitive-color-ink-950);
   --noe-color-focus-ring: var(--noe-primitive-color-alpha-focus-dark);
   --noe-color-overlay: var(--noe-primitive-color-alpha-overlay-dark);
-  --noe-shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.2), 0 18px 48px rgba(0, 0, 0, 0.26);
-  --noe-shadow-overlay: 0 30px 80px rgba(0, 0, 0, 0.46);
+  --noe-shadow-raised: 0 8px 20px rgba(0, 0, 0, 0.14);
+  --noe-shadow-overlay: 0 36px 100px rgba(0, 0, 0, 0.42);
 }
 
 /* Semantic tokens: follow the OS only when no explicit theme is set. */
@@ -206,8 +206,8 @@
     --noe-color-muted-foreground: var(--noe-primitive-color-ink-400);
     --noe-color-border: rgba(246, 244, 242, 0.14);
     --noe-color-border-strong: var(--noe-primitive-color-ink-600);
-    --noe-color-accent: var(--noe-primitive-color-cyan-400);
-    --noe-color-accent-hover: var(--noe-primitive-color-cyan-400);
+    --noe-color-accent: var(--noe-primitive-color-mint-100);
+    --noe-color-accent-hover: var(--noe-primitive-color-mint-200);
     --noe-color-accent-foreground: var(--noe-primitive-color-ink-950);
     --noe-color-signal: var(--noe-primitive-color-coral-400);
     --noe-color-success: var(--noe-primitive-color-green-500);
@@ -220,8 +220,8 @@
     --noe-color-info-foreground: var(--noe-primitive-color-ink-950);
     --noe-color-focus-ring: var(--noe-primitive-color-alpha-focus-dark);
     --noe-color-overlay: var(--noe-primitive-color-alpha-overlay-dark);
-    --noe-shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.2), 0 18px 48px rgba(0, 0, 0, 0.26);
-    --noe-shadow-overlay: 0 30px 80px rgba(0, 0, 0, 0.46);
+    --noe-shadow-raised: 0 8px 20px rgba(0, 0, 0, 0.14);
+    --noe-shadow-overlay: 0 36px 100px rgba(0, 0, 0, 0.42);
   }
 }
 

package/packages/design-tokens/src/tokens.json

@@ -111,9 +111,9 @@
       "mutedForeground": "{primitive.color.ink.500}",
       "border": "rgba(23, 25, 24, 0.16)",
       "borderStrong": "{primitive.color.ink.300}",
-      "accent": "{primitive.color.cyan.500}",
-      "accentHover": "{primitive.color.cyan.500}",
-      "accentForeground": "{primitive.color.paper.0}",
+      "accent": "{primitive.color.mint.100}",
+      "accentHover": "{primitive.color.mint.200}",
+      "accentForeground": "{primitive.color.ink.900}",
       "signal": "{primitive.color.coral.500}",
       "success": "{primitive.color.green.600}",
       "successForeground": "{primitive.color.paper.0}",
@@ -136,8 +136,8 @@
       "mutedForeground": "{primitive.color.ink.400}",
       "border": "rgba(246, 244, 242, 0.14)",
       "borderStrong": "{primitive.color.ink.600}",
-      "accent": "{primitive.color.cyan.400}",
-      "accentHover": "{primitive.color.cyan.400}",
+      "accent": "{primitive.color.mint.100}",
+      "accentHover": "{primitive.color.mint.200}",
       "accentForeground": "{primitive.color.ink.950}",
       "signal": "{primitive.color.coral.400}",
       "success": "{primitive.color.green.500}",
@@ -154,12 +154,12 @@
   },
   "shadow": {
     "light": {
-      "raised": "0 1px 2px rgba(23, 25, 24, 0.05), 0 14px 34px rgba(23, 25, 24, 0.07)",
-      "overlay": "0 24px 64px rgba(23, 25, 24, 0.16)"
+      "raised": "0 8px 20px rgba(23, 25, 24, 0.055)",
+      "overlay": "0 36px 100px rgba(23, 25, 24, 0.28)"
     },
     "dark": {
-      "raised": "0 1px 2px rgba(0, 0, 0, 0.2), 0 18px 48px rgba(0, 0, 0, 0.26)",
-      "overlay": "0 30px 80px rgba(0, 0, 0, 0.46)"
+      "raised": "0 8px 20px rgba(0, 0, 0, 0.14)",
+      "overlay": "0 36px 100px rgba(0, 0, 0, 0.42)"
     }
   },
   "font": {

package/packages/design-tokens/src/tokens.mjs

@@ -112,9 +112,9 @@ export const tokens = {
       "mutedForeground": "{primitive.color.ink.500}",
       "border": "rgba(23, 25, 24, 0.16)",
       "borderStrong": "{primitive.color.ink.300}",
-      "accent": "{primitive.color.cyan.500}",
-      "accentHover": "{primitive.color.cyan.500}",
-      "accentForeground": "{primitive.color.paper.0}",
+      "accent": "{primitive.color.mint.100}",
+      "accentHover": "{primitive.color.mint.200}",
+      "accentForeground": "{primitive.color.ink.900}",
       "signal": "{primitive.color.coral.500}",
       "success": "{primitive.color.green.600}",
       "successForeground": "{primitive.color.paper.0}",
@@ -137,8 +137,8 @@ export const tokens = {
       "mutedForeground": "{primitive.color.ink.400}",
       "border": "rgba(246, 244, 242, 0.14)",
       "borderStrong": "{primitive.color.ink.600}",
-      "accent": "{primitive.color.cyan.400}",
-      "accentHover": "{primitive.color.cyan.400}",
+      "accent": "{primitive.color.mint.100}",
+      "accentHover": "{primitive.color.mint.200}",
       "accentForeground": "{primitive.color.ink.950}",
       "signal": "{primitive.color.coral.400}",
       "success": "{primitive.color.green.500}",
@@ -155,12 +155,12 @@ export const tokens = {
   },
   "shadow": {
     "light": {
-      "raised": "0 1px 2px rgba(23, 25, 24, 0.05), 0 14px 34px rgba(23, 25, 24, 0.07)",
-      "overlay": "0 24px 64px rgba(23, 25, 24, 0.16)"
+      "raised": "0 8px 20px rgba(23, 25, 24, 0.055)",
+      "overlay": "0 36px 100px rgba(23, 25, 24, 0.28)"
     },
     "dark": {
-      "raised": "0 1px 2px rgba(0, 0, 0, 0.2), 0 18px 48px rgba(0, 0, 0, 0.26)",
-      "overlay": "0 30px 80px rgba(0, 0, 0, 0.46)"
+      "raised": "0 8px 20px rgba(0, 0, 0, 0.14)",
+      "overlay": "0 36px 100px rgba(0, 0, 0, 0.42)"
     }
   },
   "font": {

package/packages/registry/catalog-index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-29T08:49:53.291Z",
+  "generatedAt": "2026-08-29T09:30:43.936Z",
   "items": [
     {
       "id": "bidi-text",
@@ -88,7 +88,7 @@
       "package": "@noe/ui",
       "status": "available",
       "maturity": "beta",
-      "description": "Card — Primitives / Layout component. card provides primitives / layout behavior with RTL, i18n and accessibility built-in.",
+      "description": "Flat raised section primitive. It separates content from its page canvas through semantic surface tone, spacing and radius—not decorative borders or shadows. Use outlined only where a boundary conveys selection or data-entry state.",
       "registryItem": "card"
     },
     {

package/packages/registry/manifest.json

@@ -1,6 +1,6 @@
 {
   "manifestVersion": "1.0.0",
-  "generatedAt": "2026-08-29T08:49:53.284Z",
+  "generatedAt": "2026-08-29T09:30:43.923Z",
   "generatedNote": "Canonical NOE manifest — single source of truth for catalog, audit, registry, stories, docs and agent search. Generated by pnpm gen:manifest; do not edit by hand for automated fields.",
   "items": [
     {
@@ -428,12 +428,25 @@
       "status": "available",
       "maturity": "beta",
       "category": "Primitives / Layout",
-      "description": "Card — Primitives / Layout component. card provides primitives / layout behavior with RTL, i18n and accessibility built-in.",
-      "capabilityAliases": ["card", "card"],
-      "searchTerms": ["card", "card", "layout"],
-      "useWhen": ["using card in Primitives / Layout"],
-      "doNotUseWhen": ["when card semantics do not match"],
-      "alternatives": [],
+      "description": "Flat raised section primitive. It separates content from its page canvas through semantic surface tone, spacing and radius—not decorative borders or shadows. Use outlined only where a boundary conveys selection or data-entry state.",
+      "capabilityAliases": ["flat card", "raised surface", "borderless section", "outlined card"],
+      "searchTerms": [
+        "card",
+        "raised surface",
+        "flat section",
+        "borderless panel",
+        "outlined boundary"
+      ],
+      "useWhen": [
+        "grouping a top-level application region with a semantic raised surface",
+        "separating sections by color tone rather than elevation or decorative chrome",
+        "using appearance=\"outlined\" only for selection, data-entry or comparison boundaries"
+      ],
+      "doNotUseWhen": [
+        "adding a nested card solely to create visual depth",
+        "using an outlined boundary when spacing and surface tone already express grouping"
+      ],
+      "alternatives": ["SectionHeader", "Field"],
       "dependencies": [],
       "registryDependencies": [],
       "peerDependencies": ["react"],
@@ -441,20 +454,20 @@
         "label": "string | ReactNode",
         "children": "ReactNode"
       },
-      "variants": ["default"],
+      "variants": ["raised", "outlined"],
       "sizes": [],
       "slots": [],
-      "states": ["default", "hover", "focus-visible", "disabled"],
-      "tokenContracts": ["color.foreground", "color.border"],
+      "states": ["default"],
+      "tokenContracts": ["color.background", "color.surface", "color.surfaceRaised", "radius.lg"],
       "accessibility": {
-        "keyboard": ["Tab to focus", "Enter/Space activate"],
+        "keyboard": [],
         "announcements": [],
-        "focusBehavior": ["visible ring 2px"]
+        "focusBehavior": ["not focusable unless its content contains an interactive control"]
       },
       "internationalization": {
         "messageKeys": [],
         "rtl": "required",
-        "bidiNotes": ["logical properties", "no global mirror"]
+        "bidiNotes": ["logical spacing; no directional layout override"]
       },
       "examples": [
         {
@@ -463,7 +476,7 @@
           "files": ["apps/storybook/stories/catalog/card.stories.tsx"]
         }
       ],
-      "relatedPatterns": [],
+      "relatedPatterns": ["app-frame", "dashboard-shell", "section-header"],
       "untitledMapping": null,
       "storyId": "catalog-primitives-card--default",
       "registryItem": "card"

package/packages/registry/r/card.json

@@ -3,7 +3,7 @@
   "name": "card",
   "type": "registry:ui",
   "title": "Card",
-  "description": "Card — Primitives / Layout component. card provides primitives / layout behavior with RTL, i18n and accessibility built-in.",
+  "description": "Flat raised section primitive. It separates content through semantic surface tone, spacing and radius—not decorative borders or shadows. Use an outlined boundary only for selection or data-entry state.",
   "files": [
     {
       "path": "packages/ui/src/card.tsx",
@@ -37,8 +37,14 @@
     "announcements": [],
     "focusBehavior": ["visible ring 2px"]
   },
-  "tokenContracts": ["color.foreground", "color.border"],
-  "capabilityAliases": ["card", "card"],
-  "useWhen": ["using card in Primitives / Layout"],
-  "doNotUseWhen": ["when card semantics do not match"]
+  "tokenContracts": ["color.background", "color.surface", "color.surfaceRaised", "radius.lg"],
+  "capabilityAliases": ["flat card", "raised surface", "borderless section", "outlined card"],
+  "useWhen": [
+    "grouping a top-level application region with a semantic raised surface",
+    "using an outlined boundary only for selection, data-entry or comparison state"
+  ],
+  "doNotUseWhen": [
+    "adding a nested card solely to create visual depth",
+    "using a decorative stroke when spacing and surface tone already express grouping"
+  ]
 }

package/packages/registry/registry.json

@@ -1040,8 +1040,14 @@
       "dependencies": ["clsx", "tailwind-merge"],
       "peerDependencies": ["react"],
       "manifestId": "card",
-      "capabilityAliases": ["card", "card"],
-      "searchTerms": ["card", "card", "layout"]
+      "capabilityAliases": ["flat card", "raised surface", "borderless section", "outlined card"],
+      "searchTerms": [
+        "card",
+        "raised surface",
+        "flat section",
+        "borderless panel",
+        "outlined boundary"
+      ]
     },
     {
       "name": "alert",

package/packages/registry/search-index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-29T08:49:53.289Z",
+  "generatedAt": "2026-08-29T09:30:43.933Z",
   "items": [
     {
       "id": "bidi-text",
@@ -160,15 +160,28 @@
       "id": "card",
       "package": "@noe/ui",
       "title": "Card",
-      "description": "Card — Primitives / Layout component. card provides primitives / layout behavior with RTL, i18n and accessibility built-in.",
+      "description": "Flat raised section primitive. It separates content from its page canvas through semantic surface tone, spacing and radius—not decorative borders or shadows. Use outlined only where a boundary conveys selection or data-entry state.",
       "category": "Primitives / Layout",
       "status": "available",
-      "capabilityAliases": ["card", "card"],
-      "searchTerms": ["card", "card", "layout"],
-      "useWhen": ["using card in Primitives / Layout"],
-      "doNotUseWhen": ["when card semantics do not match"],
-      "alternatives": [],
-      "relatedPatterns": [],
+      "capabilityAliases": ["flat card", "raised surface", "borderless section", "outlined card"],
+      "searchTerms": [
+        "card",
+        "raised surface",
+        "flat section",
+        "borderless panel",
+        "outlined boundary"
+      ],
+      "useWhen": [
+        "grouping a top-level application region with a semantic raised surface",
+        "separating sections by color tone rather than elevation or decorative chrome",
+        "using appearance=\"outlined\" only for selection, data-entry or comparison boundaries"
+      ],
+      "doNotUseWhen": [
+        "adding a nested card solely to create visual depth",
+        "using an outlined boundary when spacing and surface tone already express grouping"
+      ],
+      "alternatives": ["SectionHeader", "Field"],
+      "relatedPatterns": ["app-frame", "dashboard-shell", "section-header"],
       "exportName": "Card",
       "registryItem": "card",
       "maturity": "beta"

package/packages/ui/src/card.tsx

@@ -2,13 +2,25 @@ import type * as React from 'react';
 
 import { cn } from './lib/cn';
 
-export function Card({ className, ...props }: React.ComponentProps<'section'>) {
+export type CardAppearance = 'raised' | 'outlined';
+
+export interface CardProps extends React.ComponentProps<'section'> {
+  /**
+   * Raised surfaces are separated from the page by a semantic surface tone only.
+   * Use outlined only where a visible boundary conveys data-entry or selection state.
+   */
+  appearance?: CardAppearance;
+}
+
+export function Card({ appearance = 'raised', className, ...props }: CardProps) {
   return (
     <section
       className={cn(
-        'flex flex-col overflow-hidden rounded-lg border border-border bg-surface-raised text-foreground',
+        'flex flex-col overflow-hidden rounded-lg bg-surface-raised text-foreground',
+        appearance === 'outlined' && 'border border-border',
         className,
       )}
+      data-appearance={appearance}
       data-slot="card"
       {...props}
     />

package/packages/ui/src/color-picker.tsx

@@ -1,9 +1,9 @@
 import type * as React from 'react';
 import { cn } from './lib/cn';
 
-// Default example value uses the semantic accent token (mint-500) — not a raw product color.
-// Input type=color requires a hex for the native picker; the displayed hex is derived from the token.
-const DEFAULT_ACCENT_HEX = '#0b6f6b'; // primitive mint-500 / semantic accent — keep in sync with tokens.json
+// The native picker needs a literal hex. Its swatch demonstrates deep mint while
+// the adjacent value keeps the standard readable text foreground.
+const DEFAULT_ACCENT_HEX = '#0b6f6b'; // primitive mint-500 — keep in sync with tokens.json
 
 export function ColorPicker({ className, ...props }: React.ComponentProps<'div'>) {
   return (
@@ -14,9 +14,7 @@ export function ColorPicker({ className, ...props }: React.ComponentProps<'div'>
         className="size-8 rounded-md border border-border"
         defaultValue={DEFAULT_ACCENT_HEX}
       />
-      <span className="text-sm text-muted-foreground" style={{ color: 'var(--noe-color-accent)' }}>
-        {DEFAULT_ACCENT_HEX}
-      </span>
+      <span className="text-sm text-muted-foreground">{DEFAULT_ACCENT_HEX}</span>
     </div>
   );
 }

package/scripts/generate-manifest.mjs

@@ -218,6 +218,41 @@ const enrichments = {
       notes: 'Variants parity full; loading and destructive covered',
     },
   },
+  card: {
+    description:
+      'Flat raised section primitive. It separates content from its page canvas through semantic surface tone, spacing and radius—not decorative borders or shadows. Use outlined only where a boundary conveys selection or data-entry state.',
+    capabilityAliases: ['flat card', 'raised surface', 'borderless section', 'outlined card'],
+    searchTerms: [
+      'card',
+      'raised surface',
+      'flat section',
+      'borderless panel',
+      'outlined boundary',
+    ],
+    useWhen: [
+      'grouping a top-level application region with a semantic raised surface',
+      'separating sections by color tone rather than elevation or decorative chrome',
+      'using appearance="outlined" only for selection, data-entry or comparison boundaries',
+    ],
+    doNotUseWhen: [
+      'adding a nested card solely to create visual depth',
+      'using an outlined boundary when spacing and surface tone already express grouping',
+    ],
+    alternatives: ['SectionHeader', 'Field'],
+    variants: ['raised', 'outlined'],
+    states: ['default'],
+    tokenContracts: ['color.background', 'color.surface', 'color.surfaceRaised', 'radius.lg'],
+    accessibility: {
+      keyboard: [],
+      announcements: [],
+      focusBehavior: ['not focusable unless its content contains an interactive control'],
+    },
+    internationalization: {
+      rtl: 'required',
+      bidiNotes: ['logical spacing; no directional layout override'],
+    },
+    relatedPatterns: ['app-frame', 'dashboard-shell', 'section-header'],
+  },
   dialog: {
     description:
       'Direction-preserving modal primitive with native focus semantics and portal propagation. Share foundation with Modal/Slideout.',
@@ -826,7 +861,7 @@ function defaultEnrichment(auditItem) {
     dependencies: deps,
     registryDependencies: registryDeps,
     peerDependencies: peerDeps,
-    propsSummary: { label: 'string | ReactNode', children: 'ReactNode' },
+    propsSummary: base.propsSummary ?? { label: 'string | ReactNode', children: 'ReactNode' },
     variants,
     sizes,
     slots,

package/tests/tokens.test.mjs

@@ -22,3 +22,23 @@ test('token CSS includes theme and reduced-motion contracts', async () => {
   assert.match(css, /--noe-primitive-color-paper-100:\s*#[0-9a-f]{6}/i);
   assert.match(css, /--noe-primitive-color-mint-100:\s*#[0-9a-f]{6}/i);
 });
+
+test('surface elevation follows the official NOE soft-depth contract', async () => {
+  assert.match(tokens.shadow.light.raised, /rgba\(23, 25, 24, 0\.055\)/);
+  assert.match(tokens.shadow.light.overlay, /rgba\(23, 25, 24, 0\.28\)/);
+  assert.match(tokens.shadow.dark.raised, /rgba\(0, 0, 0, 0\.14\)/);
+  assert.match(tokens.shadow.dark.overlay, /rgba\(0, 0, 0, 0\.42\)/);
+
+  const css = await readFile(
+    new URL('../packages/design-tokens/src/tokens.css', import.meta.url),
+    'utf8',
+  );
+  assert.match(
+    css,
+    /\[data-theme="light"\][\s\S]*?--noe-shadow-raised:\s*0 8px 20px rgba\(23, 25, 24, 0\.055\)/,
+  );
+  assert.match(
+    css,
+    /\[data-theme="dark"\][\s\S]*?--noe-shadow-overlay:\s*0 36px 100px rgba\(0, 0, 0, 0\.42\)/,
+  );
+});