@synergy-design-system/metadata 3.7.0 → 3.9.0

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

@@ -0,0 +1,40 @@
+# syn-textarea
+
+## Summary
+
+Textareas collect data from the user and allow multiple lines of text.
+
+## Common Use Cases
+
+- Collect detailed user feedback or comments.
+- Enable users to write comprehensive reviews of products or services.
+- Gather extensive information about issues or requests.
+- Capture detailed responses in surveys or questionnaires.
+
+## Usage Guidelines
+
+### Behavior and Interaction
+
+- Provide real-time validation to help users correct errors as they type.
+- Provide a visible scrollbar when text overflows.
+- Adapt the size of the field to the expected length of user input.
+- Avoid including a "clear" button to prevent unwanted loss of user input.
+
+### Content and Guidance
+
+- Inform users whenever minimum or maximum lengths are set; use the field's help text for this.
+- Use placeholder text as an addition to label as it should not include essential information required to complete the field correctly.
+- Use help text to provide hints or examples of expected inputs.
+
+## Accessibility
+
+- Ensure textarea fields are part of a logical tab order and provide a clearly visible focus state when focused.
+- Always provide a descriptive label. Placeholder text may support the label but must not replace it.
+- Ensure textarea fields remain usable across all screen sizes, including touch devices with sufficiently large touch targets.
+- Inform users about input constraints such as minimum or maximum character limits, and expose validation feedback clearly.
+- Use helper and error text that can be announced by assistive technologies (e.g., by linking descriptions and errors to the field).
+- Prefer keeping the field enabled by default and validate on submit or during input instead of blocking input unnecessarily.
+
+## Related Templates
+
+- Forms

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-11T08:29:10.576Z",
+  "builtAt": "2026-05-28T08:21:08.716Z",
   "sources": [
     {
       "entityCount": 4,
@@ -12,7 +12,7 @@
       "status": "success"
     },
     {
-      "entityCount": 56,
+      "entityCount": 57,
       "source": "components",
       "status": "success"
     },
@@ -32,7 +32,7 @@
       "status": "success"
     },
     {
-      "entityCount": 12,
+      "entityCount": 17,
       "source": "tokens",
       "status": "success"
     },

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.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.d.ts

@@ -0,0 +1,6 @@
+import type { IntentCategory } from './types.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 declare const intentCategories: IntentCategory[];

package/dist/intentPolicy/categories.js

@@ -0,0 +1,22 @@
+import { actionCategory } from './domains/action/index.js';
+import { assistanceCategory } from './domains/assistance/index.js';
+import { disclosureCategory } from './domains/disclosure/index.js';
+import { feedbackCategory } from './domains/feedback/index.js';
+import { inputCategory } from './domains/input/index.js';
+import { navigationCategory } from './domains/navigation/index.js';
+import { statusCategory } from './domains/status/index.js';
+import { structureCategory } from './domains/structure/index.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/domains/action/capabilities.d.ts

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

package/dist/intentPolicy/domains/action/capabilities.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/domains/action/category.d.ts

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

package/dist/intentPolicy/domains/action/category.js

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

package/dist/intentPolicy/domains/action/index.d.ts

@@ -0,0 +1,4 @@
+export { actionCapabilities } from './capabilities.js';
+export { actionCategory } from './category.js';
+export { actionIntents } from './intents.js';
+export { actionPatterns } from './patterns/index.js';

package/dist/intentPolicy/domains/action/index.js

@@ -0,0 +1,4 @@
+export { actionCapabilities } from './capabilities.js';
+export { actionCategory } from './category.js';
+export { actionIntents } from './intents.js';
+export { actionPatterns } from './patterns/index.js';

package/dist/intentPolicy/domains/action/intents.d.ts

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

package/dist/intentPolicy/domains/action/intents.js

@@ -0,0 +1,38 @@
+export const actionIntents = [
+    {
+        category: 'action',
+        description: 'Use when the component should present the primary action in a context.',
+        id: 'action.primary',
+        userGoal: 'Highlight the most important next action for the user.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component submits form data.',
+        id: 'action.submit',
+        userGoal: 'Submit user-provided data to a form handler.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component resets form state to defaults.',
+        id: 'action.reset',
+        userGoal: 'Clear or reset user-entered data.',
+    },
+    {
+        category: 'action',
+        description: 'Use when the component should navigate to another location.',
+        id: 'action.navigation',
+        userGoal: 'Move the user to another destination.',
+    },
+    {
+        category: 'action',
+        description: 'Use icon-only buttons for compact actions where space is constrained.',
+        id: 'action.button.icon',
+        userGoal: 'Provide a compact action trigger while preserving quick recognition.',
+    },
+    {
+        category: 'action',
+        description: 'Use grouped actions when related actions should be presented as one unit.',
+        id: 'action.grouped',
+        userGoal: 'Present related actions with clear grouping and consistent alignment.',
+    },
+];

package/dist/intentPolicy/domains/action/patterns/grouped.d.ts

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

package/dist/intentPolicy/domains/action/patterns/grouped.js

@@ -0,0 +1,9 @@
+export const actionGroupedPattern = {
+    description: 'Group related actions into one aligned unit for consistent interaction.',
+    intent: 'action.grouped',
+    notes: ['Prefer grouping actions with related intent and similar importance.'],
+    structure: {
+        component: 'syn-button-group',
+    },
+    target: { id: 'component:syn-button-group', kind: 'component', name: 'syn-button-group' },
+};

package/dist/intentPolicy/domains/action/patterns/icon.d.ts

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

package/dist/intentPolicy/domains/action/patterns/icon.js

