@veluai/velu 0.1.0

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+var me=Object.defineProperty;var g=(e,t)=>()=>(e&&(t=e(e=0)),t);var j=(e,t)=>{for(var o in t)me(e,o,{get:t[o],enumerable:!0})};var R={};j(R,{initProject:()=>ye});import y from"node:fs/promises";import w from"node:path";import{fileURLToPath as ge}from"node:url";async function ye(e,t){try{if((await y.readdir(e)).length>0)throw new Error(`Directory "${t}" already exists and is not empty. Choose a different name or remove the folder first.`)}catch(i){if(i.code!=="ENOENT")throw i}await y.mkdir(e,{recursive:!0}),await y.cp(ve,e,{recursive:!0});let o=w.join(e,"velu.json"),n=JSON.parse(await y.readFile(o,"utf-8"));n.name=t,await y.writeFile(o,JSON.stringify(n,null,2)+`
+`,"utf-8");let r=await L(e);console.log(`[velu] created ${t}/`);for(let i of r)console.log(`         ${i}`);console.log(""),console.log("Next steps:"),console.log(`  cd ${t}`),console.log("  velu dev")}async function L(e,t=e,o=[]){let n=await y.readdir(e,{withFileTypes:!0});for(let r of n){let i=w.join(e,r.name);r.isDirectory()?await L(i,t,o):o.push(w.relative(t,i).split(w.sep).join("/"))}return o.sort()}var he,ve,_=g(()=>{he=w.dirname(ge(import.meta.url)),ve=w.resolve(he,"..","templates","starter")});import{visit as we}from"unist-util-visit";import{toString as xe}from"mdast-util-to-string";import be from"github-slugger";import{valueToEstree as Se}from"estree-util-value-to-estree";function E(){return e=>{let t=new be,o=[];we(e,"heading",s=>{let l=xe(s);o.push({depth:s.depth,id:t.slug(l),label:l})});let n={children:[]},r=[{node:n,depth:0}];for(let s of o){for(;r.length>1&&r[r.length-1].depth>=s.depth;)r.pop();let l={id:s.id,label:s.label},a=r[r.length-1].node;a.children||(a.children=[]),a.children.push(l),r.push({node:l,depth:s.depth})}let i=n.children;e.children.unshift({type:"mdxjsEsm",value:"",data:{estree:{type:"Program",sourceType:"module",body:[{type:"ExportNamedDeclaration",specifiers:[],declaration:{type:"VariableDeclaration",kind:"const",declarations:[{type:"VariableDeclarator",id:{type:"Identifier",name:"toc"},init:Se(i)}]}}]}}})}}var C=g(()=>{});import ke from"node:fs/promises";import I from"node:path";function N(e={},t){let o=e.colors?.primary??$e;return{name:e.name??t??"docs",colors:{primary:o,light:e.colors?.light??o,dark:e.colors?.dark??o},favicon:e.favicon??null,font:{family:e.font?.family??Pe},navigation:e.navigation??null}}async function z(e){let t=I.join(e,"velu.json"),o;try{o=await ke.readFile(t,"utf-8")}catch(r){throw r.code==="ENOENT"?new Error(`No velu.json found in ${e}. Run \`velu init <name>\` to scaffold one.`):r}let n;try{n=JSON.parse(o)}catch(r){throw new Error(`velu.json is not valid JSON: ${r.message}`)}return N(n,I.basename(e))}function V(e){let{colors:t,font:o}=e;return[":root:root {",`  --accent-color: ${t.light};`,`  --font-sans: "${o.family}", sans-serif;`,"}",':root:root[data-theme="dark"] {',`  --accent-color: ${t.dark};`,"}"].join(`
+`)}var $e,Pe,B=g(()=>{$e="#dc143c",Pe="Google Sans Flex"});import Ae from"github-slugger";import Te from"iso-639-1";function Ne(e){let t=String(e).toLowerCase();return Te.getNativeName(t)||e}function P(e){return new Ae().slug(String(e??""))}function Fe(e){let t=String(e).replace(/^\/+|\/+$/g,"").split("/").filter(Boolean);return t[t.length-1]==="index"&&t.pop(),"/"+t.join("/")}function G(e){let t={kind:"root",children:b(e??{})};return D(t.children),t}function b(e){let t=Array.isArray(e.anchors)?e.anchors.map(Re):[];if(Array.isArray(e.products))return[...t,...e.products.map(Oe)];if(Array.isArray(e.versions))return[...t,...e.versions.map(Ue)];if(Array.isArray(e.languages))return[...t,...e.languages.map(je)];if(Array.isArray(e.tabs))return[...t,...e.tabs.map(Le)];let o=[...t];return Array.isArray(e.groups)&&o.push(...e.groups.map(M)),Array.isArray(e.pages)&&o.push(...e.pages.map(J)),o}function Oe(e){return{kind:"product",label:e.name??e.product,slug:P(e.product),icon:e.icon,color:e.color,default:!!e.default,children:b(e)}}function Ue(e){return{kind:"version",label:e.version,slug:P(e.version),default:!!e.default,children:b(e)}}function je(e){let t=String(e.language);return{kind:"language",code:t,label:Ne(t),slug:P(t),default:!!e.default,children:b(e)}}function Le(e){return{kind:"tab",label:e.tab,slug:P(e.tab),icon:e.icon,href:e.href,children:b(e)}}function Re(e){return{kind:"anchor",label:e.anchor,icon:e.icon,href:e.href,color:e.color}}function M(e){let t=(e.pages??[]).map(J);return e.root&&t.unshift({kind:"page",pagePath:e.root}),{kind:"group",label:e.group,icon:e.icon,expanded:!!e.expanded,root:e.root,children:t}}function J(e){return typeof e=="string"?{kind:"page",pagePath:e}:M(e)}function D(e){for(let t of Ee){let o=e.filter(n=>n.kind===t);o.length&&!o.some(n=>n.default)&&(o[0].default=!0)}for(let t of e)t.children&&D(t.children)}function q(e){let t=[],o=(n,r,i)=>{if(n.kind==="page"){t.push({pagePath:n.pagePath,url:_e(n.pagePath,r),ctx:{...r},ancestors:i,node:n});return}let s=r;n.kind==="product"?s={...r,product:n.default?null:n.slug}:n.kind==="version"?s={...r,version:n.default?null:n.slug}:n.kind==="language"&&(s={...r,language:n.default?null:n.slug});let l=n.kind==="root"?i:[...i,n];for(let a of n.children??[])o(a,s,l)};return o(e,{product:null,version:null,language:null},[]),t}function _e(e,t){let o=[t.product,t.version,t.language].filter(Boolean),n=Fe(e).split("/").filter(Boolean);return"/"+[...o,...n].join("/")}var Ee,F=g(()=>{Ee=["product","version","language"]});import Ce from"node:fs";import H from"node:path";function W(e,t){let o=[],n=[],r=new Set;for(let i of q(e)){if(r.has(i.url)){o.push(`duplicate URL "${i.url}" (page "${i.pagePath}") \u2014 keeping the first occurrence`);continue}r.add(i.url);let s=i.pagePath.replace(/^\/+|\/+$/g,""),l=H.join(t,...s.split("/"))+".mdx",a=Ce.existsSync(l);a||o.push(`page "${i.pagePath}" \u2192 ${H.relative(t,l)} not found`),n.push({pagePath:i.pagePath,url:i.url,fileAbsPath:l,exists:a})}return{pageEntries:n,warnings:o}}var Y=g(()=>{F()});import Ie from"node:fs";import K from"node:path";function Z(e){return{name:"velu-site",resolveId(t){return t===Q?X:null},load(t){return t!==X?null:ze(e)}}}function ze(e){let t={};try{t=JSON.parse(Ie.readFileSync(K.join(e,"velu.json"),"utf-8"))}catch{}let o=G(t.navigation??{}),{pageEntries:n,warnings:r}=W(o,e);for(let a of r)console.warn(`[velu] nav: ${a}`);let i=[],s=[],l=0;for(let a of n)if(a.exists){let A=JSON.stringify(a.fileAbsPath.split(K.sep).join("/")),p=`__p${l++}`;i.push(`import * as ${p} from ${A};`),s.push(`  ${JSON.stringify(a.url)}: { Component: ${p}.default, frontmatter: ${p}.frontmatter, toc: ${p}.toc },`)}else s.push(`  ${JSON.stringify(a.url)}: { missing: true },`);return["// AUTO-GENERATED by vite-plugin-velu-site. Do not edit.",i.join(`
+`),"","export const pages = {",s.join(`
+`),"};",`export const navigation = ${JSON.stringify(o)};`,""].join(`
+`)}var Q,X,ee=g(()=>{F();Y();Q="virtual:velu-site",X="\0"+Q});var re={};j(re,{startDevServer:()=>at});import Ve from"node:fs/promises";import te from"node:fs";import c from"node:path";import{fileURLToPath as Be}from"node:url";import{createRequire as Ge}from"node:module";import Me from"chokidar";import Je from"express";import De from"@tailwindcss/vite";import qe from"@vitejs/plugin-react";import He from"@mdx-js/rollup";import We from"remark-frontmatter";import Ye from"remark-mdx-frontmatter";import Ke from"remark-gfm";import Xe from"rehype-slug";import{createServer as Qe,searchForWorkspaceRoot as Ze}from"vite";function rt(e){return`<link rel="stylesheet" href="${`https://fonts.googleapis.com/css2?family=${encodeURIComponent(e).replace(/%20/g,"+")}:wght@300;400;500;600;700&display=swap`}" />`}async function ne(e){try{return await z(e)}catch(t){return console.warn(`[velu] ${t.message} Using defaults.`),N({},c.basename(e))}}async function it(e,t){let o=await e.moduleGraph.getModuleByUrl(t,!0),n=new Map,r=new Set;async function i(s){if(!(!s||r.has(s.url))){if(r.add(s.url),s.id&&tt.test(s.id)){let l=s.url.includes("?")?"&":"?",a=await e.transformRequest(`${s.url}${l}direct`);a?.code&&n.set(s.url,a.code)}for(let l of s.importedModules)await i(l)}}return await i(o),[...n.values()].join(`
+`)}async function at(e){console.log(`[velu-cli] dev server for: ${e}`);let t=await ne(e),o=e;try{o=te.realpathSync(e)}catch{}let r=Ge(import.meta.url).resolve("@mdx-js/react"),i=c.resolve(S,"runtime","velu-ui"),s=te.existsSync(i)?i:c.resolve(S,"..","velu-ui","src"),l=[{find:"@mdx-js/react",replacement:r},{find:/^velu-ui$/,replacement:c.join(s,"index.js")},{find:/^velu-ui\//,replacement:s+"/"}],a=Number(process.env.PORT)||5173,A=a+1,p=Je(),d=await Qe({root:S,appType:"custom",plugins:[Z(e),He({remarkPlugins:[We,Ye,Ke,E],rehypePlugins:[Xe],providerImportSource:"@mdx-js/react"}),qe(),De()],optimizeDeps:{esbuildOptions:{loader:{".mdx":"jsx"}}},resolve:{alias:l,dedupe:["react","react-dom","@mdx-js/react"]},server:{middlewareMode:!0,fs:{allow:[Ze(S),e,o]},hmr:{port:A}}});p.use(d.middlewares),p.get(oe,async(v,u,x)=>{if(!t.favicon)return u.status(404).end();let m=c.resolve(e,t.favicon.replace(/^\//,""));u.sendFile(m,f=>{f&&u.status(404).end()})}),p.use("*",async(v,u,x)=>{let m=v.originalUrl;try{let f=await Ve.readFile(st,"utf-8");f=await d.transformIndexHtml(m,f);let k="/src/runtime/server-entry.jsx",{render:$}=await d.ssrLoadModule(k),T=await $(m),U=await it(d,k),le=U?`<style data-velu-ssr>${U}</style>`:"",ce=`<style data-velu-config>
+${V(t)}
+</style>`,ue=ot.has(t.font.family)?"":rt(t.font.family),fe=t.favicon?`<link rel="icon" href="${oe}" />`:"",pe=[le,ce,ue,fe].filter(Boolean).join(`
+`),de=f.replace("<!--app-title-->",nt(t.name)).replace("<!--app-head-->",pe).replace("<!--app-html-->",T);u.status(200).set({"Content-Type":"text/html"}).end(de)}catch(f){d.ssrFixStacktrace(f),x(f)}}),Me.watch(e,{ignoreInitial:!0,ignored:/(^|[\\/])(node_modules|\.git)([\\/]|$)/,awaitWriteFinish:{stabilityThreshold:100,pollInterval:20}}).on("all",async(v,u)=>{console.log(`[velu-cli] content ${v}: ${c.relative(e,u)}`);let x=c.basename(u)==="velu.json",m=u.endsWith(".mdx"),f=x||m&&(v==="add"||v==="unlink");if(x&&(t=await ne(e)),f)d.moduleGraph.invalidateAll();else if(m){let k=u.split(c.sep).join("/"),$=d.moduleGraph.getModulesByFile(k);if($)for(let T of $)d.moduleGraph.invalidateModule(T)}d.ws.send({type:"full-reload"})}),p.listen(a,()=>{console.log(`[velu-cli] listening on http://localhost:${a}`)})}var et,tt,ot,oe,nt,S,st,ie=g(()=>{C();B();ee();et=c.dirname(Be(import.meta.url)),tt=/\.(css|less|sass|scss|styl|stylus|pcss|postcss)(\?|$)/,ot=new Set(["Google Sans Flex","Google Sans Code","Outfit"]),oe="/@velu-favicon",nt=e=>String(e).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");S=c.resolve(et,".."),st=c.resolve(S,"src","template.html")});import se from"node:path";import h from"node:process";var[,,ae,O]=h.argv;async function lt(){switch(ae){case"init":{O||(console.error("Usage: velu init <project-name>"),h.exit(1));let e=O,t=se.resolve(h.cwd(),e),{initProject:o}=await Promise.resolve().then(()=>(_(),R));await o(t,e);break}case"dev":{let e=se.resolve(h.cwd(),O??"."),{startDevServer:t}=await Promise.resolve().then(()=>(ie(),re));await t(e);break}default:console.log("Usage:"),console.log("  velu init <project-name>   scaffold a new docs project"),console.log("  velu dev [dir]             start the dev preview server"),h.exit(ae?1:0)}}lt().catch(e=>{console.error(h.env.VELU_DEBUG?e:`Error: ${e.message}`),h.exit(1)});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@veluai/velu",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": "./dist/cli.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "src/runtime/**",
+    "src/navigation.js",
+    "src/template.html",
+    "runtime/velu-ui/**",
+    "schema/**",
+    "templates/**"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  },
+  "dependencies": {
+    "@icons-pack/react-simple-icons": "^13.0.0",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tailwindcss/vite": "^4.1.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^3.6.0",
+    "estree-util-value-to-estree": "^3.5.0",
+    "express": "^4.21.1",
+    "github-slugger": "^2.0.0",
+    "iso-639-1": "^3.1.5",
+    "lucide-react": "^0.460.0",
+    "mdast-util-to-string": "^4.0.0",
+    "prism-react-renderer": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "tailwindcss": "^4.1.0",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^5.4.11"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "velu-ui": "0.0.0"
+  }
+}

