@synergy-design-system/metadata 3.6.0 → 3.8.0

package/data/layers/rules/component/component:syn-tooltip.md

@@ -0,0 +1,47 @@
+# syn-tooltip
+
+## Summary
+
+Tooltips display additional information based on a specific action.
+
+## Common Use Cases
+
+- Provide additional, useful, and non-essential information about form fields.
+- Expand abbreviations or acronyms that might be unfamiliar to users.
+- Offer detailed information about specific data points in charts or graphs.
+- Provide more context for error messages or warnings and anticipate any questions that users may have.
+
+## Usage Guidelines
+
+### Behavior and Placement
+
+- Place the tooltip where the floating element does not obscure important content related to the subject.
+- Ensure it disappears when the user interacts with other elements.
+- Avoid tooltips being cropped by other elements of the interface; use appropriate placement for this purpose.
+
+### Content
+
+- Use short, descriptive text; if a longer explanation is required, consider non-interactive means to convey this information.
+- Avoid jargon or highly technical language; aim to solve questions, not trigger more.
+- Do not use for critical or unique information.
+- Do not place links, buttons, or other interactive elements within the content.
+
+### Styling
+
+- Display a headline by bolding the text if it makes the content easier to understand.
+- Emphasize key information by bolding parts of the text.
+
+### Trigger Element
+
+- Use any interactive element as a tooltip trigger by placing it in the provided slot. The tooltip will open when the user hovers over or focuses on the trigger element.
+
+## Accessibility
+
+- Avoid placing buttons, links, or other interactive controls inside a tooltip, as it's designed to be an ephemeral container for supplementary information.
+- On desktop, tooltips open by default on hover over the trigger element, or optionally on click. They close by clicking the trigger again or by moving the pointer away.
+- On touch devices, tooltips open when tapping on the trigger element and close by tapping on the trigger element again.
+- For keyboard navigation, tooltips should open by focusing (Tab) on the trigger element and close by pressing Escape or by moving focus away.
+
+## Related Templates
+
+- tooltip

package/data/layers/rules/component/component:syn-validate.md

@@ -0,0 +1,50 @@
+# syn-validate
+
+## Summary
+
+Validate provides form field validation messages in a unified way.
+It does this by using [the native browser validation](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation)
+and showing the validation message in a consistent, user defined way.
+
+## Common Use Cases
+
+- Display field validation for forms and wizards.
+- Show custom validation messages for domain specific rules.
+- Integrate consistent error handling across native and custom form controls.
+
+## Usage Guidelines
+
+### Validation Messages
+
+- Write actionable messages that tell users what to fix and how.
+- Prefer field specific messages over generic form level errors.
+- Use consistent wording for recurring validation rules.
+
+### Display Variants
+
+- Use inline variant for persistent field level feedback.
+- Use tooltip variant where space is constrained and interaction remains clear.
+- Hide icons only when another strong error cue is present.
+
+### Validation Timing
+
+- Use eager validation for high risk fields that benefit from immediate feedback.
+- Use submit time validation to reduce interruption in long forms.
+- Support custom validation events when integrating non-standard controls.
+
+## Accessibility
+
+- Validation messages must be text based and clearly associated with the target field.
+- Use live validation thoughtfully to avoid excessive announcement noise for screen readers.
+- Provide specific corrective guidance instead of generic error statements.
+
+## Related Components
+
+- syn-input
+- syn-select
+- syn-textarea
+- syn-file
+
+## Related Templates
+
+- Forms

package/data/manifest.json

