Improve docs component reference

.agents/skills/composing-forms/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: composing-forms
+description: Compose accessible forms with existing Nexu Design primitives and patterns such as Input, Select, Checkbox, Switch, FormField, Button, Card, Dialog, and Alert, using metadata and MCP for exact props and examples instead of embedding duplicate API tables.
+---
+
+# Composing Forms
+
+Use this skill to build forms from existing Nexu Design building blocks instead of designing ad hoc field systems.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- build a form, settings panel, filter form, signup flow, or modal form
+- choose between form primitives or patterns
+- wire validation, help text, error states, submit actions, or confirmation UI
+- improve accessibility or form copy
+
+Relevant building blocks often include:
+
+- `Input`
+- `Select`
+- `Checkbox`
+- `Switch`
+- `FormField`
+- `Button`
+- `Card`
+- `Dialog`
+- `Alert`
+
+## Workflow
+
+1. Map the user flow first: inputs, choices, validation, submission, and feedback.
+2. Compose with existing primitives and patterns rather than custom wrappers unless required.
+3. Use `FormField` or equivalent documented patterns for labels, descriptions, and errors.
+4. Keep actions clear with existing `Button` variants.
+5. Use `Card` for grouped sections, `Dialog` for modal forms, and `Alert` for important blocking or status messaging when appropriate.
+6. Check exact props, examples, and usage patterns via metadata or MCP before implementing.
+7. Keep validation and copy aligned with product guidance; prefer clear labels, concise helper text, and actionable error copy.
+
+## Source of truth / lookups
+
+Use these references instead of embedding local tables:
+
+- `/guide/ai-agents`
+- `/reference/components`
+- `/llms.txt`
+- `/llms-full.txt`
+- `/api/manifest.json`
+- `/api/components.json`
+- `/api/examples.json`
+
+For exact lookups, use `@nexu-design/mcp`:
+
+```bash
+npx -y @nexu-design/mcp
+```
+
+Useful tools:
+
+- `search_components`
+- `get_component`
+- `get_component_props`
+- `get_example`
+
+Use them to verify:
+
+- correct form primitives for the job
+- available props and states
+- examples for composition and layout
+- whether a documented pattern already solves the request
+
+For validation and wording, follow the repo's copy and accessibility guidance rather than inventing inconsistent messaging.
+
+## Avoid
+
+- Do not duplicate prop tables or examples in this skill.
+- Do not build one-off local field components if existing primitives cover the need.
+- Do not separate labels, descriptions, and error text from accessible field wiring.
+- Do not rely on placeholder text as the only label.
+- Do not hard-code validation copy patterns when repo guidance or examples already exist.
+- Do not add custom visual states before checking existing component variants and documented usage.

.agents/skills/tokens-and-theming/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: tokens-and-theming
+description: Apply Nexu Design tokens, CSS variables, and theme classes correctly by using token metadata, token references, and documented component variants instead of hard-coding values or duplicating token tables.
+---
+
+# Tokens and Theming
+
+Use this skill when styling with Nexu Design tokens, CSS variables, and theme-aware component usage.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- style UI with the Nexu token system
+- choose colors, spacing, radii, typography, or shadows
+- implement or extend theming
+- understand CSS variables or theme classes
+- align custom CSS with existing component variants
+
+## Workflow
+
+1. Start with existing component variants before adding custom styling.
+2. When custom styling is needed, prefer token-backed CSS variables.
+3. Use documented theme classes and token semantics rather than raw values.
+4. Check token names, intent, and examples through metadata or MCP.
+5. Keep custom CSS aligned with existing theming behavior so components stay consistent across themes.
+
+## Source of truth / lookups
+
+Use these sources for exact token and theming information:
+
+- `/guide/ai-agents`
+- `/reference/tokens`
+- `/reference/components`
+- `/llms.txt`
+- `/llms-full.txt`
+- `/api/manifest.json`
+- `/api/tokens.json`
+- `/api/components.json`
+- `/api/examples.json`
+
+For machine-readable token lookup, use `@nexu-design/mcp`:
+
+```bash
+npx -y @nexu-design/mcp
+```
+
+Useful tools:
+
+- `search_tokens`
+- `get_token`
+- `search_components`
+- `get_component`
+- `get_example`
+
+Use these to verify:
+
+- which token or CSS variable should back a style
+- whether an existing variant already expresses the desired state
+- how a token is intended to be used in theming or component composition
+
+## Avoid
+
+- Do not hard-code colors, spacing, radii, or other design values when a token exists.
+- Do not duplicate token value tables in this skill.
+- Do not create custom theme values that drift from documented token semantics without strong reason.
+- Do not bypass existing component variants for styling that is already supported.
+- Do not treat copied raw values as the source of truth; use token metadata, token APIs, and theming docs.

