@lucasvu/scope-ui 0.1.0 → 0.1.2

package/dist/chunk-CL3F2TWE.js

@@ -0,0 +1,1039 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/ai-manifest.ts
+var uiAiManifest = {
+  packageName: "@lucasvu/scope-ui",
+  styleImport: "@lucasvu/scope-ui/styles.css",
+  rules: [
+    "Import the stylesheet once at the app entry before rendering any component.",
+    "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.",
+    "Collect the shell + screen brief first: layout preset, workspace label, route url, sidebar items, active sidebar item, page title, tabs/actions, and the page-specific content schema.",
+    "If the project ships a generated layout preset file, keep the shell aligned with it instead of inventing a new page frame.",
+    "Prefer the canonical component for each intent instead of mixing legacy MainFe components.",
+    "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.",
+    "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.",
+    'Always provide a stable rowKey to DataTable and use sortMode="server" when sorting happens on the backend.',
+    "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.",
+    "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."
+  ],
+  components: [
+    {
+      name: "Primary action",
+      importName: "Button",
+      purpose: "Render the main clickable action.",
+      useWhen: [
+        "Submitting a form",
+        "Triggering create/save/confirm flows",
+        "Need loading or block width support"
+      ],
+      avoidWhen: [
+        "Pure navigation text links without button semantics"
+      ],
+      props: [
+        { name: "variant", type: "'default' | 'secondary' | 'ghost' | 'outline' | 'destructive' | 'link' | 'confirm' | 'create'", description: "Chooses the visual emphasis." },
+        { name: "size", type: "'sm' | 'md' | 'lg' | 'icon'", description: "Chooses the button size." },
+        { name: "block", type: "boolean", description: "Expands the button to full width." },
+        { name: "loading", type: "boolean", description: "Shows a spinner and disables interaction." }
+      ],
+      example: "<Button variant='create' block>Save changes</Button>",
+      related: ["Alert", "Card"]
+    },
+    {
+      name: "Single-line text input",
+      importName: "Input",
+      purpose: "Capture short text, email, password, number-like strings, or search text.",
+      useWhen: [
+        "A single text value is needed",
+        "You need label/helper/error handling built in",
+        "You need prefix, suffix, or password toggle support"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above the control." },
+        { name: "helperText", type: "ReactNode", description: "Supplemental guidance shown below." },
+        { name: "errorMessage", type: "ReactNode", description: "Validation message shown below in error state." },
+        { name: "prefix", type: "ReactNode", description: "Visual prefix inside the field." },
+        { name: "suffix", type: "ReactNode", description: "Visual suffix inside the field." }
+      ],
+      example: "<Input label='Email' type='email' placeholder='you@example.com' />",
+      related: ["Textarea", "NumericInput", "Field"]
+    },
+    {
+      name: "Multiline text input",
+      importName: "Textarea",
+      purpose: "Capture longer free-form content.",
+      useWhen: [
+        "The user needs multiple lines of text",
+        "A description, note, or comment field is needed"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above the textarea." },
+        { name: "rows", type: "number", description: "Controls initial textarea height." },
+        { name: "helperText", type: "ReactNode", description: "Supplemental guidance shown below." },
+        { name: "errorMessage", type: "ReactNode", description: "Validation message shown below in error state." }
+      ],
+      example: "<Textarea label='Description' rows={5} placeholder='Write the details...' />",
+      related: ["Input", "Field"]
+    },
+    {
+      name: "Single select",
+      importName: "Select",
+      purpose: "Pick one value from a small fixed option set.",
+      useWhen: [
+        "Fewer options and no search is required",
+        "A simple dropdown is enough"
+      ],
+      props: [
+        { name: "options", type: "SelectOption[]", required: true, description: "List of selectable options." },
+        { name: "label", type: "ReactNode", description: "Field label rendered above the trigger." },
+        { name: "placeholder", type: "string", description: "Placeholder shown when no value is selected." },
+        { name: "onChange", type: "(value) => void", description: "Returns the original option value type." }
+      ],
+      example: "<Select label='Plan' options={[{ label: 'Starter', value: 'starter' }]} />",
+      related: ["SearchableSelect", "Combobox"]
+    },
+    {
+      name: "Searchable local select",
+      importName: "SearchableSelect",
+      purpose: "Pick one value from a larger in-memory list with search.",
+      useWhen: [
+        "More than a handful of options exist",
+        "Local filtering is enough"
+      ],
+      props: [
+        { name: "options", type: "SearchableSelectOption[]", required: true, description: "List of selectable options." },
+        { name: "searchPlaceholder", type: "string", description: "Placeholder inside the search field." },
+        { name: "onSearch", type: "(query) => void", description: "Receives the local search query." }
+      ],
+      example: "<SearchableSelect label='Country' searchPlaceholder='Search country' options={countries} />",
+      related: ["Select", "Combobox", "AsyncCombobox"]
+    },
+    {
+      name: "Type and pick",
+      importName: "Combobox",
+      purpose: "Let the user type and choose from a filtered list.",
+      useWhen: [
+        "A command-palette-like input is needed",
+        "The typed text should stay visible in the input"
+      ],
+      props: [
+        { name: "options", type: "ComboboxOption[]", required: true, description: "List of options to filter." },
+        { name: "value", type: "string | number", description: "Selected value." },
+        { name: "onChange", type: "(value) => void", description: "Selected value callback." }
+      ],
+      example: "<Combobox label='Assignee' options={users} value={assigneeId} onChange={setAssigneeId} />",
+      related: ["SearchableSelect", "AsyncCombobox"]
+    },
+    {
+      name: "Remote search combobox",
+      importName: "AsyncCombobox",
+      purpose: "Search and pick from server-backed data.",
+      useWhen: [
+        "Options are loaded from an API",
+        "Infinite scroll or async fetching is needed"
+      ],
+      props: [
+        { name: "options", type: "ComboboxOption[]", required: true, description: "Currently loaded options." },
+        { name: "loading", type: "boolean", description: "Shows async loading state." },
+        { name: "onSearch", type: "(query) => void", required: true, description: "Triggers remote search." },
+        { name: "onLoadMore", type: "() => void", description: "Loads more options when scrolling near the end." }
+      ],
+      example: "<AsyncCombobox label='User' options={options} loading={loading} onSearch={searchUsers} />",
+      related: ["Combobox", "SearchableSelect"]
+    },
+    {
+      name: "Multiple selection",
+      importName: "MultiSelect",
+      purpose: "Choose many values from a searchable list.",
+      useWhen: [
+        "The user can pick multiple tags, users, or filters"
+      ],
+      props: [
+        { name: "options", type: "MultiSelectOption[]", required: true, description: "List of selectable options." },
+        { name: "value", type: "Array<string | number>", description: "Selected values." },
+        { name: "onChange", type: "(values) => void", description: "Selected values callback." }
+      ],
+      example: "<MultiSelect label='Tags' options={tagOptions} value={tags} onChange={setTags} />",
+      related: ["Select", "SearchableSelect"]
+    },
+    {
+      name: "Structured field wrapper",
+      importName: "Field",
+      purpose: "Add a shared label/helper/error wrapper around custom content.",
+      useWhen: [
+        "Wrapping a custom control that does not expose label props",
+        "Grouping multiple controls under one heading"
+      ],
+      avoidWhen: [
+        "A built-in form control already renders its own label and helper text"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above children." },
+        { name: "helperText", type: "ReactNode", description: "Helper text below children." },
+        { name: "errorMessage", type: "ReactNode", description: "Error text below children." },
+        { name: "htmlFor", type: "string", description: "Associates the label with the wrapped control id." }
+      ],
+      example: "<Field label='Schedule' htmlFor='range'><DateRangePicker id='range' /></Field>",
+      related: ["Input", "Textarea", "Select"]
+    },
+    {
+      name: "Data table",
+      importName: "DataTable",
+      purpose: "Render sortable tabular data with optional selection, actions, loading, and pagination.",
+      useWhen: [
+        "Displaying records in rows and columns",
+        "Sort, pagination, selection, or row actions are required"
+      ],
+      props: [
+        { name: "columns", type: "DataTableColumn<T>[]", required: true, description: "Column definitions." },
+        { name: "data", type: "T[]", required: true, description: "Rows to render." },
+        { name: "rowKey", type: "keyof T | ((record: T) => string | number)", required: true, description: "Stable key for each row." },
+        { name: "pagination", type: "DataTablePagination", description: "Enables pagination controls." },
+        { name: "sortMode", type: "'client' | 'server'", description: "Choose client or backend sorting." }
+      ],
+      example: "<DataTable rowKey='id' columns={columns} data={rows} pagination={pagination} />",
+      related: ["Card", "Pagination", "Loading"]
+    },
+    {
+      name: "Status message",
+      importName: "Alert",
+      purpose: "Communicate neutral, success, warning, or danger states.",
+      useWhen: [
+        "You need a visible status or validation banner"
+      ],
+      props: [
+        { name: "tone", type: "'neutral' | 'info' | 'success' | 'warning' | 'danger'", description: "Semantic tone mapping." },
+        { name: "title", type: "ReactNode", description: "Alert headline." },
+        { name: "description", type: "ReactNode", description: "Supporting message." }
+      ],
+      example: "<Alert tone='warning' title='Missing information' description='Please fill all required fields.' />",
+      related: ["Loading", "Card"]
+    },
+    {
+      name: "Layout section",
+      importName: "Card",
+      purpose: "Wrap a coherent chunk of UI in a bordered surface.",
+      useWhen: [
+        "Building forms, dashboards, settings sections, or summary panels"
+      ],
+      props: [
+        { name: "className", type: "string", description: "Adds layout-specific spacing or width." }
+      ],
+      example: "<Card><CardHeader><CardTitle>Account</CardTitle></CardHeader><CardContent>...</CardContent></Card>",
+      related: ["CardHeader", "CardTitle", "CardContent", "CardFooter"]
+    }
+  ]
+};
+
+// src/screen-blueprint.ts
+var uiScreenBriefFields = [
+  {
+    id: "layoutPreset",
+    label: "Layout preset",
+    description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.",
+    required: false,
+    appliesTo: ["all"],
+    example: "workspace-admin-v1"
+  },
+  {
+    id: "workspaceLabel",
+    label: "Workspace label",
+    description: "Short label shown in the sidebar or workspace topbar.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Workspace"
+  },
+  {
+    id: "timezoneLabel",
+    label: "Timezone/meta label",
+    description: "Short meta label shown in the top-right shell area, such as a timezone or environment.",
+    required: false,
+    appliesTo: ["all"],
+    example: "UTC+07:00"
+  },
+  {
+    id: "pageKind",
+    label: "Page kind",
+    description: "Choose the base recipe for the screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "list"
+  },
+  {
+    id: "routeUrl",
+    label: "Route URL",
+    description: "Final route for the screen or feature entry.",
+    required: true,
+    appliesTo: ["all"],
+    example: "/admin/users"
+  },
+  {
+    id: "sidebarItems",
+    label: "Sidebar items",
+    description: "Sidebar entries with at least id, title, and href so the shell stays consistent.",
+    required: true,
+    appliesTo: ["all"],
+    example: '[{ id: "users", title: "Users", href: "/admin/users" }]'
+  },
+  {
+    id: "activeSidebarItemId",
+    label: "Active sidebar item id",
+    description: "The sidebar item that should appear active on this screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "users"
+  },
+  {
+    id: "breadcrumbs",
+    label: "Breadcrumbs",
+    description: "Ordered breadcrumb items for the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Admin", href: "/admin" }, { label: "Users", current: true }]'
+  },
+  {
+    id: "pageTitle",
+    label: "Page title",
+    description: "Main page heading shown in the content header.",
+    required: true,
+    appliesTo: ["all"],
+    example: "Users"
+  },
+  {
+    id: "pageSubtitle",
+    label: "Page subtitle",
+    description: "Short supporting text under the title.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Manage internal user accounts and permissions."
+  },
+  {
+    id: "pageTabs",
+    label: "Page tabs",
+    description: "Optional segmented tabs rendered under the intro card.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ value: "overview", label: "Overview" }, { value: "coupons", label: "Coupons" }]'
+  },
+  {
+    id: "activePageTab",
+    label: "Active page tab",
+    description: "The selected segmented tab value when tabs are present.",
+    required: false,
+    appliesTo: ["all"],
+    example: "coupons"
+  },
+  {
+    id: "primaryAction",
+    label: "Primary action",
+    description: "The highest-emphasis action shown in the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '{ label: "Create user", href: "/admin/users/create" }'
+  },
+  {
+    id: "secondaryActions",
+    label: "Secondary actions",
+    description: "Additional header actions such as export, refresh, or cancel.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Export" }, { label: "Refresh" }]'
+  },
+  {
+    id: "summaryStats",
+    label: "Summary stats",
+    description: "Top-line numbers for dashboard or overview screens.",
+    required: false,
+    appliesTo: ["dashboard", "detail"],
+    example: '[{ label: "Active users", value: "1,204", trend: "up", delta: "+12%" }]'
+  },
+  {
+    id: "filters",
+    label: "Filters",
+    description: "Filter bar controls shown above list or dashboard content.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
+  },
+  {
+    id: "searchPlaceholder",
+    label: "Search placeholder",
+    description: "Placeholder text for the main toolbar search input when the shell includes one.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: "Search by coupon code"
+  },
+  {
+    id: "tableColumns",
+    label: "Table columns",
+    description: "Columns for a list table, including label and render intent.",
+    required: false,
+    appliesTo: ["list", "detail", "dashboard"],
+    example: '[{ key: "name", title: "Name" }, { key: "role", title: "Role" }]'
+  },
+  {
+    id: "rowActions",
+    label: "Row actions",
+    description: "Per-row actions for table screens.",
+    required: false,
+    appliesTo: ["list", "detail"],
+    example: '[{ label: "Edit" }, { label: "Reset password" }]'
+  },
+  {
+    id: "formSections",
+    label: "Form sections",
+    description: "Grouped form sections and the fields inside each section.",
+    required: false,
+    appliesTo: ["form"],
+    example: '[{ title: "Basic info", fields: ["name", "email", "role"] }]'
+  },
+  {
+    id: "fields",
+    label: "Fields",
+    description: "Detailed field list with type, label, required state, and helper text.",
+    required: false,
+    appliesTo: ["form", "detail"],
+    example: '[{ name: "email", type: "input", label: "Email", required: true }]'
+  },
+  {
+    id: "detailSections",
+    label: "Detail sections",
+    description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.",
+    required: false,
+    appliesTo: ["detail"],
+    example: '[{ title: "Profile" }, { title: "Recent activity" }]'
+  },
+  {
+    id: "emptyState",
+    label: "Empty state",
+    description: "Fallback title, description, and action when there is no data.",
+    required: false,
+    appliesTo: ["list", "dashboard", "detail"],
+    example: '{ title: "No users yet", description: "Create the first user to get started." }'
+  },
+  {
+    id: "permissions",
+    label: "Permissions",
+    description: "Permission keys that affect sidebar visibility or action availability.",
+    required: false,
+    appliesTo: ["all"],
+    example: '["user.read", "user.write"]'
+  }
+];
+var uiScreenBlueprint = {
+  pageKinds: [
+    {
+      id: "list",
+      label: "List page",
+      frame: [
+        "Sidebar shell",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card",
+        "Optional stats",
+        "DataTable card"
+      ]
+    },
+    {
+      id: "form",
+      label: "Form page",
+      frame: [
+        "Sidebar shell",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Header actions",
+        "Sectioned form cards",
+        "Bottom action row"
+      ]
+    },
+    {
+      id: "detail",
+      label: "Detail page",
+      frame: [
+        "Sidebar shell",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "PageTitle with status/actions",
+        "Summary stats or metadata card",
+        "Detail cards and related tables"
+      ]
+    },
+    {
+      id: "dashboard",
+      label: "Dashboard page",
+      frame: [
+        "Sidebar shell",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card with actions",
+        "Stat cards row",
+        "Main insight cards and tables"
+      ]
+    }
+  ],
+  workflow: [
+    "Collect the shell + screen brief before coding. Do not invent layout presets, workspace labels, sidebar items, route urls, tabs, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus the workspace topbar and intro card to lock the shell before building the page body.",
+    "Choose only canonical root exports from @lucasvu/scope-ui.",
+    "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.",
+    "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.",
+    "End with a consistency check against the selected preset and the screen brief."
+  ],
+  briefFields: uiScreenBriefFields
+};
+
+// src/theme-contract.ts
+var uiThemePresets = [
+  {
+    id: "ocean",
+    label: "Ocean Glass",
+    description: "Blue-cyan preset with clean glass surfaces. Matches the current default visual language.",
+    recommendedFor: [
+      "Admin dashboards",
+      "SaaS CRUD screens",
+      "Projects that want the existing package look"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "0 0% 100%",
+        "--tw-foreground": "222.2 47.4% 11.2%",
+        "--tw-primary": "221.2 83.2% 53.3%",
+        "--tw-accent": "199 89% 48%",
+        "--tw-success": "142.1 76.2% 36.3%",
+        "--tw-destructive": "0 84.2% 60.2%",
+        "--tw-border": "214.3 31.8% 91.4%",
+        "--radius": "0.75rem",
+        "--surface": "rgba(255, 255, 255, 0.92)",
+        "--surface-strong": "rgba(241, 245, 249, 0.96)",
+        "--grey": "rgba(248, 250, 252, 0.96)",
+        "--grey-strong": "rgba(241, 245, 249, 0.98)",
+        "--shadow-sm": "0 10px 28px -18px rgba(15, 23, 42, 0.22)",
+        "--shadow": "0 24px 60px -28px rgba(15, 23, 42, 0.3)",
+        "--primary-grad-from": "199 89% 48%",
+        "--primary-grad-to": "221.2 83.2% 53.3%"
+      },
+      dark: {
+        "--tw-background": "222.2 84% 4.9%",
+        "--tw-foreground": "210 40% 98%",
+        "--tw-primary": "217.2 91.2% 59.8%",
+        "--tw-accent": "199 89% 48%",
+        "--tw-success": "142.1 70.6% 45.3%",
+        "--tw-destructive": "0 62.8% 30.6%",
+        "--tw-border": "217.2 32.6% 17.5%",
+        "--radius": "0.75rem",
+        "--surface": "rgba(15, 23, 42, 0.78)",
+        "--surface-strong": "rgba(30, 41, 59, 0.92)",
+        "--grey": "rgba(30, 41, 59, 0.88)",
+        "--grey-strong": "rgba(51, 65, 85, 0.92)",
+        "--shadow-sm": "0 16px 32px -18px rgba(2, 6, 23, 0.48)",
+        "--shadow": "0 28px 80px -32px rgba(2, 6, 23, 0.7)",
+        "--primary-grad-from": "198.6 88.7% 48.4%",
+        "--primary-grad-to": "221.2 83.2% 53.3%"
+      }
+    }
+  },
+  {
+    id: "sunset",
+    label: "Sunset Ember",
+    description: "Warm orange-coral preset with softer cream surfaces for branded landing or growth products.",
+    recommendedFor: [
+      "Growth products",
+      "Commerce backoffices",
+      "Projects that want a warmer visual tone"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "30 100% 98%",
+        "--tw-foreground": "20 24% 14%",
+        "--tw-primary": "14 90% 56%",
+        "--tw-accent": "29 100% 58%",
+        "--tw-success": "145 63% 38%",
+        "--tw-destructive": "0 78% 58%",
+        "--tw-border": "24 45% 89%",
+        "--radius": "0.85rem",
+        "--surface": "rgba(255, 247, 240, 0.92)",
+        "--surface-strong": "rgba(255, 237, 223, 0.96)",
+        "--grey": "rgba(255, 243, 231, 0.96)",
+        "--grey-strong": "rgba(255, 232, 214, 0.98)",
+        "--shadow-sm": "0 12px 30px -18px rgba(194, 65, 12, 0.18)",
+        "--shadow": "0 28px 64px -30px rgba(154, 52, 18, 0.24)",
+        "--primary-grad-from": "29 100% 58%",
+        "--primary-grad-to": "14 90% 56%"
+      },
+      dark: {
+        "--tw-background": "20 24% 8%",
+        "--tw-foreground": "40 33% 96%",
+        "--tw-primary": "18 100% 62%",
+        "--tw-accent": "35 100% 58%",
+        "--tw-success": "145 60% 47%",
+        "--tw-destructive": "0 73% 52%",
+        "--tw-border": "18 24% 22%",
+        "--radius": "0.85rem",
+        "--surface": "rgba(41, 24, 18, 0.84)",
+        "--surface-strong": "rgba(59, 34, 24, 0.9)",
+        "--grey": "rgba(70, 42, 29, 0.88)",
+        "--grey-strong": "rgba(92, 54, 38, 0.9)",
+        "--shadow-sm": "0 18px 36px -20px rgba(67, 20, 7, 0.48)",
+        "--shadow": "0 30px 84px -34px rgba(67, 20, 7, 0.62)",
+        "--primary-grad-from": "35 100% 58%",
+        "--primary-grad-to": "18 100% 62%"
+      }
+    }
+  },
+  {
+    id: "forest",
+    label: "Forest Mist",
+    description: "Emerald-teal preset with soft botanical surfaces for calmer productivity products.",
+    recommendedFor: [
+      "Operations tools",
+      "Internal platforms",
+      "Products that want a calmer green tone"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "138 40% 98%",
+        "--tw-foreground": "160 25% 14%",
+        "--tw-primary": "158 64% 40%",
+        "--tw-accent": "173 58% 44%",
+        "--tw-success": "145 63% 36%",
+        "--tw-destructive": "0 78% 58%",
+        "--tw-border": "143 21% 88%",
+        "--radius": "0.8rem",
+        "--surface": "rgba(245, 252, 249, 0.92)",
+        "--surface-strong": "rgba(232, 245, 239, 0.96)",
+        "--grey": "rgba(240, 248, 244, 0.96)",
+        "--grey-strong": "rgba(225, 240, 232, 0.98)",
+        "--shadow-sm": "0 12px 28px -18px rgba(5, 86, 66, 0.18)",
+        "--shadow": "0 26px 62px -30px rgba(6, 78, 59, 0.24)",
+        "--primary-grad-from": "173 58% 44%",
+        "--primary-grad-to": "158 64% 40%"
+      },
+      dark: {
+        "--tw-background": "164 35% 8%",
+        "--tw-foreground": "144 35% 96%",
+        "--tw-primary": "160 70% 46%",
+        "--tw-accent": "174 72% 45%",
+        "--tw-success": "145 68% 46%",
+        "--tw-destructive": "0 70% 52%",
+        "--tw-border": "160 20% 20%",
+        "--radius": "0.8rem",
+        "--surface": "rgba(16, 36, 31, 0.84)",
+        "--surface-strong": "rgba(21, 51, 44, 0.9)",
+        "--grey": "rgba(24, 61, 52, 0.88)",
+        "--grey-strong": "rgba(31, 77, 65, 0.9)",
+        "--shadow-sm": "0 18px 34px -20px rgba(1, 44, 34, 0.48)",
+        "--shadow": "0 30px 82px -34px rgba(1, 44, 34, 0.6)",
+        "--primary-grad-from": "174 72% 45%",
+        "--primary-grad-to": "160 70% 46%"
+      }
+    }
+  },
+  {
+    id: "graphite",
+    label: "Graphite Pulse",
+    description: "Neutral slate preset with restrained blue accents for products that need a steadier enterprise tone.",
+    recommendedFor: [
+      "Enterprise admin panels",
+      "B2B internal tools",
+      "Projects that want a more neutral interface"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "220 18% 97%",
+        "--tw-foreground": "222 24% 14%",
+        "--tw-primary": "221 24% 32%",
+        "--tw-accent": "198 83% 44%",
+        "--tw-success": "160 56% 38%",
+        "--tw-destructive": "0 72% 54%",
+        "--tw-border": "218 17% 86%",
+        "--radius": "0.7rem",
+        "--surface": "rgba(248, 250, 252, 0.94)",
+        "--surface-strong": "rgba(226, 232, 240, 0.96)",
+        "--grey": "rgba(241, 245, 249, 0.98)",
+        "--grey-strong": "rgba(226, 232, 240, 0.99)",
+        "--shadow-sm": "0 12px 30px -20px rgba(15, 23, 42, 0.18)",
+        "--shadow": "0 28px 66px -30px rgba(15, 23, 42, 0.24)",
+        "--primary-grad-from": "198 83% 44%",
+        "--primary-grad-to": "221 24% 32%"
+      },
+      dark: {
+        "--tw-background": "222 32% 8%",
+        "--tw-foreground": "210 25% 96%",
+        "--tw-primary": "210 24% 82%",
+        "--tw-accent": "192 92% 52%",
+        "--tw-success": "158 64% 45%",
+        "--tw-destructive": "0 72% 56%",
+        "--tw-border": "217 19% 24%",
+        "--radius": "0.7rem",
+        "--surface": "rgba(15, 23, 42, 0.82)",
+        "--surface-strong": "rgba(30, 41, 59, 0.92)",
+        "--grey": "rgba(30, 41, 59, 0.9)",
+        "--grey-strong": "rgba(51, 65, 85, 0.92)",
+        "--shadow-sm": "0 18px 38px -22px rgba(2, 6, 23, 0.48)",
+        "--shadow": "0 32px 88px -34px rgba(2, 6, 23, 0.68)",
+        "--primary-grad-from": "192 92% 52%",
+        "--primary-grad-to": "210 24% 82%"
+      }
+    }
+  }
+];
+var uiDefaultThemePreset = uiThemePresets[0];
+function createThemePresetCssExample(themePreset) {
+  const renderBlock = (tokens) => Object.entries(tokens).map(([token, value]) => `  ${token}: ${value};`).join("\n");
+  return `:root {
+${renderBlock(themePreset.tokens.light)}
+}
+
+.dark,
+[data-ui-theme='dark'] {
+${renderBlock(themePreset.tokens.dark)}
+}`;
+}
+var uiThemeContract = {
+  packageName: "@lucasvu/scope-ui",
+  importOrder: [
+    "import '@lucasvu/scope-ui/styles.css'",
+    "import './styles/ui-theme.css'"
+  ],
+  selectors: {
+    light: [":root", "[data-ui-theme='light']"],
+    dark: [".dark", "[data-ui-theme='dark']"]
+  },
+  overrideFile: "src/styles/ui-theme.css",
+  defaultPreset: uiDefaultThemePreset.id,
+  presets: uiThemePresets,
+  rules: [
+    "Import the package stylesheet before your project theme override stylesheet.",
+    "Choose one approved preset and keep the entire project on that preset instead of mixing palettes page by page.",
+    "Override tokens in one shared theme file instead of scattering colors across components.",
+    "Use :root for the default light theme and .dark or [data-ui-theme='dark'] for dark theme.",
+    "Only override tokens declared here. Do not patch component internals unless you are extending the library.",
+    "For AI-generated screens, choose one theme source of truth and keep component code token-driven."
+  ],
+  tokens: [
+    {
+      name: "--tw-background",
+      description: "Base app background in HSL triplet format.",
+      defaultLight: "0 0% 100%",
+      defaultDark: "222.2 84% 4.9%",
+      usedBy: ["body background", "Input fallback", "page background"]
+    },
+    {
+      name: "--tw-foreground",
+      description: "Primary text color in HSL triplet format.",
+      defaultLight: "222.2 47.4% 11.2%",
+      defaultDark: "210 40% 98%",
+      usedBy: ["Button", "Input", "Card", "Typography"]
+    },
+    {
+      name: "--tw-primary",
+      description: "Primary brand color in HSL triplet format.",
+      defaultLight: "221.2 83.2% 53.3%",
+      defaultDark: "217.2 91.2% 59.8%",
+      usedBy: ["Button", "focus rings", "brand emphasis"]
+    },
+    {
+      name: "--tw-accent",
+      description: "Accent color in HSL triplet format.",
+      defaultLight: "199 89% 48%",
+      defaultDark: "199 89% 48%",
+      usedBy: ["Tabs", "checkbox accent", "highlight states"]
+    },
+    {
+      name: "--tw-success",
+      description: "Success state color in HSL triplet format.",
+      defaultLight: "142.1 76.2% 36.3%",
+      defaultDark: "142.1 70.6% 45.3%",
+      usedBy: ["Alert", "confirm buttons", "status text"]
+    },
+    {
+      name: "--tw-destructive",
+      description: "Danger state color in HSL triplet format.",
+      defaultLight: "0 84.2% 60.2%",
+      defaultDark: "0 62.8% 30.6%",
+      usedBy: ["Alert", "destructive buttons", "error states"]
+    },
+    {
+      name: "--tw-border",
+      description: "Border color in HSL triplet format.",
+      defaultLight: "214.3 31.8% 91.4%",
+      defaultDark: "217.2 32.6% 17.5%",
+      usedBy: ["Input", "Select", "Card", "DataTable"]
+    },
+    {
+      name: "--radius",
+      description: "Shared component radius.",
+      defaultLight: "0.75rem",
+      defaultDark: "0.75rem",
+      usedBy: ["Button", "Input", "Card", "Tabs"]
+    },
+    {
+      name: "--surface",
+      description: "Default surface background as a CSS color.",
+      defaultLight: "rgba(255, 255, 255, 0.92)",
+      defaultDark: "rgba(15, 23, 42, 0.78)",
+      usedBy: ["Tabs", "Pagination", "glass surfaces"]
+    },
+    {
+      name: "--surface-strong",
+      description: "Stronger elevated surface as a CSS color.",
+      defaultLight: "rgba(241, 245, 249, 0.96)",
+      defaultDark: "rgba(30, 41, 59, 0.92)",
+      usedBy: ["Pagination hover", "raised surfaces"]
+    },
+    {
+      name: "--grey",
+      description: "Neutral table/header background as a CSS color.",
+      defaultLight: "rgba(248, 250, 252, 0.96)",
+      defaultDark: "rgba(30, 41, 59, 0.88)",
+      usedBy: ["DataTable header"]
+    },
+    {
+      name: "--grey-strong",
+      description: "Hover background for neutral rows as a CSS color.",
+      defaultLight: "rgba(241, 245, 249, 0.98)",
+      defaultDark: "rgba(51, 65, 85, 0.92)",
+      usedBy: ["DataTable row hover"]
+    },
+    {
+      name: "--shadow-sm",
+      description: "Small elevation shadow.",
+      defaultLight: "0 10px 28px -18px rgba(15, 23, 42, 0.22)",
+      defaultDark: "0 16px 32px -18px rgba(2, 6, 23, 0.48)",
+      usedBy: ["Tabs", "Pagination", "subtle elevation"]
+    },
+    {
+      name: "--shadow",
+      description: "Primary elevation shadow.",
+      defaultLight: "0 24px 60px -28px rgba(15, 23, 42, 0.3)",
+      defaultDark: "0 28px 80px -32px rgba(2, 6, 23, 0.7)",
+      usedBy: ["Card", "Button emphasis", "floating surfaces"]
+    },
+    {
+      name: "--text",
+      description: "Generic text color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-foreground))",
+      defaultDark: "hsl(var(--tw-foreground))",
+      usedBy: ["Pagination", "legacy utility surfaces"]
+    },
+    {
+      name: "--muted",
+      description: "Generic muted text color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-muted-foreground))",
+      defaultDark: "hsl(var(--tw-muted-foreground))",
+      usedBy: ["Pagination", "DataTable sort icon", "helper text"]
+    },
+    {
+      name: "--accent",
+      description: "Generic accent color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-accent))",
+      defaultDark: "hsl(var(--tw-accent))",
+      usedBy: ["DataTable checkbox accent", "focus accents"]
+    },
+    {
+      name: "--primary-grad-from",
+      description: "Gradient start color in HSL triplet format.",
+      defaultLight: "199 89% 48%",
+      defaultDark: "198.6 88.7% 48.4%",
+      usedBy: ["Button variant create"]
+    },
+    {
+      name: "--primary-grad-to",
+      description: "Gradient end color in HSL triplet format.",
+      defaultLight: "221.2 83.2% 53.3%",
+      defaultDark: "221.2 83.2% 53.3%",
+      usedBy: ["Button variant create"]
+    }
+  ],
+  exampleCss: createThemePresetCssExample(uiDefaultThemePreset)
+};
+var uiProjectAiRules = [
+  "Use @lucasvu/scope-ui as the default UI library for React projects, or @lucasvu/scope-ui/core for framework-agnostic theme/runtime usage.",
+  "Import @lucasvu/scope-ui/styles.css once at the app entry.",
+  "Import the project override theme file after the package stylesheet or bundled theme layer.",
+  "Stay inside the approved theme preset declared by the project and do not invent a second palette.",
+  "Read uiAiManifest to choose the correct component by intent before coding.",
+  "Read uiThemeContract and uiThemeLayerAssets before changing colors, shadows, radius, or theme behavior.",
+  "Prefer root exports and avoid MainFe unless the task explicitly targets a legacy screen."
+];
+
+// src/theme-layer-assets.ts
+var uiThemeLayerAssets = [
+  {
+    id: "default",
+    label: "Theme Default",
+    importPath: "@lucasvu/scope-ui/themes/theme-default.css",
+    activation: "global",
+    description: "Global default token layer close to the legacy shared theme baseline.",
+    recommendedFor: [
+      "Projects that want a direct global theme layer without extra setup",
+      "Legacy migrations"
+    ]
+  },
+  {
+    id: "new-main-fe",
+    label: "New Main FE",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css",
+    activation: "global",
+    description: "Global Argon-inspired shell layer that works immediately after import.",
+    recommendedFor: [
+      "Admin shells",
+      "Projects that want the current shared main-fe tone"
+    ]
+  },
+  {
+    id: "citrus-ink",
+    label: "Citrus Ink",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-citrus-ink.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "citrus-ink",
+    description: "High-contrast graphite theme with mint and citrus accents.",
+    recommendedFor: ["Brand-heavy dashboards"]
+  },
+  {
+    id: "facebook-blue",
+    label: "Facebook Blue",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-facebook-blue.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "facebook-blue",
+    description: "Blue-first neutral theme tuned around a familiar social palette.",
+    recommendedFor: ["Blue-branded products"]
+  },
+  {
+    id: "neo-slate",
+    label: "Neo Slate",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-neo-slate.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "neo-slate",
+    description: "Modern slate-indigo workspace theme with richer shell tokens.",
+    recommendedFor: ["Contemporary SaaS dashboards", "Modern admin shells"]
+  },
+  {
+    id: "siraya-brand",
+    label: "Siraya Brand Sunset",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-new-main-fe-sunset.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "siraya-brand",
+    description: "Warm branded shell with typography and page-slot overrides.",
+    recommendedFor: ["Brand-led marketing or hybrid product shells"]
+  },
+  {
+    id: "pure-white",
+    label: "Pure White",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-pure-white.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "pure-white",
+    description: "Clean white workspace theme with cobalt accents.",
+    recommendedFor: ["Minimalist backoffices"]
+  },
+  {
+    id: "siraya-vii-light",
+    label: "Siraya VII Light",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-siraya-vii-light.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "siraya-vii-light",
+    description: "Light brand system based on the Siraya VII palette.",
+    recommendedFor: ["Brand refresh experiments"]
+  },
+  {
+    id: "solstice-pop",
+    label: "Solstice Pop",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-solstice-pop.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "solstice-pop",
+    description: "Editorial warm-stone theme with stronger typography direction.",
+    recommendedFor: ["Content-heavy dashboards"]
+  },
+  {
+    id: "uat-aurora",
+    label: "UAT Aurora",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-uat-aurora.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "uat-aurora",
+    description: "Soft slate-blue experimental theme using the same token structure as sunset.",
+    recommendedFor: ["UAT or staging environments", "Blue-toned shells"]
+  },
+  {
+    id: "custom-crisp",
+    label: "Custom Crisp",
+    importPath: "@lucasvu/scope-ui/themes/theme-ui-custom-crisp.css",
+    activation: "data-client-theme",
+    clientThemeAttributeValue: "*",
+    description: "Cross-theme typography and control crispness overrides for client-theme-driven shells.",
+    recommendedFor: ["Attribute-scoped client themes that need sharper controls"]
+  }
+];
+
+// src/color-mode.ts
+var ROOT_COLOR_MODE_ATTRIBUTE = "data-ui-color-mode";
+var ROOT_CLIENT_THEME_ATTRIBUTE = "data-client-theme";
+var ROOT_DARK_CLASS = "dark";
+var SYSTEM_DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+var resolveColorModeMediaQuery = () => {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return null;
+  }
+  return window.matchMedia(SYSTEM_DARK_MEDIA_QUERY);
+};
+var isColorMode = (value) => value === "light" || value === "dark";
+var getSystemColorMode = () => resolveColorModeMediaQuery()?.matches ? "dark" : "light";
+var applyDocumentColorMode = (colorMode) => {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const root = document.documentElement;
+  root.classList.toggle(ROOT_DARK_CLASS, colorMode === "dark");
+  root.setAttribute(ROOT_COLOR_MODE_ATTRIBUTE, colorMode);
+  root.style.colorScheme = colorMode;
+};
+var initializeDocumentColorMode = (colorMode = getSystemColorMode()) => {
+  applyDocumentColorMode(colorMode);
+  return colorMode;
+};
+var subscribeToSystemColorMode = (listener) => {
+  const mediaQuery = resolveColorModeMediaQuery();
+  if (!mediaQuery) {
+    return () => void 0;
+  }
+  const handleChange = (event) => {
+    listener(event.matches ? "dark" : "light");
+  };
+  if (typeof mediaQuery.addEventListener === "function") {
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }
+  mediaQuery.addListener(handleChange);
+  return () => mediaQuery.removeListener(handleChange);
+};
+var syncDocumentColorModeToSystem = () => {
+  const applySystemColorMode = (colorMode) => {
+    applyDocumentColorMode(colorMode);
+  };
+  applySystemColorMode(getSystemColorMode());
+  return subscribeToSystemColorMode(applySystemColorMode);
+};
+var applyDocumentClientTheme = (themeId) => {
+  if (typeof document === "undefined") {
+    return;
+  }
+  const root = document.documentElement;
+  if (!themeId) {
+    root.removeAttribute(ROOT_CLIENT_THEME_ATTRIBUTE);
+    return;
+  }
+  root.setAttribute(ROOT_CLIENT_THEME_ATTRIBUTE, themeId);
+};
+
+// src/lib/cn.ts
+function cn(...values) {
+  return values.filter(Boolean).join(" ");
+}
+
+export { ROOT_CLIENT_THEME_ATTRIBUTE, ROOT_COLOR_MODE_ATTRIBUTE, __export, applyDocumentClientTheme, applyDocumentColorMode, cn, getSystemColorMode, initializeDocumentColorMode, isColorMode, subscribeToSystemColorMode, syncDocumentColorModeToSystem, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemeLayerAssets, uiThemePresets };