@cratis/pi 0.0.1

package/skills/cratis-components-schema-editor/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: cratis-components-schema-editor
+description: Use the Cratis Components schema editors — SchemaEditor for editing a JSON schema's property structure, and ObjectContentEditor for viewing and editing an object instance against a schema. Covers the exact props, the narrow JSON-schema subset they consume, how edits come back out, the type-format vocabulary, property-name validation, and the real editing limits. Use when building a UI that lets a user shape an event or payload schema, or inspect and edit a stored object. Do not use for a command form bound to a generated Arc command.
+license: MIT
+---
+
+# Cratis Components schema editors
+
+Two components edit schema-shaped data. They are **not** interchangeable:
+
+| Component | Edits | Subpath |
+| --- | --- | --- |
+| `SchemaEditor` | the **schema** — property names, types, and formats | `@cratis/components/SchemaEditor` |
+| `ObjectContentEditor` | an **object instance**, interpreted through a schema | `@cratis/components/ObjectContentEditor` |
+
+For a form bound to a generated Arc command, use `CommandForm` and its fields
+instead — see the **cratis-arc-react-page** skill. These editors are for the
+case where the shape itself is data.
+
+## Verified product sources
+
+| Package | Version | Verified from |
+| --- | --- | --- |
+| `@cratis/components` | `3.0.0` | its package manifest and the `SchemaEditor` / `ObjectContentEditor` sources |
+| `primereact` | `^11.0.0` | peer of `@cratis/components@3.0.0` |
+| `react` | `^19.0.0` | peer of `@cratis/components@3.0.0` |
+
+## The schema type these editors consume
+
+This is a deliberately narrow, hand-rolled subset — **not** a JSON Schema draft
+type. Import it from either editor's subpath.
+
+```ts
+interface JsonSchema {
+    title?: string; name?: string; $id?: string; $ref?: string;
+    type?: string; format?: string; description?: string;
+    properties?: Record<string, JsonSchemaProperty>;
+    items?: JsonSchema;
+    required?: string[];
+    definitions?: Record<string, JsonSchema>;
+}
+
+interface JsonSchemaProperty {
+    id?: string; name?: string; type?: string; format?: string; description?: string;
+    items?: JsonSchema; properties?: Record<string, JsonSchemaProperty>;
+    required?: boolean; $ref?: string;
+}
+
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+```
+
+Three limits to design around:
+
+- **`$ref` and `definitions` are declared but never resolved.** Nested
+  navigation walks `properties` and `items` literally. A schema that relies on
+  references will not render its referenced shapes.
+- **`type` is a plain string**, not a union — there is no exhaustiveness check.
+- **`required` is read but never rendered or edited** by `SchemaEditor`. Its
+  table has two columns, Property and Type. Do not promise a required toggle.
+
+## `SchemaEditor`
+
+```tsx
+import { SchemaEditor } from '@cratis/components/SchemaEditor';
+import type { JsonSchema, TypeFormat } from '@cratis/components/SchemaEditor';
+```
+
+The editor is internally stateful and pushes the **whole new schema** out on
+every structural change.
+
+```tsx
+const [schema, setSchema] = useState<JsonSchema>(initialSchema);
+
+<SchemaEditor
+    schema={schema}
+    eventTypeName='User'
+    canEdit
+    onChange={setSchema}
+    onSave={() => persist(schema)}
+    onCancel={() => reload()} />
+```
+
+### Props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `schema` | `JsonSchema` | **required** |
+| `eventTypeName` | `string` | `''` — the breadcrumb root label |
+| `canEdit` | `boolean` | `true` |
+| `canNotEditReason` | `string` | shown when `canEdit` is false |
+| `onChange` | `(schema: JsonSchema) => void` | receives the complete new schema |
+| `onSave` | `() => void` | takes **no arguments** |
+| `onCancel` | `() => void` | |
+| `editMode` | `boolean` | initial edit state only — see below |
+| `saveDisabled` | `boolean` | `false` |
+| `cancelDisabled` | `boolean` | `false` |
+| `typeFormats` | `TypeFormat[]` | the default vocabulary |
+| `className` | `string` | |
+| `labels` | `Partial<SchemaEditorLabels>` | override every visible and accessible string |
+
+### Two behaviors that decide how you wire it
+
+- **`editMode` is initial state, not a controlled prop.** It seeds the internal
+  flag once; changing it later has no effect. Drive edit mode from inside the
+  editor, or remount it with a `key` when you must force a mode.
+- **`schema` *is* re-synced.** A new `schema` identity resets both the working
+  copy and the cancel baseline. Cancel restores that baseline and calls
+  `onChange` with the restored clone, so a controlled parent stays consistent.
+
+`onSave` receives nothing — accumulate state from `onChange` and persist what
+you already hold. `onSave` also returns the editor to read mode.
+
+### Type and format vocabulary
+
+The type dropdown is built from `typeFormats`, a flat list of
+`{ jsonType, format }` pairs; the option label is the format when there is one,
+otherwise the JSON type. The container types `array` and `object` are always
+appended.
+
+The default vocabulary covers `string` (plain, `guid`, `date-time`, `date`,
+`time`), `integer` (plain, `int16`, `int32`, `int64`), `number` (plain, `float`,
+`double`), and `boolean`. Supply your own `typeFormats` to narrow or extend it.
+
+**`typeFormats` is the only extension point.** There is no registry mapping a
+schema type to a custom editor component — the cell renderers are a fixed
+branch on `array` / `object` / everything else. You can change the vocabulary,
+not the widget.
+
+Changing a property's type has side effects worth knowing: switching to `array`
+seeds `items` as a string and clears `format`; switching to `object` seeds an
+empty `properties` and clears `format` and `items`; switching to anything else
+clears both `items` and `properties`.
+
+### Nested navigation
+
+Drilling into an object property or an array's item definition pushes a
+breadcrumb segment. Array item definitions use the reserved path segment
+`$items`, rendered in the breadcrumb as `[items]`. Nested navigation is
+**click-driven only** — the breadcrumbs and rows are not keyboard-operable, so
+do not document a keyboard path that does not exist.
+
+### Property-name validation
+
+A property name must be non-empty, must match an identifier pattern (a letter
+or underscore followed by letters, digits, or underscores), and must be unique
+among its siblings. Save is disabled while any name is invalid.
+
+### Localization
+
+`SchemaEditorLabels` has ten fields, five of them accessible names:
+`edit`, `save`, `cancel`, `addProperty`, `actions`, `navigateBack`,
+`emptyMessage`, `navigateToItemDefinition`, `navigateToProperties`,
+`deleteProperty`. Pass `labels` with the ones you want to change — they merge
+over the English defaults. Never rely on the built-in English strings in a
+localized application.
+
+## `ObjectContentEditor`
+
+```tsx
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
+```
+
+Renders an object's values against a schema, read-only by default.
+
+```tsx
+const [value, setValue] = useState<Json>(storedObject);
+const [hasErrors, setHasErrors] = useState(false);
+
+<ObjectContentEditor
+    object={value}
+    schema={schema}
+    timestamp={occurred}
+    editMode
+    onChange={setValue}
+    onValidationChange={setHasErrors} />
+```
+
+### Props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `object` | `Json` | **required** |
+| `schema` | `JsonSchema` | **required** |
+| `timestamp` | `Date` | optional, displayed with the content |
+| `editMode` | `boolean` | `false` |
+| `onChange` | `(object: Json) => void` | receives the whole updated object |
+| `onValidationChange` | `(hasErrors: boolean) => void` | fires only in edit mode |
+| `className` | `string` | |
+
+### Editing limits — design around these
+
+- **Only root-level properties are editable.** Array and object values render
+  "not yet supported" text in edit mode, and any nested navigation view is
+  read-only by construction.
+- **In edit mode every field is treated as required**, regardless of the
+  schema's `required` list. The schema's `required` is consulted only in read
+  mode. If your object legitimately has optional values, either stay read-only
+  or gate saving on your own rules rather than on `onValidationChange`.
+- `onValidationChange` never fires outside edit mode, so a read-only view will
+  never report errors.
+
+### Field rendering
+
+The editor branches on the property's `type` and `format`: booleans render a
+checkbox, numbers an integer-friendly numeric input, `string` with `date-time`
+or `date` a date picker (emitting an ISO string, date-only for `date`), a long
+string a multi-line text area, and everything else a text input.
+
+Built-in format validation covers `email` and `uri`, plus numeric parseability.
+Anything richer belongs in the caller.
+
+## Breadcrumb
+
+`ObjectNavigationalBar` (`@cratis/components/ObjectNavigationalBar`) is the
+shared breadcrumb both editors use. Standalone, it takes `navigationPath`,
+`onNavigate`, and `backLabel` (which is both the tooltip and the accessible
+name — localize it). It is click-only, like the editors' own breadcrumbs.
+
+## Styling
+
+Both editors expose `className` only. Restyle their internals through a global
+PrimeReact pass-through preset on the provider rather than per instance — see
+the **cratis-components-styling** skill.
+
+## Verify
+
+- Imports use the component subpath, not the root barrel.
+- The schema passed in is the narrow subset — no `$ref` or `definitions` is
+  relied on for rendering.
+- The parent holds the schema or object state and updates it from `onChange`;
+  `onSave` is treated as a signal, not a carrier of data.
+- `editMode` on `SchemaEditor` is treated as initial state, not a controlled
+  prop.
+- Nothing in the UI or the documentation promises a required-flag toggle,
+  nested object editing, or keyboard navigation in these editors.
+- Every visible and accessible string is supplied through `labels` /
+  `backLabel` in a localized application.
+- Lint and the TypeScript build pass.

