@birdapi/velinstyle 1.0.0 → 1.2.0

package/core/a11y/component-contracts.json

@@ -1,6 +1,6 @@
 {
   "wcagLevel": "AAA",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "components": {
     "velin-accordion": {
       "status": "pass",
@@ -74,6 +74,32 @@
       "keyboard": "N/A",
       "reducedMotion": true
     },
+    "velin-data-table": {
+      "status": "pass",
+      "roles": ["button"],
+      "keyboard": "Sort buttons; editable cells: Enter/F2 edit, Escape cancel; pagination",
+      "liveRegion": "polite",
+      "reducedMotion": true,
+      "requiredAttributes": [],
+      "notes": "Enhances a light-DOM table. Optional editable attribute or data-editable cells for inline edit (velin-data-table-edit). No virtualization in v1."
+    },
+    "velin-calendar": {
+      "status": "pass",
+      "roles": ["group", "grid", "button"],
+      "keyboard": "Arrows, Home/End, PageUp/Down, Enter/Space",
+      "reducedMotion": true,
+      "requiredAttributes": [],
+      "notes": "Month calendar. value ISO date; velin-change event. Optional min/max."
+    },
+    "velin-file-dropzone": {
+      "status": "pass",
+      "roles": ["group"],
+      "keyboard": "Browse button + native file input",
+      "liveRegion": "polite",
+      "reducedMotion": true,
+      "requiredAttributes": [],
+      "notes": "Client-side dropzone. Events velin-files / velin-error. Does not upload to a server."
+    },
     "velin-dialog": {
       "status": "pass",
       "roles": ["dialog"],
@@ -97,6 +123,14 @@
       "roles": ["button"],
       "requiredAttributes": ["aria-label"]
     },
+    "velin-form-summary": {
+      "status": "pass",
+      "roles": ["alert", "link"],
+      "keyboard": "Summary links move focus to the offending field",
+      "liveRegion": "assertive",
+      "requiredAttributes": [],
+      "notes": "Disables native validation bubbles and renders a focusable role=alert summary. Sets aria-invalid and wires aria-describedby to per-field messages (WCAG 3.3.1, 3.3.3, 4.1.2). Field errors clear as soon as the field becomes valid."
+    },
     "velin-icon": {
       "status": "pass",
       "roles": ["img", "presentation"],

package/core/highlight/languages/go.js

@@ -0,0 +1,28 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /\/\/[^\n]*/y },
+  { type: 'comment', re: /\/\*[\s\S]*?\*\//y },
+  // Raw strings may span lines.
+  { type: 'string', re: /`[^`]*`/y },
+  { type: 'string', re: /"(?:\\.|[^"\\\n])*"/y },
+  { type: 'string', re: /'(?:\\.|[^'\\\n])*'/y },
+  { type: 'number', re: /\b0[xX][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]*)?(?:[eE][+-]?\d+)?i?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:break|case|chan|const|continue|default|defer|else|fallthrough|for|func|go|goto|if|import|interface|map|package|range|return|select|struct|switch|type|var)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:append|bool|byte|cap|clear|close|complex|complex64|complex128|copy|delete|error|float32|float64|imag|int|int8|int16|int32|int64|len|make|max|min|new|nil|panic|print|println|real|recover|rune|string|true|false|iota|uint|uint8|uint16|uint32|uint64|uintptr|any)\b/y,
+  },
+  { type: 'operator', re: /:=|\.\.\.|&&|\|\||<-|\+\+|--|<<=?|>>=?|&\^=?|[-+*/%&|^<>!=]=?|~/y },
+  { type: 'punctuation', re: /[[\]{}(),;:.]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexGo(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/python.js

@@ -0,0 +1,29 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /#[^\n]*/y },
+  // Triple-quoted strings first so the single-quote rules cannot split them.
+  { type: 'string', re: /[rbfu]{0,2}"""[\s\S]*?"""/y },
+  { type: 'string', re: /[rbfu]{0,2}'''[\s\S]*?'''/y },
+  { type: 'string', re: /[rbfu]{0,2}"(?:\\.|[^"\\\n])*"/y },
+  { type: 'string', re: /[rbfu]{0,2}'(?:\\.|[^'\\\n])*'/y },
+  { type: 'number', re: /\b0[xX][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]+)?(?:[eE][+-]?\d+)?j?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:and|as|assert|async|await|break|class|continue|def|del|elif|else|except|finally|for|from|global|if|import|in|is|lambda|match|nonlocal|not|or|pass|raise|return|try|while|with|yield)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:None|True|False|self|cls|abs|all|any|bool|bytes|dict|dir|enumerate|filter|float|format|frozenset|getattr|hasattr|int|isinstance|issubclass|iter|len|list|map|max|min|next|object|open|print|range|repr|reversed|round|set|setattr|sorted|str|sum|super|tuple|type|zip)\b/y,
+  },
+  // Multi-character operators first so `->` is not split into `-` and `>`.
+  { type: 'operator', re: /->|:=|\*\*=?|\/\/=?|<<=?|>>=?|[-+*/%&|^~<>!=]=?/y },
+  { type: 'punctuation', re: /[[\]{}(),:;.@]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexPython(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/rust.js

@@ -0,0 +1,32 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /\/\/\/?[^\n]*/y },
+  { type: 'comment', re: /\/\*[\s\S]*?\*\//y },
+  // Raw strings close on the same number of hashes they opened with.
+  { type: 'string', re: /b?r(#*)"[\s\S]*?"\1/y },
+  { type: 'string', re: /b?"(?:\\.|[^"\\])*"/y },
+  { type: 'string', re: /b?'(?:\\.|[^'\\])'/y },
+  // Attributes such as #[derive(Debug)] read as annotations.
+  { type: 'builtin', re: /#!?\[[^\]]*\]/y },
+  { type: 'number', re: /\b0[xXbo][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]+)?(?:[eE][+-]?\d+)?(?:[iuf](?:8|16|32|64|128|size))?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:as|async|await|break|const|continue|crate|dyn|else|enum|extern|fn|for|if|impl|in|let|loop|match|mod|move|mut|pub|ref|return|self|Self|static|struct|super|trait|type|unsafe|use|where|while)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:bool|char|f32|f64|i8|i16|i32|i64|i128|isize|str|u8|u16|u32|u64|u128|usize|String|Vec|Option|Result|Some|None|Ok|Err|Box|Rc|Arc|true|false)\b/y,
+  },
+  // Lifetimes such as 'a must not be read as an unterminated char literal.
+  { type: 'operator', re: /'[a-z_]\w*\b/y },
+  { type: 'operator', re: /=>|->|::|\.\.=?|&&|\|\||<<=?|>>=?|[-+*/%&|^<>!=]=?|[?@]/y },
+  { type: 'punctuation', re: /[[\]{}(),;:.#]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*!?\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexRust(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/yaml.js

@@ -0,0 +1,23 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /#[^\n]*/y },
+  // Document markers and block scalar indicators.
+  { type: 'punctuation', re: /^(?:---|\.\.\.)$/my },
+  { type: 'string', re: /"(?:\\.|[^"\\])*"/y },
+  { type: 'string', re: /'(?:''|[^'])*'/y },
+  // Keys are the primary structure in YAML, so they get the attr-name colour.
+  { type: 'attr-name', re: /^[ \t]*-?[ \t]*[\w.$-]+(?=[ \t]*:(?:[ \t]|$))/my },
+  { type: 'punctuation', re: /^[ \t]*-(?=[ \t]|$)/my },
+  { type: 'keyword', re: /\b(?:true|false|null|yes|no|on|off|~)\b/yi },
+  { type: 'number', re: /\b-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b/y },
+  // Anchors, aliases, tags and block scalar headers.
+  { type: 'operator', re: /[&*]\w+|![\w/!-]*|[|>][+-]?\d*(?=\s*$)/my },
+  { type: 'punctuation', re: /[:,[\]{}]/y },
+];
+
+/** @type {LexerFn} */
+export default function lexYaml(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/registry.js

@@ -28,6 +28,14 @@ const LAZY_LOADERS = {
   console: () => import('./languages/plain.js'),
   php: () => import('./languages/php.js'),
   blade: () => import('./languages/blade.js'),
+  python: () => import('./languages/python.js'),
+  py: () => import('./languages/python.js'),
+  yaml: () => import('./languages/yaml.js'),
+  yml: () => import('./languages/yaml.js'),
+  go: () => import('./languages/go.js'),
+  golang: () => import('./languages/go.js'),
+  rust: () => import('./languages/rust.js'),
+  rs: () => import('./languages/rust.js'),
 };
 
 /** @param {string} name */
@@ -49,11 +57,14 @@ export function normalizeLanguage(name) {
     md: 'markdown',
     plaintext: 'text',
     'plain-text': 'text',
-    yml: 'text',
-    yaml: 'text',
+    yml: 'yaml',
     toml: 'text',
     ini: 'text',
     php8: 'php',
+    py: 'python',
+    python3: 'python',
+    golang: 'go',
+    rs: 'rust',
   };
   return map[n] || n;
 }

package/core/meta/build.js

@@ -85,7 +85,7 @@ export function buildPageMeta(html, sourcePath = '', pkgRoot = '.') {
       : 'page';
 
   return {
-    version: readPackageMeta(pkgRoot).version || '0.9.0',
+    version: readPackageMeta(pkgRoot).version || '0.0.0',
     mime: VELIN_META_MIME,
     page: {
       intent,
@@ -164,6 +164,35 @@ export async function buildAgentBundle(options) {
     }
   }
 
+  const readJsonSafe = (rel) => {
+    const p = join(pkgRoot, rel);
+    if (!existsSync(p)) return null;
+    try {
+      return JSON.parse(readFileSync(p, 'utf-8'));
+    } catch {
+      return null;
+    }
+  };
+
+  const knowledgeComponents = readJsonSafe('core/meta/knowledge/components.json');
+  const knowledgeTokens = readJsonSafe('core/meta/knowledge/tokens.json');
+  const pageRegistry = readJsonSafe('core/meta/pages/registry.json');
+  const sectionRegistry = readJsonSafe('core/meta/sections/registry.json');
+  const skillsRegistry = readJsonSafe('packages/velinstyle-skills/registry.json');
+  const skillsCatalog = readJsonSafe('packages/velinstyle-skills/catalog.json');
+
+  const constraintDir = join(pkgRoot, 'core', 'meta', 'design-constraints');
+  const designConstraints = [];
+  if (existsSync(constraintDir)) {
+    for (const file of readdirSync(constraintDir).filter((f) => f.endsWith('.json'))) {
+      try {
+        designConstraints.push(JSON.parse(readFileSync(join(constraintDir, file), 'utf-8')));
+      } catch {
+        /* skip bad files */
+      }
+    }
+  }
+
   const bundle = {
     schemaVersion: VELIN_AGENT_SCHEMA_VERSION,
     mime: VELIN_META_MIME,
@@ -174,7 +203,8 @@ export async function buildAgentBundle(options) {
       homepage: pkg.homepage,
       repository: pkg.repository,
       tagline:
-        'VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components.',
+        'VelinStyle is a CSS framework with WCAG 2.2 AAA-oriented defaults, native JavaScript runtime, and Web Components.',
+      pipeline: 'Core Foundation → Design System → Knowledge Graph → Prompt Engine → Review Engine → AI Metadata',
     },
     packageExports: pkg.exports,
     release: {
@@ -185,6 +215,7 @@ export async function buildAgentBundle(options) {
       migration: [
         'Replace velin-tooltip-wc / velin-stepper-wc with velin-tooltip / velin-stepper.',
         'Point AI tools at velin-agent.json or docs/llms.txt for framework context.',
+        'Prefer velinstyle scaffold / plan for page generation (plan → render → review).',
       ],
     },
     components: {
@@ -195,10 +226,73 @@ export async function buildAgentBundle(options) {
       legacyAliases,
       helpers,
     },
+    knowledgeGraph: {
+      components: knowledgeComponents?.components || [],
+      componentCount: knowledgeComponents?.components?.length || 0,
+      tokens: knowledgeTokens,
+      pages: pageRegistry?.pages || [],
+      pageCount: pageRegistry?.pages?.length || 0,
+      sections: sectionRegistry?.sections || [],
+      sectionCount: sectionRegistry?.sections?.length || 0,
+      designConstraints,
+      schemas: [
+        'schemas/component-knowledge.schema.json',
+        'schemas/design-intelligence.schema.json',
+        'schemas/design-constraint.schema.json',
+        'schemas/page-template.schema.json',
+        'schemas/section.schema.json',
+        'schemas/review-report.schema.json',
+        'schemas/token-graph.schema.json',
+        'schemas/design-rule.schema.json',
+        'schemas/skill-record.schema.json',
+        'schemas/skill-registry.schema.json',
+        'schemas/skill-pack.schema.json',
+        'schemas/skill-graph.schema.json',
+        'schemas/skill-bundle.schema.json',
+        'schemas/skill-template.schema.json',
+        'schemas/skill-project.schema.json',
+      ],
+    },
+    skills: {
+      count: skillsCatalog?.totals?.skills || skillsRegistry?.skills?.length || 0,
+      categories: [...new Set((skillsRegistry?.skills || []).map((item) => item.category))].sort(),
+      capabilities: [...new Set((skillsRegistry?.skills || []).flatMap((item) => item.capabilities || []))].sort(),
+      items: (skillsRegistry?.skills || []).map((item) => ({
+        id: item.id,
+        category: item.category,
+        priority: item.priority,
+        status: item.status,
+        confidence: item.confidence,
+        capabilities: item.capabilities || [],
+      })),
+    },
+    skillPacks: skillsRegistry?.packs || [],
+    workflowGraphs: (skillsRegistry?.workflowGraphs || []).map((graph) => ({
+      id: graph.id,
+      name: graph.name,
+      entry: graph.entry,
+      nodeCount: Object.keys(graph.nodes || {}).length,
+      edgeCount: (graph.edges || []).length,
+    })),
+    bundles: skillsRegistry?.bundles || [],
+    templates: skillsRegistry?.templates || [],
+    projectSkills: skillsRegistry?.projects || [],
     attributes: { names: attributes, count: attributes.length },
     cli: { commands: cliCommands },
     tooling: {
-      categories: ['scan', 'prefix', 'scaffold', 'layout', 'perf', 'tokens', 'docs', 'search', 'meta'],
+      categories: [
+        'scan',
+        'prefix',
+        'scaffold',
+        'plan',
+        'review',
+        'layout',
+        'perf',
+        'tokens',
+        'docs',
+        'search',
+        'meta',
+      ],
       scannerRuleCount,
     },
     a11y: {
@@ -216,11 +310,17 @@ export async function buildAgentBundle(options) {
       generated: 'docs/generated/',
       guides: {
         velinMeta: 'docs/guides/velin-meta.html',
+        aiSkills: 'docs/guides/ai-skills.html',
         velinSearch: 'docs/guides/velin-search.html',
         syntaxHighlight: 'docs/guides/syntax-highlight.html',
         promptScaffolding: 'docs/guides/prompt-scaffolding.html',
         apiReference: 'docs/guides/api-reference.html',
       },
+      strategy: {
+        note: 'Maintainer strategy/ADR docs are not published (monorepo interne_docs/strategy).',
+        northStar: 'VELINSTYLE_2030.md',
+        architecture: 'ARCHITECTURE.md',
+      },
       agentFiles: {
         json: 'dist/velin-agent.json',
         llmsTxt: 'dist/llms.txt',
@@ -240,7 +340,7 @@ export async function buildAgentBundle(options) {
 export function buildLlmsTxt(bundle, baseUrl = 'https://velinstyle.info') {
   const tagline =
     bundle.framework.tagline ||
-    'VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components.';
+    'VelinStyle is a CSS framework with WCAG 2.2 AAA-oriented defaults, native JavaScript runtime, and Web Components.';
   const lines = [
     `# VelinStyle ${bundle.framework.version}`,
     '',
@@ -251,19 +351,34 @@ export function buildLlmsTxt(bundle, baseUrl = 'https://velinstyle.info') {
     '## Framework',
     `- npm: ${bundle.framework.name}`,
     `- ${tagline}`,
+    `- Pipeline: ${bundle.framework.pipeline || 'Core → Design → Knowledge → Prompt → Review → AI Metadata'}`,
+    `- Maturity: CSS/Web Components/runtime = stable; plan/review, knowledge graph, page/section registry, agent metadata = beta/foundation (seed, expanding); Studio + Utility Engine generator = planned`,
     `- Components: ${bundle.components.count} canonical Web Components (\`velin-*\`); ${bundle.components.loaderCount ?? bundle.components.count} lazy-loader entries`,
+    `- Knowledge graph: ${bundle.knowledgeGraph?.componentCount ?? 0} component nodes, ${bundle.knowledgeGraph?.pageCount ?? 0} page types, ${bundle.knowledgeGraph?.sectionCount ?? 0} sections, ${bundle.knowledgeGraph?.designConstraints?.length ?? 0} design constraint packs`,
     `- HTML attributes: ${bundle.attributes.count} \`velin-*\` bridges`,
-    `- CLI: velinstyle (scan, scaffold, docs generate, search index, meta)`,
+    `- CLI: velinstyle (scan, scaffold, plan, review, docs generate, search index, meta)`,
+    '',
+    '## Agent briefing',
+    '- Treat plan/review/knowledge graph as beta foundation — usable, not a finished AI design system.',
+    '- Build pages with plan-first flow: analyze prompt → page registry → sections → design constraints → HTML → review.',
+    '- Prefer tokens (`--velin-color-*`, `--velin-space-*`) over raw hex.',
+    '- One H1 per page; form fields need labels + `velin-form-summary` when validating.',
+    '- Hero: max 2 CTAs; FAQ uses disclosure (`velin-accordion` / details).',
+    '- Do not invent non-`velin-*` utility classes.',
+    '- Prefer registry-backed skills/workflows (`velinstyle skills ...`, `velinstyle workflow ...`) before ad-hoc orchestration.',
     '',
     '## Conventions',
     ...bundle.conventions.map((c) => `- ${c}`),
     '',
     '## Key guides',
     `- [Velin-Meta](${baseUrl}/docs/guides/velin-meta.html)`,
+    `- [AI Skills](${baseUrl}/docs/guides/ai-skills.html)`,
     `- [VelinSearch](${baseUrl}/docs/guides/velin-search.html)`,
     `- [Syntax highlighting](${baseUrl}/docs/guides/syntax-highlight.html)`,
     `- [Prompt scaffolding](${baseUrl}/docs/guides/prompt-scaffolding.html)`,
     `- [API reference (generated)](${baseUrl}/docs/guides/api-reference.html)`,
+    `- North star: VELINSTYLE_2030.md`,
+    `- Architecture: ARCHITECTURE.md`,
     '',
     '## Generated reference',
     `- [Components index](${baseUrl}/docs/generated/components/)`,
@@ -273,9 +388,14 @@ export function buildLlmsTxt(bundle, baseUrl = 'https://velinstyle.info') {
     '',
     '## Usage for agents',
     '```',
+    'npx velinstyle plan "Steuerberater Landingpage mit Kontaktformular"',
+    'npx velinstyle scaffold "Steuerberater Landingpage mit Kontaktformular" -o out.html --json',
+    'npx velinstyle review out.html --json',
     'npx velinstyle meta',
     'npx velinstyle docs generate',
-    'npx velinstyle search index',
+    'npx velinstyle skills list --capability review',
+    'npx velinstyle skills install frontend',
+    'npx velinstyle workflow landingpage --json',
     '```',
     '',
   ];

package/core/meta/design-constraints/contact.json

@@ -0,0 +1,9 @@
+{
+  "id": "contact",
+  "target": "section:contact",
+  "rules": [
+    { "id": "contact-labels", "scope": "section", "section": "contact", "rule": "Visible labels on all fields", "severity": "error" },
+    { "id": "contact-summary", "scope": "section", "section": "contact", "rule": "Include velin-form-summary for errors", "severity": "error" },
+    { "id": "contact-submit", "scope": "section", "section": "contact", "rule": "Single primary submit button", "severity": "warning" }
+  ]
+}

package/core/meta/design-constraints/faq.json

@@ -0,0 +1,9 @@
+{
+  "id": "faq",
+  "target": "section:faq",
+  "rules": [
+    { "id": "faq-questions", "scope": "section", "section": "faq", "rule": "Entries must be clear interrogatives", "severity": "error" },
+    { "id": "faq-pattern", "scope": "section", "section": "faq", "rule": "Use accordion/disclosure, not long marketing paragraphs", "severity": "error" },
+    { "id": "faq-count", "scope": "section", "section": "faq", "rule": "Prefer 5–8 high-intent FAQs", "severity": "info" }
+  ]
+}

package/core/meta/design-constraints/hero.json

@@ -0,0 +1,13 @@
+{
+  "id": "hero",
+  "target": "section:hero",
+  "rules": [
+    { "id": "hero-headline-lines", "scope": "section", "section": "hero", "rule": "Headline max 2 lines on desktop", "severity": "error" },
+    { "id": "hero-cta-max", "scope": "section", "section": "hero", "rule": "Maximum 2 CTAs", "severity": "error" },
+    { "id": "hero-image-side", "scope": "section", "section": "hero", "rule": "Image left OR right, not competing dual heroes", "severity": "warning" },
+    { "id": "hero-padding", "scope": "section", "section": "hero", "rule": "Section padding by breakpoint", "breakpoints": { "mobile": "var(--velin-space-8)", "tablet": "var(--velin-space-10)", "desktop": "var(--velin-space-12)" }, "severity": "warning" },
+    { "id": "hero-contrast", "scope": "section", "section": "hero", "rule": "Text/surface pairs must meet contrast contract", "severity": "error" },
+    { "id": "hero-motion", "scope": "section", "section": "hero", "rule": "Animation only when motion-safe", "severity": "warning" },
+    { "id": "hero-container", "scope": "section", "section": "hero", "rule": "Content inside documented container width", "severity": "warning" }
+  ]
+}