package/runtime/velu-ui/base.css

@@ -0,0 +1,311 @@
+/* Fonts are loaded via <link rel="preconnect"/"stylesheet"> in template.html
+   (faster than an @import inside critical CSS — non-blocking, parallel). */
+:root {
+  --ratio: 1.25;
+  --s-6: calc(var(--s-5) / var(--ratio));
+  --s-5: calc(var(--s-4) / var(--ratio));
+  --s-4: calc(var(--s-3) / var(--ratio));
+  --s-3: calc(var(--s-2) / var(--ratio));
+  --s-2: calc(var(--s-1) / var(--ratio));
+  --s-1: calc(var(--s0) / var(--ratio));
+  --s0: 1rem;
+  --s1: calc(var(--s0) * var(--ratio));
+  --s2: calc(var(--s1) * var(--ratio));
+  --s3: calc(var(--s2) * var(--ratio));
+  --s4: calc(var(--s3) * var(--ratio));
+  --s5: calc(var(--s4) * var(--ratio));
+}
+
+/* Semantic color tokens — verbatim from Figma (1:1 names, no translation).
+   Components reference ONLY these (never raw hex), so theme switching =
+   swapping this block (zero component changes).
+   --page-bg is PROVISIONAL: Figma has no explicit page-background token yet
+   (see note to Aravind) — replace once defined. */
+:root {
+  --page-bg: #ffffff;
+
+  --border-color: #dcdcde;
+  --text-color: #000000;
+  --accent-color: #dc143c;
+  --muted-color: #7a7a7a;
+  --surface-color: #f2f3f4;
+
+  --note-bg-color: #f2f3f4;
+  --note-stroke-color: #6b7280;
+  --warning-bg-color: #fef3e2;
+  --warning-stroke-color: #d97706;
+  --info-bg-color: #e8f4fd;
+  --info-stroke-color: #3b82f6;
+  --tip-bg-color: #e8f5e9;
+  --tip-stroke-color: #16a34a;
+  --check-bg-color: #e6f9ed;
+  --check-stroke-color: #22c55e;
+  --danger-bg-color: #fde8e8;
+  --danger-stroke-color: #dc2626;
+  --callout-bg-color: #f3e8fd;
+  --callout-stroke-color: #8b5cf6;
+
+  --post-pill-color: #e8f4fd;
+  --post-pill-stroke-color: #91bbf9;
+  --post-cta-color: #3064e3;
+  --get-pill-color: #e6f9ed;
+  --get-pill-stroke-color: #22c55e;
+  --get-cta-color: #22c55e;
+  --put-pill-color: #fef3e2;
+  --put-pill-stroke-color: #d97706;
+  --put-cta-color: #d97706;
+  --delete-pill-color: #fde8e8;
+  --delete-pill-stroke-color: #dc2626;
+  --delete-cta-color: #dc2626;
+  --patch-pill-color: #f3e8fd;
+  --patch-pill-stroke-color: #8b5cf6;
+  --patch-cta-color: #8b5cf6;
+}
+:root[data-theme="dark"] {
+  --page-bg: #0D0E10;
+
+  --border-color: #262827;
+  --text-color: #eeeff1;
+  --accent-color: #dc143c;
+  --muted-color: #7a7a7a;
+  --surface-color: #323334;
+
+  --note-bg-color: #1a1a1c;
+  --note-stroke-color: #eeeff1;
+  --warning-bg-color: #2a1f0d;
+  --warning-stroke-color: #7a5a1f;
+  --info-bg-color: #0d1f2a;
+  --info-stroke-color: #1f5a7a;
+  --tip-bg-color: #0d2a1a;
+  --tip-stroke-color: #1f7a4a;
+  --check-bg-color: #0d2a1a;
+  --check-stroke-color: #1f7a4a;
+  --danger-bg-color: #2a0d0d;
+  --danger-stroke-color: #7a1f1f;
+  --callout-bg-color: #1f0d2a;
+  --callout-stroke-color: #5a1f7a;
+
+  --post-pill-color: #1e3a8a;
+  --post-pill-stroke-color: #3b82f6;
+  --post-cta-color: #2563eb;
+  --get-pill-color: #065f46;
+  --get-pill-stroke-color: #10b981;
+  --get-cta-color: #059669;
+  --put-pill-color: #78350f;
+  --put-pill-stroke-color: #f59e0b;
+  --put-cta-color: #d97706;
+  --delete-pill-color: #7f1d1d;
+  --delete-pill-stroke-color: #ef4444;
+  --delete-cta-color: #dc2626;
+  --patch-pill-color: #4c1d95;
+  --patch-pill-stroke-color: #8b5cf6;
+  --patch-cta-color: #7c3aed;
+}
+
+:root {
+  --measure: 66ch;
+  --font-sans: "Google Sans Flex", sans-serif;
+  --font-mono: "Google Sans Code", ui-monospace, SFMono-Regular, monospace;
+  --font-brand: "Outfit", var(--font-sans);
+  font-family: var(--font-sans);
+
+  /* Approx height of the docs PageHeader (used as the offset for sticky
+     sidebars / TOC so they stick BELOW the header, not behind it). */
+  --velu-header-height: 7rem;
+
+  /* Fluid font sizes — 375px → 1440px viewport */
+  --f-body:  1rem;                                            /* 16 → 16 */
+  --f-h7:    calc(var(--f-h6) / var(--ratio));                /* micro UI text — one modular step below h6 (chips, captions, kbd) */
+  --f-h6:    clamp(0.75rem,  0.188vw + 0.68rem,  0.875rem);   /* 12 → 14 (reversed: mobile 14 → desktop 12, see note) */
+  --f-h5:    1rem;                                            /* 16 → 16 */
+  --f-h4:    clamp(1.125rem, 0.235vw + 1.07rem,  1.375rem);   /* 18 → 22 */
+  --f-h3:    clamp(1.3125rem,0.423vw + 1.214rem, 1.75rem);    /* 21 → 28 */
+  --f-h2:    clamp(1.5rem,   0.704vw + 1.335rem, 2.25rem);    /* 24 → 36 */
+  --f-h1:    clamp(1.6875rem,1.972vw + 1.226rem, 3rem);       /* 27 → 48 */
+
+  /* Line-height tokens — unitless (height ÷ font-size from Figma). The
+     single source of truth for leading; components reference these, never
+     a hardcoded ratio. */
+  --lh-body: 1.75;
+  --lh-h1:   1.75;
+  --lh-h2:   1.78;
+  --lh-h3:   1.71;
+  --lh-h4:   1.82;
+  --lh-h5:   1.75;
+  --lh-h6:   1.71;
+  --lh-h7:   1.71;
+
+  /* Hairline width — single source of truth for every box border, divider
+     and rail. (Sub-pixel: crisp on hi-dpi; some 1x displays round it.) */
+  --border-width: 0.5px;
+
+  /* Icon stroke weight — single source of truth for every lucide icon. */
+  --icon-stroke: 1.5;
+
+  /* Icon size scale — em-relative so an icon next to text inherits the
+     text size automatically. `--icon-size` matches surrounding text;
+     `--icon-size-lg` is one modular step larger (for nav lists / trees
+     where the icon should slightly outweigh the label). */
+  --icon-size:    1em;
+  --icon-size-lg: calc(1em * var(--ratio));
+
+  /* Corner-radius scale, derived from --s0 (16px) — no raw literals.
+     sm 8 / md 16 / lg 32. Components pick the right step. */
+  --radius-sm: calc(var(--s0) / 2);
+  --radius-md: var(--s0);
+  --radius-lg: calc(var(--s0) * 2);
+
+  /* Font-weight scale — single source of truth so components never
+     write raw 300/400/500/600/700. Matches Google Sans Flex's
+     variable-font axis stops. */
+  --weight-light:    300;
+  --weight-normal:   400;
+  --weight-medium:   500;
+  --weight-semibold: 600;
+  --weight-bold:     700;
+}
+
+/* lucide-react adds class="lucide …" to every icon svg. This one rule
+   tokenizes stroke weight app-wide (CSS overrides the svg's stroke-width
+   attribute), so no component sets it per-icon. */
+.lucide {
+  stroke-width: var(--icon-stroke);
+}
+
+/* Prose rhythm — wraps MDX content. MDX compiles to a flat list of
+   sibling block elements (h1, p, the velu-ui components, etc.).
+   Spacing is scaled by HEADING LEVEL so the document's structure is
+   readable at a glance:
+     - default sibling pair (paragraph rhythm):  --s1
+     - before any heading (section break):        scaled by level
+     - after  a heading  (heading → first child): one step under default
+   The rules use adjacent-sibling selectors so every same-level heading
+   gets the same lead-in regardless of what came before it (sibling
+   equality), and the larger before-heading gap reads as the section
+   break in every case. The owl rule sets the default; per-heading
+   rules below override it via source order (same specificity). */
+
+/* Scroll-anchor offset for in-page links: when a TOC click lands on
+   a heading, the browser scrolls so the heading sits at the viewport
+   top — which would otherwise put it BEHIND the sticky chrome
+   (header + TocBar). `scroll-margin-block-start` tells the scroll
+   algorithm to leave that much space above the target.
+
+   --velu-scroll-offset is published by App.jsx as
+   `headerHeight + tocbarHeight + 1rem`, measured live via
+   ResizeObserver. The scroll-spy reads the SAME variable as its
+   trigger line, so scrollIntoView lands the heading exactly where
+   the spy promotes it — no magic numbers, no drift. */
+.velu-hero h1,
+.velu-prose :is(h1, h2, h3, h4, h5, h6) {
+  scroll-margin-block-start: var(--velu-scroll-offset, 5rem);
+}
+
+/* Default prose rhythm. */
+.velu-prose > * + * {
+  margin-block-start: var(--s1);
+}
+
+/* Before-heading: progressively larger gap above higher-level headings.
+   Same level → same gap → siblings read at equal intervals. */
+.velu-prose > * + h2 {
+  margin-block-start: var(--s4);
+}
+.velu-prose > * + h3 {
+  margin-block-start: var(--s3);
+}
+.velu-prose > * + h4 {
+  margin-block-start: var(--s2);
+}
+
+/* After-heading: tighter, so the heading reads as "introducing" what
+   follows rather than floating alone above a chasm. */
+.velu-prose > h1 + *,
+.velu-prose > h2 + *,
+.velu-prose > h3 + *,
+.velu-prose > h4 + *,
+.velu-prose > h5 + *,
+.velu-prose > h6 + * {
+  margin-block-start: var(--s0);
+}
+
+/* Page hero — the frontmatter (title + description) is wrapped in
+   `.velu-hero` so the title and description sit tight as a single
+   unit, and a larger break separates the hero from the prose body. */
+.velu-hero > h1 + p {
+  margin-block-start: var(--s-2);
+}
+/* hero → body is an h1 → h2 transition (level-down, not peer-to-peer),
+   so the break is one modular step LARGER than the regular section
+   break above an h2 (--s4). Keeps the scale strictly monotonic:
+   level-down break > peer break. */
+.velu-hero + .velu-prose {
+  margin-block-start: var(--s5);
+}
+
+/* Sidebars / TOC scroll container: discreet thin scrollbar with a
+   tokenised colour in every state.
+
+   No transitions: Firefox doesn't honour CSS transitions on
+   `scrollbar-color` consistently, and the in-between interpolation +
+   Firefox's auto-derived hover/active colours can flash a yellow/amber
+   accent (it picks an OS / system accent when interpolating). Hard
+   switches avoid that. Same reason every WebKit thumb pseudo-state is
+   set explicitly — otherwise Chromium can fall back to the Windows 11
+   system accent on hover. */
+.velu-hide-scrollbar {
+  scrollbar-width: thin;
+  /* Single colour both at rest and on hover. Firefox auto-darkens on
+     interaction, but starting from a defined light grey keeps the
+     derived shade in the same family (no yellow flash). */
+  scrollbar-color: var(--border-color) transparent;
+}
+.velu-hide-scrollbar::-webkit-scrollbar {
+  inline-size: 6px;
+  block-size: 6px;
+}
+.velu-hide-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+.velu-hide-scrollbar::-webkit-scrollbar-thumb {
+  background: var(--border-color);
+  border-radius: 999px;
+}
+.velu-hide-scrollbar::-webkit-scrollbar-thumb:hover,
+.velu-hide-scrollbar::-webkit-scrollbar-thumb:active {
+  background: var(--muted-color);
+}
+
+/* Unitless line-height ratios (height ÷ font-size from Figma) */
+body {
+  font-size: var(--f-body);
+  line-height: var(--lh-body);
+  font-weight: var(--weight-normal);
+  background: var(--page-bg);
+  color: var(--text-color);
+}
+h1   { font-size: var(--f-h1);   line-height: var(--lh-h1); font-weight: var(--weight-semibold); }
+h2   { font-size: var(--f-h2);   line-height: var(--lh-h2); font-weight: var(--weight-medium); }
+h3   { font-size: var(--f-h3);   line-height: var(--lh-h3); font-weight: var(--weight-medium); }
+h4   { font-size: var(--f-h4);   line-height: var(--lh-h4); font-weight: var(--weight-normal); }
+h5   { font-size: var(--f-h5);   line-height: var(--lh-h5); font-weight: var(--weight-normal); }
+h6   { font-size: var(--f-h6);   line-height: var(--lh-h6); font-weight: var(--weight-normal); }
+
+* {
+  max-width: var(--measure);
+  box-sizing: border-box;
+}
+
+html,
+body,
+div,
+header,
+nav,
+main,
+footer,
+pre,
+code,
+span,
+button {
+  max-width: none;
+}