package/skills/cratis-components-stepper-command-dialog/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-components-stepper-command-dialog/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: cratis-components-stepper-command-dialog
+description: Build a multi-step wizard dialog for a single Cratis Arc command with StepperCommandDialog and StepperPanel from Cratis Components — named steps, per-step validation, linear navigation, vertical or horizontal orientation, and pre-populated edit wizards. Use when one command gathers information across several stages or a form has too many fields to show at once. Do not use for an ordinary single-page command dialog or for a page shell.
+license: MIT
+---
+
+# Cratis Components stepper command dialogs
+
+`StepperCommandDialog` splits **one** command's form across named steps. The
+user moves with Previous and Next; Submit appears on the last step once every
+field across every step is valid.
+
+## Verified product sources
+
+| Package | Version | Verified from |
+| --- | --- | --- |
+| `@cratis/components` | `3.0.0` | its package manifest and `CommandDialog` sources |
+| `@cratis/arc.react` | `>=20.3.1 <23` | peer range declared by `@cratis/components@3.0.0` |
+| `primereact` | `^11.0.0` | peer of `@cratis/components@3.0.0` |
+
+## Choose it over `CommandDialog` when
+
+- the form has too many fields to show at once;
+- the fields group into logical stages ("Contact → Details → Budget");
+- guided linear input with per-step feedback is what the task deserves.
+
+A four-field form is usually still an ordinary `CommandDialog`.
+
+## Step 1 — One command for the whole wizard
+
+Every step contributes properties to the same command instance. Define the
+command on the backend and run a Debug build so the TypeScript proxy exists
+before importing it.
+
+## Step 2 — Build the dialog
+
+```tsx
+import { StepperCommandDialog, StepperPanel } from '@cratis/components/CommandDialog';
+import { InputTextField, NumberField, TextAreaField } from '@cratis/components/CommandForm';
+import { DialogResult, useDialogContext } from '@cratis/arc.react/dialogs';
+import { CreateProject } from '../api/Projects/CreateProject';
+
+export const CreateProjectDialog = () => {
+    const { closeDialog } = useDialogContext();
+
+    return (
+        <StepperCommandDialog<CreateProject>
+            command={CreateProject}
+            title='Create new project'
+            okLabel='Create'
+            onSuccess={() => closeDialog(DialogResult.Ok)}
+            onCancel={() => closeDialog(DialogResult.Cancelled)}>
+            <StepperPanel header='Contact info'>
+                <InputTextField<CreateProject> value={c => c.email} title='Contact email' type='email' />
+            </StepperPanel>
+            <StepperPanel header='Project details'>
+                <InputTextField<CreateProject> value={c => c.name} title='Project name' />
+                <TextAreaField<CreateProject> value={c => c.description} title='Description' rows={4} />
+            </StepperPanel>
+            <StepperPanel header='Budget'>
+                <NumberField<CreateProject> value={c => c.budget} title='Budget' />
+            </StepperPanel>
+        </StepperCommandDialog>
+    );
+};
+```
+
+Rules:
+
+- Every `StepperPanel` needs a `header` — it is the step label.
+- All `CommandForm` fields inside any panel bind to the **same** command
+  instance through their `value` accessor.
+- Each command property belongs on exactly one step.
+- Next is disabled while the current step has validation errors.
+- Submit appears on the last step only when every field across every step is
+  valid.
+- `StepperCommandDialog` reads the dialog context when it is hosted by
+  `useDialog`, and works standalone when it is not.
+
+## Step 3 — Open it from the page
+
+```tsx
+import { useDialog } from '@cratis/arc.react/dialogs';
+
+const [CreateProjectWrapper, showCreateProject] = useDialog(CreateProjectDialog);
+
+<MenuItem label='New project' icon={() => <i className='pi pi-plus' />} command={() => showCreateProject()} />
+<CreateProjectWrapper />
+```
+
+## Validation timing
+
+Pass `validateOnInit` to run validation on mount so a wizard opened with
+pre-populated invalid values shows its errors immediately instead of after the
+first keystroke. `validateOn` (`'blur' | 'change' | 'both'`) chooses when
+subsequent validation runs.
+
+## Pre-populating an edit wizard
+
+`initialValues` is the synchronous baseline and also the change-tracking
+baseline — use it for values that must be present but are not user-entered.
+`currentValues` is the reactive overlay for values that arrive late, such as
+from a query.
+
+```tsx
+<StepperCommandDialog
+    command={UpdateProject}
+    title='Update project'
+    initialValues={{ projectId: project.id }}
+    currentValues={{ name: project.name, description: project.description }}>
+```
+
+Never seed a value required for validity in `onBeforeExecute` — validation runs
+against the pre-transform values, so the Submit button would stay permanently
+disabled.
+
+## Orientation and labels
+
+```tsx
+<StepperCommandDialog
+    command={RegisterEmployee}
+    title='Register employee'
+    orientation='vertical'
+    okLabel='Register'
+    nextLabel='Continue'
+    previousLabel='Back'>
+```
+
+## Props
+
+Dialog-level props:
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `command` | the generated command class | **required** |
+| `title` | `string` | **required** |
+| `children` | `StepperPanel` elements | — |
+| `visible` | `boolean` | `true` |
+| `width` | `string` | `'600px'` |
+| `okLabel` | `string` | `'Submit'` |
+| `nextLabel` | `string` | `'Next'` |
+| `previousLabel` | `string` | `'Previous'` |
+| `showCancel` | `boolean` | `false` |
+| `cancelLabel` | `string` | `'Cancel'` |
+| `isValid` | `boolean` | extra validity gate on top of form validity |
+| `onConfirm` / `onCancel` / `onClose` | close gates | — |
+| `onBeforeExecute` | `(values) => values` | transformer; must return the values |
+| `style` / `contentStyle` | `CSSProperties` | — |
+| `resizable` | `boolean` | `false` — accepted but has no effect |
+
+Stepper-level props (inherited from the stepper customization surface):
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `headerPosition` | `'top' \| 'bottom'` | `'top'` |
+| `linear` | `boolean` | `true` |
+| `showNavigation` | `boolean` | `true` |
+| `showSubmit` | `boolean` | `true` |
+| `start` / `end` | `React.ReactNode` | extra content beside the step headers |
+| `onChangeStep` | `(event: { index: number }) => void` | — |
+
+Command-form props (`initialValues`, `currentValues`, `validateOn`,
+`validateOnInit`, `onSuccess`, `onValidationFailure`, `onFailed`,
+`autoServerValidate`, …) all apply as well.
+
+### Two pass-through targets
+
+The inherited `pt`, `ptOptions`, and `unstyled` target the **inner stepper**.
+Use `dialogPt`, `dialogPtOptions`, `dialogUnstyled`, and `dialogClassName` to
+reach the **outer dialog**. Getting these the wrong way round is the usual cause
+of a pass-through that appears to do nothing.
+
+## Dismissal while the command runs
+
+The dialog withdraws its close control, Escape, and backdrop dismissal while the
+command is executing, so a half-submitted wizard cannot be abandoned mid-flight.
+Do not add your own Cancel button to the footer — set `showCancel` if the wizard
+needs one.
+
+## Related components
+
+`CommandStepper` (same subpath) is the stepper without the dialog chrome, for
+embedding a wizard directly in a page. It takes the same `StepperPanel`
+children.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| A hand-rolled Cancel button in the footer | Set `showCancel`, or rely on the header close control |
+| One step per field | Group related fields; aim for two to five per step |
+| The same property bound on two steps | Each property appears on exactly one step |
+| A `StepperPanel` without `header` | `header` is the navigation label |
+| Several panels wrapped in one fragment | A fragment counts as **one** step — give each step its own `StepperPanel` child |
+| A raw PrimeReact control for a command value | Use a `CommandForm` field, or validation never re-runs |
+| Seeding a required value in `onBeforeExecute` | Use `initialValues` |
+| `pt` applied expecting it to reach the dialog | `pt` targets the stepper; use `dialogPt` |
+
+## Verify
+
+- Imports come from `@cratis/components/CommandDialog` and
+  `@cratis/components/CommandForm`, not the root barrel.
+- Every `StepperPanel` has a `header` and is a direct child.
+- Every command property appears on exactly one step.
+- Required values come from `initialValues`.
+- `onBeforeExecute`, if present, returns the values.
+- Pass-through props target the intended element.
+- Lint and the TypeScript build pass.

