themelia-react-ui 1.0.1 → 1.0.2

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

@@ -37,14 +37,33 @@ identity check. It neither edits files nor installs dependencies. Add this
 command to app CI if useful; repository lint is not automatically installed.
 
 Errors cover unknown package entrypoints/symbols and statically detected overrides
-of protected popup insets or control geometry/typography. Deprecated migration
+of protected Card/popup insets, Card badges in headerAction/headerStart rather
+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.
+Standalone compact Cards and Page gutter removal also produce review warnings.
+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.
+Direct framed/default Card peers, including GridCell-wrapped peers, in a statically
+small Stack/Grid gap also warn; omitted gaps use the actual component defaults.
+Review visible ring clearance and the application's ordinary surface policy.
+Review the compact subject and actual parent inset; PageViewport supplies none.
+Recognizable metric cards, repeated fact rows and centered empty regions suggest
+Metric/MetricGrid, MetadataList/InlineStat or EmptyState. Lower-level Empty and
+modal anatomy suggest their complete workflow owners. These semantic guesses
+are contextual warnings: keep valid custom subjects, editable rows and modal
+lifecycles when the complete owner's contract differs. An arbitrary *Card name
+never establishes ownership; ChartCard and Receipt are useful counterexamples.
 Use existing app lint/typechecking for wider language, utility and accessibility
 coverage. The script is deliberately small and does not replace them.
 
-Coverage is limited to direct public imports, aliases/namespaces, and same-file
-static classes/styles/props. Dynamic expressions are reported as unresolved;
+Coverage is limited to direct public imports, aliases/namespaces, native paragraph/
+heading copy and same-file static classes/styles/props. Dynamic expressions are reported as unresolved;
 cross-file wrappers, external CSS, render functions and runtime values require
 review. Do not treat an empty report as proof of complete compliance or taste.
 
@@ -60,6 +79,14 @@ and failure/retry states. Use deferred requests to observe pending behavior.
 Confirm accepted data changes and draft retention; a toast is only feedback.
 Compare before/after at the same conditions and record unverified limits.
 
+Treat the user's appearance feedback as an acceptance criterion. Reproduce the
+reported state at its actual width/theme and improve the responsible composition
+or shared recipe. Keep source findings, measurements and inspected-image judgment
+distinct: matching classes/radii and zero overflow do not establish a coherent
+appearance. Inspect borders, rings, clipping and settled transforms in the actual
+state. Compare the requested theme value before changing a shared default; an
+image should demonstrate that the correction addresses the visible complaint.
+
 ## Application policy
 
 Keep a small app-owned reference linked from its agent instructions: name the
@@ -68,7 +95,32 @@ information priorities and relevant local tests. Link current representative
 pages. Preserve permissions, transport, translations and product-specific forms.
 Do not copy the package API manual or edit the packaged skill to encode local policy.
 
+When agent output is wrong, inspect installed/copied identity, whether the skill
+was loaded, its discovery results, the actual declarations/runtime, and competing
+app adapters/guides. An import-valid screen can still follow the wrong ownership
+rule. Check current source rather than strengthening every sentence into a ban;
+document concrete contradictions and fix the owning policy. Static checks cannot
+infer product meaning or prove which instructions an agent actually followed.
+
 Package declarations define supported props; this skill defines shared composition
 and anatomy; the app defines business meaning and page conventions. If a shared
 owner fails in a valid composition, isolate a reproduction and report the owning
 contract. Do not spread private selectors or copy the control to hide the issue.
+
+## When a valid composition looks wrong
+
+Compare the installed declarations, shipped CSS and copied skill version first.
+Test without the app reset when fonts, borders or list insets differ. Combine
+field affordances and vary density separately from spacing; inspect long copy
+in a narrow parent at a wide viewport too. Source checks cannot detect these.
+
+Prefer a minimal public-API reproduction over private descendant CSS. For example,
+use Metric's card variant for a navigable KPI with formatted value/trend instead
+of recreating its hierarchy with Card + Text. Use Heading's `size` for visual
+emphasis while `tag` keeps semantic level; its default admin scale is deliberate.
+A custom Card subject or an application-owned hero remains valid.
+
+Run discovery using both the task phrase and exact family/symbol. A zero result
+is not permission to invent an export: inspect public-api.json/declarations and
+report a missing capability. Static unknown spreads/classes remain unresolved;
+review them at runtime rather than treating an empty finding list as approval.

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

