@birdapi/velinstyle 1.0.0 → 1.2.0

package/packages/velinstyle-skills/scripts/generate-assets.mjs

@@ -0,0 +1,163 @@
+import { mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, '..');
+const registry = JSON.parse(readFileSync(join(root, 'registry.json'), 'utf-8'));
+
+const sectionTemplate = (skill) => `---
+name: ${skill.id}
+description: ${skill.description}
+---
+
+# ${skill.name}
+
+## Goal
+Deliver ${skill.name.toLowerCase()} outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: ${skill.capabilities.join(', ')}.
+
+## Prerequisites
+- Framework compatibility: ${skill.compatibility.framework.min} to ${skill.compatibility.framework.max}
+- CLI: ${skill.requiresCli.join(', ') || 'none'}
+- Dependencies: ${(skill.dependsOn || []).join(', ') || 'none'}
+
+## Workflow
+1. Validate inputs: ${skill.inputs.join(', ')}.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: ${skill.outputs.join(', ')}.
+
+## Rules
+- Respect status: ${skill.status}.
+- Respect priority: ${skill.priority}.
+- Respect confidence: ${skill.confidence}.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run ${skill.id} for this page."
+- CLI bridge example: \`velinstyle ${skill.requiresCli[0] || 'review'}\`
+
+## Anti-Patterns
+- Skipping dependency skills listed in \`dependsOn\`.
+- Running deprecated/legacy skills by default.
+- Ignoring \`onlyIf\` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: ${skill.outputs.join(', ')}.
+`;
+
+mkdirSync(join(root, 'skills'), { recursive: true });
+
+for (const skill of registry.skills || []) {
+  const targetPath = join(root, skill.prosePath);
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, sectionTemplate(skill), 'utf-8');
+}
+
+mkdirSync(join(root, 'packs'), { recursive: true });
+for (const pack of registry.packs || []) {
+  const text = `id: ${pack.id}
+name: ${pack.name}
+version: ${pack.version}
+priority: ${pack.priority}
+skills:
+${(pack.skills || []).map((s) => `  - ${s}`).join('\n')}
+`;
+  writeFileSync(join(root, 'packs', `${pack.id}.pack.yaml`), text, 'utf-8');
+}
+
+mkdirSync(join(root, 'graphs'), { recursive: true });
+for (const graph of registry.workflowGraphs || []) {
+  const nodes = Object.entries(graph.nodes || {})
+    .map(([nodeId, node]) => `  ${nodeId}: { skill: ${node.skill} }`)
+    .join('\n');
+  const edges = (graph.edges || [])
+    .map((edge) => `  - { from: ${edge.from}, to: ${edge.to}${edge.when ? `, when: ${edge.when}` : ''} }`)
+    .join('\n');
+  const text = `id: ${graph.id}
+name: ${graph.name}
+entry: ${graph.entry}
+nodes:
+${nodes}
+edges:
+${edges}
+`;
+  writeFileSync(join(root, 'graphs', `${graph.id}.graph.yaml`), text, 'utf-8');
+}
+
+mkdirSync(join(root, 'bundles'), { recursive: true });
+for (const bundle of registry.bundles || []) {
+  const text = `id: ${bundle.id}
+origin: ${bundle.origin}
+packs:
+${(bundle.packs || []).map((v) => `  - ${v}`).join('\n')}
+graphs:
+${(bundle.graphs || []).map((v) => `  - ${v}`).join('\n')}
+templates:
+${(bundle.templates || []).map((v) => `  - ${v}`).join('\n')}
+docs:
+${(bundle.docs || []).map((v) => `  - ${v}`).join('\n')}
+`;
+  writeFileSync(join(root, 'bundles', `${bundle.id}.bundle.yaml`), text, 'utf-8');
+}
+
+mkdirSync(join(root, 'templates'), { recursive: true });
+for (const template of registry.templates || []) {
+  const text = `id: ${template.id}
+workflowGraph: ${template.workflowGraph}
+packs:
+${(template.packs || []).map((v) => `  - ${v}`).join('\n')}
+theme: ${template.theme}
+demo: ${template.demo}
+docs:
+${(template.docs || []).map((v) => `  - ${v}`).join('\n')}
+starterFiles:
+${(template.starterFiles || []).map((v) => `  - ${v}`).join('\n')}
+`;
+  writeFileSync(join(root, 'templates', `${template.id}.template.yaml`), text, 'utf-8');
+}
+
+mkdirSync(join(root, 'projects'), { recursive: true });
+for (const project of registry.projects || []) {
+  const text = `id: ${project.id}
+name: ${project.name}
+priority: ${project.priority}
+workflowGraph: ${project.workflowGraph}
+packs:
+${(project.packs || []).map((v) => `  - ${v}`).join('\n')}
+skills:
+${(project.skills || []).map((v) => `  - ${v}`).join('\n')}
+optimizedFor:
+${(project.optimizedFor || []).map((v) => `  - ${v}`).join('\n')}
+`;
+  writeFileSync(join(root, 'projects', `${project.id}.project.yaml`), text, 'utf-8');
+}
+
+const readme = `# VelinStyle Skills Registry
+
+Registry-first skill assets for AI Runtime + Skill Engine.
+
+- Source of truth: \`registry.json\`
+- Derived: \`catalog.json\`, \`skills/**/SKILL.md\`, \`packs/*.yaml\`, \`graphs/*.yaml\`, \`bundles/*.yaml\`, \`templates/*.yaml\`, \`projects/*.yaml\`
+`;
+
+writeFileSync(join(root, 'README.md'), readme, 'utf-8');

