@vireo-ai/trellis-ui 0.1.60 → 0.1.62

package/packages/theme-engine/generated/schemas/theme-manifest-v1.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trellis.build/schemas/theme-manifest-v1.json",
+  "additionalProperties": false,
+  "type": "object",
+  "required": [
+    "$schema",
+    "formatVersion",
+    "engineVersion",
+    "base",
+    "commits",
+    "outputs"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://trellis.build/schemas/theme-manifest-v1.json",
+      "type": "string"
+    },
+    "formatVersion": {
+      "const": 1,
+      "type": "number"
+    },
+    "engineVersion": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "base": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "commits": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "additionalProperties": false,
+        "type": "object",
+        "required": [
+          "path"
+        ],
+        "properties": {
+          "path": {
+            "minLength": 1,
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/packages/theme-engine/skills/create-trellis-theme/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: create-trellis-theme
+description: Create or tune a Trellis theme from brand, product, or visual direction using the knob catalog and source-controlled patch commits. Use for theme-wide color, typography, density, shape, depth, or composition changes, rather than component-specific CSS fixes.
+---
+
+# Create a Trellis theme
+
+Translate the requested design direction into the smallest sufficient sequence of Theme Patch Commits. Preserve the
+workspace as ordinary source: a complete base, an append-ordered JSONL log, and deterministic generated outputs.
+
+## Locate the toolchain and workspace
+
+Locate the authoring resource root: the directory containing `THEME_AUTHORING.md` and `generated/knobs/v1/`.
+For this packaged skill, it is two directories above the skill folder (`../../` from
+`skills/create-trellis-theme/`). If the skill was copied into an agent's skill directory, locate those resources in the
+project's installed `@vireo-ai/trellis-ui` package, under `packages/theme-engine/` (normally
+`node_modules/@vireo-ai/trellis-ui/packages/theme-engine/`). In the Trellis repository, the root is
+`packages/theme-engine/`.
+All resource paths below are relative to this root, not the application working directory.
+
+Read `THEME_AUTHORING.md`. Confirm the local CLI is available before changing source. In a consumer project, use
+`npm exec --no -- trellis …` from the project root; this uses the installed command without fetching another package.
+In the Trellis repository, use `pnpm trellis …`. The examples below use the consumer invocation.
+If the CLI, guide, or catalog is missing, report the missing resource and the installed package version; do not guess
+config paths or silently download a replacement toolchain.
+
+Locate the intended `theme.json`; do not infer a repository-wide active theme. If several Theme Workspaces exist, use
+the one belonging to the application or site in scope. A request to create a new theme authorizes initializing its
+workspace with `npm exec --no -- trellis theme init <directory>`. Reuse the existing workspace for tuning requests.
+
+The versioned Theme Config schema is at `generated/schemas/theme-config-v1.json` and identifies itself as
+`https://trellis.build/schemas/theme-config-v1.json`. A config's own `$schema` property is optional editor metadata:
+the compiler does not require or insert it, and a Theme Patch Commit must not add or remove it as a design change.
+
+Inspect the workspace's `theme.json`, `base.json`, and relevant recent lines of `commits.jsonl`. Never hand-edit a
+configured generated artifact.
+
+## Discover knobs progressively
+
+1. Read `generated/knobs/v1/manifest.json` for the available axes, semantic groups, tier counts, and impact scopes.
+2. Search `index.json` with filesystem or JSON tools for words from the request. Keep the result narrow; do not load the
+   complete index into the conversation.
+3. Search Primary and Tuning entries first. Map promising index entries' `group` IDs to the manifest's group `file`
+   paths, and open only those files.
+4. In a group file, use the knob's path, description, constraints, defaults, parameters, `patch.operation`, and
+   `patch.missingParents` to construct valid operations.
+5. Substitute every `{parameter}` with one of the documented values before emitting a JSON Pointer.
+
+The escalation tiers are intentional:
+
+- **Primary:** establish identity and broad character. Prefer these first.
+- **Tuning:** refine a specific relationship after the primary direction is sound.
+- **Expert:** change low-level policy only when Primary and Tuning controls cannot express the result.
+- **Escape Hatch:** set exact authored values that bypass generator behavior. Use only for an explicit need and state
+  why the higher-level controls were insufficient.
+
+Do not use many low-level knobs to simulate a higher-level change. Exact palette steps are an escape hatch, not the
+normal way to select an accent or neutral direction.
+
+## Author one coherent commit
+
+Create a temporary JSON file containing one `ThemePatchCommit`:
+
+```json
+{
+  "message": "Make control corners softer",
+  "operations": [
+    {"op": "replace", "path": "/radius/roles/control", "value": 4}
+  ]
+}
+```
+
+Use only supported RFC 6902 `add`, `remove`, and `replace` operations. Follow catalog constraints exactly. When a knob
+lists missing parents, add the required structure before its leaf in the same commit. Array members may be replaced,
+but array membership cannot be changed.
+
+Prefer the fewest leaf operations that express one design intention. Do not fill optional fields merely because they
+exist, rewrite the base to record an iteration, or rewrite earlier commits for a follow-up adjustment.
+
+Apply the candidate through the toolchain:
+
+```bash
+npm exec --no -- trellis theme apply path/to/theme.json path/to/candidate.json
+```
+
+An accepted apply appends one canonical JSONL record and refreshes selected outputs. If validation or compilation
+fails, use the diagnostics and catalog metadata to correct the candidate; do not patch around the compiler.
+If apply reports a concurrent commit-log change, reload the workspace and reassess the candidate before retrying.
+
+## Inspect and iterate
+
+Review `commits.jsonl`, generated outputs, and the Git diff. When a runnable application is available, inspect
+representative components in both light and dark appearances, including text hierarchy, controls, nested surfaces,
+focus, disabled and selected states, and one overlay.
+
+Treat the user's next instruction as a new commit against the current materialized theme. Keep attribution and rollback
+in Git; do not invent conversation state, snapshots, branches, undo commands, or a second revision graph.
+
+Use `npm exec --no -- trellis theme build <manifest>` after manual source or merge changes, and
+`npm exec --no -- trellis theme check <manifest>` for a read-only stale-output check. `init` creates source files;
+run `build` to produce the initial outputs. Paths in the manifest resolve relative to the manifest; CLI operands
+resolve from the command's working directory.
+
+## Hand off
+
+Report the design intention, knob paths and tiers used, accepted diagnostics, generated outputs, and checks performed.
+Call out any Expert or Escape Hatch use explicitly. Do not paste generated CSS unless the user asks for it.

package/packages/client/src/components/app/styles.css

@@ -1 +0,0 @@
-/* App shell structure is generated from the theme composition axis. */

package/packages/client/src/components/brand/styles.css

@@ -1,8 +0,0 @@
-@layer components {
-  [data-ui-brand-logo] svg {
-    display: block;
-    flex-shrink: 0;
-    height: 100%;
-    width: 100%;
-  }
-}

package/packages/client/src/styles/motion.css

@@ -1,26 +0,0 @@
-@keyframes ui-motion-progress {
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-@keyframes ui-motion-progress-reduced {
-  from {
-    opacity: 0.55;
-  }
-
-  to {
-    opacity: 1;
-  }
-}
-
-.ui-motion-progress {
-  animation: ui-motion-progress var(--motion-duration-continuous, 800ms) linear infinite;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .ui-motion-progress {
-    animation-name: ui-motion-progress-reduced;
-    animation-direction: alternate;
-  }
-}

package/packages/client/src/styles/static.css

@@ -1,4 +0,0 @@
-@import "./generated/theme-fonts.css";
-@import "tailwindcss" source(none);
-@import "./theme.css";
-@import "./motion.css";

package/packages/client/types/assets/full-runtime.generated.d.ts

@@ -1,2 +0,0 @@
-declare const fullRuntimeAssetIds: readonly ["trellis:core", "trellis:motion", "trellis:resizable", "trellis:sortable", "trellis:shortcut", "trellis:accordion", "trellis:button", "trellis:checkbox", "trellis:date-picker", "trellis:direct-upload", "trellis:dropdown", "trellis:field", "trellis:file-upload", "trellis:formset", "trellis:import-mapper", "trellis:input", "trellis:keybinding", "trellis:modal", "trellis:panels", "trellis:radio", "trellis:scroll-area", "trellis:select", "trellis:sidebar", "trellis:slider", "trellis:switch", "trellis:tabs", "trellis:toast", "trellis:tooltip", "trellis:data-grid", "trellis:virtualizer", "trellis:table"];
-export { fullRuntimeAssetIds };

package/packages/client/types/capabilities/motion.d.ts

@@ -1,6 +0,0 @@
-import type { Alpine as AlpineType } from 'alpinejs';
-import { registerBoundsDirective } from '../directives/bounds';
-import { motion } from '../motion';
-declare const registerMotionCapability: (AlpineInstance: AlpineType) => void;
-export { motion, registerBoundsDirective, registerMotionCapability };
-export type * from '../motion';

package/packages/client/types/capabilities/motion.entry.generated.d.ts

@@ -1,3 +0,0 @@
-import { registerMotionCapability } from './motion';
-export default registerMotionCapability;
-export * from './motion';

package/packages/client/types/cdn.d.ts

@@ -1,2 +0,0 @@
-import trellisUi from './index';
-export default trellisUi;

package/packages/client/types/components/entry.generated.d.ts

@@ -1,36 +0,0 @@
-import type { Alpine as AlpineType } from 'alpinejs';
-type ComponentsPlugin = (AlpineInstance: AlpineType) => void;
-declare const components: ComponentsPlugin;
-export { components };
-export default components;
-export type { ComponentsPlugin };
-export * from './accordion/entry.generated';
-export * from './button/entry.generated';
-export * from './checkbox/entry.generated';
-export * from './date-picker/entry.generated';
-export * from './direct-upload/entry.generated';
-export * from './dropdown/entry.generated';
-export * from './field/entry.generated';
-export * from './file-upload/entry.generated';
-export * from './formset/entry.generated';
-export * from './import-mapper/entry.generated';
-export * from './input/entry.generated';
-export * from './keybinding/entry.generated';
-export * from './modal/entry.generated';
-export * from './panels/entry.generated';
-export * from './radio/entry.generated';
-export * from './scroll-area/entry.generated';
-export * from './select/entry.generated';
-export * from './sidebar/entry.generated';
-export * from './slider/entry.generated';
-export * from './switch/entry.generated';
-export * from './tabs/entry.generated';
-export * from './toast/entry.generated';
-export * from './tooltip/entry.generated';
-export * from './data-grid/entry.generated';
-export * from './virtualizer/entry.generated';
-export * from './table/entry.generated';
-export * from '../capabilities/motion';
-export * from '../capabilities/resizable';
-export * from '../capabilities/sortable';
-export * from '../capabilities/shortcut';

package/packages/client/types/components/runtime-docs.d.ts

@@ -1,2 +0,0 @@
-declare const componentRuntimeDocs: import("../docs/transition-docs").ComponentTransitionDocs[];
-export { componentRuntimeDocs };

package/packages/client/types/directives/bounds.d.ts

@@ -1,4 +0,0 @@
-import type Alpine from 'alpinejs';
-declare const BOUNDS_ATTR = "data-ui-bounds";
-declare const registerBoundsDirective: (Alpine: Alpine.Alpine) => void;
-export { BOUNDS_ATTR, registerBoundsDirective };

package/packages/client/types/directives/layout.d.ts

@@ -1,3 +0,0 @@
-import type Alpine from 'alpinejs';
-declare const registerLayoutDirective: (Alpine: Alpine.Alpine) => void;
-export { registerLayoutDirective };

package/packages/client/types/index.d.ts

@@ -1,8 +0,0 @@
-import type { Alpine as AlpineType } from 'alpinejs';
-type TrellisUIPlugin = (AlpineInstance: AlpineType) => void;
-declare const trellisUi: TrellisUIPlugin;
-export { trellisUi };
-export default trellisUi;
-export type { TrellisUIPlugin };
-export * from './core';
-export * from './components/entry.generated';

package/packages/client/types/motion/bounds.d.ts

@@ -1,20 +0,0 @@
-import type { MotionHandle } from './animate';
-import { type MotionRoleName } from './recipe';
-type BoundsProperty = 'height' | 'width' | 'maxHeight' | 'maxWidth';
-type BoundsMotionOptions = Readonly<{
-    properties?: readonly BoundsProperty[];
-    role?: MotionRoleName;
-}>;
-type BoundsUpdateOptions = Readonly<{
-    animate?: boolean;
-    /** Stable identity for an animated destination, used to coalesce duplicate syncs. */
-    key?: string;
-}>;
-type BoundsMotion = Readonly<{
-    update(mutate?: () => void, options?: BoundsUpdateOptions): MotionHandle | null;
-    refresh(options?: BoundsUpdateOptions): MotionHandle | null;
-    destroy(): void;
-}>;
-declare const createBoundsMotion: (element: HTMLElement, options?: BoundsMotionOptions) => BoundsMotion;
-export { createBoundsMotion };
-export type { BoundsMotion, BoundsMotionOptions, BoundsProperty, BoundsUpdateOptions };

package/packages/client/types/motion/controller.d.ts

@@ -1,33 +0,0 @@
-import { type ValueAnimationTransition } from 'motion';
-import { type MotionHandle } from './animate';
-import { type MotionPreference } from './reduced-motion';
-type ControllerScalar = string | number;
-type ControllerValues = Record<string, ControllerScalar>;
-type ControllerValueDefinition<T extends ControllerScalar> = T | Readonly<{
-    initial: T;
-    transition?: ValueAnimationTransition<T>;
-}>;
-type ControllerDefinitions = Record<string, ControllerValueDefinition<ControllerScalar>>;
-type Widen<T> = T extends number ? number : T extends string ? string : never;
-type DefinitionValue<T> = T extends {
-    initial: infer Initial;
-} ? Widen<Initial> : Widen<T>;
-type ControllerState<T extends ControllerDefinitions> = {
-    [K in keyof T]: DefinitionValue<T[K]>;
-};
-type StyleProjection<T extends ControllerValues> = (values: Readonly<T>) => Readonly<Record<string, string | number>>;
-type ControllerOptions<T extends ControllerDefinitions> = Readonly<{
-    values: T;
-    style: StyleProjection<ControllerState<T>>;
-    reducedMotion?: MotionPreference;
-}>;
-type Controller<T extends ControllerValues> = {
-    mount(element: HTMLElement): () => void;
-    set(values: Partial<T>): void;
-    animate(values: Partial<T>, transition?: ValueAnimationTransition): MotionHandle;
-    current(): Readonly<T>;
-    destroy(): void;
-};
-declare const createController: <T extends ControllerDefinitions>(options: ControllerOptions<T>) => Controller<ControllerState<T>>;
-export { createController };
-export type { Controller, ControllerDefinitions, ControllerOptions, ControllerScalar, ControllerState, ControllerValueDefinition, ControllerValues, StyleProjection, };

package/packages/client/types/motion/flip.d.ts

@@ -1,14 +0,0 @@
-import { type MotionHandle } from './animate';
-import { type MotionRoleName, type MotionTransition } from './recipe';
-import { type MotionSubject } from './subject';
-type FlipOptions = Readonly<{
-    target?: Element | string | readonly (Element | string)[];
-    update(): void;
-    role?: MotionRoleName;
-    transition?: MotionTransition;
-    signal?: AbortSignal | null;
-}>;
-/** Commit final geometry once, then animate every visual from its inverse frame using transform only. */
-declare const flip: (subject: MotionSubject, options: FlipOptions) => MotionHandle;
-export { flip };
-export type { FlipOptions };

package/packages/client/types/motion/plan.d.ts

@@ -1,52 +0,0 @@
-import { type DOMKeyframesDefinition } from 'motion';
-import { type MotionHandle } from './animate';
-import { type MotionRoleName, type MotionSpeed, type MotionTransition } from './recipe';
-import { type ResizeOptions } from './resize';
-import { type MotionSubject } from './subject';
-type MotionTarget = Element | string;
-type AnimateSegment = Readonly<{
-    kind: 'animate';
-    target?: MotionTarget;
-    keyframes: Readonly<DOMKeyframesDefinition>;
-    speed?: MotionSpeed;
-    role?: MotionRoleName;
-    transition?: MotionTransition;
-}>;
-type ResizeSegment = Readonly<{
-    kind: 'resize';
-    options: ResizeOptions;
-    speed?: MotionSpeed;
-    role?: MotionRoleName;
-    transition?: MotionTransition;
-}>;
-type MotionSegment = AnimateSegment | ResizeSegment;
-type MotionStage = readonly MotionSegment[];
-type MotionDefaults = Readonly<{
-    speed?: MotionSpeed;
-    role?: MotionRoleName;
-    transition?: MotionTransition;
-}>;
-type MotionPlanOptions = Readonly<{
-    speed?: MotionSpeed;
-    role?: MotionRoleName;
-    transition?: MotionTransition;
-}>;
-declare class MotionPlan {
-    #private;
-    constructor(subject: MotionSubject, stages?: readonly MotionStage[], defaults?: MotionDefaults);
-    animate(keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    animate(target: MotionTarget, keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    with(keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    with(target: MotionTarget, keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    then(keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    then(target: MotionTarget, keyframes: Readonly<DOMKeyframesDefinition>): MotionPlan;
-    resize(options: ResizeOptions): MotionPlan;
-    speed(speed: MotionSpeed): MotionPlan;
-    role(role: MotionRoleName): MotionPlan;
-    transition(transition: MotionTransition): MotionPlan;
-    defaults(options: MotionPlanOptions): MotionPlan;
-    play(): MotionHandle;
-}
-declare const createMotionPlan: (subject: MotionSubject) => MotionPlan;
-export { createMotionPlan, MotionPlan };
-export type { MotionDefaults, MotionPlanOptions, MotionSegment, MotionStage, MotionTarget };

package/packages/client/types/motion/stream.d.ts

@@ -1,18 +0,0 @@
-import { type AnimateViewOptions } from './view';
-import { type MotionTarget, type ViewScope } from './targets';
-import { type MotionHandle } from './animate';
-import { type MotionPreference } from './reduced-motion';
-type StreamPatchLike = {
-    html?: string | null;
-    target?: string | null;
-    selector?: string | null;
-};
-type AnimateStreamPatchOptions = Omit<AnimateViewOptions, 'scope' | 'preset'> & {
-    scope?: ViewScope | 'target';
-    update?: () => void | Promise<void>;
-    reducedMotion?: MotionPreference;
-};
-declare const streamTargetsFromPatches: (patches: StreamPatchLike[]) => MotionTarget[];
-declare const animateStreamPatch: <AlpineInstance>(_Alpine: AlpineInstance, patchOrPatches: StreamPatchLike | StreamPatchLike[], options?: AnimateStreamPatchOptions) => MotionHandle;
-export { animateStreamPatch, streamTargetsFromPatches };
-export type { AnimateStreamPatchOptions, StreamPatchLike };

package/packages/client/types/motion/targets.d.ts

@@ -1,23 +0,0 @@
-import { MOTION_KEY_ATTR, MOTION_LAYOUT_ATTR, markLayoutParticipant } from '../runtime/layout-participant';
-type MotionTarget = Element | string | {
-    selector: string;
-} | {
-    part: string;
-} | {
-    key: string;
-} | {
-    from: MotionTarget;
-    to: MotionTarget;
-};
-type ViewScope = Element | Document | string | Iterable<Element>;
-type ViewTargetDefinition = Element | string;
-type ResolvedViewTarget = {
-    subject: ViewTargetDefinition;
-    newSubject?: ViewTargetDefinition;
-};
-declare const cssEscape: (value: string) => string;
-declare const keySelector: (key: string) => string;
-declare const partSelector: (part: string) => string;
-declare const resolveViewTargets: (scope?: ViewScope, targets?: MotionTarget | MotionTarget[] | null) => ResolvedViewTarget[];
-export { MOTION_KEY_ATTR, MOTION_LAYOUT_ATTR, cssEscape, keySelector, markLayoutParticipant, partSelector, resolveViewTargets, };
-export type { MotionTarget, ResolvedViewTarget, ViewScope, ViewTargetDefinition };

package/packages/client/types/motion/view.d.ts

@@ -1,27 +0,0 @@
-import { type AnimationOptions, type DOMKeyframesDefinition, type ViewTransitionOptions } from 'motion';
-import { type MotionHandle } from './animate';
-import { type MotionPreference } from './reduced-motion';
-import { type MotionTarget, type ViewScope } from './targets';
-type ViewPreset = 'layout' | 'stream' | 'none';
-type AnimateViewOptions = {
-    scope?: ViewScope;
-    reducedMotion?: MotionPreference;
-    preset?: ViewPreset;
-    transition?: ViewTransitionOptions;
-    layout?: boolean | AnimationOptions;
-    newView?: DOMKeyframesDefinition;
-    oldView?: DOMKeyframesDefinition;
-    enter?: DOMKeyframesDefinition;
-    exit?: DOMKeyframesDefinition;
-    className?: string;
-    crop?: boolean;
-    group?: boolean;
-};
-type ViewOptions = AnimateViewOptions & {
-    targets?: MotionTarget | MotionTarget[] | null;
-};
-declare const configureViewFlush: (flush: () => Promise<unknown>) => void;
-declare const animateView: (update: () => void | Promise<void>, targets?: MotionTarget | MotionTarget[] | null, options?: AnimateViewOptions) => MotionHandle;
-declare const view: (update: () => void | Promise<void>, options?: ViewOptions) => MotionHandle;
-export { animateView, configureViewFlush, view };
-export type { AnimateViewOptions, ViewOptions, ViewPreset };