package/runtime/velu-ui/components/Accordion.jsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Accordion + AccordionGroup — collapsible disclosure.
+ *
+ * Native <details>/<summary>: zero JS, SSR-safe, accessible, chevron rotates
+ * via CSS on [open] (same pattern as Sidebar). Fully tokenized — border /
+ * hover / expanded surface / radius / spacing / type all from base.css
+ * tokens, so light + dark theme automatically via [data-theme].
+ *
+ * - <Accordion title=… defaultOpen?>content</Accordion> — standalone bordered
+ *   rounded box.
+ * - <AccordionGroup><Accordion/>…</AccordionGroup> — items joined into ONE
+ *   bordered box with dividers between them (no per-item border/radius). A
+ *   context tells nested Accordions they're grouped so they drop their own
+ *   chrome; the group container owns the border + radius + dividers.
+ *
+ * @param {{ title: React.ReactNode, defaultOpen?: boolean,
+ *   children: React.ReactNode, className?: string }} props
+ */
+
+const GroupCtx = React.createContext(false);
+
+export function Accordion({
+  title,
+  defaultOpen = false,
+  children,
+  className = '',
+  ...rest
+}) {
+  const inGroup = React.useContext(GroupCtx);
+  const cls = [
+    'velu-accordion',
+    inGroup ? 'velu-accordion--in-group' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <details className={cls} open={defaultOpen || undefined} {...rest}>
+      <summary className="velu-accordion__summary">
+        <span className="velu-accordion__chevron" aria-hidden="true">
+          {resolveIcon('chevron-right', { size: '1em' })}
+        </span>
+        <span className="velu-accordion__title">{title}</span>
+      </summary>
+      <div className="velu-accordion__content">{children}</div>
+    </details>
+  );
+}
+
+export function AccordionGroup({ children, className = '', ...rest }) {
+  return (
+    <GroupCtx.Provider value={true}>
+      <div className={`velu-accordion-group ${className}`.trim()} {...rest}>
+        {children}
+      </div>
+    </GroupCtx.Provider>
+  );
+}
+
+export default Accordion;

