noecosystem-design 0.2.0 → 0.2.1

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/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,15 @@ 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 a flat surface hierarchy: page canvas and raised regions are separated by
+semantic background tone, spacing, and radius—not decorative borders or shadows.
+`Card` therefore defaults to a raised, borderless appearance. Its outlined
+appearance is only for controls or data boundaries with a meaningful selection
+state. See [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,59 @@
+# 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.
+
+NOE shadow tokens are intentionally `none`. Do not add local `box-shadow` values
+to product styles. 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 every section/card/panel has `box-shadow: none` and no visible outer
+  stroke unless it is explicitly an outlined control.
+- 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,7 @@
 - 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`
 - 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.1",
   "private": false,
   "description": "Agent-readable NOE design-system source, registry metadata, and verification contracts.",
   "keywords": [

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

@@ -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: none;
+  --noe-shadow-overlay: none;
 }
 
 /* Semantic tokens: explicit dark theme. */
@@ -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: none;
+  --noe-shadow-overlay: none;
 }
 
 /* Semantic tokens: follow the OS only when no explicit theme is set. */
@@ -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: none;
+    --noe-shadow-overlay: none;
   }
 }
 

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

@@ -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": "none",
+      "overlay": "none"
     },
     "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": "none",
+      "overlay": "none"
     }
   },
   "font": {

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

@@ -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": "none",
+      "overlay": "none"
     },
     "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": "none",
+      "overlay": "none"
     }
   },
   "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/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,17 @@ 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 is intentionally shadow-free in both themes', async () => {
+  assert.equal(tokens.shadow.light.raised, 'none');
+  assert.equal(tokens.shadow.light.overlay, 'none');
+  assert.equal(tokens.shadow.dark.raised, 'none');
+  assert.equal(tokens.shadow.dark.overlay, 'none');
+
+  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*none/);
+  assert.match(css, /\[data-theme="dark"\][\s\S]*?--noe-shadow-overlay:\s*none/);
+});