npm - @exxatdesignux/ui - Versions diffs - 0.5.11 → 0.5.12 - Mend

@exxatdesignux/ui 0.5.11 → 0.5.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/template/app/(app)/layout.tsx DELETED Viewed

@@ -1,77 +0,0 @@
-import { cookies } from "next/headers"
-import {
-  AppSidebar,
-  SidebarShell,
-  SecondaryPanelProvider,
-  SecondaryPanel,
-} from "@/components/sidebar"
-import {
-  SIDEBAR_STATE_COOKIE_NAME,
-  sidebarDefaultOpenFromCookie,
-} from "@/lib/sidebar-state-cookie"
-import { DashboardViewProvider } from "@/contexts/dashboard-view-context"
-import { ChartVariantProvider }  from "@/contexts/chart-variant-context"
-import { AskLeoProvider, AskLeoSidebar } from "@/components/ask-leo-sidebar"
-import { KeyMetricsAskLeoBridge } from "@/components/key-metrics-ask-leo-bridge"
-import { SystemBannerProvider } from "@/contexts/system-banner-context"
-import { SystemBannerSlot } from "@/components/system-banner-slot"
-import { CommandMenu } from "@/components/command-menu"
-import { CommandMenuProvider } from "@/contexts/command-menu-context"
-import { buildCommandMenuConfig } from "@/lib/command-menu-config"
-import { COMMAND_MENU_SEARCH_DATA_GROUPS } from "@/lib/command-menu-search-data"
-/**
- * Shared app layout:
- *   [          SystemBanner (main-page width)          ]
- *   [AppSidebar] [SecondaryPanel?] [page] [AskLeo?]
- *
- * The SystemBanner is configured from Settings (persisted to localStorage
- * via SystemBannerProvider) — no hardcoded copy here.
- */
-export default async function AppLayout({ children }: { children: React.ReactNode }) {
-  const cookieStore = await cookies()
-  const sidebarDefaultOpen = sidebarDefaultOpenFromCookie(
-    cookieStore.get(SIDEBAR_STATE_COOKIE_NAME)?.value,
-  )
-  const commandMenuConfig = buildCommandMenuConfig({
-    dataGroups: COMMAND_MENU_SEARCH_DATA_GROUPS,
-  })
-  return (
-    <DashboardViewProvider>
-    <ChartVariantProvider>
-    <AskLeoProvider>
-    <KeyMetricsAskLeoBridge>
-    <SystemBannerProvider>
-    <CommandMenuProvider value={commandMenuConfig}>
-    <SidebarShell defaultOpen={sidebarDefaultOpen} wrapperClassName="flex min-h-svh flex-col">
-      {/* ⌘K command palette */}
-      <CommandMenu />
-      <SystemBannerSlot />
-      {/* Sidebar + content row — flex-1 min-h-0 below min-h-svh shell; SidebarInset self-stretch + PrimaryPageTemplate flex-1 fills viewport when page body is short. */}
-      {/* suppressHydrationWarning: the Cursor IDE browser preview injects a
-          `data-cursor-ref` attribute on this layout root before React hydrates.
-          Scoped to this element's own attributes only. See companion comment
-          in components/templates/nested-secondary-panel-shell.tsx. */}
-      <div
-        className="flex min-h-0 w-full flex-1 items-stretch has-data-[variant=inset]:bg-sidebar"
-        suppressHydrationWarning
-      >
-        <SecondaryPanelProvider>
-          <AppSidebar variant="inset" />
-          <SecondaryPanel />
-          {children}
-        </SecondaryPanelProvider>
-        <AskLeoSidebar />
-      </div>
-    </SidebarShell>
-    </CommandMenuProvider>
-    </SystemBannerProvider>
-    </KeyMetricsAskLeoBridge>
-    </AskLeoProvider>
-    </ChartVariantProvider>
-    </DashboardViewProvider>
-  )
-}

package/template/app/global-error.tsx DELETED Viewed

