@birdapi/velinstyle 0.8.0 → 0.9.0

package/cli/docgen/extract-a11y.js

@@ -0,0 +1,89 @@
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { banner, heading, table } from './markdown.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..', '..');
+
+/** @type {{ id: string, level: string, name: string, owner: string, status: string, testId: string }[]} */
+export const WCAG_AAA_CRITERIA = [
+  { id: '1.3.1', level: 'A', name: 'Info and Relationships', owner: 'Author + CSS', status: 'partial', testId: 'scan-a11y' },
+  { id: '1.4.3', level: 'AA', name: 'Contrast (Minimum)', owner: 'Tokens', status: 'pass', testId: 'test:contrast' },
+  { id: '1.4.6', level: 'AAA', name: 'Contrast (Enhanced)', owner: 'Tokens', status: 'pass', testId: 'test:contrast' },
+  { id: '1.4.11', level: 'AA', name: 'Non-text Contrast', owner: 'Tokens + WC', status: 'partial', testId: 'test:a11y' },
+  { id: '2.1.1', level: 'A', name: 'Keyboard', owner: 'Web Components', status: 'partial', testId: 'test:a11y' },
+  { id: '2.3.3', level: 'AAA', name: 'Animation from Interactions', owner: 'CSS + Motion', status: 'pass', testId: 'reduced-motion' },
+  { id: '2.4.1', level: 'A', name: 'Bypass Blocks', owner: 'CSS skip-link', status: 'pass', testId: 'scan-a11y' },
+  { id: '2.4.7', level: 'AA', name: 'Focus Visible', owner: 'CSS focus', status: 'pass', testId: 'test:a11y' },
+  { id: '2.4.11', level: 'AA', name: 'Focus Not Obscured (Minimum)', owner: 'CSS', status: 'pass', testId: 'focus-not-obscured' },
+  { id: '2.4.13', level: 'AAA', name: 'Focus Appearance', owner: 'CSS', status: 'pass', testId: 'focus-appearance' },
+  { id: '2.5.7', level: 'AA', name: 'Dragging Movements', owner: 'CSS + Sample', status: 'pass', testId: 'wcag22-dragging' },
+  { id: '2.5.8', level: 'AA', name: 'Target Size', owner: 'CSS + WC', status: 'pass', testId: 'target-size' },
+  { id: '3.2.6', level: 'A', name: 'Consistent Help', owner: 'CSS', status: 'pass', testId: 'consistent-help' },
+  { id: '3.3.2', level: 'A', name: 'Labels or Instructions', owner: 'Forms + WC', status: 'partial', testId: 'scan-a11y' },
+  { id: '3.3.7', level: 'A', name: 'Redundant Entry', owner: 'velin-persist + Author', status: 'partial', testId: 'velin-persist' },
+  { id: '3.3.8', level: 'AA', name: 'Accessible Authentication', owner: 'CSS + Sample', status: 'pass', testId: 'wcag22-auth' },
+  { id: '4.1.2', level: 'A', name: 'Name, Role, Value', owner: 'Web Components', status: 'partial', testId: 'contracts' },
+  { id: '4.1.3', level: 'AA', name: 'Status Messages', owner: 'Announcer + WC', status: 'pass', testId: 'live-regions' },
+];
+
+export function loadComponentContracts(pkgRoot = PKG_ROOT) {
+  const path = join(pkgRoot, 'core', 'a11y', 'component-contracts.json');
+  if (!existsSync(path)) return { wcagLevel: 'AAA', components: {} };
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+export function renderWcagAaaMatrix(contracts) {
+  let md = banner('core/a11y + src/a11y');
+  md += heading(1, 'WCAG 2.2 AAA framework matrix');
+  md += '\n> **Using VelinStyle does not certify your application.** This matrix tracks what the **framework** provides by default.\n\n';
+  md += `Framework target: **WCAG 2.2 Level ${contracts.wcagLevel || 'AAA'}** (token defaults + component contracts).\n\n`;
+
+  md += heading(2, 'Success criteria');
+  md += table(
+    ['Criterion', 'Level', 'Name', 'Owner', 'Status', 'Test'],
+    WCAG_AAA_CRITERIA.map((c) => [
+      c.id,
+      c.level,
+      c.name,
+      c.owner,
+      c.status,
+      `\`${c.testId}\``,
+    ]),
+  );
+
+  const comps = contracts.components || {};
+  const rows = Object.entries(comps).sort(([a], [b]) => a.localeCompare(b));
+  md += heading(2, 'Web component contracts');
+  md += table(
+    ['Element', 'Status', 'Keyboard', 'Live region', 'Required attrs'],
+    rows.map(([tag, c]) => [
+      `\`<${tag}>\``,
+      c.status || '—',
+      c.keyboard || '—',
+      c.liveRegion || '—',
+      (c.requiredAttributes || []).map((a) => `\`${a}\``).join(', ') || '—',
+    ]),
+  );
+
+  md += '\nRun `npm run test:a11y:coverage` for coverage score.\n';
+  return md;
+}
+
+export function renderComponentA11ySection(tag, contracts) {
+  const c = contracts.components?.[tag];
+  if (!c) return '';
+  let md = heading(2, 'Accessibility');
+  md += `WCAG contract status: **${c.status}** (framework target: ${contracts.wcagLevel}).\n\n`;
+  if (c.roles?.length) md += `- **Roles:** ${c.roles.map((r) => `\`${r}\``).join(', ')}\n`;
+  if (c.keyboard) md += `- **Keyboard:** ${c.keyboard}\n`;
+  if (c.liveRegion) md += `- **Live region:** \`${c.liveRegion}\`\n`;
+  if (c.reducedMotion) md += `- **Reduced motion:** honored\n`;
+  if (c.requiredAttributes?.length) {
+    md += `- **Required attributes:** ${c.requiredAttributes.map((a) => `\`${a}\``).join(', ')}\n`;
+  }
+  if (c.notes) md += `- **Notes:** ${c.notes}\n`;
+  md += '\n';
+  return md;
+}

package/cli/docgen/extract-attributes.js

@@ -0,0 +1,95 @@
+import { join } from 'path';
+import { listRegisteredAttributes } from '../../core/attributes/registry.js';
+import { banner, heading } from './markdown.js';
+
+const ATTRIBUTE_DOCS = {
+  'velin-modal': 'Opens a modal dialog (bridges to `<velin-modal>`).',
+  'velin-tabs': 'Tab navigation (bridges to `<velin-tabs>`).',
+  'velin-accordion': 'Accordion sections (bridges to `<velin-accordion>`).',
+  'velin-tooltip': 'Tooltip on hover/focus (bridges to `<velin-tooltip>`).',
+  'velin-copy': 'Copy text to clipboard (bridges to `<velin-copy>`).',
+  'velin-counter': 'Animated number counter (bridges to `<velin-counter>`).',
+  'velin-notify': 'Show a toast notification (bridges to `<velin-toast>`).',
+  'velin-theme': 'Theme toggle or set `data-velin-theme`.',
+  'velin-progress': 'Progress bar or ring (`ring` for `<velin-progress-ring>`).',
+  'velin-search': 'Attach VelinSearch to an element.',
+  'velin-reveal': 'Reveal element when scrolled into view.',
+  'velin-fade': 'Fade-in on scroll.',
+  'velin-slide': 'Slide-in on scroll (`up`, `down`, …).',
+  'velin-scale': 'Scale-in on scroll.',
+  'velin-parallax': 'Parallax background (`slow` optional).',
+  'velin-hover': 'Hover lift/glow animation.',
+  'velin-stagger': 'Stagger child animations (delay in ms).',
+  'velin-scroll': 'Smooth scroll to anchor (`href="#id"`).',
+  'velin-anchor': 'Scroll-margin for anchor targets.',
+  'velin-lazy': 'Lazy-load images with optional skeleton.',
+  'velin-skeleton': 'Skeleton placeholder (`text`, `avatar`, `image`, …).',
+  'velin-loading': 'Loading spinner state.',
+  'velin-grid': 'Auto grid layout (column count).',
+  'velin-code': 'Code block with copy button and VelinHighlight syntax colors (use `language` or `velin-code="js"`).',
+  'velin-quote': 'Styled blockquote.',
+  'velin-highlight': 'Inline text mark (not syntax highlighting — use `velin-code` or `velinSyntax`).',
+};
+
+const A11Y_NOTES = {
+  'velin-reveal': 'Honors `prefers-reduced-motion`: content shown immediately without animation.',
+  'velin-fade': 'Honors `prefers-reduced-motion`.',
+  'velin-slide': 'Honors `prefers-reduced-motion`.',
+  'velin-scale': 'Honors `prefers-reduced-motion`.',
+  'velin-parallax': 'Disabled under `prefers-reduced-motion` (CSS + motion runtime).',
+  'velin-hover': 'Motion reduced globally when user prefers reduced motion.',
+  'velin-stagger': 'Stagger delays collapse under reduced motion.',
+  'velin-scroll': 'Uses `scroll-behavior: auto` when reduced motion is preferred.',
+  'velin-skeleton': 'Sets `aria-hidden` only on empty placeholders — do not use on containers with real text.',
+  'velin-loading': 'Sets `aria-busy`, `role="status"`, default `aria-label="Loading"`.',
+  'velin-notify': 'Dispatches toast event; pair with `<velin-announcer>` or `initA11y()`.',
+  'velin-lazy': 'Adds `loading="lazy"` on `<img>` only.',
+};
+
+export function extractAttributes() {
+  return listRegisteredAttributes().map((name) => ({
+    name,
+    description: ATTRIBUTE_DOCS[name] || 'Velin HTML attribute extension.',
+  }));
+}
+
+export function renderAttribute(attr) {
+  let md = banner('velinstyle docs generate');
+  md += heading(1, attr.name);
+  md += `\n${attr.description}\n\n`;
+  md += '## Example\n\n```html\n';
+  if (attr.name === 'velin-code') {
+    md += '<pre velin-code="js" language="js"><code>const x = 42;</code></pre>\n';
+  } else if (attr.name === 'velin-scroll') {
+    md += '<a href="#section" velin-scroll>Jump to section</a>\n';
+  } else {
+    md += `<div ${attr.name}${attr.name === 'velin-slide' ? '="up"' : ''}>…</div>\n`;
+  }
+  md += '```\n';
+  if (A11Y_NOTES[attr.name]) {
+    md += '\n## Accessibility\n\n';
+    md += `${A11Y_NOTES[attr.name]}\n`;
+  }
+  return md;
+}
+
+export function renderAttributesIndex(attrs) {
+  let md = banner('velinstyle docs generate');
+  md += heading(1, 'Velin HTML attributes');
+  md += '\nDeclarative extensions interpreted by `bootAttributes()` / `bootFromDOM({ attributes: true })`.\n\n';
+  md += '| Attribute | Description |\n| --- | --- |\n';
+  for (const a of attrs) {
+    md += `| [\`${a.name}\`](./${a.name}.md) | ${a.description} |\n`;
+  }
+  return md;
+}
+
+export function writeAttributesDocs(outDir) {
+  const attrs = extractAttributes();
+  const written = [];
+  for (const a of attrs) {
+    written.push({ path: join(outDir, 'attributes', `${a.name}.md`), content: renderAttribute(a) });
+  }
+  written.push({ path: join(outDir, 'attributes', 'README.md'), content: renderAttributesIndex(attrs) });
+  return written;
+}