.agents/skills/using-nexu-design/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: using-nexu-design
+description: Guide consumers and agents to use @nexu-design/ui-web and @nexu-design/tokens correctly, relying on Nexu Design docs, metadata endpoints, and MCP lookups instead of recreating components, variants, prop tables, or token tables locally.
+---
+
+# Using Nexu Design
+
+Use this skill when working with Nexu Design as a consumer-facing UI system rather than inventing a parallel one.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- build UI with `@nexu-design/ui-web`
+- consume `@nexu-design/tokens`
+- find the right existing component or variant
+- check installation, imports, props, examples, or token usage
+- integrate Nexu Design into an app, prototype, or AI workflow
+
+## Workflow
+
+1. Confirm the task is consumption, composition, or lookup.
+2. Start from Nexu Design source-of-truth docs and machine-readable metadata.
+3. Identify the existing component, pattern, variant, or token before proposing new UI.
+4. Prefer published package usage:
+   - install `@nexu-design/ui-web` and/or `@nexu-design/tokens`
+   - import the package stylesheet: `@nexu-design/ui-web/styles.css`
+5. Reuse existing components and variants instead of recreating them locally.
+6. For exact APIs or examples, fetch them from metadata or MCP instead of writing static tables into the answer.
+
+## Source of truth / lookups
+
+Prefer these in roughly this order:
+
+- `/guide/ai-agents`
+- `/reference/components`
+- `/reference/tokens`
+- `/llms.txt`
+- `/llms-full.txt`
+- `/api/manifest.json`
+- `/api/components.json`
+- `/api/tokens.json`
+- `/api/examples.json`
+
+For machine-readable lookups, use `@nexu-design/mcp`:
+
+```bash
+npx -y @nexu-design/mcp
+```
+
+Useful tools:
+
+- `search_components`
+- `get_component`
+- `get_component_props`
+- `get_example`
+- `search_tokens`
+- `get_token`
+
+Use MCP or metadata to answer questions like:
+
+- which component should I use?
+- what props or variants exist?
+- is there an example for this pattern?
+- which token or CSS variable should power this style?
+
+## Avoid
+
+- Do not create local duplicate components when an existing Nexu Design component fits.
+- Do not invent new variants before checking metadata, docs, and examples.
+- Do not copy component API tables, prop tables, or token value tables into the skill.
+- Do not hard-code design decisions that should come from tokens or documented variants.
+- Do not treat memory as the source of truth when MCP or metadata can answer exactly.

.changeset/fresh-menus-hover.md

@@ -0,0 +1,5 @@
+---
+'@nexu-design/ui-web': patch
+---
+
+Improve low-emphasis hover and highlighted states so menus, selects, comboboxes, toggles, and ghost buttons remain visible on layered surfaces.

.github/workflows/ci.yml

@@ -47,9 +47,9 @@ jobs:
           ADDED_OR_MODIFIED="$(git diff --name-only --diff-filter=AM "$BASE"...HEAD)"
           CHANGESET_FILES="$(printf '%s\n' "$ADDED_OR_MODIFIED" | grep -E '^\.changeset/.+\.md$' | grep -Ev '^\.changeset/README\.md$' || true)"
 
-          if printf '%s\n' "$CHANGED_FILES" | grep -Eq '^packages/(tokens|ui-web)/'; then
+          if printf '%s\n' "$CHANGED_FILES" | grep -Eq '^packages/(tokens|ui-web|mcp-server)/'; then
             if [ -z "$CHANGESET_FILES" ]; then
