@nadicodeai/design-system 0.1.0

package/DESIGN.md

@@ -0,0 +1,613 @@
+---
+version: alpha
+name: NadicodeAI Design System
+description: >-
+  Reusable design-system contract for NadicodeAI: engineered page geometry,
+  neutral high-contrast surfaces, AI-agent work artifacts, and strict
+  12-column/10-column composition rules for the public website and package
+  token exports.
+
+colors:
+  primary: "#171717"
+  on-primary: "#ffffff"
+  ink: "#171717"
+  body: "#4d4d4d"
+  muted: "#888888"
+  canvas: "#ffffff"
+  canvas-soft: "#fafafa"
+  canvas-soft-2: "#f5f5f5"
+  line: "#e5e5e5"
+  seam: "#e4e7ec"
+  cross: "#a1a1a1"
+  link: "#007a5e"
+  link-deep: "#005d49"
+  link-bg-soft: "#d8f0e9"
+  success: "#008c45"
+  error: "#b80022"
+  error-soft: "#f4d7dc"
+  error-deep: "#820018"
+  warning: "#f5a623"
+  warning-soft: "#ffefcf"
+  warning-deep: "#ab570a"
+  cyan: "#50e3c2"
+  cyan-soft: "#aaffec"
+  cyan-deep: "#29bc9b"
+  flag-red: "#cd212a"
+  gradient-develop-start: "#007a5e"
+  gradient-develop-end: "#00dfd8"
+  gradient-ship-start: "#b80022"
+  gradient-ship-end: "#f9cb28"
+  selection-bg: "#171717"
+  selection-fg: "#f2f2f2"
+  state-ready: "#171717"
+  state-running: "#007a5e"
+  state-review: "#f5a623"
+  state-blocked: "#b80022"
+  state-complete: "#008c45"
+
+typography:
+  display-xl:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 72px
+    fontWeight: 600
+    lineHeight: 74px
+    letterSpacing: -1.5px
+  display-lg:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 52px
+    fontWeight: 600
+    lineHeight: 54px
+    letterSpacing: -1px
+  display-md:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: 0px
+  display-sm:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 20px
+    fontWeight: 600
+    lineHeight: 28px
+    letterSpacing: 0px
+  title-lg:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 40px
+    fontWeight: 600
+    lineHeight: 41px
+    letterSpacing: 0px
+  title-md:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 30px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: 0px
+  title-sm:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 22px
+    fontWeight: 600
+    lineHeight: 25px
+    letterSpacing: 0px
+  body-lg:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 18px
+    fontWeight: 400
+    lineHeight: 27px
+    letterSpacing: 0px
+  body-md:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 25px
+    letterSpacing: 0px
+  body-md-strong:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 16px
+    fontWeight: 500
+    lineHeight: 24px
+    letterSpacing: 0px
+  body-sm:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 20px
+    letterSpacing: 0px
+  body-sm-strong:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 20px
+    letterSpacing: 0px
+  caption:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 16px
+    letterSpacing: 0px
+  caption-mono:
+    fontFamily: Geist Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, monospace
+    fontSize: 12px
+    fontWeight: 500
+    lineHeight: 16px
+    letterSpacing: 0px
+  code:
+    fontFamily: Geist Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, monospace
+    fontSize: 13px
+    fontWeight: 400
+    lineHeight: 20px
+    letterSpacing: 0px
+  button-md:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 18px
+    letterSpacing: 0px
+  button-lg:
+    fontFamily: Geist, Inter, system-ui, -apple-system, sans-serif
+    fontSize: 16px
+    fontWeight: 500
+    lineHeight: 24px
+    letterSpacing: 0px
+
+rounded:
+  none: 0px
+  xs: 4px
+  sm: 6px
+  md: 8px
+  lg: 12px
+  xl: 16px
+  pill-sm: 64px
+  pill: 100px
+  full: 9999px
+
+spacing:
+  xxs: 4px
+  xs: 8px
+  sm: 12px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  2xl: 40px
+  3xl: 48px
+  4xl: 64px
+  5xl: 96px
+  6xl: 128px
+  section: 192px
+  guide: 1px
+  page-pad: 24px
+  page-max-mobile: 448px
+  page-max-tablet: 624px
+  page-max-desktop: 1440px
+  frame-max: 1392px
+  frame-gap: 24px
+  cell-padding: 24px
+  section-gap: 48px
+  cross-size-mobile: 11px
+  cross-size-tablet: 15px
+  cross-size-desktop: 21px
+  h-strip-mobile: 72px
+  h-strip-tablet: 80px
+  h-strip-desktop: 88px
+  h-cell-sm: 120px
+  h-cell-md-mobile: 144px
+  h-cell-md-tablet: 160px
+  h-cell-md-desktop: 168px
+  h-cell-lg-mobile: 220px
+  h-cell-lg-desktop: 240px
+  h-visual-mobile: 276px
+  h-visual-tablet: 318px
+  h-visual-desktop: 360px
+  h-precision-mobile: 276px
+  h-precision-tablet: 480px
+  h-precision-desktop: 720px
+  h-hero-mobile: 560px
+  h-hero-desktop: 720px
+  h-action-strip-mobile: 20px
+  h-action-strip-desktop: 32px
+  h-action-body-mobile: 320px
+  h-action-body-tablet: 338px
+  h-action-band: 260px
+  h-feature-mobile: 360px
+  h-feature-tablet: 400px
+  h-feature-desktop: 456px
+  h-editorial-feature-mobile: 360px
+  h-editorial-feature-tablet: 440px
+  h-editorial-feature-desktop: 560px
+  h-bento-primary: 384px
+  h-bento-secondary: 240px
+  h-bento-mobile-copy: 248px
+  h-bento-mobile-main: 537px
+  h-bento-strip: 20px
+
+components:
+  label-mono:
+    textColor: "{colors.muted}"
+    typography: "{typography.caption-mono}"
+    padding: "0px"
+  artifact-surface:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    padding: "{spacing.lg}"
+  status-tag:
+    backgroundColor: "{colors.canvas-soft}"
+    textColor: "{colors.body}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.lg}"
+    padding: "5px 9px"
+    height: 28px
+  status-tag-approved:
+    backgroundColor: "{colors.link-bg-soft}"
+    textColor: "{colors.link-deep}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.lg}"
+    padding: "5px 9px"
+    height: 28px
+  image:
+    backgroundColor: "{colors.canvas-soft}"
+    textColor: "{colors.body}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.none}"
+    padding: 0px
+  badge-secondary:
+    backgroundColor: "{colors.canvas-soft}"
+    textColor: "{colors.body}"
+    typography: "{typography.caption}"
+    rounded: "{rounded.full}"
+    padding: "0px {spacing.xs}"
+  state-tag-ready:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "0px {spacing.xs}"
+    height: 26px
+  state-tag-running:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "0px {spacing.xs}"
+    height: 26px
+  state-tag-review:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "0px {spacing.xs}"
+    height: 26px
+  state-tag-blocked:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "0px {spacing.xs}"
+    height: 26px
+  state-tag-complete:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "0px {spacing.xs}"
+    height: 26px
+  approval-gate:
+    backgroundColor: "{colors.warning-soft}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-sm}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.md}"
+  agent-avatar:
+    backgroundColor: "{colors.canvas-soft}"
+    rounded: "{rounded.full}"
+    padding: "0px"
+  usage-meter:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.body}"
+    typography: "{typography.caption-mono}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xxs} {spacing.xs}"
+  run-timeline:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-sm}"
+    padding: "0px"
+  memory-item:
+    backgroundColor: "{colors.canvas-soft}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-sm}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  handoff-banner:
+    backgroundColor: "{colors.link-bg-soft}"
+    textColor: "{colors.link-deep}"
+    typography: "{typography.body-sm-strong}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm} {spacing.md}"
+  chat-thread:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    padding: "{spacing.lg}"
+  chat-bubble-user:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    typography: "{typography.body-sm}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm} {spacing.md}"
+  chat-bubble-agent:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.ink}"
+    typography: "{typography.body-sm}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.sm} {spacing.md}"
+  tool-call-trace:
+    backgroundColor: "{colors.canvas-soft-2}"
+    textColor: "{colors.ink}"
+    typography: "{typography.code}"
+    rounded: "{rounded.sm}"
+    padding: "{spacing.xs} {spacing.sm}"
+  link-inline:
+    backgroundColor: "{colors.canvas}"
+    textColor: "{colors.link}"
+    typography: "{typography.body-md}"
+    padding: "0px"
+---
+
+## Overview
+
+NadicodeAI is an AI agency for SMBs. The design system exists to make the public website and future implementation feel engineered, clear, and serious without becoming enterprise software theatre. The interface should help a pragmatic buyer understand the work: repeated workflows, agents trained with people, inspectable outputs, human approval, and one useful first use case.
+
+The visual language is a continuous page frame with precise seams. Sections are not floating cards and not isolated decorative blocks. A page is built from rows inside a 12-column frame; most content sits in the centered 10-column active lane while columns 1 and 12 remain visibly owned by side fills, borders, or guide structure. The page should read as one coherent system.
+
+The kernel is the reusable implementation layer. `DESIGN.md` defines the reusable contract and exported scalar tokens; the `@nadicodeai/design-system/css` bundle (`src/css/**`) demonstrates and exercises that contract. Homepage copy, page-specific ordering, and temporary prototypes do not belong in this file.
+
+## Colors
+
+The palette keeps the broad neutral, accent, state, and gradient families that NadicodeAI started from, then adds the newer kernel seam vocabulary. The public website may use a restrained subset, but the design-system contract remains broader than any current specimen.
+
+- **Ink / Primary** (`{colors.ink}`, `{colors.primary}`): near-black for text, primary actions, and dark action bands.
+- **Canvas** (`{colors.canvas}`): white content cells.
+- **Canvas Soft** (`{colors.canvas-soft}`): page background and diagonal filler base.
+- **Canvas Soft 2** (`{colors.canvas-soft-2}`): subtle filler stripe and inset surface tone.
+- **Line** (`{colors.line}`): the universal 1 px divider and seam color. It is the only token used to tune ordinary seam visibility; keep it visible on `{colors.canvas}` and `{colors.canvas-soft}` while remaining quiet. Do not darken individual borders, gap backgrounds, hatch stripes, or dividers locally.
+- **Cross** (`{colors.cross}`): stronger gray for visible marks, pending nodes, and crosshair markers.
+- **Seam** (`{colors.seam}`): dashed connector and secondary guide color.
+- **Body / Muted** (`{colors.body}`, `{colors.muted}`): secondary copy and low-priority labels.
+- **Italian Link Green** (`{colors.link}`): inline links, navigational accents, and approved/example proof states. It is intentionally green, not blue, so NadicodeAI keeps an Italian signal without turning the interface into flag decoration.
+- **Semantic** (`{colors.success}`, `{colors.error}`, `{colors.warning}` plus soft/deep variants): validation, caution, approval, and operational feedback. `success` uses the Italian flag green family; `error` uses a deeper Italian red so destructive and blocked states are visible without defaulting to generic web red.
+- **Accent** (`{colors.cyan}`): high-energy accent available for visuals, states, and generated assets.
+- **Flag Red** (`{colors.flag-red}`): a decorative Italian-flag red reserved for brand-asset decoration only (identity marks such as Nadia's flag-red bar). It is distinct from `{colors.error}`; never use `flag-red` for destructive, blocked, or validation states.
+- **Gradient Pairs** (`{colors.gradient-develop-*}`, `{colors.gradient-ship-*}`): reserved gradient vocabulary for artifact- and asset-level energy; do not use them to repair page structure or seams.
+- **Workflow States** (`{colors.state-ready}`, `{colors.state-running}`, `{colors.state-review}`, `{colors.state-blocked}`, `{colors.state-complete}`): left-border/state vocabulary for agentic work surfaces.
+
+Do not delete a color because the current website kernel does not consume it. Prototype usage is not palette authority; removals require an explicit palette migration decision.
+
+## Typography
+
+Geist Sans carries all narrative and interface copy. Geist Mono is reserved for eyebrows, labels, status tags, code, traces, and small technical metadata.
+
+All body, title, caption, and code typography uses `letterSpacing: 0px`. Do not use viewport-scaled type (no `vw`/`vh` font sizing): use fixed token sizes stepped by breakpoint-specific rules when a headline must grow. The two large display tiers carry a small negative tracking — `display-xl` at `-1.5px` and `display-lg` at `-1px` — so large type reads optically tight; this is a display-heading-only exception and every non-display tier stays at `0px`.
+
+| Token | Size | Weight | Line Height | Use |
+| --- | --- | --- | --- | --- |
+| `{typography.display-xl}` | 72px | 600 | 74px | Large desktop homepage hero only. |
+| `{typography.display-lg}` | 52px | 600 | 54px | Compact hero and major landing headlines. |
+| `{typography.display-md}` | 24px | 600 | 32px | Recovered display tier for compact cards, pricing names, and asset labels. |
+| `{typography.display-sm}` | 20px | 600 | 28px | Recovered small display tier for inline display micro-headings. |
+| `{typography.title-lg}` | 40px | 600 | 41px | Kernel specimen headings and major section headings. |
+| `{typography.title-md}` | 30px | 600 | 32px | Standard section title. |
+| `{typography.title-sm}` | 22px | 600 | 25px | Cell and artifact titles. |
+| `{typography.body-lg}` | 18px | 400 | 27px | Hero/lead paragraphs. |
+| `{typography.body-md}` | 16px | 400 | 25px | Default body copy. |
+| `{typography.body-md-strong}` | 16px | 500 | 24px | Emphasised body copy at the default size. |
+| `{typography.body-sm}` | 14px | 400 | 20px | Secondary copy, nav, compact cell copy. |
+| `{typography.body-sm-strong}` | 14px | 500 | 20px | Emphasised secondary copy and compact labels. |
+| `{typography.caption}` | 12px | 400 | 16px | Footer secondary lines and badge labels. |
+| `{typography.caption-mono}` | 12px | 500 | 16px | Eyebrows, labels, status tags. |
+| `{typography.code}` | 13px | 400 | 20px | Tool calls, snippets, traces. |
+| `{typography.button-lg}` | 16px | 500 | 24px | Marketing-scale button labels. |
+| `{typography.button-md}` | 14px | 500 | 18px | Standard button and control labels. |
+
+## Layout
+
+The kernel layout is mathematical and single-owner.
+
+### Frame System
+
+- Marketing bands may use `{spacing.section}` when they need the broader inherited hero rhythm.
+- `page-system` adds `{spacing.page-pad}` horizontal page padding and `{spacing.4xl}` vertical padding, so the frame floats on clear canvas between the sticky nav chrome and the footer instead of stacking against their hairlines.
+- `page-frame` is centered and capped at `{spacing.frame-max}`. It owns the outer left/right/top borders.
+- `page-row` is the only direct section unit inside `page-frame`. It owns the bottom border for each row.
+- Desktop rows use 12 equal columns with `{spacing.frame-gap}` gutters.
+- `active-lane` spans columns 2 through 11 on desktop and all columns on smaller viewports.
+- Full-lane rows span all 12 columns only when the content owns columns 1 and 12 explicitly through the `stage` geometry (`nc-stage-frame`/`nc-stage-fill`/`nc-stage-grid`/`nc-stage-active`).
+- Columns 1 and 12 are the page's quiet margin: empty canvas by default. Their presence is the whitespace itself — the grid sizes them whether or not anything paints there, matching the reference container model where structure lives inside bounded modules and never as page-length gutter texture. The diagonal `side-fill` is a scarce structural accent a row opts into with `data-rails="hatch"`; reserve it for the page's anchor rows (the opening hero, the closing conversion row), never as a default on every row. When present, the fill is bounded on both sides — the frame perimeter outside, the fill's own inner rail inside — so the texture reads as a deliberate panel, not an unbounded wash.
+
+### Seam Ownership
+
+Every visible line has one owner. Do not draw borders on both adjacent children at the same coordinate. Use a line-colored parent background plus `{spacing.guide}` gaps, or use a single explicit border owned by the parent row/component.
+
+On a `blueprint-field` surface the model is draw-all-then-occlude: the texture layer owns every line uniformly and opaque content (`cell-solid` or a content slot) occludes the lines it covers. This is distinct from the parent-plus-gap model used by `cell-grid`; both keep exactly one owner per visible line.
+
+The universal guide weight is `{spacing.guide}`. Crosshairs use the same physical weight as the line they mark; they are darker through `{colors.cross}`, not thicker.
+
+### Responsive Rules
+
+Mobile collapses the 12-column frame to a single content column while preserving the outer frame. Tablet may use 2 or 3 internal tracks for repeated cell grids. Desktop restores the 12-column frame and centered 10-column active lane.
+
+Height tokens are fixed by component family and breakpoint. Components may grow when real content requires it, but the default specimen height comes from the exported height tokens so repeated rows align predictably.
+
+Page shells must prevent horizontal scrollbars when a mathematically aligned full-bleed surface uses viewport width. Clip horizontal overflow at the shell/root level; do not hide overflow on structural cells to mask bad seam math.
+
+Kernel compositions arrange approved primitives for a content role. They must not redefine page-frame math, row seams, marker placement, side-fill ownership, active-lane spans, or global guide primitives. If a composition needs new structural geometry, promote that geometry into the page grammar or a real component first.
+
+### Delivery Tiers
+
+Each reusable concern has one home and one authoring surface, so a member is documented and shipped in exactly one place:
+
+- **Tokens** — exact reusable values live in this contract's `colors`, `spacing`, `rounded`, and `typography`; they export to the generated token layer (with a hand-authored local token layer beside it). No component or section may re-encode a token value.
+- **Framework-agnostic CSS components** — the brand/display CSS components that remain in this package (the agent-chat family, the run-state `state-tag` family, `image`, and the small label/badge/link metadata components). Contracted CSS components are paired between `components:` YAML entries and `## Components` Markdown entries, and are realised by design-system CSS. The named CSS-internal components (`artifact-preview`, `typing-dots`, `state-row`) are documented exceptions: they realise brand display structure but carry no exported component token.
+- **Reusable compositions and sections** — patterns that arrange the page grammar and lower tiers for a content role. They ship as React shadcn compositions from `@nadicodeai/ui`, composed over the kept page grammar; they are not a pure-CSS section layer and carry no `components:` YAML entry or exported component token.
+- **Layout grammar** — the page-frame, row, lane, seam, stage, and marker system documented across this `## Layout` section, carried by the layout CSS layer.
+- **Specimens** — static demonstrations of already-defined primitives. They invent no geometry, seams, heights, or responsive behavior; they only assemble shipped tiers for inspection.
+
+The page grammar below is the `## Layout` home for the structural names; the section-level compositions that arrange them ship from `@nadicodeai/ui`.
+
+### Page Grammar
+
+Page grammar is the NadicodeAI structural system. It defines how pages are built before any content surface appears. These names do not live in YAML `components:`. Exact reusable values are exported through `colors`, `spacing`, `rounded`, and `typography`; the structural semantics live here as layout doctrine, not as interface components.
+
+**`page-frame`** (`nc-page-frame`) — centered bordered frame capped by `{spacing.frame-max}`. Owns the outer left/right/top seams.
+
+**`page-row`** (`nc-page-row`) — one continuous section row inside `page-frame`. Owns the bottom seam and default row background.
+
+**`active-lane`** — the centered 10-column lane. On desktop it spans columns 2 / 12; on smaller viewports it spans the row.
+
+**`side-fill`** (`nc-side-fill`) — the opt-in owner for columns 1 and 12 when a row uses the active lane. Hidden by default (the quiet-gutter doctrine: the empty margin column is the default treatment); a row enables it with `data-rails="hatch"` on the `page-row`, reserved for the page's anchor rows. When shown, it paints the diagonal filler, expands into the frame gutter so the texture touches the active content edge, and owns its single inner boundary rail (`{colors.line}` on its lane-facing edge) so the hatch is bounded on both sides — frame perimeter outside, fill rail inside.
+
+**`cell-grid`** (`nc-row-grid`) — repeated cell math. Uses `{colors.line}` parent background and `{spacing.guide}` gaps so the seam has one owner. Supports 2, 3, 4, 5, and 6 column desktop variants with responsive collapse.
+
+**`panel-cell`** — a square structural content cell inside `cell-grid`. Uses `{spacing.cell-padding}` and no local border.
+
+**`marker`** — sparse crosshair marker for major section/frame corners. It marks intersections; it is not decorative chrome for every card. It is placed on a grid-field track intersection and derives its position from the grid, not from a frame-relative offset.
+
+**`diagonal-fill`** — structural filler for outer columns and empty side lanes.
+
+**`dotted-field`** — artifact/canvas background for conversations, outputs, and diagrams. It indicates a work surface, not generic decoration.
+
+**`blueprint-field`** — a feathered structural-pitch background texture that visualizes a grid as graph-paper rather than as load-bearing DOM. Column and row pitch track the meaningful column count so it stays legible; the field is always feathered so it reads as texture, not as paper. On the blueprint surface the lines are drawn once underneath and occluded by opaque content (`cell-solid` or the content slot) — the draw-all-then-occlude model. It is incidental brand texture: if the blueprint field is the first thing you notice, it is too strong.
+
+**`rule-svg`** — bounded dashed connector rule. Uses `{colors.seam}` and never overlaps a cell seam.
+
+The generic marketing/SaaS section patterns (hero, bento stage, action/CTA band, split, card grid, pricing, testimonials, stats, FAQ, logo/integration walls, contact, newsletter, banner, article index, team) ship as React shadcn compositions from `@nadicodeai/ui`, composed over the kept page grammar above. This contract no longer documents them as a pure-CSS section layer; the page grammar is the framework-agnostic foundation those compositions assemble.
+
+### Related Layout Helpers
+
+These live helpers are part of the kept page-grammar layout layer. They are not YAML components: they support index/long-form page assemblies rather than naming an interface component.
+
+**`index-grid`** — layout helper for index-style page assemblies (blog, learn, and case-study rows whose guide layer owns the dividers).
+
+**`article-frame`** — layout helper for the long-form reading companion in article/index page assemblies.
+
+`index-card` is the repeated item class inside `index-grid`, not a standalone contract key.
+
+## Elevation & Depth
+
+NadicodeAI website depth is flat and architectural. Hairlines, contrast, dotted fields, diagonal fills, and dark action bands create hierarchy. Shadows are optional for small artifact cards only and must stay subtle.
+
+The public website should not rely on floating card stacks as the main structure. Cards may exist inside a cell as an artifact, but the page frame and row grid must remain the dominant structure.
+
+## Shapes
+
+Corners are restrained.
+
+- Use `{rounded.none}` for page rows, frame edges, grid cells, and structural modules.
+- Use `{rounded.sm}` to `{rounded.lg}` for buttons, chips, status tags, chat bubbles, and small artifacts.
+- Use `{rounded.full}` only for truly circular identity or avatar chrome.
+
+Cards are not rounded by default. A cell is usually square because its parent frame supplies the visual system.
+
+## Components
+
+Component entries are grouped by design-system family so the decision model stays small while the exported token surface remains available. YAML `components:` is reserved for reusable UI, content, and agentic-work surfaces with component-style token hooks. Page grammar and composition semantics live in `## Layout` and must not be duplicated in YAML `components:`.
+
+### Interface Atoms
+
+Interface CSS components provide small metadata, label, and link chrome. They inherit NadicodeAI tokens and stay subordinate to the page grammar; they must not create independent layout systems or repair structural seams. The generic interactive controls (navigation, buttons, inputs, footer chrome, the marketing card/code/pricing/proof surfaces, the standard sections) ship as React shadcn components from `@nadicodeai/ui`; this contract keeps only the brand/display CSS components and primitives that belong in the framework-agnostic package.
+
+Interactive CSS components must expose a visible `:focus-visible` state using the NadicodeAI link/accent family or a contrast-safe inverse on dark surfaces. Do not remove outlines without an equivalent replacement.
+
+**`label-mono`** — mono eyebrow/label text for section labels and low-priority metadata.
+
+**`badge-secondary`** — small rounded metadata badge for "New", "Beta", "Live", or similar labels.
+
+**`link-inline`** — inline body link. Uses `{colors.link}` and normal body rhythm.
+
+### Content Surfaces
+
+Content surfaces display specific content types inside the grammar. They are valid when the content exists; they do not replace the page frame, row model, or seam rules.
+
+**`image`** — editorial media mount, the single home for art-directed imagery inside the grammar. A bounded media fill (img, picture, video, or inline SVG) with an optional mono tag chip overlaid on the media and an optional body-tone caption bar below it, both typed by the generated caption utilities applied in markup. Square-cornered (`{rounded.none}`): a mounted print, not a floating card — the parent frame supplies the visual system. With `data-frame="true"` it draws exactly one hairline (its own `{colors.line}` border), so it sits inside a borderless `panel-cell` or a visual slot without repairing or stacking onto any grid seam. The aspect ratio is the per-instance `--nc-image-ratio` knob (default 4 / 3) — set the prop on the element, never re-derive geometry inline. Variant: `data-strip="true"` is the full-width divider form for thin editorial bands between page rows (thread, texture, panorama) — the ratio unlocks and the height resolves from the responsive `{spacing.h-strip-*}` tokens through the layout-layer collapsed alias. Use `image` for every illustrated image, photographic surface, or image divider; use `artifact-preview` when the visual is an agent-produced document surface.
+
+### Agentic Work Surfaces
+
+Agentic work surfaces are the NadicodeAI-specific layer. They show people and agents working together through conversations, artifacts, approvals, memory, state, tools, and handoffs. Use these when there is concrete work output or workflow state to inspect.
+
+**`artifact-surface`** — inspectable output area. Use for proposal previews, reports, plans, spreadsheets, schedules, approval states, source traces, run logs, workflow maps, and conversation artifacts.
+
+**`status-tag`** — mono status/proof label. Labels examples, internal states, anonymous examples, review states, or approved artifacts only when source support exists.
+
+**`status-tag-approved`** — approved or reviewed status variant. Uses the link soft surface and deep link text; only use when the source really supports approval or review.
+
+**`chat-thread`** — conversation container showing how people instruct, correct, review, or approve agents. Autoplaying threads carry an enhancer-injected pause/resume control (WCAG 2.2.2); the control is never authored in static markup.
+
+**`chat-bubble-user`** — human message bubble. Dark surface, white text.
+
+**`chat-bubble-agent`** — agent message bubble. Light surface, ink text.
+
+**`tool-call-trace`** — compact code/trace row. Use only when tool use is relevant to the explanation.
+
+State-tag variants share the same shape — a compact rectangular pill at `{typography.caption-mono}` — and differentiate by a 3 px colored `border-left` consuming the matching `{colors.state-*}` token. Shape carries meaning; color carries variant. State is never conveyed through swatches, dots, pulses, breathing animations, or loading spinners.
+
+**`state-tag-ready`** — workflow state tag for work that is ready or waiting to start. Uses `{colors.state-ready}` for the left edge.
+
+**`state-tag-running`** — workflow state tag for work currently being executed by an agent or system. Uses `{colors.state-running}` for the left edge.
+
+**`state-tag-review`** — workflow state tag for human review or approval. Uses `{colors.state-review}` for the left edge.
+
+**`state-tag-blocked`** — workflow state tag for blocked work or failed preconditions. Uses `{colors.state-blocked}` for the left edge.
+
+**`state-tag-complete`** — workflow state tag for completed work. Uses `{colors.state-complete}` for the left edge.
+
+**`approval-gate`** — human-in-the-loop pause surface. Use when an agent action requires explicit review, correction, approval, or rejection.
+
+**`agent-avatar`** — identity slot for an agent personality or role. The chrome is reusable; the visual asset is project-specific.
+
+**`usage-meter`** — token, cost, latency, or run-count display.
+
+**`run-timeline`** — vertical step thread for an agent run, handoff, or workflow execution.
+
+**`memory-item`** — remembered-fact row for company brain, context, or persistent workflow knowledge.
+
+**`handoff-banner`** — agent-to-agent or human-to-agent handoff surface. It explains the handoff reason and destination. It carries a 3 px colored `border-left` consuming the matching `{colors.link}` token and a leading direction marker tinted with the same token; the accent edge and arrow carry the handoff direction.
+
+## Do's and Don'ts
+
+### Do
+
+- Do build pages as continuous `page-row` sequences inside one `page-frame`.
+- Do keep centered content in the 10-column `active-lane` while preserving visible ownership of columns 1 and 12.
+- Do use `side-fill`, guide strips, or component-owned fillers whenever content does not occupy the outer columns.
+- Do use `{spacing.guide}` and `{colors.line}` for ordinary seams.
+- Do tune line visibility by changing `{colors.line}` at the token contract, then rebuilding generated exports.
+- Do use `{colors.cross}` for crosshair color while keeping crosshair weight equal to `{spacing.guide}`.
+- Do use fixed height tokens for default component/specimen height and let content grow only when required.
+- Do separate different story beats into separate rows.
+- Do use the full-lane `stage` geometry for one major use-case/artifact story, not as a container for every page concept.
+- Do make agent visuals show conversations, artifacts, review states, or work output.
+- Do keep ordinary CSS components compact and subordinate to the page grammar.
+- Do use pricing, logo, banner, and showcase compositions only when the page truly contains that content type.
+
+### Don't
+
+- Don't create naked centered 10-column sections without visible ownership of columns 1 and 12.
+- Don't draw the same seam from two adjacent elements.
+- Don't add borders inside cells to fix visual seams; fix the owner layer.
+- Don't tune seam contrast with local opacity, raw colors, or component-specific border colors.
+- Don't use viewport-scaled typography.
+- Don't use negative letter spacing in the website kernel.
+- Don't use gradients, decorative blobs, or atmospheric chrome as the page structure.
+- Don't name NadicodeAI components after external reference brands.
+- Don't promote homepage-specific copy, one-off page order, or prototype-only modules into this contract.
+- Don't use one full-lane stage to present multiple unrelated use cases.
+- Don't add component prop APIs, state matrices, screenshots, implementation notes, page placement examples, or framework-specific instructions to this file.
+- Don't use pricing, logo, or banner compositions as placeholder credibility or decoration when the underlying content does not exist.
+- Don't use status swatches, status dots, pulses, breathing animations, or loading spinners to communicate operational state; the `state-tag` family carries state through a 3 px colored `border-left`.
+- Don't animate outside the motion layer's four moves (Settle, Type, Confirm, Invite); `src/css/motion.css` owns the motion contract — register, vocabulary, craft rules, and what is banned.
+
+## Iconography
+
+Icons are derived from Lucide (ISC) and carry the NadicodeAI house render: 1.5 px
+stroke, butt caps, miter joins, no fill, and a stroke that tracks the surrounding
+text color. The render is consistent everywhere an icon appears — standalone and
+inside components — at sizes sm / md / lg = 12 / 16 / 24 px (md default), each
+tinted with a `{colors.*}` token. Rounded outer corners are retained — the
+engineered register comes from stroke weight and terminals, not squared geometry.