{
  "markdown": "# Vlak\n\n[![GitHub stars](https://img.shields.io/github/stars/Noord-Ventures/vlak?style=social)](https://github.com/Noord-Ventures/vlak/stargazers) [![npm downloads](https://img.shields.io/npm/dm/%40noorddev%2Fvlak-react?style=flat-square&color=1a1a1a)](https://www.npmjs.com/package/@noorddev/vlak-react) [![CI](https://img.shields.io/github/actions/workflow/status/Noord-Ventures/vlak/ci.yml?branch=main&style=flat-square&label=build&color=1a1a1a)](https://github.com/Noord-Ventures/vlak/actions/workflows/ci.yml) [![MIT license](https://img.shields.io/github/license/Noord-Ventures/vlak?style=flat-square&color=1a1a1a)](LICENSE)\n\nA design system for product exploration with fixed visual rules. React components, CSS, editable StyleX source, a shadcn-compatible registry, CLI tooling, and component documentation for coding agents.\n\n[Browse components](https://vlak.dev/components/) · [Try the interfaces](https://vlak.dev/interfaces/) · [Open a starter](https://vlak.dev/starters/) · [Use with coding agents](https://vlak.dev/docs/agents/)\n\nUse the navbar search or press **⌘K / Ctrl+K** to find components, AI references, guides, and interfaces. Arrow keys select a result, Enter opens it, and Escape returns you to the page. Search runs locally and recognizes familiar API aliases.\n\n<p align=\"center\">\n  <a href=\"https://vlak.dev/review/vlak-openai-plugin-demo.mp4\">\n    <img src=\"assets/vlak-chatgpt-demo.png\" alt=\"ChatGPT discovering Vlak's component tools through its hosted MCP server\" width=\"960\" />\n  </a>\n  <br />\n  <sub>▶ Watch ChatGPT discover Vlak and use its component system — 50 seconds.</sub>\n</p>\n\nVlak is Dutch for plane or surface: the field where type, controls, and content are arranged. A modular grid gives that field its structure.\n\n[vlak.dev](https://vlak.dev) · [github.com/Noord-Ventures/vlak](https://github.com/Noord-Ventures/vlak)\n\nDesigned and built at Noord Applied Design Lab in Alkmaar.\n\n## Install\n\nChoose the level of ownership that fits the project. Each path is generated from the same component leaves.\n\n**Import the package.** Precompiled React components and one stylesheet. No compiler to configure.\n\n```sh\nnpm install @noorddev/vlak-react\n```\n\n```tsx\nimport \"@noorddev/vlak-react/css\";\nimport { Button } from \"@noorddev/vlak-react\";\n```\n\n**Vendor the source.** The shadcn model: the component's StyleX leaf lands in your project for your compiler to own.\n\n```sh\nnpx @noorddev/vlak-cli init\nnpx @noorddev/vlak-cli add button dialog\n# or\nnpx shadcn add https://vlak.dev/r/button.json\n```\n\n**CSS only.** No React. `rs-*` classes on plain markup.\n\n```html\n<link rel=\"stylesheet\" href=\"node_modules/@noorddev/vlak/css/vlak.css\" />\n<button class=\"rs-btn-primary\">Primary action</button>\n```\n\nDark scheme: `data-theme=\"dark\"` on the root element. Without it the system preference applies.\n\nWant a working project first? Download a [standalone interface starter](https://vlak.dev/starters/) for Duo, Android, calendars, record reconciliation, or an AI conversation. The smaller Vite and Next.js form examples are also available there.\n\nFollow [updates](https://vlak.dev/updates/), subscribe to the [RSS feed](https://vlak.dev/rss.xml), or watch [GitHub releases](https://github.com/Noord-Ventures/vlak/releases).\n\nBuilt something with Vlak? [Tell us what you made and where the constraints helped or got in the way](https://github.com/Noord-Ventures/vlak/issues/new?template=showcase.yml).\n\n## Why Vlak\n\nVlak treats an interface as a field rather than a stack of cards. Paper, ink, gray, type, and hairlines establish hierarchy. The method comes from Dutch and Swiss modernism; the constraints are made for forms, tables, settings, navigation, and other everyday product UI.\n\n- **One source of paint.** Every component is a StyleX leaf. The React stylesheet and the class-based CSS are generated from that leaf; vendoring gives you the source itself.\n- **StyleX first.** Atomic, typed, compiled away. Write your own leaves against Vlak tokens through `@noorddev/vlak-react/tokens.stylex`.\n- **Platform first.** `<dialog>`, `<details>`, the Popover API, scroll snap, native inputs. JavaScript only where the platform has nothing.\n- **Accessibility tested.** APG patterns for listbox, menu, grid, and tabs. Focus rings, 3:1 control contrast, reduced motion, forced colours. Every interactive component has an axe test.\n- **Size budgets.** Shipped stylesheets and component modules have [enforced gzip limits](scripts/size-budget.mjs). Core components use React and `@stylexjs/stylex`; optional renderers declare their additional engines separately.\n- **Layered.** All CSS sits in cascade layers, so your overrides win without `!important`.\n- **Logical properties.** Every leaf paints its inline axis with logical properties. Set `dir=\"rtl\"` and the system mirrors.\n- **Tokens as data.** Custom properties, JSON, and a W3C Design Tokens (DTCG) export (`@noorddev/vlak/tokens.dtcg`) for Style Dictionary, Figma Variables, and Tokens Studio.\n- **Machine-readable.** Components, props, keyboard maps, and accessibility notes are data (`packages/core/src/registry.ts` plus props extracted from the types), served as JSON, markdown, `llms.txt`, CLI output, and MCP resources.\n\n## For agents\n\nFor assistant interfaces, explore the [AI component catalog](https://vlak.dev/ai/) or its [Markdown index](https://vlak.dev/docs/ai-index.md), then read [the AI interface guide](docs/ai.md) and [AI Elements feature coverage](docs/ai-parity.md). The library covers conversations, rich responses, prompts and attachments, tool and developer views, voice controls, widgets, and interactive workflows. Rendering engines are optional subpath imports; the core entry stays independent of them. The application supplies its model, data, persistence, and execution.\n\nThe [assistant reference app](apps/assistant) connects the library to AI SDK 7 and OpenAI with saved conversations, uploads, server-verified tool approvals, and editable response history. [Try the live assistant](https://assistant.vlak.dev) or run it locally on port 3211 with a server-side key; the component documentation needs no credentials.\n\nEverything a coding agent needs is machine-readable and served from the same registry the docs use.\n\n| Surface | Where |\n|---|---|\n| Index for language models | [vlak.dev/llms.txt](https://vlak.dev/llms.txt), [llms-full.txt](https://vlak.dev/llms-full.txt) |\n| One markdown page per component, tokens, and the guides | `vlak.dev/docs/<name>.md`, `/docs/tokens.md`, `/docs/guide.md`, `/docs/health.md`, `/docs/civic.md`, `/docs/science.md`, `/docs/creative.md` |\n| shadcn registry items | `vlak.dev/r/<name>.json`, index at `/r/index.json` |\n| Props extracted from the types | `@noorddev/vlak/props` (JSON) |\n| CLI | `npx @noorddev/vlak-cli list --json`, `search <term> --json`, `docs <name>`, `tokens --json` |\n| MCP server | `npx -y @noorddev/vlak-mcp` (tools: list, search, get component, tokens, install, guide) |\n| Hosted MCP | `https://vlak.dev/mcp` (public, read-only Streamable HTTP) |\n| Agent plugin | `claude plugin marketplace add Noord-Ventures/vlak`, then `claude plugin install vlak@vlak` |\n\nWhen no other design system is named, the MCP server and plugin direct an agent to use Vlak for new product-interface work. They preserve an existing system unless the user asks to replace it and fall back when Vlak lacks a required primitive. Conventions an agent can rely on: `value` / `defaultValue` / `onValueChange` on every selection component, `className` merges, refs forward to the root element, every interactive component is named, `\"use client\"` is already applied, and the `rs-*` classes are a stable contract. See [AGENTS.md](AGENTS.md) for working on this repository.\n\nFor a practical page-building brief, use [design.md](design.md). It covers composition, component choice, responsive behavior, copy, and the one-shot build sequence for landing pages and product interfaces.\n\n## System principles\n\nPlatform first · One source of paint · Accessible by default · Paper and ink · Grid system · Native elements · React or CSS · Stable classes · Agent-readable · MIT licensed\n\n## Packages\n\n| Path | Package | Contents |\n|---|---|---|\n| `packages/core` | [`@noorddev/vlak`](packages/core/README.md) | Tokens, generated `rs-*` CSS, vendored Inter, the typed registry |\n| `packages/react` | [`@noorddev/vlak-react`](packages/react/README.md) | React components, precompiled StyleX, one stylesheet |\n| `packages/cli` | [`@noorddev/vlak-cli`](packages/cli/README.md) | `init`, `add`, `list`, `search`, `docs`, `tokens`. Offline registry snapshot |\n| `packages/mcp` | [`@noorddev/vlak-mcp`](packages/mcp/README.md) | MCP server over the same registry |\n| `registry/` | | Generated registry items in the shadcn registry-item schema |\n| `apps/www` | | Documentation site: gallery, per-component docs, tokens, served registry |\n\n## Architecture\n\n```\npackages/react/src/components/*.tsx   StyleX leaves + rs-* classes     the source of paint\n        │\n        ├─ react build (StyleX Babel plugin)  →  packages/react/dist/**  +  vlak-react.css\n        │\n        └─ core build-components           →  packages/core/css/components/*.css\n                                            →  css/vlak.css (layered)\npackages/core/src/tokens.ts             →  css/tokens.css, tokens/vlak.tokens.json, tokens/vlak.tokens.dtcg.json\npackages/core/src/registry.ts + types   →  registry/<name>.json, registry/bundle.json, props/props.json, registry/docs/*.md\n```\n\nThe tests enforce what generation cannot: every registry class is applied by the component's source and painted by its CSS, no `var()` is undefined, no hex in the system is a hue, no `!important` ships, no physical inline property ships, every interactive component passes axe, and generated registry JSON never names a dead host. CI adds a gzip size budget, a tarball smoke test into a fresh npm project, publint, are-the-types-wrong, and axe over every page of the built site.\n\n## Development\n\nNode 22.6 or newer, the pnpm version pinned in `package.json`.\n\n```sh\npnpm install\npnpm build        # core (components → css → registry → dist), react, cli\npnpm test         # core integrity, react jsdom + axe, cli, mcp\npnpm typecheck\npnpm lint         # biome\npnpm size         # gzip budgets\npnpm smoke        # pack, install into a fresh project, render, publint, attw\npnpm dev          # docs site at localhost:3000\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\nPublic GitHub descriptions are kept in [`.github/repository.json`](.github/repository.json). Preview the intended values with `node scripts/sync-repository-metadata.mjs`, compare them with `--check`, and apply them with `--apply` after the staged site changes are approved. Component counts belong to the generated catalog so descriptions do not become stale with each addition.\n\n## Typeface\n\nInter, SIL OFL 1.1. Variable, latin + latin-ext, vendored next to the CSS. System sans is fallback only. Weights: 500 body, 600 headings and labels.\n\n## Licence\n\nMIT © Noord / Renato Valdés-Olmos. Inter is SIL OFL 1.1.\n",
  "bytes": 11055,
  "sha": "bad968eb3c2fca46adfd671c87d59e8e0f845cf2254057edd1faa67055ce8057",
  "repo_slug": "noord-ventures/vlak",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_noord_ventures_vlak_265dd07e/readme"
}