package/cli/docgen/extract-cli.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { banner, heading, table } from './markdown.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Commands registered in cli/index.js switch */
+export const REGISTERED_COMMANDS = [
+  'init', 'build', 'themes', 'add', 'icons', 'blueprint', 'tokens',
+  'scan', 'prefix', 'scaffold', 'layout', 'perf', 'docs', 'meta',
+];
+
+export function loadCliManifest() {
+  const path = join(__dirname, '..', 'cli-manifest.json');
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+  const names = manifest.commands.map((c) => c.name);
+  for (const cmd of REGISTERED_COMMANDS) {
+    if (!names.includes(cmd)) {
+      errors.push(`Manifest missing command: ${cmd}`);
+    }
+  }
+  for (const name of names) {
+    if (!REGISTERED_COMMANDS.includes(name)) {
+      errors.push(`Manifest has unknown command (not in router): ${name}`);
+    }
+  }
+  return errors;
+}
+
+export function renderCliDocs(manifest) {
+  let md = banner('cli/cli-manifest.json');
+  md += heading(1, 'CLI commands');
+  md += `\nVelinStyle CLI v${manifest.version}. Run \`velinstyle --help\` for full usage.\n\n`;
+  md += table(
+    ['Command', 'Summary', 'Subcommands', 'Flags', 'Example'],
+    manifest.commands.map((c) => [
+      `\`${c.name}\``,
+      c.summary,
+      (c.subcommands || []).join(', ') || '—',
+      (c.flags || []).join(', ') || '—',
+      `\`${c.example}\``,
+    ]),
+  );
+  return md;
+}