package/packages/velinstyle-skills/skills/velin-a11y-focus-keyboard/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-a11y-focus-keyboard
+description: Validates keyboard navigation and visible focus behavior.
+---
+
+# Focus Keyboard
+
+## Goal
+Deliver focus keyboard outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: accessibility, test.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: review
+- Dependencies: velin-a11y-page-checklist
+
+## Workflow
+1. Validate inputs: html, screenshot.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: report, checklist.
+
+## Rules
+- Respect status: beta.
+- Respect priority: recommended.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-a11y-focus-keyboard for this page."
+- CLI bridge example: `velinstyle review`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: report, checklist.

package/packages/velinstyle-skills/skills/velin-a11y-page-checklist/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-a11y-page-checklist
+description: Runs page-level accessibility checklist before release.
+---
+
+# A11y Page Checklist
+
+## Goal
+Deliver a11y page checklist outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: accessibility, review.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: review
+- Dependencies: none
+
+## Workflow
+1. Validate inputs: html, docs.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: checklist, report.
+
+## Rules
+- Respect status: stable.
+- Respect priority: core.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-a11y-page-checklist for this page."
+- CLI bridge example: `velinstyle review`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: checklist, report.

package/packages/velinstyle-skills/skills/velin-a11y-scan-fix/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-a11y-scan-fix
+description: Uses scanner output to fix high-confidence accessibility issues.
+---
+
+# A11y Scan Fix
+
+## Goal
+Deliver a11y scan fix outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: accessibility, review.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: scan
+- Dependencies: velin-a11y-page-checklist
+
+## Workflow
+1. Validate inputs: html.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: report, diff.
+
+## Rules
+- Respect status: stable.
+- Respect priority: core.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-a11y-scan-fix for this page."
+- CLI bridge example: `velinstyle scan`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: report, diff.

package/packages/velinstyle-skills/skills/velin-ai-agent-briefing/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-ai-agent-briefing
+description: Prepares agent context and guardrails from velin metadata.
+---
+
+# AI Agent Briefing
+
+## Goal
+Deliver ai agent briefing outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: ai-orchestration, documentation.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: meta
+- Dependencies: none
+
+## Workflow
+1. Validate inputs: docs, meta-json.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: markdown, checklist.
+
+## Rules
+- Respect status: beta.
+- Respect priority: core.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-ai-agent-briefing for this page."
+- CLI bridge example: `velinstyle meta`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: markdown, checklist.