@@ -1,63 +0,0 @@
-"use client"
-import * as React from "react"
-import "./globals.css"
-import { isChunkLoadError } from "@/lib/chunk-load-error"
-/**
- * Root error boundary — catches failures outside the (app) segment layout.
- */
-export default function GlobalError({
-  error,
-  reset,
-}: {
-  error: Error & { digest?: string }
-  reset: () => void
-}) {
-  const chunkStale = isChunkLoadError(error)
-  React.useEffect(() => {
-    if (process.env.NODE_ENV === "development") {
-      console.error(error)
-    }
-  }, [error])
-  return (
-    <html lang="en">
-      <body className="bg-background font-sans text-foreground">
-        <div
-          className="flex min-h-svh flex-col items-center justify-center gap-4 px-4 py-12 text-center"
-          role="alert"
-        >
-          <h1 className="text-lg font-semibold">Something went wrong</h1>
-          <p className="max-w-md text-sm text-muted-foreground">
-            {chunkStale
-              ? "The app loaded an outdated script bundle (common after a dev-server rebuild). Reload the page to fetch the latest chunks."
-              : process.env.NODE_ENV === "development"
-                ? error.message
-                : "Please try again. If the problem continues, contact support."}
-          </p>
-          <div className="flex flex-wrap items-center justify-center gap-2">
-            {chunkStale ? (
-              <button
-                type="button"
-                className="inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground"
-                onClick={() => window.location.reload()}
-              >
-                Reload page
-              </button>
-            ) : null}
-            <button
-              type="button"
-              className="inline-flex h-9 items-center justify-center rounded-md border border-input bg-background px-4 text-sm font-medium"
-              onClick={() => reset()}
-            >
-              Try again
-            </button>
-          </div>
-          </div>
-      </body>
-    </html>
-  )
-}

package/template/app/layout.tsx DELETED Viewed