@@ -8,21 +8,50 @@ Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, se
 
 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.
 
-Default --radius is 1rem (16px). rounded-radius is the default throughout the package. rounded-inner is opt-in for nested bodies/items and derives at 0.6× (9.6px). Do not invent an outer/surface radius or enlarge an individual card based on padding. Circular avatars/dots remain intentional shapes.
+The default `--radius` is 0.75rem (12px). One public root drives two shared
+roles; component owners choose the role, so ordinary callers add no radius class.
+
+| Role | Owners | Default |
+| --- | --- | --- |
+| `rounded-radius` | Cards, popup/command shells and other outer surfaces | 12px |
+| `rounded-inner` | Inputs, buttons, select/facet triggers, collection/navigation rows and intentional nested bodies | 9px |
+
+Standalone controls retain the inner role; a complete nested Card retains its
+outer-shell role. Physical nesting does not select a different recipe.
+
+The inner role is `min(radius × 0.75, min(height-action, height-control) ×
+density-scale ÷ 4)`. The height bound keeps short controls restrained when an app
+increases the global radius; a 0.75 multiplier alone would still produce capsules.
+The smaller base height preserves a common inner radius when action and field
+heights differ. Density scales that bound once: the default roots at density
+0.875 yield 7.875px inner corners. Control size variants share the role; spacing
+scale and surface padding do not change it. Do not override the derived alias as
+another theme setting. Circular avatars/dots and joined-edge resets retain their
+explicit shape mechanics; Badge retains its own root-based recipe.
+
+CSS fits overlapping curves to the actual box, so computed values alone do not
+prove the visible shape. Inspect settled corners, borders, clipping and focus
+rings in opened surfaces. Change `--radius` at the theme boundary, rather than
+replacing individual components' owned corners.
 
 ```css
-/* After themelia-react-ui/style.css; no Tailwind build needed for overrides. */
+/* Intentional 40px controls, after style.css; overrides need no Tailwind build. */
 :root {
-  --radius: 1rem;
+  --radius: 0.75rem;
   --height-action: 2.5rem;
   --height-control: 2.5rem;
-  --surface-x: 1rem;
-  --surface-y: 1rem;
+  --surface-x: 1.25rem;
+  --surface-y: 1.25rem;
 }
 ```
 
 Action and editable-control heights are separate roles; keep roots equal for adjoining alignment. `--space-scale` multiplies structural gaps, inline insets and surface padding. `--density-scale` multiplies action/control height and collection block padding. Roots are unscaled measurements; do not pre-multiply and then apply the utility again.
 
+Both surface roots default to 1.25rem. At a 16px root font and space-scale 1,
+ordinary surface insets are 20px, compact insets are 10px and large insets are
+36px. Page's default large gutters inherit that same recipe. Row insets,
+control heights and copy gaps keep their independent roots.
+
 | Shared geometry | Root / derivation |
 | --- | --- |
 | Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
@@ -40,6 +69,12 @@ Explicit portal containers take precedence over the nearest ThemeScope. Place th
 
 Apps using semantic utilities in their own JSX process themelia-react-ui/theme.css after Tailwind in a Tailwind v4 stylesheet. Compiled style.css styles shipped components but does not compile arbitrary app utility names. Keep app-owned classes namespaced and layout-focused.
 
+The package class merger recognizes token overrides only for advertised utilities and exact class spellings emitted by the library stylesheet, including their negative, important and responsive forms. A valid Tailwind alias such as `m-space-2xl` can still be absent from that stylesheet. Unshipped aliases preserve existing fallback classes; they do not receive package override semantics merely because an app's separate Tailwind build can generate them. Use the app's own merge configuration for additional app-compiled aliases.
+
+`ring` and `sidebar-ring` are focus roles tested at full strength. Preserve that
+strength and verify at least 3:1 against adjacent surfaces when overriding the
+theme; adding opacity can invalidate contrast even when the root color passes.
+
 ## Extend without drift
 
 Reuse existing color, text, action/control, row, surface or shell responsibilities first. An app token stays app-owned, not a package knob. New package tokens require multiple consumers, one owner/default/purpose, contract/docs updates and scoped behavior verification. Never expand the budget to fix one preview.