package/runtime/velu-ui/components/ApiClient.jsx

@@ -0,0 +1,121 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import Cluster from '../primitives/Cluster.jsx';
+import MethodBadge from './MethodBadge.jsx';
+import TryItBar from './TryItBar.jsx';
+
+/**
+ * ApiClient — the "try-it" playground layout shell.
+ *
+ *   <ApiClient
+ *     method="DELETE"
+ *     label="Trigger Delete"
+ *     path="/project/preview/{projectId}"
+ *     description="Trigger a documentation deployment…"
+ *     onClose={() => …}
+ *     aside={
+ *       <CodeGroup>…response / samples / examples…</CodeGroup>
+ *     }
+ *   >
+ *     <AccordionGroup>
+ *       <Accordion title="Authorization">
+ *         <ApiField name="Authorization" type="string" required
+ *                   prefix="Bearer" />
+ *       </Accordion>
+ *       <Accordion title="Path">
+ *         <ApiField name="projectId" type="string" required />
+ *       </Accordion>
+ *     </AccordionGroup>
+ *   </ApiClient>
+ *
+ * ApiClient is a pure layout shell — it owns the frame, the close
+ * button, the operation/endpoint head row, and the two-column body.
+ * It does NOT re-implement collapsibles or code panels:
+ *
+ *  - LEFT column  = `children` — compose the request sections with the
+ *    shared <Accordion> / <AccordionGroup> + <ApiField>.
+ *  - RIGHT column = `aside`    — compose the response / code-sample
+ *    panels with the shared <CodeBlock> / <CodeGroup>.
+ *
+ * CTAs (Send, the operation dropdown) are presentational stubs — wire
+ * `onSend` / a real selector when the OpenAPI adapter lands.
+ */
+
+export default function ApiClient({
+  method = 'GET',
+  label,
+  path = '',
+  description,
+  onSend,
+  onClose,
+  aside,
+  children,
+  className = '',
+  ...rest
+}) {
+  const key = String(method).toLowerCase();
+  const cls = `velu-api-client velu-api-client--${key} ${className}`.trim();
+
+  return (
+    <div className={cls} {...rest}>
+      {/* Close button row — only when shown as a modal (onClose set). */}
+      {onClose && (
+        <div className="velu-api-client__close-row">
+          <button
+            type="button"
+            className="velu-api-client__close"
+            onClick={onClose}
+            aria-label="Close"
+          >
+            {resolveIcon('x', { size: '1em' })}
+          </button>
+        </div>
+      )}
+
+      {/* Head — operation dropdown (dummy) + TryItBar relabeled "Send".
+          Cluster keeps each at its natural width: the dropdown hugs its
+          text (flex: none), the bar fills the rest (flex: 1). When the
+          bar can't keep its min width, Cluster wraps it below the
+          dropdown. */}
+      <Cluster
+        space="var(--s-1)"
+        align="flex-start"
+        className="velu-api-client__head"
+      >
+        <div className="velu-api-client__op">
+          <MethodBadge method={method} />
+          {label && (
+            <span className="velu-api-client__op-label">{label}</span>
+          )}
+          <span className="velu-api-client__op-chevron" aria-hidden="true">
+            {resolveIcon('chevron-down', { size: '1em' })}
+          </span>
+        </div>
+        <TryItBar
+          method={method}
+          path={path}
+          cta="Send"
+          onTry={onSend}
+          className="velu-api-client__bar"
+        />
+      </Cluster>
+
+      {/* Two-column body — left: request sections, right: response /
+          code panels. */}
+      <div className="velu-api-client__body">
+        <div className="velu-api-client__left">
+          {label && (
+            <h3 className="velu-api-client__title">{label}</h3>
+          )}
+          {description && (
+            <p className="velu-api-client__description">{description}</p>
+          )}
+          {children}
+        </div>
+        {aside != null && (
+          <div className="velu-api-client__right">{aside}</div>
+        )}
+      </div>
+    </div>
+  );
+}