@@ -1,133 +0,0 @@
-import type { Metadata, Viewport } from "next"
-import { Inter } from "next/font/google"
-import Script from "next/script"
-import "./globals.css"
-import { ThemeProvider } from "@/components/theme-provider"
-import { TooltipProvider } from "@/components/ui/tooltip"
-import { ProductProvider } from "@/contexts/product-context"
-import { DevChunkLoadRecovery } from "@/components/dev-chunk-load-recovery"
-import { ThemeColorSync } from "@/components/theme-color-sync"
-import { cn } from "@/lib/utils"
-/**
- * Inter — primary brand typeface for Exxat One (Lavender) and Exxat Prism (Rose).
- * Loaded via next/font for zero layout shift and optimal subsetting.
- */
-const inter = Inter({
-  subsets: ["latin"],
-  weight: ["300", "400", "500", "600", "700", "800"],
-  variable: "--font-sans",
-  display: "swap",
-})
-export const metadata: Metadata = {
-  title: "Exxat Design System",
-  description:
-    "Shared UI component library for Exxat One and Exxat Prism — built to WCAG 2.1 Level AA.",
-  icons: {
-    icon: "/favicon.ico",
-  },
-}
-export const viewport: Viewport = {
-  width: "device-width",
-  initialScale: 1,
-}
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode
-}>) {
-  return (
-    /**
-     * RTL: dir="rtl" mirrors layout for right-to-left languages.
-     * lang="en" is the default; override per-page for localised content.
-     *
-     * WCAG notes:
-     *  - suppressHydrationWarning prevents theme-flicker false positives.
-     *  - Theme classes (theme-one / theme-prism / dark) are managed by
-     *    ThemeProvider and applied to <html>.
-     *  - "theme-one" sets Exxat One Lavender as the default brand.
-     *    Replace with "theme-prism" to switch to Exxat Prism Rose.
-     */
-    <html
-      lang="en"
-      suppressHydrationWarning
-      className={cn(inter.variable)}
-    >
-      <head>
-        {/* Default until ThemeColorSync hydrates (brand + mode override client-side) */}
-        <meta name="theme-color" content="#f6f3ff" />
-        {/*
-         * Adobe Fonts — preconnect + preload Ivy Presto · Kit ID: wuk5wqn.
-         *
-         * Trust model & Subresource Integrity (SRI):
-         *  - Adobe Typekit serves *dynamically subsetted* CSS that hashes
-         *    differently per response, so SRI cannot be applied — the kit URL
-         *    is locked to a single Adobe-owned origin instead.
-         *  - `crossOrigin=""` (anonymous CORS) is set on both the preconnect
-         *    and the stylesheet so the browser uses one CORS-correct
-         *    connection for preconnect + preload + fetch, and so styles
-         *    cannot read first-party cookies or credentials.
-         *  - The same origins are pinned in `style-src` / `font-src` /
-         *    `connect-src` of the Content-Security-Policy declared in
-         *    `next.config.mjs`, which is what actually prevents arbitrary
-         *    third-party CSS/fonts from loading.
-         */}
-        <link rel="preconnect" href="https://use.typekit.net" crossOrigin="" />
-        <link rel="preconnect" href="https://p.typekit.net" crossOrigin="" />
-        <link
-          rel="preload"
-          href="https://use.typekit.net/wuk5wqn.css"
-          as="style"
-          crossOrigin=""
-        />
-        <link
-          rel="stylesheet"
-          href="https://use.typekit.net/wuk5wqn.css"
-          crossOrigin=""
-        />
-      </head>
-      <body className="bg-sidebar text-foreground font-sans">
-        <DevChunkLoadRecovery />
-        {/*
-         * Font Awesome Pro Kit — subset via fontawesome-subset.manifest.json +
-         * fontawesome.com/kits (Icon Selection).
-         *
-         * Trust model & SRI: the kit loader URL is content-versioned by
-         * fontawesome.com and rotates whenever the subset changes, so SRI
-         * cannot be pinned. We instead:
-         *  - Restrict the script to kit.fontawesome.com (and font/data fetch
-         *    to ka-f.fontawesome.com) via CSP `script-src` / `font-src` /
-         *    `connect-src` in `next.config.mjs`.
-         *  - Load with `crossOrigin="anonymous"` so the script runs with
-         *    CORS semantics and no credentials.
-         */}
-        <Script
-          src="https://kit.fontawesome.com/d9bd5774e0.js"
-          crossOrigin="anonymous"
-          strategy="afterInteractive"
-        />
-        <ThemeProvider
-          attribute="class"
-          defaultTheme="system"
-          enableSystem
-          disableTransitionOnChange
-        >
-          <ProductProvider>
-            <ThemeColorSync />
-            <TooltipProvider delayDuration={300}>
-              {/* Skip to main content — WCAG 2.4.1 (Bypass Blocks) */}
-              <a href="#main-content" className="skip-to-content">
-                Skip to main content
-              </a>
-              {children}
-            </TooltipProvider>
-          </ProductProvider>
-        </ThemeProvider>
-      </body>
-    </html>
-  )
-}

package/template/app/page.tsx DELETED Viewed

@@ -1,9 +0,0 @@
-import { redirect } from "next/navigation"
-/**
- * Root route — redirects to the main dashboard.
- * Add additional top-level routes here as the DS grows.
- */
-export default function Page() {
-  redirect("/dashboard")
-}

package/template/docs/HANDBOOK.md DELETED Viewed