@@ -49,8 +84,18 @@ Use public structures/utilities for custom composition. Missing API seams should
 
 ## Copy rhythm
 
-Normal title/description gaps use `--gap-normal` (0.5rem); dense row and menu
-copy uses `--gap-dense` (0.25rem). Both multiply once by `--space-scale` and
+Normal title/description gaps use `--gap-normal` (0.25rem); dense row and menu
+copy uses `--gap-dense` (0.125rem). Both multiply once by `--space-scale` and
 inherit through ThemeScope and portaled surfaces. Control heights and insets
 remain separate. Use `textGap="normal" | "dense"` on headed surfaces and
 `gap="normal" | "dense"` on Stack/Grid instead of adding a description margin.
+
+## Independent geometry roles
+
+Use `--space-scale` for room around content and `--density-scale` for control
+heights. `--icon` and `--avatar` set media dimensions independently. Component
+`size` picks a shared sm/md/lg recipe; collection `density` changes row padding.
+Test these choices separately and in combination. Tables follow row insets,
+Cards and code/message bodies follow surfaces, and image containment uses generic
+spacing. Foundation directional spacing utilities ship with style.css and use
+the same seven steps as gaps; generated spellings are not new theme roots.

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

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "structural": [
     {
       "name": "--space-scale",
@@ -14,12 +14,12 @@
     },
     {
       "name": "--gap-normal",
-      "default": "0.5rem",
+      "default": "0.25rem",
       "purpose": "Vertical rhythm between titles and structural descriptions."
     },
     {
       "name": "--gap-dense",
-      "default": "0.25rem",
+      "default": "0.125rem",
       "purpose": "Vertical rhythm between row titles and compact supporting copy."
     },
     {
@@ -49,12 +49,12 @@
     },
     {
       "name": "--surface-x",
-      "default": "1rem",
+      "default": "1.25rem",
       "purpose": "Default inline inset for cards and multi-content surfaces."
     },
     {
       "name": "--surface-y",
-      "default": "1rem",
+      "default": "1.25rem",
       "purpose": "Default block inset for cards and multi-content surfaces."
     },
     {
@@ -120,11 +120,11 @@
   ],
   "radius": {
     "name": "--radius",
-    "default": "1rem",
-    "purpose": "Default corners throughout the package; opt-in nested corners derive from this root.",
+    "default": "0.75rem",
+    "purpose": "Shared 8px corners keep short controls rectangular; nested corners derive from this root.",
     "defaultUtility": "rounded-radius",
     "innerUtility": "rounded-inner",
-    "innerFormula": "calc(var(--radius) * 0.6)"
+    "innerFormula": "min(calc(var(--radius) * 0.75), calc(min(var(--height-action), var(--height-control)) * var(--density-scale) / 4))"
   },
   "advanced": [
     "--font-heading",
@@ -256,7 +256,175 @@
       "gap-x-normal",
       "gap-x-dense",
       "gap-y-normal",
-      "gap-y-dense"
+      "gap-y-dense",
+      "pt-space-2xs",
+      "pt-space-xs",
+      "pt-space-sm",
+      "pt-space-md",
+      "pt-space-lg",
+      "pt-space-xl",
+      "pt-space-2xl",
+      "pb-space-2xs",
+      "pb-space-xs",
+      "pb-space-sm",
+      "pb-space-md",
+      "pb-space-lg",
+      "pb-space-xl",
+      "pb-space-2xl",
+      "pl-space-2xs",
+      "pl-space-xs",
+      "pl-space-sm",
+      "pl-space-md",
+      "pl-space-lg",
+      "pl-space-xl",
+      "pl-space-2xl",
+      "pr-space-2xs",
+      "pr-space-xs",
+      "pr-space-sm",
+      "pr-space-md",
+      "pr-space-lg",
+      "pr-space-xl",
+      "pr-space-2xl",
+      "ps-space-2xs",
+      "ps-space-xs",
+      "ps-space-sm",
+      "ps-space-md",
+      "ps-space-lg",
+      "ps-space-xl",
+      "ps-space-2xl",
+      "pe-space-2xs",
+      "pe-space-xs",
+      "pe-space-sm",
+      "pe-space-md",
+      "pe-space-lg",
+      "pe-space-xl",
+      "pe-space-2xl",
+      "m-space-2xs",
+      "m-space-xs",
+      "m-space-sm",
+      "m-space-md",
+      "m-space-lg",
+      "m-space-xl",
+      "m-space-2xl",
+      "mx-space-2xs",
+      "mx-space-xs",
+      "mx-space-sm",
+      "mx-space-md",
+      "mx-space-lg",
+      "mx-space-xl",
+      "mx-space-2xl",
+      "my-space-2xs",
+      "my-space-xs",
+      "my-space-sm",
+      "my-space-md",
+      "my-space-lg",
+      "my-space-xl",
+      "my-space-2xl",
+      "mt-space-2xs",
+      "mt-space-xs",
+      "mt-space-sm",
+      "mt-space-md",
+      "mt-space-lg",
+      "mt-space-xl",
+      "mt-space-2xl",
+      "mb-space-2xs",
+      "mb-space-xs",
+      "mb-space-sm",
+      "mb-space-md",
+      "mb-space-lg",
+      "mb-space-xl",
+      "mb-space-2xl",
+      "ml-space-2xs",
+      "ml-space-xs",
+      "ml-space-sm",
+      "ml-space-md",
+      "ml-space-lg",
+      "ml-space-xl",
+      "ml-space-2xl",
+      "mr-space-2xs",
+      "mr-space-xs",
+      "mr-space-sm",
+      "mr-space-md",
+      "mr-space-lg",
+      "mr-space-xl",
+      "mr-space-2xl",
+      "ms-space-2xs",
+      "ms-space-xs",
+      "ms-space-sm",
+      "ms-space-md",
+      "ms-space-lg",
+      "ms-space-xl",
+      "ms-space-2xl",
+      "me-space-2xs",
+      "me-space-xs",
+      "me-space-sm",
+      "me-space-md",
+      "me-space-lg",
+      "me-space-xl",
+      "me-space-2xl",
+      "top-space-2xs",
+      "top-space-xs",
+      "top-space-sm",
+      "top-space-md",
+      "top-space-lg",
+      "top-space-xl",
+      "top-space-2xl",
+      "bottom-space-2xs",
+      "bottom-space-xs",
+      "bottom-space-sm",
+      "bottom-space-md",
+      "bottom-space-lg",
+      "bottom-space-xl",
+      "bottom-space-2xl",
+      "left-space-2xs",
+      "left-space-xs",
+      "left-space-sm",
+      "left-space-md",
+      "left-space-lg",
+      "left-space-xl",
+      "left-space-2xl",
+      "right-space-2xs",
+      "right-space-xs",
+      "right-space-sm",
+      "right-space-md",
+      "right-space-lg",
+      "right-space-xl",
+      "right-space-2xl",
+      "start-space-2xs",
+      "start-space-xs",
+      "start-space-sm",
+      "start-space-md",
+      "start-space-lg",
+      "start-space-xl",
+      "start-space-2xl",
+      "end-space-2xs",
+      "end-space-xs",
+      "end-space-sm",
+      "end-space-md",
+      "end-space-lg",
+      "end-space-xl",
+      "end-space-2xl",
+      "inset-space-2xs",
+      "inset-space-xs",
+      "inset-space-sm",
+      "inset-space-md",
+      "inset-space-lg",
+      "inset-space-xl",
+      "inset-space-2xl",
+      "inset-x-space-2xs",
+      "inset-x-space-xs",
+      "inset-x-space-sm",
+      "inset-x-space-md",
+      "inset-x-space-lg",
+      "inset-x-space-xl",
+      "inset-x-space-2xl",
+      "inset-y-space-2xs",
+      "inset-y-space-xs",
+      "inset-y-space-sm",
+      "inset-y-space-md",
+      "inset-y-space-lg",
+      "inset-y-space-xl",
+      "inset-y-space-2xl"
     ],
     "states": [
       "text-link-color",

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

@@ -12,6 +12,20 @@ This recipe uses `themelia-react-ui/features/table`, so install `@tanstack/react
 
 Verify loading, empty refresh, failure/retry and ready records. Open the row menu with pointer and keyboard, activate Open account, and assert the requested URL. Check narrow overflow and email-link behavior. If you need a presentational table without TanStack features, discover `themelia-react-ui/base/table` and inspect its separate declaration.
 
+`enableResizing` enables pointer and keyboard separators on individual/grouped
+headers. Arrow keys follow inherited text direction; Home/End use leaf minimums
+and explicit maximums from your column definitions. The table owns its one named
+scroll region. Verify grouped widths, sticky header rows and first-column behavior
+with real overflow in both directions, rather than adding another focusable wrapper.
+
+## Comment attachments
+
+`Comments` and `CommentComposer` announce attachment validation/upload errors.
+Use their existing attachment error `strings` for localization. Headless
+`useAttachmentUpload` accepts those same keys through `strings`; render feedback
+from `onError` in your own composer. Failed chips retain retry/remove actions.
+Reset/removal aborts pending uploads; the app owns transport and persistence.
+
 ## Detail and framing
 
 [AccountDetail](../examples/detail.tsx) exports `AccountDetail`, `AccountDetailProps` and `AccountDetailRecord`. Supply `account`, `onEdit(id)` and `onBack()`. Card owns the frame/header/body/footer; Name, Email, Date, Money and Value own formatting and missing-value fallbacks. `balanceMinor` uses `Money unit="minor"`; currency and date values come from the app.
@@ -63,6 +77,24 @@ that callback stable when its meaning is unchanged. Stabilize these lifecycle
 inputs deliberately, not every object. A real record/scope change can replace
 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.
+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
+needs that independent Card before nesting it under Page. Avoid repeating the
+route heading just to frame the same facts. Page owns gutters; PageViewport owns
+scrolling only. App navigation, record loading/missing/error/retry, permissions,
+edit and delete callbacks remain application responsibilities.
+
+Use `WorkspaceLayout` from `themelia-react-ui/layout/workspace` when independently composed record header,
+sidebar/main/rail regions are needed; inspect `features/resource` for complete
+resource coordination. A single record does not automatically need either.
+Read [layout composition](composition.md#application-layouts) for boundary and
+parent-width behavior, then the exact selected declaration for its current props.
+
 ## Validated editing
 
 [AccountEdit](../examples/edit.tsx) exports `AccountEdit`, `AccountEditProps` and `AccountEditValue`. Supply `initial`, `onSave(value): Promise<AccountEditValue>` and `onCancel()`. Mount with `key={initial.id}` when switching records. The draft is local to that mount; resetting the same record's draft deliberately also requires a new key or your own controlled adaptation.

package/docs/consumer-skill/scripts/check-composition.mjs

@@ -23,7 +23,7 @@ try {
   const reports = [...files].sort().map(filename => analyzeComposition(fs.readFileSync(filename, 'utf8'), { filename, index, ts }));
   const findings = reports.flatMap(report => report.findings);
   const errors = findings.filter(finding => finding.severity === 'error').length;
-  process.stdout.write(JSON.stringify({ package: index.package, version: index.version, files: files.size, errors, warnings: findings.length - errors, findings, unresolved: reports.flatMap(report => report.unresolved), limits: 'Direct public imports and same-file static JSX only; external CSS, cross-file wrappers and dynamic values require review.' }, null, 2) + '\n');
+  process.stdout.write(JSON.stringify({ package: index.package, version: index.version, files: files.size, errors, warnings: findings.length - errors, findings, unresolved: reports.flatMap(report => report.unresolved), limits: 'Source analysis only: recognized imports and same-file static JSX. External CSS, cross-file wrappers and dynamic values require review. No rendered, interaction, visual-acceptance or production-readiness verdict.' }, null, 2) + '\n');
   process.exitCode = errors ? 1 : 0;
 } catch (error) {
   process.stderr.write(`check-composition: ${error.message}\nRun from the consumer app with its TypeScript development dependency installed.\n`);