themelia-react-ui 1.0.2 → 2.0.0

package/docs/consumer-skill/references/public-api.json

@@ -2,10 +2,11 @@
   "schemaVersion": 1,
   "discoveryVersion": 1,
   "package": "themelia-react-ui",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "stylesheets": [
     "themelia-react-ui/style.css",
     "themelia-react-ui/theme.css",
+    "themelia-react-ui/themes/green.css",
     "themelia-react-ui/features/map/style.css"
   ],
   "peers": [
@@ -1134,21 +1135,6 @@
         }
       ],
       "recipes": [
-        {
-          "file": "examples/app-layout.tsx",
-          "exports": [
-            "WorkspaceLayout"
-          ],
-          "symbols": [
-            "Button"
-          ],
-          "references": [
-            "references/composition.md#application-layouts",
-            "references/integration.md",
-            "references/workflows.md#single-resource-page"
-          ],
-          "optionalPeers": []
-        },
         {
           "file": "examples/composition.tsx",
           "exports": [
@@ -1191,22 +1177,6 @@
           ],
           "optionalPeers": []
         },
-        {
-          "file": "examples/detail.tsx",
-          "exports": [
-            "AccountDetailPage"
-          ],
-          "symbols": [
-            "Button"
-          ],
-          "references": [
-            "references/analytics.md#usage-facts-and-verification",
-            "references/composition.md#application-layouts",
-            "references/workflows.md#detail-and-framing",
-            "references/workflows.md#single-resource-page"
-          ],
-          "optionalPeers": []
-        },
         {
           "file": "examples/edit.tsx",
           "exports": [
@@ -1302,6 +1272,15 @@
         "defaultSmartCardStrings",
         "hasRenderableContent"
       ],
+      "deprecated": {
+        "SmartCard": "Use Card.",
+        "SmartCardAction": "Use CardAction.",
+        "SmartCardProps": "Use CardProps.",
+        "SmartCardSkeleton": "Use CardSkeleton.",
+        "SmartCardSkeletonProps": "Use CardSkeletonProps.",
+        "SmartCardStrings": "Use CardStrings.",
+        "SmartCardSurface": "Use CardSurface."
+      },
       "optionalPeers": [],
       "layer": "base",
       "responsibility": "Base family: Card.",
@@ -2918,6 +2897,14 @@
         "defaultContentBlockStrings",
         "defaultDateBlockStrings"
       ],
+      "deprecated": {
+        "ContentBlock": "Use Card with surface=\"flat\" and padding=\"none\" for unframed content.",
+        "ContentBlockPadding": "Part of deprecated ContentBlock. Use Card with surface=\"flat\" and padding=\"none\" for unframed content.",
+        "ContentBlockProps": "Part of deprecated ContentBlock. Use Card with surface=\"flat\" and padding=\"none\" for unframed content.",
+        "ContentBlockStrings": "Part of deprecated ContentBlock. Use Card with surface=\"flat\" and padding=\"none\" for unframed content.",
+        "ContentBlockSurface": "Part of deprecated ContentBlock. Use Card with surface=\"flat\" and padding=\"none\" for unframed content.",
+        "ContentBlockTitleSize": "Part of deprecated ContentBlock. Use Card with surface=\"flat\" and padding=\"none\" for unframed content."
+      },
       "optionalPeers": [],
       "layer": "base",
       "responsibility": "Base family: Boolean indicator; Collapsible; Date block; Icon badge; Placeholder pattern; Scroll area; Separator; Tooltip; Visually hidden.",
@@ -6071,11 +6058,22 @@
         "SheetTitle",
         "SheetTrigger"
       ],