package/cli/docgen/extract-components.js

@@ -0,0 +1,175 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { banner, heading, table, bulletList, sortByKey } from './markdown.js';
+import { loadComponentContracts, renderComponentA11ySection } from './extract-a11y.js';
+
+function tagFromFile(file) {
+  return basename(file, '.js');
+}
+
+function parseBlockComment(source) {
+  const m = source.match(/^\/\*\*?([\s\S]*?)\*\//);
+  if (!m) return null;
+  return m[1]
+    .split('\n')
+    .map((l) => l.replace(/^\s*\* ?/, '').trimEnd())
+    .join('\n')
+    .trim();
+}
+
+function parseObservedAttributes(source) {
+  const m = source.match(/static\s+get\s+observedAttributes\s*\(\s*\)\s*\{\s*return\s*\[([^\]]*)\]/);
+  if (!m) return [];
+  return [...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]);
+}
+
+function parseEvents(source) {
+  const events = new Set();
+  const re = /CustomEvent\s*\(\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) events.add(m[1]);
+  return [...events].sort();
+}
+
+function parseParts(source) {
+  const parts = new Set();
+  const re = /part\s*=\s*["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(source)) !== null) parts.add(m[1]);
+  return [...parts].sort();
+}
+
+function parseSlots(source) {
+  const slots = [];
+  const re = /<slot\b([^>]*)>/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const attrs = m[1];
+    const nameM = attrs.match(/name\s*=\s*["']([^"']+)["']/);
+    slots.push(nameM ? nameM[1] : '(default)');
+  }
+  return [...new Set(slots)].sort();
+}
+
+function parsePublicApi(source) {
+  const methods = new Set();
+  const getters = new Set();
+
+  const classM = source.match(/class\s+\w+\s+extends\s+HTMLElement\s*\{([\s\S]*)\n\}/);
+  if (!classM) return { methods: [], getters: [] };
+  const body = classM[1];
+
+  const methodRe = /^\s{2}([a-zA-Z][\w]*)\s*\([^)]*\)\s*\{/gm;
+  let m;
+  while ((m = methodRe.exec(body)) !== null) {
+    const name = m[1];
+    if (name.startsWith('_') || name === 'constructor') continue;
+    if (['connectedCallback', 'disconnectedCallback', 'attributeChangedCallback'].includes(name)) continue;
+    methods.add(name);
+  }
+
+  const getRe = /^\s{2}get\s+([a-zA-Z][\w]*)\s*\(/gm;
+  while ((m = getRe.exec(body)) !== null) getters.add(m[1]);
+
+  const setRe = /^\s{2}set\s+([a-zA-Z][\w]*)\s*\(/gm;
+  while ((m = setRe.exec(body)) !== null) getters.add(`${m[1]} (setter)`);
+
+  return {
+    methods: [...methods].sort(),
+    getters: [...getters].sort(),
+  };
+}
+
+export function extractComponentFile(filePath) {
+  const source = readFileSync(filePath, 'utf-8');
+  const tag = tagFromFile(filePath);
+  const { methods, getters } = parsePublicApi(source);
+  return {
+    tag,
+    file: `components/${basename(filePath)}`,
+    description: parseBlockComment(source),
+    observedAttributes: parseObservedAttributes(source),
+    events: parseEvents(source),
+    parts: parseParts(source),
+    slots: parseSlots(source),
+    methods,
+    getters,
+  };
+}
+
+export function extractComponents(componentsDir) {
+  if (!existsSync(componentsDir)) return [];
+  const seen = new Set();
+  const items = [];
+  for (const name of readdirSync(componentsDir)) {
+    if (!name.startsWith('velin-') || !name.endsWith('.js')) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push(extractComponentFile(join(componentsDir, name)));
+  }
+  return sortByKey(items, 'tag');
+}
+
+export function renderComponent(meta, contracts) {
+  let md = banner(meta.file);
+  md += heading(1, `<${meta.tag}>`);
+  md += `\nSource: \`${meta.file}\`\n\n`;
+
+  if (meta.description) {
+    md += heading(2, 'Description');
+    md += `${meta.description}\n\n`;
+  }
+
+  if (contracts) {
+    md += renderComponentA11ySection(meta.tag, contracts);
+  }
+
+  md += heading(2, 'Attributes');
+  if (meta.observedAttributes.length) {
+    md += table(
+      ['Attribute', 'Notes'],
+      meta.observedAttributes.map((a) => [`\`${a}\``, 'Observed — triggers `attributeChangedCallback` when changed']),
+    );
+  } else {
+    md += '_No `observedAttributes` declared._\n\n';
+  }
+
+  md += heading(2, 'Events');
+  md += bulletList(meta.events.map((e) => `\`${e}\` (bubbles)`));
+
+  md += heading(2, 'CSS parts');
+  md += bulletList(meta.parts.map((p) => `\`${p}\``));
+
+  md += heading(2, 'Slots');
+  md += bulletList(meta.slots.map((s) => `\`${s}\``));
+
+  md += heading(2, 'Public API');
+  const apiRows = [
+    ...meta.methods.map((m) => ['Method', `\`${m}()\``]),
+    ...meta.getters.map((g) => ['Property', `\`${g}\``]),
+  ];
+  if (apiRows.length) {
+    md += table(['Kind', 'Name'], apiRows);
+  } else {
+    md += '_No public methods detected._\n';
+  }
+
+  return md;
+}
+
+export function renderComponentsIndex(components) {
+  let md = banner('components/velin-*.js');
+  md += heading(1, 'Web Components');
+  md += '\nCustom elements in `components/`. Import via `@birdapi/velinstyle` or lazy-load with `./runtime`.\n\n';
+  md += table(
+    ['Element', 'Attributes', 'Events', 'Reference'],
+    components.map((c) => [
+      `\`<${c.tag}>\``,
+      String(c.observedAttributes.length),
+      String(c.events.length),
+      `[${c.tag}.md](./${c.tag}.md)`,
+    ]),
+  );
+  return md;
+}

package/cli/docgen/extract-meta.js

@@ -0,0 +1,32 @@
+import { banner, heading, bulletList } from './markdown.js';
+import { VELIN_META_MIME } from '../../core/meta/schema.js';
+
+/**
+ * @param {object} bundle
+ */
+export function renderMetaReadme(bundle) {
+  let md = banner('velinstyle meta');
+  md += heading(1, 'Velin-Meta (agent context)');
+  md += '\n> **Do not edit manually.** Regenerate with `velinstyle meta` or `velinstyle docs generate --scope meta`.\n\n';
+  md += heading(2, 'MIME and files');
+  md += `\n- MIME: \`${VELIN_META_MIME}\`\n`;
+  md += '- Bundle: `dist/velin-agent.json`\n';
+  md += '- Index: `dist/llms.txt`\n\n';
+  md += heading(2, 'CLI');
+  md += '\n```bash\nnpx velinstyle meta\nnpx velinstyle meta --llms --base-url https://velinstyle.info\nnpx velinstyle meta page path/to/page.html\n```\n\n';
+  md += heading(2, 'Page embedding');
+  md += '\n```html\n<script type="' + VELIN_META_MIME + '" id="velin-meta">\n{\n  "version": "' + bundle.framework.version + '",\n  "page": { "intent": "component-doc" },\n  "allowed": { "classesPrefix": ["velin-"] }\n}\n</script>\n```\n\n';
+  md += heading(2, 'Snapshot');
+  md += `\n- Framework: ${bundle.framework.name}@${bundle.framework.version}\n`;
+  md += `- Components: ${bundle.components.count}\n`;
+  md += `- Attributes: ${bundle.attributes.count}\n`;
+  md += `- CLI commands: ${bundle.cli.commands.length}\n`;
+  md += `- Scanner rules: ${bundle.tooling.scannerRuleCount}\n`;
+  if (bundle.searchIndex.entryCount != null) {
+    md += `- Search index entries: ${bundle.searchIndex.entryCount}\n`;
+  }
+  md += '\n' + heading(2, 'Conventions');
+  md += '\n' + bulletList(bundle.conventions);
+  md += '\n';
+  return md;
+}

package/cli/docgen/extract-rules.js

@@ -0,0 +1,76 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { SCANNER_RULES, PERF_RULES } from '../scanner-rules-data.js';
+import { banner, heading, table, sortByKey } from './markdown.js';
+
+const VELIN_SELECTOR_RE = /\.(velin-[\w-]+)/g;
+
+function firstComment(content) {
+  const m = content.match(/\/\*\s*([^*]+?)\s*\*\//);
+  return m ? m[1].trim() : null;
+}
+
+export function extractA11yModules(srcDir) {
+  const a11yDir = join(srcDir, 'a11y');
+  if (!existsSync(a11yDir)) return [];
+  const modules = [];
+  for (const file of readdirSync(a11yDir).filter((f) => f.endsWith('.css')).sort()) {
+    const content = readFileSync(join(a11yDir, file), 'utf-8');
+    const selectors = new Set();
+    let m;
+    const re = new RegExp(VELIN_SELECTOR_RE.source, 'g');
+    while ((m = re.exec(content)) !== null) selectors.add(m[1]);
+    modules.push({
+      name: basename(file, '.css'),
+      file: `src/a11y/${file}`,
+      description: firstComment(content),
+      selectors: [...selectors].sort(),
+    });
+  }
+  return modules;
+}
+
+export function renderScannerRules() {
+  const all = sortByKey([...SCANNER_RULES, ...PERF_RULES], 'id');
+  let md = banner('cli/scanner-rules-data.js');
+  md += heading(1, 'Scanner rules');
+  md += '\nRun `velinstyle scan [path]` for security, a11y, CSS, and PII checks. `velinstyle perf audit` for performance.\n\n';
+  md += '```bash\nvelinstyle scan . --severity warning\nvelinstyle scan . --only pii --fix-dry-run\nvelinstyle perf audit samples/\n```\n\n';
+
+  const categories = [...new Set(all.map((r) => r.category))].sort();
+  for (const cat of categories) {
+    const rules = all.filter((r) => r.category === cat);
+    md += heading(2, cat);
+    md += table(
+      ['Rule ID', 'Severity', 'Message', 'Fix hint'],
+      rules.map((r) => [`\`${r.id}\``, r.severity, r.message, r.fixHint || '—']),
+    );
+  }
+  return md;
+}
+
+export function renderA11yModules(modules) {
+  let md = banner('src/a11y/*.css');
+  md += heading(1, 'Accessibility CSS modules');
+  md += '\nImported in `@layer a11y` from `src/velinstyle.css`.\n\n';
+  md += table(
+    ['Module', 'Selectors', 'Reference'],
+    modules.map((m) => [m.name, String(m.selectors.length), `\`${m.file}\``]),
+  );
+  md += '\n';
+  for (const m of modules) {
+    md += heading(2, m.name);
+    if (m.description) md += `${m.description}\n\n`;
+    md += `Source: \`${m.file}\`\n\n`;
+    if (m.selectors.length) {
+      md += bulletListSelectors(m.selectors);
+    } else {
+      md += '_No `.velin-*` class selectors (may use element/attribute selectors)._\n\n';
+    }
+  }
+  return md;
+}
+
+function bulletListSelectors(items) {
+  return `${items.map((s) => `- \`.${s}\``).join('\n')}\n\n`;
+}

package/cli/docgen/extract-tokens.js

@@ -0,0 +1,79 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { banner, heading, table, sortByKey } from './markdown.js';
+
+const VAR_RE = /(--velin-[\w-]+)\s*:\s*([^;]+);/g;
+
+export function parseTokenCss(content) {
+  const tokens = [];
+  let m;
+  const re = new RegExp(VAR_RE.source, 'g');
+  while ((m = re.exec(content)) !== null) {
+    tokens.push({ name: m[1], value: m[2].trim() });
+  }
+  return tokens;
+}
+
+export function extractTokens(srcDir) {
+  const tokensDir = join(srcDir, 'tokens');
+  if (!existsSync(tokensDir)) return { categories: [], byCategory: {} };
+
+  const files = readdirSync(tokensDir).filter((f) => f.endsWith('.css')).sort();
+  const byCategory = {};
+
+  for (const file of files) {
+    const content = readFileSync(join(tokensDir, file), 'utf-8');
+    const category = basename(file, '.css');
+    const tokens = sortByKey(parseTokenCss(content), 'name');
+    byCategory[category] = { file: `src/tokens/${file}`, tokens };
+  }
+
+  return { categories: Object.keys(byCategory).sort(), byCategory };
+}
+
+export function renderTokenCategory(category, data) {
+  let md = banner(`src/tokens/${category}.css`);
+  md += heading(1, `Tokens: ${category}`);
+  md += `\nSource: \`${data.file}\`\n\n`;
+  if (!data.tokens.length) {
+    md += '_No \`--velin-*\` variables found._\n';
+    return md;
+  }
+  md += table(
+    ['Token', 'Value'],
+    data.tokens.map((t) => [`\`${t.name}\``, `\`${t.value}\``]),
+  );
+  if (category === 'color') {
+    md += '\n## Contrast (WCAG 2.2 AAA)\n\n';
+    md += 'VelinStyle defaults target **7:1** for body text on `--velin-color-surface-bright` and semantic text tokens. ';
+    md += 'CI runs `npm run test:contrast` across `:root`, dark mode, and all 13 theme presets.\n\n';
+    md += 'For **AA (4.5:1)** body text (migration from pre-0.9 palettes), set `data-velin-contrast="aa"` on `<html>` ';
+    md += '(see `src/a11y/high-contrast-aaa.css`). AAA remains the default when the attribute is omitted.\n\n';
+    md += 'See [WCAG 2.2 AAA matrix](../a11y/wcag22-aaa-matrix.md) and [Accessibility guide](../../../docs/a11y.html).\n';
+  }
+  return md;
+}
+
+export function renderTokensIndex(extracted) {
+  let md = banner('src/tokens/*.css');
+  md += heading(1, 'Design tokens');
+  md += '\nCSS custom properties from `src/tokens/`. Use with `var(--velin-*, fallback)`.\n\n';
+  md += 'See also: [`examples/tokens.full.json`](../../examples/tokens.full.json) for JSON `tokens build` input.\n\n';
+  md += table(
+    ['Category', 'Variables', 'Reference'],
+    extracted.categories.map((cat) => {
+      const n = extracted.byCategory[cat].tokens.length;
+      return [cat, String(n), `[${cat}.md](./${cat}.md)`];
+    }),
+  );
+  return md;
+}
+
+export function renderJsonSchema(schemaPath, schemaContent) {
+  let md = banner(schemaPath);
+  md += heading(1, 'Tokens JSON schema');
+  md += `\nSchema file: \`${schemaPath}\`\n\n`;
+  md += 'Supported top-level blocks: `tokens`, `themes`, `fonts`, `motion`, `zIndex`, `displayP3`.\n\n';
+  md += '```json\n' + JSON.stringify(JSON.parse(schemaContent), null, 2) + '\n```\n';
+  return md;
+}

package/cli/docgen/extract-utilities.js

@@ -0,0 +1,75 @@
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { banner, heading, table, sortByKey } from './markdown.js';
+
+const CLASS_RULE_RE = /\.(velin-[\w\\\/:-]+)\s*\{([^}]*)\}/g;
+const NESTED_CLASS_RE = /[\s,>+~](\.velin-[\w\\\/:-]+)\s*\{([^}]*)\}/g;
+
+function truncateCss(body, max = 120) {
+  const one = body.replace(/\s+/g, ' ').trim();
+  if (one.length <= max) return one;
+  return `${one.slice(0, max - 1)}…`;
+}
+
+export function parseUtilityCss(content) {
+  const classes = [];
+  let m;
+  const re = new RegExp(CLASS_RULE_RE.source, 'g');
+  while ((m = re.exec(content)) !== null) {
+    classes.push({ selector: m[1], output: truncateCss(m[2]) });
+  }
+  const nested = new RegExp(NESTED_CLASS_RE.source, 'g');
+  while ((m = nested.exec(content)) !== null) {
+    const sel = m[1].replace(/^\./, '');
+    if (!classes.some((c) => c.selector === sel)) {
+      classes.push({ selector: sel, output: truncateCss(m[2]) });
+    }
+  }
+  return classes;
+}
+
+export function extractUtilities(srcDir) {
+  const utilDir = join(srcDir, 'utilities');
+  if (!existsSync(utilDir)) return { files: [], byFile: {} };
+
+  const files = readdirSync(utilDir).filter((f) => f.endsWith('.css')).sort();
+  const byFile = {};
+
+  for (const file of files) {
+    const content = readFileSync(join(utilDir, file), 'utf-8');
+    const category = basename(file, '.css');
+    const classes = sortByKey(parseUtilityCss(content), 'selector');
+    byFile[category] = { file: `src/utilities/${file}`, classes };
+  }
+
+  return { files: Object.keys(byFile).sort(), byFile };
+}
+
+export function renderUtilityFile(category, data) {
+  let md = banner(data.file);
+  md += heading(1, `Utilities: ${category}`);
+  md += `\nSource: \`${data.file}\`\n\n`;
+  if (!data.classes.length) {
+    md += '_No `.velin-*` utility classes found._\n';
+    return md;
+  }
+  md += table(
+    ['Class', 'CSS output'],
+    data.classes.map((c) => [`\`.${c.selector}\``, `\`${c.output}\``]),
+  );
+  return md;
+}
+
+export function renderUtilitiesIndex(extracted) {
+  let md = banner('src/utilities/*.css');
+  md += heading(1, 'Utility classes');
+  md += '\nClasses in `@layer utilities` from `src/utilities/`.\n\n';
+  md += table(
+    ['Category', 'Classes', 'Reference'],
+    extracted.files.map((cat) => {
+      const n = extracted.byFile[cat].classes.length;
+      return [cat, String(n), `[${cat}.md](./${cat}.md)`];
+    }),
+  );
+  return md;
+}