package/runtime/velu-ui/components/ApiField.jsx

@@ -0,0 +1,87 @@
+import React, { useId } from 'react';
+import Cluster from '../primitives/Cluster.jsx';
+
+/**
+ * ApiField — an input-bearing field for the ApiClient playground.
+ *
+ * Distinct from <Field> (which is doc-only — it documents a parameter
+ * but has no control). ApiField renders a real <input> the user types
+ * a value into when trying an endpoint.
+ *
+ *   <ApiSection title="Path">
+ *     <ApiField name="projectId" type="string" required>
+ *       Your project ID. Copy it from the API keys page.
+ *     </ApiField>
+ *   </ApiSection>
+ *
+ * Layout — a flex-wrap pair:
+ *   [ name + type + required ]      [ prefix? input ]
+ *   [ description … ]
+ * The info column (label + description) and the control column wrap
+ * onto separate lines on narrow widths; no media queries.
+ *
+ *  - `name`        parameter identifier (mono, accent)
+ *  - `type`        schema type → grey chip ("string", "boolean", …)
+ *  - `required`    boolean → red "required" pill
+ *  - `default`     pre-fills the input's value
+ *  - `prefix`      static text shown inside the input before the field
+ *                  (e.g. "Bearer" for an Authorization header)
+ *  - `placeholder` input placeholder (defaults to `enter <name>`)
+ *  - `value`/`onChange`  optional controlled-input wiring; uncontrolled
+ *                  otherwise
+ *  - `children`    description block
+ */
+
+export default function ApiField({
+  name,
+  type,
+  required = false,
+  default: defaultValue,
+  prefix,
+  placeholder,
+  value,
+  onChange,
+  children,
+  className = '',
+  ...rest
+}) {
+  const inputId = useId();
+  const controlled = value !== undefined;
+  return (
+    <div className={`velu-api-field ${className}`.trim()} {...rest}>
+      <div className="velu-api-field__info">
+        <Cluster space="var(--s-1)" align="baseline">
+          <label className="velu-api-field__name" htmlFor={inputId}>
+            {name}
+          </label>
+          {type != null && (
+            <span className="velu-api-field__chip">{type}</span>
+          )}
+          {required && (
+            <span className="velu-api-field__required">required</span>
+          )}
+        </Cluster>
+        {children != null && children !== false && (
+          <div className="velu-api-field__desc">{children}</div>
+        )}
+      </div>
+      <div className="velu-api-field__control">
+        {prefix != null && (
+          <span className="velu-api-field__prefix">{prefix}</span>
+        )}
+        <input
+          id={inputId}
+          className="velu-api-field__input"
+          type="text"
+          placeholder={placeholder ?? `enter ${name}`}
+          {...(controlled
+            ? { value, onChange }
+            : {
+                defaultValue:
+                  defaultValue != null ? String(defaultValue) : undefined,
+              })}
+        />
+      </div>
+    </div>
+  );
+}