-              echo "Changes to packages/tokens or packages/ui-web require a new or updated changeset entry."
+              echo "Changes to packages/tokens, packages/ui-web, or packages/mcp-server require a new or updated changeset entry."
               exit 1
             fi
           fi
@@ -66,5 +66,8 @@ jobs:
       - name: Run typecheck
         run: pnpm typecheck
 
+      - name: Run docs checks
+        run: pnpm check:docs
+
       - name: Run build
         run: pnpm build

.gitignore

@@ -1,13 +1,21 @@
 node_modules
+.next
+.source
+
+# TypeScript incremental build info
+*.tsbuildinfo
 dist
 storybook-static
 .turbo
+.vercel
 .DS_Store
 coverage
 debug-storybook.log
 .ralph/
 .opencode/
 apps/slark/out/
+apps/docs/out/
+out/
 
 # Local design notes / scratchpads (personal, not shipped)
 competitive-analysis.md

.node-version

@@ -0,0 +1 @@
+22.16.0

.nvmrc

@@ -1 +1 @@
-24.15.0
+22.16.0

apps/docs/.node-version

@@ -0,0 +1 @@
+22.16.0

apps/docs/.nvmrc

@@ -0,0 +1 @@
+22.16.0

apps/docs/app/.well-known/mcp.json/route.ts

@@ -0,0 +1,25 @@
+export const dynamic = "force-static";
+
+export function GET() {
+  return Response.json({
+    name: "Nexu Design MCP",
+    package: "@nexu-design/mcp",
+    command: "npx -y @nexu-design/mcp",
+    transport: "stdio",
+    docsUrl: "../guide/ai-agents",
+    metadata: {
+      components: "../api/components.json",
+      examples: "../api/examples.json",
+      tokens: "../api/tokens.json",
+    },
+    tools: [
+      "search_components",
+      "get_component",
+      "get_component_props",
+      "get_example",
+      "search_tokens",
+      "get_token",
+    ],
+    scope: "read-only",
+  });
+}

apps/docs/app/[...slug]/page.tsx

@@ -0,0 +1,51 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+
+import { DocsShell } from "../../components/docs-shell";
+import { docsPages, getPageBySlug } from "../../lib/docs";
+
+interface DocsPageProps {
+  params: Promise<{
+    slug: string[];
+  }>;
+}
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return docsPages.map((page) => ({ slug: page.slug }));
+}
+
+export async function generateMetadata({ params }: DocsPageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const page = getPageBySlug(slug);
+
+  if (!page) {
+    return {};
+  }
+
+  return {
+    title: page.title,
+    description: page.description,
+  };
+}
+
+export default async function DocsPage({ params }: DocsPageProps) {
+  const { slug } = await params;
+  const page = getPageBySlug(slug);
+
+  if (!page) {
+    notFound();
+  }
+
+  return (
+    <DocsShell
+      title={page.title}
+      description={page.description}
+      headings={page.headings}
+      pathname={`/${slug.join("/")}`}
+    >
+      {page.content}
+    </DocsShell>
+  );
+}

apps/docs/app/api/components.json/route.ts

@@ -0,0 +1,7 @@
+import { getComponentsApi } from "../../../lib/agent-artifacts";
+
+export const dynamic = "force-static";
+
+export function GET() {
+  return Response.json(getComponentsApi());
+}

apps/docs/app/api/examples.json/route.ts

@@ -0,0 +1,7 @@
+import { getExamplesApi } from "../../../lib/agent-artifacts";
+
+export const dynamic = "force-static";
+
+export function GET() {
+  return Response.json(getExamplesApi());
+}

apps/docs/app/api/manifest.json/route.ts

@@ -0,0 +1,7 @@
+import { getAgentManifest } from "../../../lib/agent-artifacts";
+
+export const dynamic = "force-static";
+
+export function GET() {
+  return Response.json(getAgentManifest());
+}

apps/docs/app/api/tokens.json/route.ts

@@ -0,0 +1,7 @@
+import { getTokensApi } from "../../../lib/agent-artifacts";
+
+export const dynamic = "force-static";
+
+export function GET() {
+  return Response.json(getTokensApi());
+}