@@ -1,5 +1,5 @@
 {
-  "builtAt": "2026-05-06T08:56:23.924Z",
+  "builtAt": "2026-05-21T10:37:34.454Z",
   "sources": [
     {
       "entityCount": 4,

package/data/schemas/core-entity.schema.json

@@ -33,6 +33,7 @@
               "enum": [
                 "examples",
                 "interface",
+                "rules",
                 "full"
               ],
               "type": "string"

package/data/schemas/layer-ref.schema.json

@@ -6,6 +6,7 @@
       "enum": [
         "examples",
         "interface",
+        "rules",
         "full"
       ],
       "type": "string"

package/dist/bin/install-skills.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/install-skills.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * CLI entry point: install-skills
+ *
+ * Usage:
+ *   npx @synergy-design-system/metadata install-skills --path .github/skills
+ *   npx @synergy-design-system/metadata install-skills --path=/absolute/path
+ */
+import { resolve } from 'node:path';
+import { generateSkillBundle } from '../public/index.js';
+const SYNERGY_LOGO = `
+  +------------------------------+
+  |----+++++++--------+++++++----|
+  |---++------+*---*-+------++---|
+  |---++---------%*---------++---|
+  |---++---------++---------++---|
+  |---++-----*+++**+++%-----*+---|
+  |----**----*---++---*----++----|
+  |------****%********%****------|
+  |----++----*---++---*----**----|
+  |---+*-----%+++**+++*-----++---|
+  |---++---------++---------++---|
+  |---++---------*%---------++---|
+  |---++------+-*---*+------++---|
+  |----+++++++--------+++++++----|
+  +------------------------------+
+`;
+/**
+ * Parse command line arguments into options.
+ */
+function parseArgs(args) {
+    return args.reduce((opts, arg, index) => {
+        if (arg === '--path' && index + 1 < args.length) {
+            return { ...opts, path: args[index + 1] };
+        }
+        if (arg.startsWith('--path=')) {
+            return { ...opts, path: arg.substring('--path='.length) };
+        }
+        return opts;
+    }, {});
+}
+/**
+ * Validate parsed options and throw if required fields are missing.
+ */
+function validateOptions(opts) {
+    if (!opts.path) {
+        throw new Error('--path argument is required\nUsage: install-skills --path <directory>');
+    }
+}
+async function main() {
+    try {
+        const opts = parseArgs(process.argv.slice(2));
+        validateOptions(opts);
+        const absolutePath = resolve(process.cwd(), opts.path);
+        console.log(`Installing Synergy skills to: ${absolutePath}`);
+        await generateSkillBundle({ outputPath: absolutePath });
+        console.log(SYNERGY_LOGO);
+        console.log('✓ Synergy skills installed successfully\n');
+        console.log('Next steps:');
+        console.log('  1. In VS Code, reference the skill with: @synergy-component');
+        console.log('  2. Ask questions like: "How do I use syn-button?"');
+        console.log(`\nSkill location: ${absolutePath}`);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('--path')) {
+            throw new Error(`Error: ${error.message}`);
+        }
+        else {
+            throw new Error(`Error installing skills: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+main()
+    .then(() => process.exit(0))
+    .catch((e) => {
+    console.error(e.message);
+    process.exit(1);
+});

package/dist/intentPolicy/capabilities/action.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const actionCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/action.js

@@ -0,0 +1,26 @@
+export const actionCapabilities = [
+    {
+        categories: ['action'],
+        target: {
+            id: 'component:syn-button',
+            kind: 'component',
+            name: 'syn-button',
+        },
+    },
+    {
+        categories: ['action'],
+        target: {
+            id: 'component:syn-icon-button',
+            kind: 'component',
+            name: 'syn-icon-button',
+        },
+    },
+    {
+        categories: ['action'],
+        target: {
+            id: 'component:syn-button-group',
+            kind: 'component',
+            name: 'syn-button-group',
+        },
+    },
+];

package/dist/intentPolicy/capabilities/assistance.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const assistanceCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/assistance.js

@@ -0,0 +1,10 @@
+export const assistanceCapabilities = [
+    {
+        categories: ['assistance'],
+        target: { id: 'component:syn-tooltip', kind: 'component', name: 'syn-tooltip' },
+    },
+    {
+        categories: ['assistance'],
+        target: { id: 'component:syn-icon', kind: 'component', name: 'syn-icon' },
+    },
+];

package/dist/intentPolicy/capabilities/disclosure.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const disclosureCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/disclosure.js

@@ -0,0 +1,14 @@
+export const disclosureCapabilities = [
+    {
+        categories: ['disclosure'],
+        target: { id: 'component:syn-details', kind: 'component', name: 'syn-details' },
+    },
+    {
+        categories: ['disclosure'],
+        target: { id: 'component:syn-accordion', kind: 'component', name: 'syn-accordion' },
+    },
+    {
+        categories: ['disclosure'],
+        target: { id: 'component:syn-popup', kind: 'component', name: 'syn-popup' },
+    },
+];

package/dist/intentPolicy/capabilities/feedback.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const feedbackCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/feedback.js

@@ -0,0 +1,42 @@
+export const feedbackCapabilities = [
+    {
+        categories: ['feedback'],
+        target: {
+            id: 'component:syn-alert',
+            kind: 'component',
+            name: 'syn-alert',
+        },
+    },
+    {
+        categories: ['feedback'],
+        target: {
+            id: 'component:syn-badge',
+            kind: 'component',
+            name: 'syn-badge',
+        },
+    },
+    {
+        categories: ['feedback'],
+        target: {
+            id: 'component:syn-tag',
+            kind: 'component',
+            name: 'syn-tag',
+        },
+    },
+    {
+        categories: ['feedback'],
+        target: {
+            id: 'component:syn-tag-group',
+            kind: 'component',
+            name: 'syn-tag-group',
+        },
+    },
+    {
+        categories: ['feedback'],
+        target: {
+            id: 'component:syn-validate',
+            kind: 'component',
+            name: 'syn-validate',
+        },
+    },
+];

package/dist/intentPolicy/capabilities/index.d.ts

@@ -0,0 +1,6 @@
+import type { IntentCapability } from '../types.js';
+/**
+ * A comprehensive list of intent capabilities, categorized by their respective intent categories.
+ * Each capability outlines the specific functionalities and features that an intent can support within a user interface, providing designers and developers with a clear understanding of how to effectively implement and leverage these capabilities to enhance user interactions and overall experience.
+ */
+export declare const targetCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/index.js

@@ -0,0 +1,22 @@
+import { actionCapabilities } from './action.js';
+import { assistanceCapabilities } from './assistance.js';
+import { disclosureCapabilities } from './disclosure.js';
+import { feedbackCapabilities } from './feedback.js';
+import { inputCapabilities } from './input.js';
+import { navigationCapabilities } from './navigation.js';
+import { statusCapabilities } from './status.js';
+import { structureCapabilities } from './structure.js';
+/**
+ * A comprehensive list of intent capabilities, categorized by their respective intent categories.
+ * Each capability outlines the specific functionalities and features that an intent can support within a user interface, providing designers and developers with a clear understanding of how to effectively implement and leverage these capabilities to enhance user interactions and overall experience.
+ */
+export const targetCapabilities = [
+    ...actionCapabilities,
+    ...feedbackCapabilities,
+    ...inputCapabilities,
+    ...navigationCapabilities,
+    ...disclosureCapabilities,
+    ...statusCapabilities,
+    ...assistanceCapabilities,
+    ...structureCapabilities,
+];

package/dist/intentPolicy/capabilities/input.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const inputCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/input.js

@@ -0,0 +1,38 @@
+export const inputCapabilities = [
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-input', kind: 'component', name: 'syn-input' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-textarea', kind: 'component', name: 'syn-textarea' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-select', kind: 'component', name: 'syn-select' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-combobox', kind: 'component', name: 'syn-combobox' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-checkbox', kind: 'component', name: 'syn-checkbox' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-switch', kind: 'component', name: 'syn-switch' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-radio-group', kind: 'component', name: 'syn-radio-group' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-file', kind: 'component', name: 'syn-file' },
+    },
+    {
+        categories: ['input'],
+        target: { id: 'component:syn-range', kind: 'component', name: 'syn-range' },
+    },
+];

package/dist/intentPolicy/capabilities/navigation.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const navigationCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/navigation.js

@@ -0,0 +1,54 @@
+export const navigationCapabilities = [
+    {
+        categories: ['navigation', 'action'],
+        target: {
+            classes: ['syn-link'],
+            id: 'style:syn-link',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link',
+        },
+    },
+    {
+        categories: ['navigation'],
+        target: {
+            classes: ['syn-link-list'],
+            id: 'style:syn-link-list',
+            kind: 'style',
+            layer: 'examples',
+            selector: '.syn-link-list',
+        },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-tab-group', kind: 'component', name: 'syn-tab-group' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-menu', kind: 'component', name: 'syn-menu' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-dropdown', kind: 'component', name: 'syn-dropdown' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-pagination', kind: 'component', name: 'syn-pagination' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-breadcrumb', kind: 'component', name: 'syn-breadcrumb' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-breadcrumb-item', kind: 'component', name: 'syn-breadcrumb-item' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-side-nav', kind: 'component', name: 'syn-side-nav' },
+    },
+    {
+        categories: ['navigation'],
+        target: { id: 'component:syn-nav-item', kind: 'component', name: 'syn-nav-item' },
+    },
+];

package/dist/intentPolicy/capabilities/status.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const statusCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/status.js

@@ -0,0 +1,14 @@
+export const statusCapabilities = [
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-spinner', kind: 'component', name: 'syn-spinner' },
+    },
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-progress-bar', kind: 'component', name: 'syn-progress-bar' },
+    },
+    {
+        categories: ['status'],
+        target: { id: 'component:syn-progress-ring', kind: 'component', name: 'syn-progress-ring' },
+    },
+];

package/dist/intentPolicy/capabilities/structure.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCapability } from '../types.js';
+export declare const structureCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities/structure.js

@@ -0,0 +1,22 @@
+export const structureCapabilities = [
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-dialog', kind: 'component', name: 'syn-dialog' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-drawer', kind: 'component', name: 'syn-drawer' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-header', kind: 'component', name: 'syn-header' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-card', kind: 'component', name: 'syn-card' },
+    },
+    {
+        categories: ['structure'],
+        target: { id: 'component:syn-divider', kind: 'component', name: 'syn-divider' },
+    },
+];

package/dist/intentPolicy/capabilities.d.ts

@@ -0,0 +1,6 @@
+import type { IntentCapability } from './types.js';
+/**
+ * A comprehensive list of intent capabilities, categorized by their respective intent categories.
+ * Each capability outlines the specific functionalities and features that an intent can support within a user interface, providing designers and developers with a clear understanding of how to effectively implement and leverage these capabilities to enhance user interactions and overall experience.
+ */
+export declare const targetCapabilities: IntentCapability[];

package/dist/intentPolicy/capabilities.js

@@ -0,0 +1,22 @@
+import { actionCapabilities } from './domains/action/index.js';
+import { assistanceCapabilities } from './domains/assistance/index.js';
+import { disclosureCapabilities } from './domains/disclosure/index.js';
+import { feedbackCapabilities } from './domains/feedback/index.js';
+import { inputCapabilities } from './domains/input/index.js';
+import { navigationCapabilities } from './domains/navigation/index.js';
+import { statusCapabilities } from './domains/status/index.js';
+import { structureCapabilities } from './domains/structure/index.js';
+/**
+ * A comprehensive list of intent capabilities, categorized by their respective intent categories.
+ * Each capability outlines the specific functionalities and features that an intent can support within a user interface, providing designers and developers with a clear understanding of how to effectively implement and leverage these capabilities to enhance user interactions and overall experience.
+ */
+export const targetCapabilities = [
+    ...actionCapabilities,
+    ...feedbackCapabilities,
+    ...inputCapabilities,
+    ...navigationCapabilities,
+    ...disclosureCapabilities,
+    ...statusCapabilities,
+    ...assistanceCapabilities,
+    ...structureCapabilities,
+];

package/dist/intentPolicy/categories/action.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const actionCategory: IntentCategory;

package/dist/intentPolicy/categories/action.js

@@ -0,0 +1,4 @@
+export const actionCategory = {
+    description: 'Contextual actions such as primary, submit, reset, or navigation actions.',
+    id: 'action',
+};

package/dist/intentPolicy/categories/assistance.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const assistanceCategory: IntentCategory;

package/dist/intentPolicy/categories/assistance.js

@@ -0,0 +1,4 @@
+export const assistanceCategory = {
+    description: 'Contextual micro-guidance for nearby controls or content.',
+    id: 'assistance',
+};

package/dist/intentPolicy/categories/disclosure.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const disclosureCategory: IntentCategory;

package/dist/intentPolicy/categories/disclosure.js

@@ -0,0 +1,4 @@
+export const disclosureCategory = {
+    description: 'Progressive disclosure of secondary information.',
+    id: 'disclosure',
+};

package/dist/intentPolicy/categories/feedback.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const feedbackCategory: IntentCategory;

package/dist/intentPolicy/categories/feedback.js

@@ -0,0 +1,4 @@
+export const feedbackCategory = {
+    description: 'Contextual user feedback such as inline or toast notifications.',
+    id: 'feedback',
+};

package/dist/intentPolicy/categories/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A comprehensive list of intent categories, each representing a distinct classification of user intents that can be utilized within a user interface.
+ * These categories serve as a foundational framework for organizing and understanding the various types of user interactions and behaviors that can occur within a digital product, enabling designers and developers to create more intuitive and user-friendly interfaces that effectively address the needs and goals of their users.
+ */
+export declare const intentCategories: import("../types.js").IntentCategory[];

package/dist/intentPolicy/categories/index.js

@@ -0,0 +1,22 @@
+import { actionCategory } from './action.js';
+import { assistanceCategory } from './assistance.js';
+import { disclosureCategory } from './disclosure.js';
+import { feedbackCategory } from './feedback.js';
+import { inputCategory } from './input.js';
+import { navigationCategory } from './navigation.js';
+import { statusCategory } from './status.js';
+import { structureCategory } from './structure.js';
+/**
+ * A comprehensive list of intent categories, each representing a distinct classification of user intents that can be utilized within a user interface.
+ * These categories serve as a foundational framework for organizing and understanding the various types of user interactions and behaviors that can occur within a digital product, enabling designers and developers to create more intuitive and user-friendly interfaces that effectively address the needs and goals of their users.
+ */
+export const intentCategories = [
+    actionCategory,
+    feedbackCategory,
+    inputCategory,
+    navigationCategory,
+    disclosureCategory,
+    statusCategory,
+    assistanceCategory,
+    structureCategory,
+];

package/dist/intentPolicy/categories/input.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const inputCategory: IntentCategory;

package/dist/intentPolicy/categories/input.js

@@ -0,0 +1,4 @@
+export const inputCategory = {
+    description: 'Data-entry and selection intents for forms and controls.',
+    id: 'input',
+};

package/dist/intentPolicy/categories/navigation.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const navigationCategory: IntentCategory;

package/dist/intentPolicy/categories/navigation.js

@@ -0,0 +1,4 @@
+export const navigationCategory = {
+    description: 'Information architecture and movement between sections or datasets.',
+    id: 'navigation',
+};

package/dist/intentPolicy/categories/status.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const statusCategory: IntentCategory;

package/dist/intentPolicy/categories/status.js

@@ -0,0 +1,4 @@
+export const statusCategory = {
+    description: 'Transient loading and processing indicators.',
+    id: 'status',
+};

package/dist/intentPolicy/categories/structure.d.ts

@@ -0,0 +1,2 @@
+import type { IntentCategory } from '../types.js';
+export declare const structureCategory: IntentCategory;

package/dist/intentPolicy/categories/structure.js

@@ -0,0 +1,4 @@
+export const structureCategory = {
+    description: 'Structural interaction intent requiring composition, slots, and semantic roles.',
+    id: 'structure',
+};