@@ -0,0 +1,9 @@
+export const actionIconPattern = {
+    description: 'Compact icon-only action button with accessible label requirements.',
+    intent: 'action.button.icon',
+    notes: ['Provide an accessible label (for example aria-label) because no visible text is shown.'],
+    structure: {
+        component: 'syn-icon-button',
+    },
+    target: { id: 'component:syn-icon-button', kind: 'component', name: 'syn-icon-button' },
+};

package/dist/intentPolicy/domains/action/patterns/index.d.ts

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

package/dist/intentPolicy/domains/action/patterns/index.js

@@ -0,0 +1,14 @@
+import { actionGroupedPattern } from './grouped.js';
+import { actionIconPattern } from './icon.js';
+import { actionNavigationPattern } from './navigation.js';
+import { actionPrimaryPattern } from './primary.js';
+import { actionResetPattern } from './reset.js';
+import { actionSubmitPattern } from './submit.js';
+export const actionPatterns = [
+    actionPrimaryPattern,
+    actionSubmitPattern,
+    actionResetPattern,
+    actionNavigationPattern,
+    actionIconPattern,
+    actionGroupedPattern,
+];

package/dist/intentPolicy/domains/action/patterns/navigation.d.ts

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

package/dist/intentPolicy/domains/action/patterns/navigation.js

@@ -0,0 +1,39 @@
+export const actionNavigationPattern = {
+    description: 'Navigation action uses href and text variant.',
+    intent: 'action.navigation',
+    structure: {
+        component: 'syn-button',
+        config: {
+            contentRules: [
+                {
+                    code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                    kind: 'requiredContent',
+                    message: 'syn-button must contain visible content (text and/or child nodes).',
+                    rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                    suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                },
+            ],
+            propRules: [
+                {
+                    code: 'REQUIRED_PROP_HREF',
+                    kind: 'requiredEquals',
+                    message: 'href property must be set for navigation action intent.',
+                    prop: 'href',
+                    rationale: 'The href property provides the navigation target for semantic link behavior.',
+                    suggestedFix: 'Set href property to the target URL or route.',
+                    value: '#',
+                },
+                {
+                    code: 'REQUIRED_PROP_TEXT_VARIANT',
+                    kind: 'requiredEquals',
+                    message: 'variant property should be set to "text" for navigation action styling.',
+                    prop: 'variant',
+                    rationale: 'Text variant provides unstyled appearance appropriate for link-like navigation.',
+                    suggestedFix: 'Set variant property to "text".',
+                    value: 'text',
+                },
+            ],
+        },
+    },
+    target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+};

package/dist/intentPolicy/domains/action/patterns/primary.d.ts

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

package/dist/intentPolicy/domains/action/patterns/primary.js

@@ -0,0 +1,39 @@
+export const actionPrimaryPattern = {
+    description: 'Primary action button styling for default primary interaction.',
+    intent: 'action.primary',
+    structure: {
+        component: 'syn-button',
+        config: {
+            contentRules: [
+                {
+                    code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                    kind: 'requiredContent',
+                    message: 'syn-button must contain visible content (text and/or child nodes).',
+                    rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                    suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                },
+            ],
+            propRules: [
+                {
+                    code: 'REQUIRED_PROP_BUTTON_TYPE',
+                    kind: 'requiredEquals',
+                    message: 'type property must be set to "button" for primary action intent.',
+                    prop: 'type',
+                    rationale: 'The semantic button type ensures proper HTML behavior and accessibility.',
+                    suggestedFix: 'Set type property to "button".',
+                    value: 'button',
+                },
+                {
+                    code: 'REQUIRED_PROP_FILLED_VARIANT',
+                    kind: 'requiredEquals',
+                    message: 'variant property should be set to "filled" for primary action emphasis.',
+                    prop: 'variant',
+                    rationale: 'Filled variant provides clear visual priority for primary actions.',
+                    suggestedFix: 'Set variant property to "filled".',
+                    value: 'filled',
+                },
+            ],
+        },
+    },
+    target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+};

package/dist/intentPolicy/domains/action/patterns/reset.d.ts

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

package/dist/intentPolicy/domains/action/patterns/reset.js

@@ -0,0 +1,39 @@
+export const actionResetPattern = {
+    description: 'Reset action styling for secondary importance.',
+    intent: 'action.reset',
+    structure: {
+        component: 'syn-button',
+        config: {
+            contentRules: [
+                {
+                    code: 'REQUIRED_CONTENT_BUTTON_LABEL',
+                    kind: 'requiredContent',
+                    message: 'syn-button must contain visible content (text and/or child nodes).',
+                    rationale: 'An empty button is inaccessible and provides no affordance to the user.',
+                    suggestedFix: 'Add a label, text, or child element such as syn-icon inside the button.',
+                },
+            ],
+            propRules: [
+                {
+                    code: 'REQUIRED_PROP_RESET_TYPE',
+                    kind: 'requiredEquals',
+                    message: 'type property must be set to "reset" for reset action intent.',
+                    prop: 'type',
+                    rationale: 'The semantic reset type ensures proper form reset behavior.',
+                    suggestedFix: 'Set type property to "reset".',
+                    value: 'reset',
+                },
+                {
+                    code: 'REQUIRED_PROP_TEXT_VARIANT',
+                    kind: 'requiredEquals',
+                    message: 'variant property should be set to "text" for secondary action styling.',
+                    prop: 'variant',
+                    rationale: 'Text variant provides lower visual priority appropriate for reset actions.',
+                    suggestedFix: 'Set variant property to "text".',
+                    value: 'text',
+                },
+            ],
+        },
+    },
+    target: { id: 'component:syn-button', kind: 'component', name: 'syn-button' },
+};

package/dist/intentPolicy/domains/action/patterns/submit.d.ts

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