[ismail9k]

Closes #35

What changes for readers

The showcase at design.the9klabs.com was one very long page holding all 60 components. It is now a documentation site built with VitePress and styled in the 9k design language.

• A page per component at /components/<slug>. Each page has live demos above their code, gotchas, the props, emits and slots read from the component's source, its types, and a self-contained agent prompt.
• Getting started, foundations and guides:
  • installation, and setup for Vue Router and Nuxt;
  • working with AI agents;
  • tokens, sizes and tones, theming and dark mode, Arabic and RTL, and page layout;
  • notifications and dialogs;
  • building a new component, which ends with a prompt that teaches an agent the repository's conventions;
  • the rules for agents.
• Navigation: search (⌘K), a sidebar, an "On this page" outline, previous and next links, and a theme switch. A button in the nav flips every live demo to right-to-left.
• For agents:
  • Every page is also Markdown at its URL plus .md.
  • llms.txt (in the llmstxt.org format) indexes those Markdown pages and opens with the rules.
  • llms-full.txt holds every page in one file.
  • components.json stays.
  • Each page's head links its Markdown version with rel="alternate", and each page has "Copy page as Markdown" and "View as Markdown" buttons.

How it is built

• Theme: showcase/.vitepress/theme/style.css maps every --vp-* variable onto a token from src/styles/, so the docs change when the system does. VitePress and the system both use html.dark, so dark mode needs no second mapping.
• Component pages are generated from showcase/registry/<Name>.ts by pages/components/[slug].paths.ts. The registry is still the one place a component's docs are written, and showcaseRegistry.test.ts still fails when an export has no entry.
• Live demos: VitePress ships Vue's runtime-only build, so compileDemo compiles demo templates with @vue/compiler-dom itself. The code shown on the page is still the string that renders. Demos sit in .vp-raw, which keeps VitePress's prose styles off the components.
• Guide pages are Markdown files listed in sidebar order in showcase/site/pages.ts.
• Machine-readable files: the Markdown pages, llms.txt, llms-full.txt, components.json and the sitemap are written in buildEnd, and a dev middleware serves the same files.
• Removed: the old single-page app, its SSR entry, prerender.mjs, and the tests that covered them.
• Kept as they were: the deploy setup (wrangler.jsonc, showcase-dist/, the workflow), _headers and robots.txt. The last two moved to showcase/pages/public/.
• Docs: AGENTS.md, the README, and the spec and plan in docs/superpowers/ describe the new site.

Verification

• npm run check passes: 1134 tests, format, lint, typecheck, library build, Storybook build, and the docs build (73 pages, 77 machine-readable files).
• New tests/showcaseSite.test.ts:
  • every guide file is listed in the sidebar list, and the reverse;
  • every registry entry has a page;
  • the slugs;
  • the Markdown versions of pages: API tables, widgets expanded, links made absolute, and an unknown widget fails the build;
  • every rule and page appears in llms.txt;
  • component pages escape < and > in prose.
• Checked in the browser:
  • light and dark;
  • demos left to right and right to left;
  • phone width (375px): the home page, plus a modal demo checked earlier;
  • a v-model demo updates as you type, with no console warnings.
• The built HTML includes the server-rendered demos and the rel="alternate" Markdown link.

🤖 Generated with Claude Code