@@ -1,187 +0,0 @@
-# Exxat DS — Handbook
-> **Start here.** One page. Read in 10 minutes. Links out to everything else.
->
-> **Audience:** designers, engineers, contributors, AI agents — anyone shipping UI in the Exxat product.
->
-> **Working with an AI assistant?** Read [`.cursor/skills/exxat-token-economy/SKILL.md`](../../.cursor/skills/exxat-token-economy/SKILL.md) **first** (or `.claude/skills/exxat-token-economy/SKILL.md` for Claude Code). It's a one-page pre-flight that cuts token usage by ~50%: a task → minimum-file-set table, the five-question rule check, and tiny scaffolds that mean the assistant never has to re-read this handbook for the common case.
----
-## 1. Five principles
-Every screen, primitive, and pattern in this design system serves one or more of these. When in doubt, the principle wins over the convenience.
-1. **Clarity over decoration.** Users see one product, one shell, one rhythm. Surprise (mystery icons, hidden states, novel layouts) is a tax on attention.
-2. **Progressive disclosure.** Beginners see what they need. Power users reach what they want. Default to the simpler surface; expose density on opt-in (Properties drawer, view tabs, secondary panel).
-3. **Same-shaped tools.** A hub looks like a hub. A drawer looks like a drawer. A KPI looks like a KPI. Pick the canonical primitive (§5 reference pages) before composing your own.
-4. **Accessibility is non-negotiable.** WCAG 2.1 AA is the **floor**, not the goal. Keyboard, screen-reader, contrast, touch-target, format hints — all enforced by rules, lints, and a checklist.
-5. **The data drives the chrome.** KPIs, status, trend polarity, descriptions — they come from the dataset (or the product) and are honest. No spin arrows, no decorative placeholders.
----
-## 2. How to build a hub in 6 steps
-This is the **happy path** for the most common task: "I have an entity (records, library items, tokens, …); ship a hub for it." Follow these in order and the page lands at "best UX/UI", not "random design".
-| Step | What to do | Where it lives | Rule |
-|---|---|---|---|
-| 1 | Add typed mock rows in `lib/mock/<entity>.ts`. Aim for ~12 realistic records. | `apps/web/lib/mock/` | `.cursor/rules/exxat-centralized-list-dataset.mdc` |
-| 2 | Write **one** KPI helper `lib/mock/<entity>-kpi.ts` returning `MetricItem[]` (≤ 4 tiles). | same | `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` |
-| 3 | Build the column defs (`ColumnDef[]`). Set `filter:` per column to get filter chips automatically. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
-| 4 | Mount **`HubTable`** (NOT raw `<DataTable>`) inside `ListPageTemplate.renderContent`. `HubTable` wires `useTableState`, toolbar (search + filter chips + sort), and the **Properties drawer** in one place. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
-| 5 | Compose the page client with `PrimaryPageTemplate` → `ListPageTemplate` (KPIs in `metrics`, view tabs in `defaultTabs`, the `HubTable` in `renderContent`). | `apps/web/components/<entity>-client.tsx` | `exxat-list-page-connected-views.mdc` |
-| 6 | Add to nav (`lib/mock/navigation.tsx`). If the hub needs scoped sub-navigation (e.g. categories), declare `secondaryPanel: "<id>"` and register the panel. | `apps/web/lib/mock/navigation.tsx`, `apps/web/components/sidebar/secondary-panel.tsx` | `exxat-primary-nav-secondary-panel.mdc` |
-**Reference pages to copy:** `apps/web/components/library-table.tsx` + `library-client.tsx` (canonical seven-view hub), `apps/web/components/columns-showcase.tsx` (custom columns + same Add view via `LibraryTable`), `apps/web/components/tokens-themes-client.tsx` + `tokens-hub-auxiliary-views.tsx`. See **`hub-supported-views-pattern.md`** before changing Add view.
-> **Stop signs.** If you find yourself building a parallel table stack, a second metrics strip, a custom filter row, or pasting raw `<DataTable>` into `renderContent` — **stop and re-read** `.cursor/rules/exxat-reuse-before-custom.mdc`.
----
-## 3. Where everything lives
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ PRINCIPLES + HANDBOOK   →  docs/HANDBOOK.md (this file)             │
-│                                                                     │
-│ FOUNDATIONS                                                         │
-│   tokens                →  docs/token-taxonomy.md                   │
-│   icons (Font Awesome)  →  .cursor/rules/exxat-fontawesome-icons    │
-│   typography            →  docs/token-taxonomy.md (font-* tokens)   │
-│   spacing / radius      →  docs/token-taxonomy.md (--exxat-*)       │
-│   color & themes        →  apps/web/components/tokens-themes-*      │
-│   voice & tone          →  docs/voice-and-tone.md                   │
-│   glossary              →  docs/glossary.md                         │
-│   reference pages       →  docs/reference-implementations.md        │
-│                                                                     │
-│ DECIDING (selection guides)                                         │
-│   which component?      →  docs/component-selection-guide.md        │
-│   page vs drawer vs     →  docs/drawer-vs-dialog-pattern.md         │
-│     dialog vs route        + .cursor/rules/exxat-{drawer-vs-dialog, │
-│                              page-vs-drawer}.mdc                    │
-│   card vs row vs list   →  docs/card-vs-rows-pattern.md             │
-│                                                                     │
-│ BLUEPRINTS  (framework-agnostic specs — one per pattern)            │
-│                         →  docs/blueprints/                         │
-│                            page-header · data-table ·               │
-│                            list-page-template · board-card ·        │
-│                            key-metrics                              │
-│                                                                     │
-│ PATTERNS  (long-form narrative — the "why" + the "how")             │
-│                         →  docs/*.md (data-views-pattern,           │
-│                            kpi-trend-pattern, drawer-vs-dialog-     │
-│                            pattern, dedicated-search,               │
-│                            command-menu, …)                         │
-│                                                                     │
-│ RULES  (binding MUST / MUST NOT — for AI agents + reviewers)        │
-│                         →  .cursor/rules/*.mdc                      │
-│                                                                     │
-│ SKILLS  (workflows + checklists — for AI agents doing a task)       │
-│                         →  .cursor/skills/  +  .claude/skills/      │
-│                                                                     │
-│ MIGRATIONS  (deprecation history, every breaking change)            │
-│                         →  docs/migrations/                         │
-│                                                                     │
-│ AGENT HANDBOOK  (authoritative §-numbered manual)                   │
-│                         →  apps/web/AGENTS.md                       │
-└─────────────────────────────────────────────────────────────────────┘
-```
-### Quick "which file should I open?" cheat-sheet
-| You want to… | Open this |
-|---|---|
-| Pick the right component for a job | [`docs/component-selection-guide.md`](./component-selection-guide.md) |
-| Know what "hub" / "view tab" / "KPI band" mean | [`docs/glossary.md`](./glossary.md) |
-| Write empty-state / error / button copy | [`docs/voice-and-tone.md`](./voice-and-tone.md) |
-| Find the canonical reference page to copy | [`docs/reference-implementations.md`](./reference-implementations.md) |
-| Know the spec for a pattern | [`docs/blueprints/`](./blueprints/) |
-| Understand the "why" of a pattern | [`docs/<pattern>-pattern.md`](.) |
-| Know the binding MUST / MUST NOT | [`.cursor/rules/`](../../../.cursor/rules/) |
-| Run a recurring agent workflow | [`.cursor/skills/`](../../../.cursor/skills/) or [`.claude/skills/`](../../../.claude/skills/) |
-| Token name & semantics | [`docs/token-taxonomy.md`](./token-taxonomy.md) |
-| Full authoritative handbook | [`apps/web/AGENTS.md`](../AGENTS.md) |
----
-## 4. Rule precedence (when sources conflict)
-If two docs say different things, **the higher row wins**:
-1. **`.cursor/rules/*.mdc`** — these are MUST / MUST NOT; they bind the AI agent and the reviewer.
-2. **`apps/web/AGENTS.md`** — authoritative §-numbered handbook. The rules above are summaries of this.
-3. **`docs/blueprints/*.md`** — framework-agnostic specs for a single pattern.
-4. **`docs/*-pattern.md`** — long-form narrative for a pattern.
-5. **Reference page in code** (`apps/web/components/<reference>.tsx`) — the working implementation.
-6. **This handbook** — orientation only. If it conflicts with rules or AGENTS, the rules/AGENTS win.
-> **Found a conflict?** Open a PR that updates the *binding* layer (rule or AGENTS section) first, then propagate down. Don't fork the truth.
----
-## 5. The canonical primitives (memorize these)
-These are the ones you'll use on >90% of screens. If a screen needs something else, it almost certainly already exists — search `components/` before building.
-| Need | Primitive | Lives in |
-|---|---|---|
-| Page chrome (breadcrumbs, site header, max-width content rail) | `PrimaryPageTemplate` | `apps/web/components/templates/primary-page-template.tsx` |
-| Hub frame (header + metrics + view tabs + content) | `ListPageTemplate` | `packages/ui` |
-| **Hub view body** (table + search + filters + Properties drawer + bulk-actions) | **`HubTable`** | `packages/ui` (re-exported from `@/components/data-views`) |
-| Page header (title + subtitle + actions + collaborators rail) | `PageHeader` | `apps/web/components/page-header.tsx` |
-| KPI strip / band | `KeyMetrics` (`variant="flat"` on hubs) | `packages/ui` |
-| Status chip + icon | `ListHubStatusBadge` + `lib/list-status-badges.ts` | `apps/web/components/` |
-| Board / kanban card | `ListPageBoardCard` + primitives | `packages/ui` |
-| Side overlay | `Sheet` floating panels (NOT toast — `exxat-no-toast.mdc`) | `packages/ui` |
-| Persistent banner | `LocalBanner` / `SystemBanner` | `packages/ui` |
-| Inline status / format hint | `FormDescription`, inline `<small>` | `packages/ui` |
-| Tooltip | `Tip` / `Tooltip` | `packages/ui` |
-| Keyboard shortcut hint | `Kbd` (`variant="bare"` inside buttons) | `packages/ui` |
-| Global search | `CommandMenu` (⌘K) | `apps/web/components/command-menu.tsx` |
-| AI assistant chrome | Ask Leo side panel (⌘⌥K) | `apps/web/components/` |
-For a fuller decision tree see [`docs/component-selection-guide.md`](./component-selection-guide.md).
----
-## 6. The shortest accessibility checklist
-Run this on every PR. If you can't tick every box, the change isn't ready. (Full list: `.cursor/skills/exxat-accessibility/SKILL.md` and [`AGENTS.md` §8](../AGENTS.md).)
-- [ ] **Keyboard.** Every interactive thing reachable via Tab + activatable via Enter / Space. Focus ring visible (≥ 3:1).
-- [ ] **Touch target ≥ 24×24 CSS px** (or 24 px spacing) per WCAG 2.5.8.
-- [ ] **Icons that mean something** have a text alt — either adjacent label (Case A, `aria-hidden`), or `role="img" + aria-label + Tooltip` (Case B), or `aria-label + Tooltip` on the button (Case C). No silent icons.
-- [ ] **Contrast.** Text ≥ 4.5:1; UI components ≥ 3:1. Don't encode state with color alone — pair with icon or label.
-- [ ] **Format hints are persistent**, never placeholder-only. Use `FormDescription`.
-- [ ] **Dialogs / drawers / sheets** have a `Title` (use `sr-only` if visually hidden).
-- [ ] **Tabs** use `role="tablist"` correctly (no mixed children); composite switchers use `role="toolbar"` instead.
-- [ ] **No toast.** Use banners, inline status, or dialogs (`exxat-no-toast.mdc`).
-- [ ] **HC modes.** Forced-colors and `data-contrast="high"` covered for any fill-only state (progress, gauge, pill).
----
-## 7. The "you're done" definition
-A hub or screen is **done** when:
-1. It uses `PrimaryPageTemplate` + `ListPageTemplate` (or another canonical template).
-2. The data surface is `HubTable` (or, for non-hubs, the right primitive from §5).
-3. KPIs use `KeyMetrics` with `delta` for counts, `description` for prose, ≤ 4 tiles, polarity set correctly.
-4. The §6 accessibility checklist is green.
-5. Copy passes [`docs/voice-and-tone.md`](./voice-and-tone.md).
-6. No new shared primitives were added without `.cursor/rules/exxat-reuse-before-custom.mdc` approval.
-7. The §13 PR-review checklist in [`AGENTS.md`](../AGENTS.md#section-13) is green.
----
-## 8. Where to ask for help
-- **Code-level questions** — open the file referenced in a rule's "See also" section.
-- **Pattern-level questions** — open the matching `docs/*-pattern.md`.
-- **"Is this the right approach?"** — read [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../../.cursor/rules/exxat-reuse-before-custom.mdc). If still unsure, ask before building.
-- **AGENTS.md is too long** — that's why this handbook exists. Bring the §-number you're stuck on; we'll split it out.
----
-*This file is intentionally short. If you want to add something, ask whether it belongs in a rule, a pattern, a blueprint, or the glossary instead.*

package/template/docs/blueprints/README.md DELETED Viewed

@@ -1,86 +0,0 @@
-# Exxat DS — Blueprints
-**Audience:** humans + AI agents.
-**Inspired by:** [SLDS Component Blueprints](https://www.lightningdesignsystem.com/components).
-A **blueprint** is a **framework-agnostic spec** for a UI pattern. It says
-*what* the pattern is, *what it must do*, and *what tokens it consumes* —
-**without committing to any one implementation**.
-A **component** is the React + Tailwind implementation that satisfies the
-blueprint inside this app.
-| Blueprint says… | Component does… |
-|---|---|
-| "A page header has a title, optional icon, optional meta line, optional action slot, optional `+ N collaborators` rail" | `PageHeader` renders that with `variant="object-home" / "record-home" / "collaboration"` etc. |
-| "A data list is a sortable, filterable, columnable grid of records with search, properties drawer, and view tabs" | `DataTable` + `ListPageTemplate` + `TablePropertiesDrawer` compose to satisfy this |
----
-## Why blueprints exist
-1. **They survive framework changes.** If we ever ship a second consumer
-   (mobile, embed widget, design-token export to Figma), the blueprint stays
-   true; only the implementation changes.
-2. **They make the design language explicit.** New contributors can read a
-   single page that says "this is what a page header **is** at Exxat" without
-   spelunking through React props.
-3. **They let designers, engineers, and AI agents share one vocabulary.** The
-   blueprint is the contract; the React component is the receipt.
----
-## Anatomy of a blueprint doc
-Each blueprint follows the same template. Copy it from
-[`_template.md`](./_template.md) when adding a new one.
-```
-# <Blueprint name>
-## 1. Intent          → What user need does this solve? When NOT to use it.
-## 2. Anatomy         → Required + optional slots, with an ASCII or markdown sketch.
-## 3. States          → Default, hover, active, disabled, loading, empty, error, RTL.
-## 4. Tokens consumed → Exact token names from `docs/token-taxonomy.md`.
-## 5. Accessibility   → Roles, focus order, keyboard, screen-reader.
-## 6. Variants        → Named families that share anatomy but swap layout/density.
-## 7. Implementation  → Table of frameworks → component(s); React is required.
-## 8. Do / Don't      → Anti-patterns + correct alternatives.
-## 9. References      → Linked AGENTS.md sections, cursor rules, related blueprints.
-```
-The React row in §7 is **required**; other frameworks are listed as `—` until
-they ship.
----
-## Authoritative file pointers
-For most patterns, the blueprint complements an existing narrative doc — it
-does **not** replace it. The blueprint is the spec; the narrative is the deep
-dive.
-| Blueprint | Narrative doc | Cursor rule(s) | React component(s) |
-|---|---|---|---|
-| [page-header](./page-header.md) | `apps/web/docs/data-views-pattern.md` (Page header section) | `exxat-collaboration-access.mdc` (variant), `exxat-mono-ids.mdc` (subtitle IDs) | `PageHeader`, `PlacementsPageHeader`, `TeamPageHeader`, `LibraryPageHeader` |
-| [data-table](./data-table.md) | `apps/web/docs/data-views-pattern.md` | `exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc` | `DataTable`, `DataTablePaginated`, `useTableState`, `TablePropertiesDrawer` |
-| [list-page-template](./list-page-template.md) | `apps/web/docs/data-views-pattern.md`, `kpi-flat-band-pattern.md` | `exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc`, `exxat-list-page-view-shells.mdc` | `ListPageTemplate`, `HubTable`, `useTableState`, `TablePropertiesDrawer` |
-| [board-card](./board-card.md) | `apps/web/docs/data-views-pattern.md` (board UI section) | `exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc` | `ListPageBoardCard`, `ListPageBoardCardTitleRow`, `ListPageBoardCardBadgeRow`, `BoardCardTwoLineBlock`, `BoardCardIconRow`, `ListHubStatusBadge` |
-| [key-metrics](./key-metrics.md) | `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md` | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` | `KeyMetrics`, `MetricItem`, `MetricInsight`, `KeyMetricsProvider` |
-Future blueprints to write (open a PR when adding one):
-- `drawer-vs-dialog.md` — overlay decision (already in `docs/drawer-vs-dialog-pattern.md`, formalize as blueprint)
-- `command-menu.md` — global ⌘K palette + Ask Leo split
-- `dedicated-search.md` — landing vs results
-- `sidebar.md` — primary nav + secondary panel + product switcher
-- `coach-mark.md` — onboarding tours
-- `status-badge.md` — `ListHubStatusBadge` + `lib/list-status-badges.ts`
----
-## See also
-- [`apps/web/docs/token-taxonomy.md`](../token-taxonomy.md) — the design-token namespace these blueprints reference
-- [`apps/web/docs/component-selection-guide.md`](../component-selection-guide.md) — decision tree across blueprints
-- [`apps/web/AGENTS.md`](../../AGENTS.md) §9 architecture pointers (component reuse table)

package/template/docs/blueprints/_template.md DELETED Viewed

@@ -1,91 +0,0 @@
-# Blueprint: <Name>
-> **Status:** Draft / Stable. **Owner:** <team or person>. **Implements:** <SC refs>.
-## 1. Intent
-What user need does this pattern solve? In one paragraph.
-**Use when:**
-- Bullet
-- Bullet
-**Do NOT use when:**
-- Bullet
-## 2. Anatomy
-ASCII / markdown sketch with labelled slots. List every named slot and whether
-it is required, optional, or conditional.
-```
-┌──────────────────────────────────────────┐
-│ [icon]  Title                  [actions] │  ← slot: title-row (required)
-│ ───────────────────────────────────────  │
-│ subtitle · ID · meta                     │  ← slot: meta (optional)
-└──────────────────────────────────────────┘
-```
-| Slot | Required? | What it carries |
-|---|---|---|
-| `title` | required | Single H1 string |
-| `icon` | optional | FA glyph or product mark |
-| `actions` | optional | Primary CTA + optional `⋯` overflow |
-| `meta` | optional | Count · freshness · sort summary |
-## 3. States
-| State | Visual / behavior |
-|---|---|
-| Default | … |
-| Loading | … |
-| Empty | … |
-| Error | … |
-| RTL | … |
-## 4. Tokens consumed
-List every token the blueprint references from
-[`docs/token-taxonomy.md`](../token-taxonomy.md). Be precise — no "a brand
-color"; name `--brand-color`.
-| Token | Used for |
-|---|---|
-| `--background` / `--foreground` | Surface + ink |
-| … | … |
-## 5. Accessibility
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.1.1 Non-text content | Icons are decorative (Case A) when adjacent to text; standalone icons follow Case B (label + tooltip) |
-| 1.3.1 Info & relationships | … |
-| 2.1.1 Keyboard | Tab order: … |
-| 2.4.6 Headings / labels | The title slot is the `<h1>` for the route |
-| 2.4.11 Focus visible | Inherits `:focus-visible` ring (≥ 3:1) |
-## 6. Variants
-| Variant | When to use | Differences from default |
-|---|---|---|
-| `base` | … | — |
-## 7. Implementation
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `PrimaryComponent` + `RelatedComponent` | `apps/web/components/<file>.tsx` |
-| Mobile | — | — |
-| Figma | — | — |
-## 8. Do / Don't
-| ✅ Do | ❌ Don't |
-|---|---|
-| Bullet | Bullet |
-## 9. References
-- `apps/web/docs/<related-narrative>.md`
-- `.cursor/rules/<related-rule>.mdc`
-- `apps/web/AGENTS.md` §<section>