+      "deprecated": {
+        "Sheet": "Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetBody": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetClose": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetContent": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetDescription": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetFooter": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetHeader": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetTitle": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`.",
+        "SheetTrigger": "Part of deprecated Sheet. Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`."
+      },
       "optionalPeers": [],
       "layer": "base",
       "responsibility": "Base family: Sheet.",
       "jobs": [
-        "A custom side-attached overlay needs low-level trigger/content/header/footer anatomy."
+        "Maintaining code that still imports the deprecated Sheet parts."
       ],
       "tags": [
         "base",
@@ -6089,16 +6087,16 @@
       "guidance": [
         {
           "title": "Sheet",
-          "description": "A custom side-attached overlay needs low-level trigger/content/header/footer anatomy.",
+          "description": "Maintaining code that still imports the deprecated Sheet parts.",
           "chooseWhen": [
-            "A custom side-attached overlay needs low-level trigger/content/header/footer anatomy."
+            "Maintaining code that still imports the deprecated Sheet parts."
           ],
           "avoidWhen": [
-            "The workflow fits a centered dialog or the standard callback-driven drawer recipe."
+            "Any new dialog, drawer or side panel: use ActionDialog, ConfirmDialog or ActionDrawer from features/overlays."
           ],
           "appOwned": [],
           "jobs": [
-            "A custom side-attached overlay needs low-level trigger/content/header/footer anatomy."
+            "Maintaining code that still imports the deprecated Sheet parts."
           ],
           "tags": [
             "base",
@@ -6748,7 +6746,7 @@
       "layer": "base",
       "responsibility": "Base family: Structural composition.",
       "jobs": [
-        "Passive siblings need one-axis spacing, explicit responsive tracks, or available-width-driven equal tracks."
+        "Compose layout blocks, vertical siblings, a horizontal row, wrapping actions, responsive grids and peer card gaps."
       ],
       "tags": [
         "base",
@@ -6758,6 +6756,9 @@
       "aliases": [
         "copy gaps",
         "copy-gap",
+        "horizontal row",
+        "layout blocks",
+        "peer card gaps",
         "title description spacing"
       ],
       "references": [
@@ -6770,7 +6771,7 @@
       "guidance": [
         {
           "title": "Structural composition",
-          "description": "Passive siblings need one-axis spacing, explicit responsive tracks, or available-width-driven equal tracks.",
+          "description": "Compose passive layout blocks with Stack rows, responsive Grid tracks, GridCell spans and available-width AdaptiveGrid.",
           "chooseWhen": [
             "Passive siblings need one-axis spacing, explicit responsive tracks, or available-width-driven equal tracks."
           ],
@@ -6779,14 +6780,18 @@
           ],
           "appOwned": [],
           "jobs": [
-            "Passive siblings need one-axis spacing, explicit responsive tracks, or available-width-driven equal tracks."
+            "Compose layout blocks, vertical siblings, a horizontal row, wrapping actions, responsive grids and peer card gaps."
           ],
           "tags": [
             "base",
             "foundations",
             "structure"
           ],
-          "aliases": [],
+          "aliases": [
+            "layout blocks",
+            "horizontal row",
+            "peer card gaps"
+          ],
           "section": "Foundations",
           "browse": {
             "category": "foundations",
@@ -6835,21 +6840,6 @@
         }
       ],
       "recipes": [
-        {
-          "file": "examples/app-layout.tsx",
-          "exports": [
-            "WorkspaceLayout"
-          ],
-          "symbols": [
-            "Stack"
-          ],
-          "references": [
-            "references/composition.md#application-layouts",
-            "references/integration.md",
-            "references/workflows.md#single-resource-page"
-          ],
-          "optionalPeers": []
-        },
         {
           "file": "examples/composition.tsx",
           "exports": [
@@ -6933,6 +6923,21 @@
             "@tanstack/react-table"
           ]
         },
+        {
+          "file": "examples/layout-blocks.tsx",
+          "exports": [
+            "LayoutBlocks"
+          ],
+          "symbols": [
+            "Stack"
+          ],
+          "references": [
+            "references/composition.md#horizontal-rows",
+            "references/composition.md#main-and-aside-card-gaps",
+            "references/composition.md#structure-and-spacing"
+          ],
+          "optionalPeers": []
+        },
         {
           "file": "examples/planning-usage-edit.tsx",
           "exports": [
@@ -9552,6 +9557,7 @@
         "AnalyticsStrings",
         "ChartCard",
         "ChartCardProps",
+        "FormatMetricValueOptions",
         "Metric",
         "MetricBar",
         "MetricBarProps",
@@ -9812,7 +9818,7 @@
         },
         {
           "title": "Comparison",
-          "description": "`MetricComparison` — side-by-side current vs previous with a tone-tinted delta box. Reuses the unified `MetricData` shape so currency/percent formatting carries through.",
+          "description": "`MetricComparison` — side-by-side current vs previous with a signed delta badge. Reuses the unified `MetricData` shape so currency/percent formatting carries through.",
           "chooseWhen": [],
           "avoidWhen": [],
           "appOwned": [],
@@ -12577,7 +12583,7 @@
         },
         {
           "title": "Changelog",
-          "description": "ChangelogTimeline renders release history as a marker rail, mapping added, removed, modified, and fixed to colour-coded chips with version, author, and timestamp.",
+          "description": "ChangelogTimeline renders release history as a marker rail, mapping added, removed, modified, and fixed to neutral kind chips and marker icons with version, author, and timestamp.",
           "chooseWhen": [],
           "avoidWhen": [],
           "appOwned": [],
@@ -13836,7 +13842,7 @@
             "PreparedEmail"
           ],
           "references": [
-            "references/integration.md"
+            "references/integration.md#dialogs-confirmations-and-drawers"
           ],
           "optionalPeers": [
             "@tiptap/react",
@@ -13854,7 +13860,7 @@
             "PreparedEmail"
           ],
           "references": [
-            "references/integration.md"
+            "references/integration.md#dialogs-confirmations-and-drawers"
           ],
           "optionalPeers": [
             "@tiptap/react",
@@ -15035,7 +15041,7 @@
             "A modal, drawer, or confirmation needs standardized confirm/cancel, async loading, error, strings, and tone behavior."
           ],
           "avoidWhen": [
-            "The caller needs custom compound anatomy without the shared action lifecycle."
+            "The surface is anchored to a trigger (a popover, menu, select or tooltip) rather than a dialog."
           ],
           "appOwned": [],
           "jobs": [
@@ -15068,7 +15074,8 @@
             }
           ],
           "alternatives": [
-            "themelia-react-ui/base/sheet"
+            "themelia-react-ui/base/popover",
+            "themelia-react-ui/layout/sidebar"
           ]
         }
       ],
@@ -16636,6 +16643,7 @@
         "PageActionsProps",
         "PageActionsStrings",
         "PageHeader",
+        "PageHeaderAction",
         "PageHeaderProps",
         "PageHeaderSlots",
         "PageProps",
@@ -17104,8 +17112,11 @@
         "website"
       ],
       "aliases": [
+        "main aside card gaps",
+        "main aside layout",
         "public website",
         "service overview",
+        "two column layout",
         "website landing page"
       ],
       "sections": [
@@ -17142,7 +17153,10 @@
           "aliases": [
             "website landing page",
             "public website",
-            "service overview"
+            "service overview",
+            "main aside card gaps",
+            "main aside layout",
+            "two column layout"
           ],
           "section": "Layouts",
           "browse": {
@@ -17186,6 +17200,21 @@
         }
       ],
       "recipes": [
+        {
+          "file": "examples/layout-blocks.tsx",
+          "exports": [
+            "LayoutBlocks"
+          ],
+          "symbols": [
+            "TwoColumnLayout"
+          ],
+          "references": [
+            "references/composition.md#horizontal-rows",
+            "references/composition.md#main-and-aside-card-gaps",
+            "references/composition.md#structure-and-spacing"
+          ],
+          "optionalPeers": []
+        },
         {
           "file": "examples/website.tsx",
           "exports": [
@@ -17618,6 +17647,7 @@
         "PageActionsProps",
         "PageActionsStrings",
         "PageHeader",
+        "PageHeaderAction",
         "PageHeaderProps",
         "PageHeaderSlots",
         "PageProps",
@@ -17628,7 +17658,7 @@
       "layer": "layout",
       "responsibility": "Layout family: Page shell; Resource detail.",
       "jobs": [
-        "A page needs shell-level title, back/link rendering, actions, content, and page composition slots.",
+        "A page needs shell-level title, back/link rendering, role-based primary/secondary commands, content, and page composition slots.",
         "Build a responsive resource detail page with primary facts, related context, and actions."
       ],
       "tags": [
@@ -17642,12 +17672,16 @@
       ],
       "aliases": [
         "centered detail page",
+        "more actions menu",
         "narrow resource page",
+        "page commands",
         "page gutters",
         "page header",
         "page padding",
+        "primary action",
         "route heading",
         "scope navigation",
+        "secondary actions",
         "single record page",
         "single resource page"
       ],
@@ -17705,20 +17739,20 @@
         },
         {
           "title": "Page shell",
-          "description": "A page needs shell-level title, back/link rendering, actions, content, and page composition slots.",
+          "description": "A page needs shell-level title, back/link rendering, role-based primary/secondary commands, content, and page composition slots.",
           "chooseWhen": [
-            "A page needs shell-level title, back/link rendering, actions, content, and page composition slots."
+            "A page needs shell-level title, back/link rendering, role-based primary/secondary commands, content, and page composition slots."
           ],
           "avoidWhen": [
             "An existing shell needs only a visual title/description/badge block."
           ],
           "appOwned": [
             "route title and contextual lead",
-            "primary command importance",
+            "which command is primary and which are destructive",
             "navigation callbacks and permissioned actions"
           ],
           "jobs": [
-            "A page needs shell-level title, back/link rendering, actions, content, and page composition slots."
+            "A page needs shell-level title, back/link rendering, role-based primary/secondary commands, content, and page composition slots."
           ],
           "tags": [
             "layout",
@@ -17734,7 +17768,11 @@
             "narrow resource page",
             "centered detail page",
             "single resource page",
-            "single record page"
+            "single record page",
+            "primary action",
+            "secondary actions",
+            "page commands",
+            "more actions menu"
           ],
           "section": "Layouts",
           "browse": {
@@ -18221,6 +18259,8 @@
         "Link",
         "LinkProps",
         "Money",
+        "MoneyFormatter",
+        "MoneyFormatterOptions",
         "MoneyLayout",
         "MoneyProps",
         "MoneySecondaryEmphasis",
@@ -18253,7 +18293,8 @@
         "formatFileSize",
         "formatInitials",
         "formatName",
-        "parseDateInput"
+        "parseDateInput",
+        "useMoneyFormatter"
       ],
       "optionalPeers": [],
       "layer": "foundations",

package/docs/consumer-skill/references/review.md

@@ -19,7 +19,8 @@ workflow/declarations; this is a review aid, not a new design system.
   empty/missing values and narrow parent width? Zero and unavailable differ.
 
 These criteria allow different product layouts. Do not impose a universal card
-count, row-line limit, primary button count or one-column form rule.
+count, row-line limit or one-column form rule. Emphasis is the exception: keep
+one solid primary command per page or surface, so the next action stays obvious.
 
 ## Optional source checker
 
@@ -42,10 +43,25 @@ than titleSuffix, control geometry/typography, fixed DisplayLabel/Badge
 roles, cross-role shell/inner radius replacements, display-copy margins, or
 attenuated shared focus rings on imported controls. Intentional nested bodies,
 circular owners and joined-edge corner resets retain their roles. Import ownership
-follows lexical bindings, preserving locally shadowed application components. Deprecated migration
-owners, nested framed subjects and repeated literal headings produce review
-warnings; warnings alone do not fail CI. Messages identify the owner and remedy.
+follows lexical bindings, preserving locally shadowed application components. Imports of
+symbols the public index marks deprecated, nested framed subjects and repeated
+literal headings produce review warnings; warnings alone do not fail CI. Messages
+identify the owner and remedy. Dialog-like UI outside the overlay owners warns
+too: native elements with `role="dialog"`/`"alertdialog"` or `aria-modal`, a
+`fixed inset-0` layer, and imports of another modal library.
 Standalone compact Cards and Page gutter removal also produce review warnings.
+Buttons placed in a Page or PageHeader `actions` region warn as well: pass
+commands as `primaryAction` and ordered `secondaryActions` so the header owns
+their emphasis, size and overflow. Non-command controls stay valid there.
+A Page with more than one solid primary command, counting `header.primaryAction`
+and every Button with `tone="primary"` and no other style, warns as well. Overlays own
+their own primary command and are not counted. Raw palette classes such as
+`bg-blue-500`, `text-gray-600` or `border-white` warn on any element; use a
+semantic surface/foreground pair or a status tone. A Card title icon and an icon on
+more than one MetadataList fact warn as decoration; keep a glyph only when it
+encodes state or a brand. Native `<button>` and
+`<h1>`–`<h6>` elements warn in favour of Button/TextButton and Heading, which
+own focus, loading and disabled states or margins and the heading scale.
 Verified Card-owning Metric/card-grid, UsageCard and TaskCard compositions also
 participate in nested-surface and peer-gap review. Metric without its card variant,
 compact MetricGrid, flat TaskCard, ChartCard and Receipt do not establish a frame.

package/docs/consumer-skill/references/theming.md

@@ -4,7 +4,7 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
-Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration.
+Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the control boundary and keeps 3:1 against every surface (WCAG 1.4.11); `--border` is for dividers and surface edges. Keep that split when rebranding.
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
 
@@ -63,6 +63,12 @@ control heights and copy gaps keep their independent roots.
 
 Use discrete inset, density and size props for the component responsibility described in [composition](composition.md). CSS scales are independent continuous theme settings. Primary row text does not shrink to xs merely because a density is compact. Public Input and Command search retain normal desktop editable text; coarse-pointer devices use text-base at mobile and tablet widths. Typography components remain margin-free.
 
+The default primary is near-black so success and other status colors never compete
+with it. `themelia-react-ui/themes/green.css`, imported after `style.css`, is the
+opt-in Themelia green brand (primary, its foreground, the dark accent and the first
+chart series). Rebrand by setting `--primary` and `--primary-foreground` in both
+`:root` and `.dark`; keep the brand hue clear of the status hues and check 4.5:1.
+
 Root overrides reach body portals. Scoped themes use ThemeScope from ui-provider. Advanced editing uses the theme-tweaker public API, editing CSS rather than adding another JavaScript styling system.
 
 Explicit portal containers take precedence over the nearest ThemeScope. Place those containers inside the intended theme boundary; a portal deliberately moved outside it cannot inherit that boundary automatically. Test the opened popup, not only its trigger.

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "structural": [
     {
       "name": "--space-scale",
@@ -121,7 +121,7 @@
   "radius": {
     "name": "--radius",
     "default": "0.75rem",
-    "purpose": "Shared 8px corners keep short controls rectangular; nested corners derive from this root.",
+    "purpose": "Shared 12px outer corners; inner control/row corners derive from this root and stay rectangular.",
     "defaultUtility": "rounded-radius",
     "innerUtility": "rounded-inner",
     "innerFormula": "min(calc(var(--radius) * 0.75), calc(min(var(--height-action), var(--height-control)) * var(--density-scale) / 4))"
@@ -209,6 +209,7 @@
       "gap-space-lg",
       "gap-space-xl",
       "gap-space-2xl",
+      "gap-space-3xl",
       "gap-x-space-2xs",
       "gap-x-space-xs",
       "gap-x-space-sm",
@@ -216,6 +217,7 @@
       "gap-x-space-lg",
       "gap-x-space-xl",
       "gap-x-space-2xl",
+      "gap-x-space-3xl",
       "gap-y-space-2xs",
       "gap-y-space-xs",
       "gap-y-space-sm",
@@ -223,6 +225,7 @@
       "gap-y-space-lg",
       "gap-y-space-xl",
       "gap-y-space-2xl",
+      "gap-y-space-3xl",
       "p-space-2xs",
       "p-space-xs",
       "p-space-sm",

package/docs/consumer-skill/references/workflows.md

@@ -79,8 +79,10 @@ definitions; the app then chooses appropriate destination focus.
 
 ## Single resource page
 
-Use `Page`, `PageHeader` and `PageActions` from `themelia-react-ui/layout/page`
-for the record route's identity, back navigation, content bounds and commands.
+Use `Page` from `themelia-react-ui/layout/page` for the record route's identity,
+back navigation, content bounds and commands. Pass the record's main command as
+`header.primaryAction` and supporting commands as `header.secondaryActions`;
+`PageHeader` and `PageActions` remain for custom shells and toolbars.
 The [layout recipe](../examples/app-layout.tsx) demonstrates that route boundary;
 the [detail recipe](../examples/detail.tsx) demonstrates an independently framed
 record subject with MetadataList and value primitives. Decide whether the record