package/packages/velinstyle-skills/skills/velin-ai-plan-scaffold-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-ai-plan-scaffold-review
+description: Runs the canonical AI workflow from prompt to reviewed HTML.
+---
+
+# AI Plan Scaffold Review
+
+## Goal
+Deliver ai plan scaffold review outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: ai-orchestration, build, review.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: plan, scaffold, review
+- Dependencies: velin-dev-plan-first, velin-dev-page-scaffold, velin-review-page-gate
+
+## Workflow
+1. Validate inputs: prompt.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: html, review-json.
+
+## Rules
+- Respect status: beta.
+- Respect priority: core.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-ai-plan-scaffold-review for this page."
+- CLI bridge example: `velinstyle plan`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: html, review-json.

package/packages/velinstyle-skills/skills/velin-ai-skill-authoring/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-ai-skill-authoring
+description: Authors new skills with registry-first metadata quality gates.
+---
+
+# AI Skill Authoring
+
+## Goal
+Deliver ai skill authoring outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: ai-orchestration, documentation.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: docs, meta
+- Dependencies: velin-ai-agent-briefing
+
+## Workflow
+1. Validate inputs: markdown, docs, meta-json.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: markdown, registry-json.
+
+## Rules
+- Respect status: beta.
+- Respect priority: advanced.
+- Respect confidence: medium.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-ai-skill-authoring for this page."
+- CLI bridge example: `velinstyle docs`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: markdown, registry-json.

package/packages/velinstyle-skills/skills/velin-components-accessibility-map/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-components-accessibility-map
+description: Maps every chosen component to a11y expectations and test hooks.
+---
+
+# Component Accessibility Map
+
+## Goal
+Deliver component accessibility map outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: accessibility, documentation.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: docs
+- Dependencies: velin-components-api-contract
+
+## Workflow
+1. Validate inputs: docs, html.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: markdown, report.
+
+## Rules
+- Respect status: beta.
+- Respect priority: advanced.
+- Respect confidence: medium.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-components-accessibility-map for this page."
+- CLI bridge example: `velinstyle docs`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: markdown, report.

package/packages/velinstyle-skills/skills/velin-components-api-contract/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-components-api-contract
+description: Validates component contracts and event/API usage.
+---
+
+# API Contract
+
+## Goal
+Deliver api contract outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: documentation, review.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: review
+- Dependencies: velin-components-select-compose
+
+## Workflow
+1. Validate inputs: html, docs.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: markdown, report.
+
+## Rules
+- Respect status: beta.
+- Respect priority: recommended.
+- Respect confidence: high.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-components-api-contract for this page."
+- CLI bridge example: `velinstyle review`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: markdown, report.

package/packages/velinstyle-skills/skills/velin-components-recipe/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: velin-components-recipe
+description: Builds reusable component recipes for recurring UI blocks.
+---
+
+# Component Recipe
+
+## Goal
+Deliver component recipe outcomes with VelinStyle constraints.
+
+## Description
+Use this skill when capability targets include: build, documentation.
+
+## Prerequisites
+- Framework compatibility: 1.2.0 to 2.x
+- CLI: scaffold
+- Dependencies: velin-components-select-compose
+
+## Workflow
+1. Validate inputs: prompt, html.
+2. Apply rules from DESIGN_RULES and registry metadata.
+3. Execute required CLI steps when available.
+4. Emit outputs: html, markdown.
+
+## Rules
+- Respect status: beta.
+- Respect priority: recommended.
+- Respect confidence: medium.
+- Do not contradict DESIGN_RULES or DESIGN_INTELLIGENCE.
+
+## Best Practices
+- Keep changes scoped to one goal per section.
+- Prefer deterministic CLI output over ad-hoc edits.
+- Validate before release with review/security/perf gates.
+
+## Examples
+- Prompt example: "Run velin-components-recipe for this page."
+- CLI bridge example: `velinstyle scaffold`
+
+## Anti-Patterns
+- Skipping dependency skills listed in `dependsOn`.
+- Running deprecated/legacy skills by default.
+- Ignoring `onlyIf` predicates.
+
+## Checklist
+- [ ] Inputs are present and typed.
+- [ ] Dependencies resolved.
+- [ ] Quality gate passed.
+- [ ] Output matches declared format.
+
+## Quality Rules
+- Must satisfy a11y basics (labels, focus, contrast).
+- Must keep velin-* naming conventions.
+- Must avoid one-off undocumented tokens/classes.
+
+## Output Format
+- Primary outputs: html, markdown.