package/skills/cratis-components-styling/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/skills/cratis-components-styling/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: cratis-components-styling
+description: Style and theme an application built on Cratis Components — the stylesheet imports an app must make, the --cratis-* design-token layer and the PrimeReact token chain behind it, choosing between the baseline theme, a styled preset, a custom palette, and fully unstyled, dark mode, the PrimeReact pass-through prop, and where Tailwind actually fits. Use when setting up a new Cratis frontend, changing colors or theming, fixing components that render unstyled, or reaching into a component's internal DOM. Do not use for component API or page composition questions.
+license: MIT
+---
+
+# Styling Cratis Components
+
+Cratis Components builds on PrimeReact 11, which is **unstyled-first**: it ships
+no CSS and renders no class names of its own. Everything a Cratis application
+looks like comes from the layers below. Getting the setup wrong shows up as
+components rendering completely unstyled, which is the single most common
+first-run problem.
+
+## Verified product sources
+
+| Package | Version | Verified from |
+| --- | --- | --- |
+| `@cratis/components` | `3.0.0` | its package manifest, `Styled/`, and the CSS sources |
+| `primereact` | `^11.0.0` | peer of `@cratis/components@3.0.0` |
+| `@primereact/core`, `@primereact/headless`, `@primereact/hooks` | `^11.0.0` | peers of `@cratis/components@3.0.0` |
+| `@primereact/styles`, `@primereact/types`, `@primeuix/themes` | optional peers | `@primereact/styles`/`types` `^11.0.0`, `@primeuix/themes` `^3.0.0` |
+| `primeicons` | `^8.0.0` | peer of `@cratis/components@3.0.0` |
+
+PrimeReact is a **peer dependency** — install it in the application yourself.
+Two copies mean two provider contexts, which breaks overlays and pass-through
+silently. Remove any `resolutions` or `overrides` pin that used to work around
+this.
+
+## Step 1 — What an app must do
+
+Two things, or the components render unstyled:
+
+1. **Mount `CratisComponentsProvider`** (from `@cratis/components/Common`)
+   above every Cratis component. It wraps the PrimeReact provider and merges
+   your configuration over the Cratis defaults, so anything you pass wins.
+2. **Import the stylesheets explicitly**, in this order — components no longer
+   import their own CSS:
+
+   ```ts
+   import '@cratis/components/tokens';   // the --cratis-* layer every component reads
+   import '@cratis/components/styles';   // every component stylesheet, in one file
+   import '@cratis/components/theme';    // optional: the license-free baseline look
+   ```
+
+Order matters: both `styles` and `theme` consume the tokens. The `styles` entry
+also vendors the split-pane CSS the `DataPage` details pane needs, so importing
+it is not optional even in a fully custom-styled app.
+
+## Step 2 — Pick one of four setups
+
+| Setup | What you do | When |
+| --- | --- | --- |
+| **Baseline theme** | import `tokens` + `styles` + `theme`, add the theme class to a root element | you want a working look with no license and little effort |
+| **Styled mode** | import `tokens` + `styles`, pass the Cratis styled-mode configuration to the provider | you want a full PrimeReact-preset look |
+| **Custom palette** | styled mode with your own preset | you have brand colors |
+| **Fully unstyled** | import `tokens` + `styles`, supply your own pass-through or CSS | you have your own design system |
+
+A preset **alone** is not one of these. Passing `theme: { preset }` to the
+provider emits the PrimeReact token variables but styles nothing that Cratis
+Components renders, because those are PrimeReact *primitives* — they render
+data attributes rather than class names, so a preset has nothing to attach to.
+That is exactly what the styled-mode helper fixes.
+
+### Styled mode
+
+`@cratis/components/styled` exports the pieces:
+
+- `CratisPreset` — a PrimeReact preset derived from Lara with the Cratis blue
+  primary ramp and a deliberate one-step surface shift so dark mode matches the
+  previous Cratis look.
+- `primeReactStyles` — the component-defaults map that glues the PrimeReact
+  primitive styles onto the primitives Cratis Components renders. This is the
+  part a bare preset is missing.
+- `styledMode(options?)` — returns `{ theme, defaults }` ready to hand to the
+  provider.
+
+```tsx
+import { CratisComponentsProvider } from '@cratis/components/Common';
+import { styledMode } from '@cratis/components/styled';
+
+<CratisComponentsProvider value={styledMode()}>
+    <App />
+</CratisComponentsProvider>
+```
+
+`styledMode` accepts `preset` (yours instead of `CratisPreset`),
+`darkModeSelector`, and `cssLayer`. Its defaults are the dark-mode selector
+`.cratis-dark` and a CSS layer named `primereact` ordered
+`theme, base, primereact, components, utilities`. That order is deliberate: the
+theme sits above Tailwind's `base` so preflight cannot strip table and input
+padding, and below `components` and `utilities` so a utility class still wins.
+
+### Dark mode
+
+Toggle the `cratis-dark` class on the root element. The baseline theme scopes
+its dark palette to that class, and styled mode uses it as the preset's dark
+selector by default.
+
+## Step 3 — Colors: use the token layer
+
+Never hard-code a hex or `rgb()` value for UI chrome — it breaks the moment the
+theme changes. Read a `--cratis-*` custom property instead.
+
+The chain is: **preset (JavaScript) → `--p-*` (runtime) → `--cratis-*` (the
+tokens stylesheet) → component CSS.** Each `--cratis-*` token resolves a
+PrimeReact 11 token with a PrimeReact 10 name as fallback, so both eras work.
+The tokens are intentionally fallback-free at the end of the chain: if nothing
+resolves, the rule no-ops rather than painting a wrong color.
+
+The full vocabulary:
+
+| Group | Tokens |
+| --- | --- |
+| Surfaces | `--cratis-surface-0`, `--cratis-surface-100`, `--cratis-surface-ground`, `--cratis-surface-section`, `--cratis-surface-card`, `--cratis-surface-overlay`, `--cratis-surface-hover`, `--cratis-surface-border` |
+| Text | `--cratis-text-color`, `--cratis-text-color-secondary` |
+| Primary | `--cratis-primary-color`, `--cratis-primary-color-text`, `--cratis-primary-300`, `--cratis-primary-400`, `--cratis-primary-500`, `--cratis-primary-600` |
+| Highlight | `--cratis-highlight-bg`, `--cratis-highlight-text-color` |
+| Semantic | `--cratis-green-500`, `--cratis-orange-500`, `--cratis-red-500` |
+| Geometry | `--cratis-border-radius` |
+| Effects | `--cratis-focus-ring`, `--cratis-maskbg` |
+
+Only hard-code a color that is intentionally theme-independent — a brand accent
+dot, a traffic-light indicator.
+
+A back-compatibility stylesheet
+(`@cratis/components/primereact-v10-palette`) republishes the PrimeReact 10
+names (`--surface-ground`, `--text-color`, `--primary-color`, and the numbered
+ramps) for code that has not migrated. Import it to keep an old application
+running; **write nothing new against those names.**
+
+## Step 4 — Writing styles
+
+- Put static styles in a **co-located `.css` file** and reference it from the
+  application's stylesheet manifest. Never write `import './Foo.css'` inside a
+  `.tsx` — a CSS file in the JavaScript module graph is what made the published
+  Cratis Components package unloadable in Node, and the library's own build now
+  fails if a component stylesheet is only reachable that way.
+- One CSS file per component. A composition root's CSS carries layout and
+  positioning for its children, not the children's own styling.
+- Use inline `style` **only** for runtime-dynamic values such as computed
+  pixel positions. A `style` object full of static token names bypasses theming
+  and review — move it to a class.
+- Name classes with a prefix matching the component.
+
+## Step 5 — Pass-through: reaching a component's internals
+
+PrimeReact's pass-through (`pt`) prop targets the internal parts of a rendered
+component; `ptOptions` controls how your values merge with existing ones, and
+`unstyled` opts a component out of the theme entirely. Cratis Components
+forwards all three, typed against the underlying primitive, on roughly thirty
+components — every command-form field, the buttons, dialogs, dropdowns, data
+tables, the toaster, and more.
+
+Three shapes to expect:
+
+1. **A single `pt`** on most components.
+2. **Named pass-throughs** where a component wraps two primitives —
+   `DataPage` takes `tablePt` / `tablePtOptions` / `tableUnstyled` and
+   `menubarPt` / `menubarPtOptions` / `menubarUnstyled`;
+   `StepperCommandDialog` uses plain `pt` for the inner stepper and `dialogPt`
+   for the outer dialog. Applying `pt` and expecting it to reach the other
+   element is the usual cause of a pass-through that seems to do nothing.
+3. **Composite pass-throughs**, such as the toaster's `{ region, toast }`.
+
+There is **no global Cratis pass-through preset shipped** — the library's
+defaults are deliberately empty so an application's configuration always wins.
+Supply your own through the provider's value when you want an app-wide preset:
+
+```tsx
+<CratisComponentsProvider value={{ pt: myAppPreset }}>
+```
+
+A few components expose `className` only and have no pass-through of their own —
+`SchemaEditor`, `ObjectContentEditor`, and `ObjectNavigationalBar`. Restyle
+those through the global preset. `BusyIndicatorDialog` is also global-preset
+only, because its request type is owned by the Arc React package.
+
+### Pass-through as attribute removal
+
+Setting a pass-through value to `undefined` **removes** that attribute. Cratis
+Components uses this deliberately to strip invalid ARIA that PrimeReact 11 emits
+— for example clearing `role` and `aria-controls` off stepper headers whose
+target ids are never rendered. It is a legitimate tool when you need to delete
+an attribute rather than add one.
+
+### The compatibility contract
+
+`@cratis/components/compatibility` exports a machine-checkable description of
+which pass-through keys and slots this major version supports against which
+PrimeReact major, plus an assertion helper. Use it in a specification when your
+application depends on reaching a specific internal part, so a PrimeReact
+upgrade that moves the part fails loudly instead of silently.
+
+## Where Tailwind fits
+
+Tailwind is **one supported path, not the Cratis default.** Cratis Components
+compiles Tailwind utilities with **preflight deliberately excluded**, so
+Tailwind's base resets never strip the component styling. If your application
+enables preflight, keep the CSS layer order from styled mode so the theme still
+sits above `base`.
+
+Do not reach for Tailwind utilities as the primary styling mechanism for Cratis
+components; reach for the token layer and pass-through first.
+
+## Verify
+
+- PrimeReact and its `@primereact/*` peers are installed in the application, at
+  one version each.
+- `CratisComponentsProvider` wraps the tree.
+- `@cratis/components/tokens` and `@cratis/components/styles` are imported once
+  at the entry point, tokens first.
+- Exactly one of the four setups is chosen — a bare preset with no styled-mode
+  defaults is not one of them.
+- No hex or `rgb()` value is hard-coded for UI chrome; colors read `--cratis-*`.
+- No new code is written against the PrimeReact 10 palette names.
+- No `.tsx` imports a `.css` file.
+- Inline `style` carries only runtime-dynamic values.
+- Pass-through props target the intended element, especially on `DataPage` and
+  `StepperCommandDialog`.
+- Dark mode is toggled with the `cratis-dark` class on the root element.

package/skills/cratis-components-toolbar/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.